contourpy

contourpy is a Python library, backed by a compiled C++ core, for calculating contour lines and filled contour polygons from scalar data defined on 2D quadrilateral grids. Given a grid of z-values and one or more threshold levels, it produces the line segments or closed polygons that trace where the surface crosses those levels — the computational step underlying every contour and filled-contour plot.

It was extracted from Matplotlib’s internal contouring code to be a standalone, independently maintained, and faster replacement, and now serves as Matplotlib’s default contouring backend as well as a pluggable engine other plotting libraries (such as Bokeh) can call directly, with several selectable algorithms trading off speed, corner-case handling, and output structure.

What You Get

• contour_generator() factory producing a configurable contour-generation object for a given grid
• Multiple selectable algorithms (mpl2005, mpl2014, serial, threaded) trading off speed, threading, and corner-case fidelity
• Line-contour and filled-contour (polygon) output modes
• NumPy array-based input/output for direct integration into scientific Python pipelines
• Chunked/grid-partitioned processing for large datasets, with dechunking utilities
• Type-checked, py.typed public API with .pyi stubs for the compiled extension

Common Use Cases

• Computing contour lines and filled contour polygons for Matplotlib’s contour/contourf plotting functions
• Powering contour rendering in other plotting libraries (e.g., Bokeh) that call contourpy directly
• Extracting isoline/isoband geometry from gridded scientific or geospatial data for further geometric processing
• Benchmarking or comparing different contouring algorithms for large-grid performance-sensitive pipelines

Under The Hood

Architecture - the numerically heavy work lives in a C++ core (src/, ~20 files including contour_generator.cpp, serial.cpp, threaded.cpp, mpl2005.cpp, mpl2014.cpp) implementing several interchangeable contouring algorithms behind a common ContourGenerator interface, compiled into a _contourpy extension module via pybind11-style bindings (wrap.cpp) and Meson as the build backend; the thin Python layer in lib/contourpy/ (__init__.py, array.py, chunk.py, convert.py, dechunk.py) handles input validation, NumPy array marshaling, chunk/grid partitioning, and format conversion between line and fill representations, dispatching the actual computation to the compiled core. Tech Stack - C++ compiled with Meson/meson-python as the PEP 517 build backend, NumPy as the sole runtime array dependency, with optional Matplotlib/Bokeh integration exercised in tests; pyproject.toml and meson.build define the mixed-language build. Code Quality - the tests/ directory is extensive (20+ files) including dedicated algorithm-comparison tests (test_lines.py, test_filled.py), image-comparison regression tests against baseline images, static type-checking tests (test_typecheck.py, test_static.py), and build-configuration tests, reflecting the project’s role as a performance- and correctness-critical dependency for Matplotlib; a benchmarks/ directory with asv config tracks performance regressions across algorithm variants. API Design - the public entry point (contour_generator(x, y, z, name=...)) intentionally exposes algorithm choice as a named parameter so callers can trade accuracy/speed, while keeping the line/fill output format consistent across algorithms — a deliberately narrow, computation-focused API rather than a general plotting interface, since rendering is left entirely to the calling library.