xrspatial.bilateral.bilateral#

xrspatial.bilateral.bilateral(agg, sigma_spatial=1.0, sigma_range=10.0, name='bilateral', boundary='nan')[source]#

Apply a bilateral filter for feature-preserving smoothing.

Smooths a raster while preserving edges. Each pixel is replaced by a weighted average of its neighbours, where the weight depends on both the spatial distance and the value difference between the neighbour and the center pixel. Neighbours that are far away or very different in value contribute little, so edges stay sharp.

Parameters:

  • agg (xarray.DataArray or xr.Dataset) – 2D (or 3D multi-band) array of input values. Supports NumPy, CuPy, Dask+NumPy, and Dask+CuPy backends.

  • sigma_spatial (float, default 1.0) – Standard deviation of the spatial Gaussian. Controls the size of the neighbourhood: kernel radius = ceil(2 * sigma_spatial). Must be at least sqrt(np.finfo(float64).tiny) (~1.49e-154) so that 2 * sigma_spatial**2 does not underflow to a denormal and turn the Gaussian weight into NaN.

  • sigma_range (float, default 10.0) – Standard deviation of the range (value-similarity) Gaussian. Larger values allow more smoothing across value differences; smaller values preserve more edges. Same lower bound as sigma_spatial.

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

  • boundary (str, default 'nan') – How to handle edges where the kernel extends beyond the raster. 'nan' – fill missing neighbours with NaN (default). 'nearest' – repeat edge values. 'reflect' – mirror at boundary. 'wrap' – periodic / toroidal.

Returns:

out – Filtered array of the same shape, dtype, dims, and coords as the input.

Return type:

xarray.DataArray or xr.Dataset

Examples

>>> import numpy as np
>>> import xarray as xr
>>> from xrspatial import bilateral
>>> data = np.array([
...     [0., 0., 0., 100., 100.],
...     [0., 0., 0., 100., 100.],
...     [0., 0., 0., 100., 100.],
...     [0., 0., 0., 100., 100.],
...     [0., 0., 0., 100., 100.]])
>>> raster = xr.DataArray(data)
>>> smoothed = bilateral(raster, sigma_spatial=1.0, sigma_range=5.0)

References

Tomasi & Manduchi, “Bilateral Filtering for Gray and Color Images,” ICCV 1998.