rasterix.rasterize.core¶

Module Contents¶

rasterix.rasterize.core.rasterize(obj, geometries, *, engine=None, xdim='x', ydim='y', all_touched=False, merge_alg='replace', geoms_rechunk_size=None, clip=False, **engine_kwargs)[source]¶

Dask-aware rasterization of geometries.

Returns a 2D DataArray with integer codes for cells that are within the provided geometries.

Parameters:

objxr.Dataset or xr.DataArray: Xarray object whose grid to rasterize onto.
geometriesGeoDataFrame: Either a geopandas or dask_geopandas GeoDataFrame.
engine{“rasterio”, “rusterize”, “exactextract”} or None: Rasterization engine to use. If None, auto-detects based on installed packages (prefers rusterize if available, falls back to rasterio). Note: “exactextract” must be explicitly requested and is not auto-selected.
xdimstr: Name of the “x” dimension on obj.
ydimstr: Name of the “y” dimension on obj.
all_touchedbool: If True, all pixels touched by geometries will be burned in. If False, only pixels whose center is within the geometry are burned. Note: Not supported by rusterize or exactextract engines.
merge_algstr: Merge algorithm when geometries overlap. - “replace”: later geometries overwrite earlier ones - “add”: values are summed where geometries overlap The rusterize engine also accepts: “first”, “min”, “max”, “count”, “any”.
geoms_rechunk_sizeint or None: Size to rechunk the geometry array to after conversion from dataframe.
clipbool: If True, clip raster to the bounding box of the geometries. Ignored for dask-geopandas geometries.
**engine_kwargs: Additional keyword arguments passed to the engine. For rasterio: env (rasterio.Env for GDAL configuration).

Returns:

DataArray: 2D DataArray with geometries “burned in” as integer codes.

See also

rasterio.features.rasterize
rusterize.rusterize
exactextract.exact_extract

Notes

Different engines may produce slightly different results at pixel boundaries due to differences in how they handle geometry-pixel intersection tests:

rasterio: Uses GDAL’s rasterization. By default (all_touched=False), only pixels whose center falls within the geometry are burned. With all_touched=True, any pixel that intersects the geometry is burned. Requires GDAL.
rusterize: A Rust-based rasterization engine. Does not require GDAL.
exactextract: Uses the exactextract library for precise sub-pixel coverage computation. Any pixel with non-zero coverage is burned, which produces results equivalent to rasterio’s all_touched=True. Does not require GDAL. Does not support all_touched=True (raises NotImplementedError) since this is already its default behavior.

rasterix.rasterize.core.geometry_mask(obj, geometries, *, engine=None, xdim='x', ydim='y', all_touched=False, invert=False, geoms_rechunk_size=None, clip=False, **engine_kwargs)[source]¶

Dask-aware geometry masking.

Creates a boolean mask from geometries.

Parameters:

objxr.DataArray or xr.Dataset: Xarray object used to extract the grid.
geometriesGeoDataFrame or DaskGeoDataFrame: Geometries used for masking.
engine{“rasterio”, “rusterize”, “exactextract”} or None: Rasterization engine to use. If None, auto-detects based on installed packages (prefers rusterize if available, falls back to rasterio). Note: “exactextract” must be explicitly requested and is not auto-selected.
xdimstr: Name of the “x” dimension on obj.
ydimstr: Name of the “y” dimension on obj.
all_touchedbool: If True, all pixels touched by geometries will be included in mask. Note: Not supported by rusterize or exactextract engines.
invertbool: If True, pixels inside geometries are True (unmasked). If False (default), pixels inside geometries are False (masked).
geoms_rechunk_sizeint or None: Chunksize for geometry dimension of the output.
clipbool: If True, clip raster to the bounding box of the geometries. Ignored for dask-geopandas geometries.
**engine_kwargs: Additional keyword arguments passed to the engine. For rasterio: env (rasterio.Env for GDAL configuration).

Returns:

DataArray: 2D boolean DataArray mask.

See also

rasterize
rasterio.features.geometry_mask

Notes

See rasterize() for details on engine differences. The exactextract engine produces results equivalent to rasterio’s all_touched=True.

rasterix.rasterize.core.geometry_clip(obj, geometries, *, engine=None, xdim='x', ydim='y', all_touched=False, invert=False, geoms_rechunk_size=None, clip=True, **engine_kwargs)[source]¶

Dask-aware geometry clipping.

Clips an xarray object to geometries by masking values outside the geometries.

Parameters:

objxr.DataArray or xr.Dataset: Xarray object to clip.
geometriesGeoDataFrame or DaskGeoDataFrame: Geometries used for clipping.
engine{“rasterio”, “rusterize”, “exactextract”} or None: Rasterization engine to use. If None, auto-detects based on installed packages (prefers rusterize if available, falls back to rasterio). Note: “exactextract” must be explicitly requested and is not auto-selected.
xdimstr: Name of the “x” dimension on obj.
ydimstr: Name of the “y” dimension on obj.
all_touchedbool: If True, all pixels touched by geometries will be included. Note: Not supported by rusterize or exactextract engines.
invertbool: If True, preserve values outside the geometry (invert the clip). If False (default), preserve values inside the geometry.
geoms_rechunk_sizeint or None: Chunksize for geometry dimension of the output.
clipbool: If True, clip raster to the bounding box of the geometries. Ignored for dask-geopandas geometries.
**engine_kwargs: Additional keyword arguments passed to the engine. For rasterio: env (rasterio.Env for GDAL configuration).

Returns:

DataArray: Clipped DataArray with values outside geometries set to NaN.

See also

rasterize
geometry_mask
rasterio.features.geometry_mask

Notes

See rasterize() for details on engine differences. The exactextract engine produces results equivalent to rasterio’s all_touched=True, while rusterize may produce slightly different results at pixel boundaries.