0
# Data Conversion and Processing
1

2
Functions for converting between different contour data formats and processing chunked results. These utilities enable interoperability between different output formats and efficient handling of large datasets processed in chunks.
3

4
## Capabilities
5

6
### Format Conversion
7

8
Convert contour data between different line and fill formats.
9

10
```python { .api }
11
def convert_lines(
12
    lines,
13
    line_type_from: LineType | str,
14
    line_type_to: LineType | str
15
):
16
    """
17
    Convert contour line data from one format to another.
18
    
19
    Parameters:
20
    - lines: Line contour data in source format
21
    - line_type_from: Source LineType format
22
    - line_type_to: Target LineType format
23
    
24
    Returns:
25
    Line contour data in target format
26
    """
27

28
def convert_filled(
29
    filled,
30
    fill_type_from: FillType | str, 
31
    fill_type_to: FillType | str
32
):
33
    """
34
    Convert filled contour data from one format to another.
35
    
36
    Parameters:
37
    - filled: Filled contour data in source format
38
    - fill_type_from: Source FillType format
39
    - fill_type_to: Target FillType format
40
    
41
    Returns:
42
    Filled contour data in target format
43
    """
44

45
def convert_multi_lines(
46
    multi_lines: list,
47
    line_type_from: LineType | str,
48
    line_type_to: LineType | str
49
) -> list:
50
    """
51
    Convert multiple line contour datasets between formats.
52
    
53
    Parameters:
54
    - multi_lines: List of line contour datasets
55
    - line_type_from: Source LineType format
56
    - line_type_to: Target LineType format
57
    
58
    Returns:
59
    List of converted line contour datasets
60
    """
61

62
def convert_multi_filled(
63
    multi_filled: list,
64
    fill_type_from: FillType | str,
65
    fill_type_to: FillType | str
66
) -> list:
67
    """
68
    Convert multiple filled contour datasets between formats.
69
    
70
    Parameters:
71
    - multi_filled: List of filled contour datasets
72
    - fill_type_from: Source FillType format
73
    - fill_type_to: Target FillType format
74
    
75
    Returns:
76
    List of converted filled contour datasets
77
    """
78
```
79

80
### Dechunking Functions
81

82
Move chunked contour data into a single chunk for simplified processing.
83

84
```python { .api }
85
def dechunk_lines(
86
    lines,
87
    line_type: LineType | str
88
):
89
    """
90
    Move chunked line contour data into the first chunk.
91
    
92
    Individual contour lines are unchanged, only the chunk organization
93
    is modified. Non-chunked data and single-chunk data are returned unmodified.
94
    
95
    Parameters:
96
    - lines: Chunked line contour data
97
    - line_type: LineType format of the data
98
    
99
    Returns:
100
    Line contour data consolidated into single chunk
101
    """
102

103
def dechunk_filled(
104
    filled,
105
    fill_type: FillType | str  
106
):
107
    """
108
    Move chunked filled contour data into the first chunk.
109
    
110
    Individual polygons are unchanged, only the chunk organization
111
    is modified. Non-chunked data and single-chunk data are returned unmodified.
112
    
113
    Parameters:
114
    - filled: Chunked filled contour data
115
    - fill_type: FillType format of the data
116
    
117
    Returns:
118
    Filled contour data consolidated into single chunk
119
    """
120

121
def dechunk_multi_lines(
122
    multi_lines: list,
123
    line_type: LineType | str
124
) -> list:
125
    """
126
    Dechunk multiple line contour datasets.
127
    
128
    Parameters:
129
    - multi_lines: List of chunked line contour datasets
130
    - line_type: LineType format of the data
131
    
132
    Returns:
133
    List of dechunked line contour datasets
134
    """
135

136
def dechunk_multi_filled(
137
    multi_filled: list,
138
    fill_type: FillType | str
139
) -> list:
140
    """
141
    Dechunk multiple filled contour datasets.
142
    
143
    Parameters:
144
    - multi_filled: List of chunked filled contour datasets
145
    - fill_type: FillType format of the data
146
    
147
    Returns:
148
    List of dechunked filled contour datasets
149
    """
150
```
151

