xrspatial.resample.resample#

xrspatial.resample.resample(agg: DataArray, scale_factor: float | tuple[float, float] | None = None, target_resolution: float | tuple[float, float] | None = None, method: str = 'nearest', nodata: float | None = None, name: str = 'resample') → DataArray[source]#

Change raster resolution without changing its CRS.

Exactly one of scale_factor or target_resolution must be given.

Parameters:

  • agg (xarray.DataArray or xarray.Dataset) – Input raster. 2-D (y, x) or 3-D (band, y, x). For 3-D inputs each band is resampled independently and the leading non-spatial coordinate is preserved. If a Dataset is passed, the operation is applied to each data variable independently (via the @supports_dataset decorator).

  • scale_factor (float or (float, float), optional) – Multiplicative factor applied to the number of pixels. 0.5 halves the pixel count (doubles the cell size); 2.0 doubles the pixel count (halves the cell size). A two-element tuple sets (scale_y, scale_x) independently.

  • target_resolution (float or (float, float), optional) – Desired cell size in the same units as the raster coordinates. A scalar sets both axes to the same resolution; a 2-tuple sets (res_y, res_x) independently.

  • method (str, default 'nearest') – Resampling algorithm. Interpolation methods ('nearest', 'bilinear', 'cubic') work for both upsampling and downsampling. Aggregation methods ('average', 'min', 'max', 'median', 'mode') only support downsampling (scale_factor <= 1).

  • nodata (float, optional) – Sentinel value in the input that should be treated as missing. Input pixels equal to nodata are replaced with NaN before resampling. When None, falls back to agg.attrs['_FillValue'] then agg.attrs['nodata']. The output uses NaN as the sentinel regardless of the input convention.

  • name (str, default 'resample') – Name for the output DataArray.

Returns:

Resampled raster with updated coordinates and res attribute. Output dtype matches the input float dtype (float32 or float64); integer inputs return float32 since NaN-sentinel resampling requires a float type.

Return type:

xarray.DataArray

Raises:

ValueError – If agg has a zero-length spatial dimension; if neither or both of scale_factor and target_resolution are given; if either is a sequence whose length is not 2; if any component is zero, negative, NaN, or infinite; if method is not in ALL_METHODS; if the spatial coordinates of agg are not strictly monotonic and evenly spaced (resample only supports regular monotonic rasters); or if nodata does not round-trip exactly into an integer agg.dtype (a fractional or out-of-range sentinel that would wrap on the cast).