rasterix.rasterize.exact

Module Contents

rasterix.rasterize.exact.coverage(obj, geometries, *, xdim='x', ydim='y', strategy='feature-sequential', coverage_weight='fraction', clip=False)[source]

Calculate pixel coverage fractions for geometries using exactextract.

This function computes how much of each raster pixel is covered by each geometry, returning precise fractional coverage values or area measurements. It supports both in-memory and dask-based computation for large datasets.

Parameters:
objxarray.DataArray or xarray.Dataset

Xarray object defining the raster grid. If a grid mapping coordinate variable (e.g. spatial_ref) is present, it will be propagated to the output.

geometriesgeopandas.GeoDataFrame or dask_geopandas.GeoDataFrame

Vector geometries for which to calculate coverage. CRS should match the raster object (though this is not currently enforced).

xdimstr, default “x”

Name of the x (longitude/easting) dimension in the raster object.

ydimstr, default “y”

Name of the y (latitude/northing) dimension in the raster object.

strategy{“feature-sequential”, “raster-sequential”, “raster-parallel”}, default “feature-sequential”

Processing strategy passed to exactextract. Controls how computation is parallelized and memory is managed.

coverage_weight{“fraction”, “none”, “area_cartesian”, “area_spherical_m2”, “area_spherical_km2”}, default “fraction”

Type of coverage measurement to compute:

  • “fraction”: Fractional coverage (0-1)

  • “none”: Binary coverage (0 or 1)

  • “area_cartesian”: Area in map units squared

  • “area_spherical_m2”: Spherical area in square meters

  • “area_spherical_km2”: Spherical area in square kilometers

clip: bool

If True, clip raster to the bounding box of the geometries. Ignored for dask-geopandas geometries.

Returns:
xarray.DataArray

3D DataArray with dimensions (geometry, y, x) containing coverage values. Data type depends on coverage_weight: uint8 for “none”, float64 otherwise. Includes appropriate units and long_name attributes for area measurements.

Raises:
ValueError

If exactextract encounters chunks of size 1 (not supported by exactextract).

See also

exactextract.exact_extract

Underlying exactextract function used for coverage calculation

Examples

Calculate fractional coverage:

>>> import rasterix.rasterize.exact as exact
>>> import xarray as xr
>>> import geopandas as gpd
>>> # Load raster data with CRS info
>>> raster = xr.open_dataarray("data.tif")
>>> # Load vector geometries
>>> geometries = gpd.read_file("polygons.shp")
>>> # Calculate coverage fractions
>>> coverage = exact.coverage(raster, geometries)
>>> print(coverage.dims)  # ('geometry', 'y', 'x')

Calculate area in square meters:

>>> area_coverage = exact.coverage(raster, geometries, coverage_weight="area_spherical_m2")
>>> print(area_coverage.units)  # 'm2'