152
## Usage Examples
153

154
### Format Conversion
155

156
```python
157
import contourpy
158

159
# Create contour generator with one format
160
cont_gen = contourpy.contour_generator(
161
    X, Y, Z, 
162
    line_type="Separate",
163
    fill_type="OuterCode"
164
)
165

166
# Generate contours
167
lines = cont_gen.lines(1.0)
168
filled = cont_gen.filled(0.5, 1.5)
169

170
# Convert to different formats
171
lines_with_codes = contourpy.convert_lines(
172
    lines, "Separate", "SeparateCode"
173
)
174

175
filled_with_offsets = contourpy.convert_filled(
176
    filled, "OuterCode", "OuterOffset"  
177
)
178
```
179

180
### Working with Multiple Levels
181

182
```python
183
# Generate multiple contour levels
184
levels = [1.0, 2.0, 3.0, 4.0]
185
multi_lines = cont_gen.multi_lines(levels)
186
multi_filled = cont_gen.multi_filled(levels)
187

188
# Convert all levels to different format
189
multi_lines_coded = contourpy.convert_multi_lines(
190
    multi_lines, "Separate", "SeparateCode"
191
)
192

193
multi_filled_offset = contourpy.convert_multi_filled(
194
    multi_filled, "OuterCode", "OuterOffset"
195
)
196
```
197

198
### Dechunking Chunked Data
199

200
```python
201
# Create chunked contour generator
202
chunked_gen = contourpy.contour_generator(
203
    X, Y, Z,
204
    chunk_size=(25, 25),
205
    line_type="ChunkCombinedCode",
206
    fill_type="ChunkCombinedCodeOffset"
207
)
208

209
# Generate chunked contours
210
chunked_lines = chunked_gen.lines(2.0)
211
chunked_filled = chunked_gen.filled(1.0, 3.0)
212

213
# Consolidate chunks into single chunk
214
single_chunk_lines = contourpy.dechunk_lines(
215
    chunked_lines, "ChunkCombinedCode"
216
)
217

218
single_chunk_filled = contourpy.dechunk_filled(
219
    chunked_filled, "ChunkCombinedCodeOffset"
220
)
221
```
222

223
### Processing Pipeline
224

225
```python
226
# Complete processing pipeline: chunked -> dechunked -> converted
227
chunked_gen = contourpy.contour_generator(
228
    X, Y, Z,
229
    chunk_count=(4, 4),
230
    line_type="ChunkCombinedOffset"
231
)
232

233
# Generate multiple levels with chunking
234
levels = [0.5, 1.0, 1.5, 2.0]
235
chunked_multi = chunked_gen.multi_lines(levels)
236

237
# Dechunk the data
238
dechunked_multi = contourpy.dechunk_multi_lines(
239
    chunked_multi, "ChunkCombinedOffset"
240
)
241

242
# Convert to simple separate format
243
final_lines = contourpy.convert_multi_lines(
244
    dechunked_multi, "ChunkCombinedOffset", "Separate"
245
)
246
```
247

248
## Format Compatibility
249

250
### Line Type Conversions
251

252
- **Separate** ↔ **SeparateCode**: Add/remove path codes
253
- **ChunkCombined*** ↔ **Separate/SeparateCode**: Consolidate chunks
254
- **ChunkCombinedCode** ↔ **ChunkCombinedOffset**: Code/offset conversion
255

256
### Fill Type Conversions
257

258
- **OuterCode** ↔ **OuterOffset**: Code/offset conversion
259
- **ChunkCombined*** ↔ **Outer***: Consolidate chunks
260
- Various **ChunkCombined*** formats: Different combination strategies
261

262
### Performance Considerations
263

264
- Dechunking consolidates memory usage but may increase peak memory
265
- Format conversion creates new arrays, consider memory implications
266
- Chunked formats enable parallel processing and memory management
267
- Choose appropriate formats based on downstream usage requirements