0
# ContourPy
1

2
ContourPy is a Python library for calculating contours of 2D quadrilateral grids. Written in C++11 and wrapped using pybind11, it provides the 2005 and 2014 algorithms used in Matplotlib as well as newer algorithms available in both serial and multithreaded versions. It enables Python applications to perform efficient contour calculations without requiring Matplotlib as a dependency.
3

4
## Package Information
5

6
- **Package Name**: contourpy
7
- **Language**: Python
8
- **Installation**: `pip install contourpy`
9

10
## Core Imports
11

12
```python
13
import contourpy
14
```
15

16
Most common for creating contour generators:
17

18
```python
19
from contourpy import contour_generator
20
```
21

22
For working with specific algorithms and types:
23

24
```python
25
from contourpy import (
26
    contour_generator,
27
    FillType,
28
    LineType,
29
    ZInterp,
30
    ContourGenerator,
31
    SerialContourGenerator,
32
    ThreadedContourGenerator,
33
    __version__
34
)
35
```
36

37
For utility functions:
38

39
```python
40
from contourpy.util import build_config
41
```
42

43
## Basic Usage
44

45
```python
46
import contourpy
47
import numpy as np
48

49
# Create sample 2D data
50
x = np.linspace(-3, 3, 100)
51
y = np.linspace(-3, 3, 100)
52
X, Y = np.meshgrid(x, y)
53
Z = X**2 + Y**2
54

55
# Create a contour generator
56
cont_gen = contourpy.contour_generator(X, Y, Z)
57

58
# Generate contour lines at a specific level
59
lines = cont_gen.lines(4.0)
60

61
# Generate filled contours between two levels
62
filled = cont_gen.filled(2.0, 6.0)
63

64
# Generate multiple contour lines at different levels
65
levels = [1.0, 2.0, 3.0, 4.0, 5.0]
66
multi_lines = cont_gen.multi_lines(levels)
67

68
# Generate multiple filled contours
69
multi_filled = cont_gen.multi_filled(levels)
70
```
71

72
## Architecture
73

74
ContourPy provides multiple algorithm implementations through a unified interface:
75

76
- **ContourGenerator**: Abstract base class defining the standard interface
77
- **Algorithm Implementations**: Four concrete implementations with different capabilities:
78
  - `Mpl2005ContourGenerator`: Legacy Matplotlib 2005 algorithm
79
  - `Mpl2014ContourGenerator`: Legacy Matplotlib 2014 algorithm with corner masking
80
  - `SerialContourGenerator`: Modern serial algorithm with full feature support
81
  - `ThreadedContourGenerator`: Modern multithreaded algorithm for parallel processing
82
- **Data Formats**: Flexible output formats controlled by `LineType` and `FillType` enums
83
- **Processing Options**: Chunking support for large datasets and memory management
84

85
## Capabilities
86

87
### Contour Generation
88

89
Core functionality for creating contour generators and computing contours with multiple algorithm options, output formats, and processing configurations.
90

91
```python { .api }
92
def contour_generator(
93
    x: ArrayLike | None = None,
94
    y: ArrayLike | None = None,
95
    z: ArrayLike | np.ma.MaskedArray | None = None,
96
    *,
97
    name: str = "serial",
98
    corner_mask: bool | None = None,
99
    line_type: LineType | str | None = None,
100
    fill_type: FillType | str | None = None,
101
    chunk_size: int | tuple[int, int] | None = None,
102
    chunk_count: int | tuple[int, int] | None = None,
103
    total_chunk_count: int | None = None,
104
    quad_as_tri: bool = False,
105
    z_interp: ZInterp | str | None = ZInterp.Linear,
106
    thread_count: int = 0,
107
) -> ContourGenerator: ...
108
```
109

110
[Contour Generation](./contour-generation.md)
111

112
### Algorithm Classes
113

114
Direct access to specific contour generation algorithms with their individual constructors and capabilities.
115

116
```python { .api }
117
class ContourGenerator:
118
    def lines(self, level: float) -> LineReturn: ...
119
    def filled(self, lower_level: float, upper_level: float) -> FillReturn: ...
120
    def multi_lines(self, levels) -> list[LineReturn]: ...
121
    def multi_filled(self, levels) -> list[FillReturn]: ...
122

123
class SerialContourGenerator(ContourGenerator): ...
124
class ThreadedContourGenerator(ContourGenerator): ...
125
class Mpl2005ContourGenerator(ContourGenerator): ...
126
class Mpl2014ContourGenerator(ContourGenerator): ...
127
```
128

129
[Algorithm Classes](./algorithm-classes.md)
130

131
### Data Conversion and Processing
132

133
Functions for converting between different contour data formats and processing chunked results.
134

135
```python { .api }
136
def convert_filled(filled, fill_type_from: FillType | str, fill_type_to: FillType | str): ...
137
def convert_lines(lines, line_type_from: LineType | str, line_type_to: LineType | str): ...
138
def dechunk_filled(filled, fill_type: FillType | str): ...
139
def dechunk_lines(lines, line_type: LineType | str): ...
140
```
141

142
[Data Conversion](./data-conversion.md)
143

144
### Configuration and Types
145

146
Enums for configuring output formats and interpolation methods, plus utility functions.
147

148
```python { .api }
149
class FillType:
150
    OuterCode: FillType
151
    OuterOffset: FillType
152
    ChunkCombinedCode: FillType
153
    ChunkCombinedOffset: FillType
154
    ChunkCombinedCodeOffset: FillType
155
    ChunkCombinedOffsetOffset: FillType
156

157
class LineType:
158
    Separate: LineType
159
    SeparateCode: LineType
160
    ChunkCombinedCode: LineType
161
    ChunkCombinedOffset: LineType
162
    ChunkCombinedNan: LineType
163

164
class ZInterp:
165
    Linear: ZInterp
166
    Log: ZInterp
167

168
def max_threads() -> int: ...
169
```
170

171
[Types and Configuration](./types-configuration.md)
172

173
### Version and Build Information
174

175
Package version and build configuration utilities.
176

177
```python { .api }
178
__version__: str  # Package version string
179

180
# Available in contourpy.util submodule
181
def build_config() -> dict[str, str]:  # Build configuration details
182
```
183

184
## Types
185

186
```python { .api }
187
# Required imports for type definitions
188
from numpy.typing import ArrayLike, NDArray
189
import numpy as np
190

191
# Input array types
192
CoordinateArray = NDArray[np.float64]  # For x, y coordinates
193
MaskArray = NDArray[np.bool_]  # For data masks
194
LevelArray = ArrayLike  # For contour level specifications
195

196
# Output array types
197
PointArray = NDArray[np.float64]  # Contour point coordinates
198
CodeArray = NDArray[np.uint8]  # Path codes for matplotlib compatibility
199
OffsetArray = NDArray[np.uint32]  # Offset arrays for line/polygon segments
200

201
# Return types from contour methods
202
LineReturn = list[PointArray] | tuple[list[PointArray], list[CodeArray]] | tuple[list[PointArray | None], ...]
203
FillReturn = tuple[list[PointArray], list[CodeArray | OffsetArray]] | tuple[list[PointArray | None], ...]
204
```