0
# Types and Configuration
1

2
Enums for configuring output formats and interpolation methods, plus utility functions and type definitions. These components control how contour data is formatted and processed.
3

4
## Capabilities
5

6
### Fill Type Configuration
7

8
Enum controlling the format of filled contour output data.
9

10
```python { .api }
11
class FillType:
12
    """Enum specifying filled contour output formats."""
13
    
14
    OuterCode: FillType
15
    """
16
    List of point arrays with separate list of code arrays.
17
    Format: (list[PointArray], list[CodeArray])
18
    Each polygon has corresponding point and code arrays.
19
    """
20
    
21
    OuterOffset: FillType  
22
    """
23
    List of point arrays with separate list of offset arrays.
24
    Format: (list[PointArray], list[OffsetArray])
25
    Offsets specify polygon boundaries within point arrays.
26
    """
27
    
28
    ChunkCombinedCode: FillType
29
    """
30
    Chunked format with combined points and separate codes.
31
    Format: (list[PointArray | None], list[CodeArray | None])
32
    None entries represent empty chunks.
33
    """
34
    
35
    ChunkCombinedOffset: FillType
36
    """
37
    Chunked format with combined points and separate offsets.
38
    Format: (list[PointArray | None], list[OffsetArray | None])
39
    None entries represent empty chunks.
40
    """
41
    
42
    ChunkCombinedCodeOffset: FillType
43
    """
44
    Chunked format with points, codes, and outer offsets.
45
    Format: (list[PointArray | None], list[CodeArray | None], list[OffsetArray | None])
46
    Provides both code and offset information per chunk.
47
    """
48
    
49
    ChunkCombinedOffsetOffset: FillType
50
    """
51
    Chunked format with points and two levels of offsets.
52
    Format: (list[PointArray | None], list[OffsetArray | None], list[OffsetArray | None])
53
    Inner and outer offset arrays for complex polygon structures.
54
    """
55
    
56
    __members__: dict[str, FillType]
57
    """Dictionary mapping string names to FillType values."""
58
    
59
    @property
60
    def name(self) -> str:
61
        """String name of the FillType."""
62
    
63
    @property  
64
    def value(self) -> int:
65
        """Integer value of the FillType."""
66
```
67

68
### Line Type Configuration
69

70
Enum controlling the format of contour line output data.
71

72
```python { .api }
73
class LineType:
74
    """Enum specifying contour line output formats."""
75
    
76
    Separate: LineType
77
    """
78
    List of separate point arrays, one per contour line.
79
    Format: list[PointArray]
80
    Each line is a separate array of (x, y) coordinates.
81
    """
82
    
83
    SeparateCode: LineType
84
    """
85
    List of point arrays with corresponding code arrays.
86
    Format: (list[PointArray], list[CodeArray])
87
    Includes matplotlib-compatible path codes.
88
    """
89
    
90
    ChunkCombinedCode: LineType
91
    """
92
    Chunked format with combined points and separate codes.
93
    Format: (list[PointArray | None], list[CodeArray | None])
94
    None entries represent empty chunks.
95
    """
96
    
97
    ChunkCombinedOffset: LineType
98
    """
99
    Chunked format with combined points and offset arrays.
100
    Format: (list[PointArray | None], list[OffsetArray | None])
101
    Offsets specify line boundaries within point arrays.
102
    """
103
    
104
    ChunkCombinedNan: LineType
105
    """
106
    Chunked format with NaN-separated combined points.
107
    Format: (list[PointArray | None],)
108
    Lines separated by NaN values in single point array per chunk.
109
    """
110
    
111
    __members__: dict[str, LineType]
112
    """Dictionary mapping string names to LineType values."""
113
    
114
    @property
115
    def name(self) -> str:
116
        """String name of the LineType."""
117
    
118
    @property
119
    def value(self) -> int:
120
        """Integer value of the LineType."""
121
```
122

123
### Z Interpolation Configuration
124

125
Enum controlling how Z values are interpolated during contour calculation.
126

127
```python { .api }
128
class ZInterp:
129
    """Enum specifying Z-value interpolation methods."""
130
    
131
    Linear: ZInterp
132
    """
133
    Linear interpolation between Z values (default).
134
    Standard linear interpolation for most use cases.
135
    """
136
    
137
    Log: ZInterp
138
    """
139
    Logarithmic interpolation between Z values.
140
    Useful for data spanning multiple orders of magnitude.
141
    """
142
    
143
    __members__: dict[str, ZInterp]
144
    """Dictionary mapping string names to ZInterp values."""
145
    
146
    @property
147
    def name(self) -> str:
148
        """String name of the ZInterp."""
149
    
150
    @property
151
    def value(self) -> int:
152
        """Integer value of the ZInterp."""
153
```
154

155
### Enum Conversion Utilities
156

157
Functions to convert between string and enum representations.
158

