0
# Contour Generation
1

2
Core functionality for creating contour generators and computing contours. The `contour_generator()` function is the main factory function that creates appropriate algorithm instances based on the specified parameters.
3

4
## Capabilities
5

6
### Main Factory Function
7

8
Creates and returns a ContourGenerator object with the class and properties determined by the function arguments.
9

10
```python { .api }
11
def contour_generator(
12
    x: ArrayLike | None = None,
13
    y: ArrayLike | None = None,
14
    z: ArrayLike | np.ma.MaskedArray | None = None,
15
    *,
16
    name: str = "serial",
17
    corner_mask: bool | None = None,
18
    line_type: LineType | str | None = None,
19
    fill_type: FillType | str | None = None,
20
    chunk_size: int | tuple[int, int] | None = None,
21
    chunk_count: int | tuple[int, int] | None = None,
22
    total_chunk_count: int | None = None,
23
    quad_as_tri: bool = False,
24
    z_interp: ZInterp | str | None = ZInterp.Linear,
25
    thread_count: int = 0,
26
) -> ContourGenerator:
27
    """
28
    Create and return a ContourGenerator object.
29

30
    Parameters:
31
    - x: array-like of shape (ny, nx) or (nx,), optional - X-coordinates of z values
32
    - y: array-like of shape (ny, nx) or (ny,), optional - Y-coordinates of z values  
33
    - z: array-like of shape (ny, nx) - 2D gridded values to calculate contours of
34
    - name: str - Algorithm name ("serial", "threaded", "mpl2005", "mpl2014")
35
    - corner_mask: bool, optional - Enable/disable corner masking for masked arrays
36
    - line_type: LineType or str, optional - Format of contour line data
37
    - fill_type: FillType or str, optional - Format of filled contour data
38
    - chunk_size: int or tuple(int, int), optional - Chunk size in (y, x) directions
39
    - chunk_count: int or tuple(int, int), optional - Chunk count in (y, x) directions
40
    - total_chunk_count: int, optional - Total number of chunks
41
    - quad_as_tri: bool - Treat quads as 4 triangles (default False)
42
    - z_interp: ZInterp or str, optional - Z value interpolation method
43
    - thread_count: int - Number of threads for threaded algorithm (default 0)
44

45
    Returns:
46
    ContourGenerator instance configured according to parameters
47
    """
48
```
49

50
### Basic Usage Examples
51

52
#### Simple contour generation:
53
```python
54
import contourpy
55
import numpy as np
56

57
# Create sample data
58
x = np.linspace(0, 10, 50)
59
y = np.linspace(0, 10, 50)
60
X, Y = np.meshgrid(x, y)
61
Z = np.sin(X) * np.cos(Y)
62

63
# Create contour generator with default settings
64
cont_gen = contourpy.contour_generator(X, Y, Z)
65

66
# Generate contour lines
67
lines = cont_gen.lines(0.5)
68
```
69

70
#### Algorithm selection:
71
```python
72
# Use threaded algorithm for better performance
73
cont_gen = contourpy.contour_generator(X, Y, Z, name="threaded", thread_count=4)
74

75
# Use legacy Matplotlib 2014 algorithm
76
cont_gen = contourpy.contour_generator(X, Y, Z, name="mpl2014")
77
```
78

79
#### Custom output formats:
80
```python
81
# Configure output formats
82
cont_gen = contourpy.contour_generator(
83
    X, Y, Z,
84
    line_type="SeparateCode",  # Include path codes with lines
85
    fill_type="OuterOffset"    # Use offset format for filled contours
86
)
87
```
88

89
#### Working with masked data:
90
```python
91
# Create masked array
92
Z_masked = np.ma.masked_where(Z < 0.2, Z)
93

94
# Enable corner masking for better masked contours
95
cont_gen = contourpy.contour_generator(X, Y, Z_masked, corner_mask=True)
96
```
97

98
#### Chunking for large datasets:
99
```python
100
# Use chunking for memory efficiency
101
cont_gen = contourpy.contour_generator(
102
    X, Y, Z,
103
    chunk_size=(20, 20),  # Process in 20x20 chunks
104
    name="threaded",      # Use threaded algorithm
105
    thread_count=2        # Use 2 threads
106
)
107
```
108

109
### Algorithm Selection
110

111
Four algorithms are available:
112

113
- **"serial"** (default): Modern serial algorithm with full feature support
114
- **"threaded"**: Modern multithreaded algorithm for parallel processing
115
- **"mpl2005"**: Legacy Matplotlib 2005 algorithm (limited chunking support)
116
- **"mpl2014"**: Legacy Matplotlib 2014 algorithm with corner masking support
117

118
### Chunking Options
119

120
Control memory usage and enable parallelization:
121

122
- **chunk_size**: Specify chunk dimensions directly
123
- **chunk_count**: Specify number of chunks in each direction  
124
- **total_chunk_count**: Specify total number of chunks (auto-distributed)
125

126
Only one of these options should be specified at a time.
127

128
### Interpolation Methods
129

130
Control how Z values are interpolated:
131

132
- **ZInterp.Linear** (default): Linear interpolation
133
- **ZInterp.Log**: Logarithmic interpolation
134

135
### Thread Configuration
136

137
For the "threaded" algorithm:
138

139
- **thread_count=0**: Use maximum available threads (auto-detected)
140
- **thread_count=N**: Use N specific threads
141
- Requires sufficient chunks for effective parallelization