Performance¶

These historical measurements predate the current dependency and algorithm updates and have not been rerun for this revision. The numbers below were collected on Linux x86_64, Intel i7-10700K, release build, Python 3.13.5, and NumPy 2.4.2. Reproduce with scripts/benchmark.py.

For a new run, save measurements and environment versions with uv run python scripts/benchmark.py --output results.json. Use --measure-process-rss to include retained process RSS measurements.

API differences vs rasterio.features.shapes¶

These benchmarks compare contourrs to rasterio.features.shapes, which is the main public Python baseline for polygonization.

If you already have a NumPy array in memory, this is the closest apples-to-apples comparison. If you need dataset IO, metadata propagation, or format conversion, the broader rasterio/GDAL stack still covers more ground.

Methodology¶

• Timing — median of 5 runs after 2 warmup runs (3 + 1 for the real-world cases)
• Synthetic polygonize — random uint8 raster with 5 categorical values; intentionally noisy, high-boundary workload
• Synthetic contours — random float32 raster with 5 thresholds; near worst-case for marching-squares ring count
• Python heap — peak allocation from tracemalloc
• Retained process RSS delta — fresh-subprocess RSS after the call, with its result retained, minus a post-import, post-input-load baseline; this is not peak RSS

Polygonization of synthetic rasters¶

rasterio.features.shapes is the main public Python baseline for shapes() and shapes_arrow(). Internally it wraps GDAL's polygonize path, but the numbers here are intended as an apples-to-apples Python API comparison.

shapes_arrow() avoids Python GeoJSON dict/list construction and passes WKB buffers to PyArrow.

Polygonization of CDL¶

512x512 crop of the 2023 USDA Cropland Data Layer for Polk County, Iowa.

On real land-cover data, shapes_arrow() is still about 4.4x faster than shapes() and about 7.5x faster than rasterio.

Contouring of synthetic rasters¶

These are contours() vs contours_arrow() on random float32 data with 5 thresholds. This is intentionally harsh on isoband extraction because it maximizes tiny rings.

The contour path spends most of its time in marching squares and polygon assembly, so Arrow helps less than it does for categorical polygonization.

Contouring of a DEM¶

2048x2048 Mt. Rainier DEM with 250 m contour bands.

Real DEMs are much smoother than random noise, so contour extraction is faster than the synthetic worst case.

Polygonization memory¶

Python heap peak (tracemalloc)¶

The <0.1MB entries measure Python-managed allocations, not the native buffers that hold the Arrow output.

Retained process RSS delta (fresh subprocess)¶

shapes_arrow() allocates native memory for labeling, polygon tracing, WKB serialization, and Arrow buffers. Its retained process RSS is ~28-29% lower than rasterio on the larger grids in this benchmark. These before-and-after measurements do not capture peak memory during the call.

Contouring memory¶

Python heap peak (tracemalloc)¶

Retained process RSS delta (fresh subprocess)¶

For contours, Arrow reduces Python overhead and still lowers process memory, but the end-to-end savings are smaller than the tracemalloc table alone suggests.

Dtype timing¶

1024x1024 grid, shapes_arrow().

Input dtype has little effect on the Arrow polygonize path in this benchmark; all tested dtypes fall within about 1% of each other.