159
```python { .api }
160
def as_fill_type(fill_type: FillType | str) -> FillType:
161
    """
162
    Convert string or FillType to FillType enum.
163
    
164
    Parameters:
165
    - fill_type: FillType enum or string name
166
    
167
    Returns:
168
    FillType enum value
169
    
170
    Raises:
171
    ValueError: If string is not a valid FillType name
172
    """
173

174
def as_line_type(line_type: LineType | str) -> LineType:
175
    """
176
    Convert string or LineType to LineType enum.
177
    
178
    Parameters:
179
    - line_type: LineType enum or string name
180
    
181
    Returns:
182
    LineType enum value
183
    
184
    Raises:
185
    ValueError: If string is not a valid LineType name
186
    """
187

188
def as_z_interp(z_interp: ZInterp | str) -> ZInterp:
189
    """
190
    Convert string or ZInterp to ZInterp enum.
191
    
192
    Parameters:
193
    - z_interp: ZInterp enum or string name
194
    
195
    Returns:
196
    ZInterp enum value
197
    
198
    Raises:
199
    ValueError: If string is not a valid ZInterp name
200
    """
201
```
202

203
### Utility Functions
204

205
```python { .api }
206
def max_threads() -> int:
207
    """
208
    Get maximum number of threads available for threaded algorithms.
209
    
210
    Returns:
211
    Maximum number of hardware threads detected by C++11
212
    std::thread::hardware_concurrency()
213
    """
214

215
def calc_chunk_sizes(
216
    chunk_size: int | tuple[int, int] | None,
217
    chunk_count: int | tuple[int, int] | None,
218
    total_chunk_count: int | None,
219
    ny: int,
220
    nx: int,
221
) -> tuple[int, int]:
222
    """
223
    Calculate optimal chunk sizes for processing.
224
    
225
    Parameters:
226
    - chunk_size: Direct chunk size specification
227
    - chunk_count: Number of chunks in each direction
228
    - total_chunk_count: Total number of chunks (auto-distributed)
229
    - ny: Grid height (number of y points)
230
    - nx: Grid width (number of x points)
231
    
232
    Returns:
233
    Tuple of (y_chunk_size, x_chunk_size) 
234
    
235
    Note:
236
    Only one of chunk_size, chunk_count, total_chunk_count should be specified.
237
    """
238
```
239

240
### Build Configuration
241

242
```python { .api }
243
def build_config() -> dict[str, str]:
244
    """
245
    Get build configuration information.
246
    
247
    Returns:
248
    Dictionary containing build configuration details including
249
    compiler information, build flags, and system details.
250
    """
251
```
252

253
## Usage Examples
254

255
### Working with Enums
256

257
```python
258
import contourpy
259

260
# Use enum values directly
261
fill_type = contourpy.FillType.OuterCode
262
line_type = contourpy.LineType.SeparateCode
263
z_interp = contourpy.ZInterp.Linear
264

265
# Convert from strings
266
fill_type = contourpy.as_fill_type("OuterOffset")
267
line_type = contourpy.as_line_type("Separate")  
268
z_interp = contourpy.as_z_interp("Log")
269

270
# Check enum properties
271
print(f"Fill type name: {fill_type.name}")
272
print(f"Line type value: {line_type.value}")
273
```
274

275
### Configuration with Factory Function
276

277
```python
278
# Configure output formats using enums
279
cont_gen = contourpy.contour_generator(
280
    X, Y, Z,
281
    line_type=contourpy.LineType.SeparateCode,
282
    fill_type=contourpy.FillType.OuterOffset,
283
    z_interp=contourpy.ZInterp.Log
284
)
285

286
# Or using strings (converted automatically)
287
cont_gen = contourpy.contour_generator(
288
    X, Y, Z,
289
    line_type="ChunkCombinedOffset",
290
    fill_type="ChunkCombinedCodeOffset", 
291
    z_interp="Linear"
292
)
293
```
294

295
### Threading Configuration
296

297
```python
298
# Check maximum available threads
299
max_threads = contourpy.max_threads()
300
print(f"Maximum threads available: {max_threads}")
301

302
# Use optimal thread count
303
cont_gen = contourpy.contour_generator(
304
    X, Y, Z,
305
    name="threaded",
306
    thread_count=min(4, max_threads)  # Use up to 4 threads
307
)
308
```
309

310
### Chunk Size Calculation
311

312
```python
313
# Calculate optimal chunk sizes
314
ny, nx = Z.shape
315
y_chunk, x_chunk = contourpy.calc_chunk_sizes(
316
    chunk_size=None,
317
    chunk_count=(2, 3),  # 2x3 grid of chunks
318
    total_chunk_count=None,
319
    ny=ny,
320
    nx=nx
321
)
322
print(f"Calculated chunk sizes: {y_chunk} x {x_chunk}")
323
```
324

325
### Build Information
326

327
```python
328
# Get build configuration details
329
config = contourpy.build_config()
330
print("ContourPy build configuration:")
331
for key, value in config.items():
332
    print(f"  {key}: {value}")
333
```
334

335
## Type Relationships
336

337
### Data Flow
338

339
1. **Input**: CoordinateArray (x, y) + CoordinateArray (z) + optional MaskArray
340
2. **Processing**: Algorithm + ZInterp configuration
341
3. **Output**: LineReturn or FillReturn based on LineType/FillType
342
4. **Post-processing**: Conversion and dechunking as needed
343

344
### Format Selection Guidelines
345

346
- **Separate/OuterCode**: Simple, matplotlib-compatible formats
347
- **ChunkCombined***: Memory-efficient for large datasets
348
- **Offset formats**: Efficient for complex geometries
349
- **Code formats**: matplotlib Path compatibility
350
- **NaN format**: Simple line concatenation with separators