isobands

An easy way to make filled contour maps with Python.

isobands converts a regular two-dimensional xarray raster into filled contour polygons backed by a GeoPandas GeoDataFrame.

Install

Install GDAL 3.10.2 or 3.12.2 and matching development headers using the official GDAL installation guide. Then install the matching binding:

pip install "isobands[gdal310]"  # native GDAL 3.10.2
# or
pip install "isobands[gdal312]"  # native GDAL 3.12.2

Quick start

import numpy as np
import xarray as xr

from isobands import isobands

data = xr.DataArray(
    np.array([[0.0, 1.0, 2.0], [1.0, 2.0, 3.0], [2.0, 3.0, 4.0]]),
    dims=("y", "x"),
    coords={"x": [0.0, 1.0, 2.0], "y": [2.0, 1.0, 0.0]},
)
bands = isobands(data, levels=[1.5, 2.5], crs="EPSG:4326")
print(bands[["min_value", "max_value", "geometry"]])

The result always has the stable min_value, max_value, and geometry columns and a GeoPandas CRS. Exactly one of levels or interval is required. Use levels for strictly increasing interior thresholds, or interval for integral thresholds. Values equal to a threshold belong to the upper band.

Compatibility APIs

isobands() is the stable convenience API. Its min_value/max_value/geometry schema and finite interior-threshold semantics remain unchanged.

Use gdal_fixed_level_polygons() when a workflow needs native gdal_contour -p -fl fixed-level output:

from isobands import gdal_fixed_level_polygons

native = gdal_fixed_level_polygons(
    data,
    levels=[0.0, 1.0, 2.0, 3.0, 4.0],
    crs="EPSG:4326",
)

It returns GDAL-style ID/floor/ceil/geometry features in native order without clipping or post-contour normalization. It uses GDAL's virtual in-memory GeoJSON output, not intermediate files. See the guide for its exact contract and limits.

Regular one-dimensional rectilinear coordinates are required, and coordinate names do not imply a CRS. Pass crs= explicitly when metadata is absent or ambiguous. Explicit finite nodata takes precedence over _FillValue and missing_value; otherwise nonfinite cells are excluded. Dask-backed arrays are materialized eagerly for GDAL's in-memory dataset. See the guide for usage examples and the API reference.

Real-world example

The runnable NOAA/NCEP example uses the pinned fixture in examples/data/, calls isobands with Kelvin levels and EPSG:4326, checks the schema, CRS, and geometry validity, and dissolves components with GeoPandas:

python examples/air_temperature.py

The ERA5 MapLibre example downloads the global daily high temperature for August 16, 2020, creates five-degree Celsius isobands, and writes GeoJSON for the accompanying era5_maplibre.html page. It requires a Copernicus Climate Data Store API key and the optional cdsapi, h5netcdf, and h5py packages.

Documentation

The hosted documentation is intended for palewi.re/docs/isobands/. The source is in docs/, with a single-page guide covering installation, quick start, the API reference, and the MapLibre example. Benchmarks and their reference data remain in benchmarks/.