Skip to content

Python API reference

rusterize.rusterize(data, like=None, res=None, out_shape=None, extent=None, field=None, by=None, burn=None, fun='last', background=np.nan, encoding='xarray', all_touched=False, tap=False, dtype='float64')

Parameters:

Name Type Description Default

data

(GeoDataFrame, GeoSeries, DataFrame, list, ndarray)

Input data to rasterize.

  • If polars.DataFrame, it must be have a "geometry" column with geometries stored in WKB or WKT format.
  • If list or numpy.ndarray, geometries must be in WKT, WKB, or shapely formats (EPSG is not inferred and defaults to None).
 required

like

xarray.DataArray or xarray.Dataset (default: None)

Template array used as a spatial blueprint (resolution, shape, extent). Mutually exclusive with res, out_shape, and extent. Requires xarray and rioxarray.

 None

res

tuple or list (default: None)

Pixel resolution defined as (xres, yres). Mutually exclusive with out_shape.

 None

out_shape

tuple or list (default: None)

Output raster dimensions defined as (nrows, ncols). Mutually exclusive with res.

 None

extent

`tuple` or `list` (default: None)

Spatial bounding box defined as (xmin, ymin, xmax, ymax).

 None

field

`str` (default: None)

Column name to use for pixel values. Mutually exclusive with burn. Not considered when input is list or numpy.ndarray.

 None

by

`str` (default: None)

Column used for grouping. Each group is rasterized into a distinct band in the output. Not considered when input is list or numpy.ndarray.

 None

burn

`int`, `float`, or `numpy.ndarray` (default: None)

A static value or a list of values to apply to each geometries. If a numpy.ndarray, it must match the length of the geometry data. Mutually exclusive with field. If burn is a numpy.ndarray, its dtype should match the output dtype, otherwise it is internally casted. If data is a geopandas.GeoSeries, its index is used as burn value, unless otherwise specified.

 None

fun

`str` (default: "last")

Pixel function to use when burning geometries. Available options: sum, first, last, min, max, count, or any.

 'last'

background

`int` or `float` (default: numpy.nan)

Value assigned to pixels not covered by any geometry.

 nan

encoding

`str` (default: "xarray")

The format of the returned object: "xarray", "numpy", or "sparse".

 'xarray'

all_touched

`bool` (default: False)

If True, every pixel touched by a geometry is burned.

 False

tap

`bool` (default: False)

Target Aligned Pixels: aligns the extent to the pixel resolution.

 False

dtype

`str` (default: "float64")

Output data type (e.g., uint8, int32, float32).

 'float64'

Returns:

Type Description
xarray.DataArray, numpy.ndarray, or a sparse array in COO format.
Notes

If encoding is "numpy" or input is list or numpy.ndarray, the return array is without any spatial reference.

When any of res, out_shape, or extent is not provided, it is inferred from the other arguments when applicable. If like is specified, res, out_shape, and extent are inferred from the like DataArray or Dataset. Unless extent is specified, a half-pixel buffer is applied to avoid missing points on the border. The logics dictating the final spatial properties of the rasterized geometries follow those of GDAL.

If field is not in data, then a default burn value of 1 is rasterized.

A None value for dtype corresponds to the default of that dtype. An illegal value for a dtype will be replaced with the default of that dtype. For example, a background=np.nan for dtype="uint8" will become background=0, where 0 is the default for uint8.

SparseArray

Returned when encoding="sparse". Currently, this internal structure holds the triplets of (band, row, col) values for each lazily burned pixel, thus avoiding to materialize a full array in memory. This is advantageous when you have large empty portions or want to save memory until you actually need it.

A SparseArray has the following converters:

  • to_xarray() → xarray.DataArray
  • to_numpy() → numpy.ndarray
  • to_frame() → polars.DataFrame