xrspatial.surface_distance.surface_distance#

xrspatial.surface_distance.surface_distance(raster: DataArray, elevation: DataArray, x: str = 'x', y: str = 'y', target_values: list = [], max_distance: float = inf, connectivity: int = 8, method: str = 'planar') → DataArray[source]#

Compute surface distance along terrain to nearest target pixel.

For every pixel, computes the minimum accumulated distance along the 3D terrain surface to reach the nearest target pixel. Edge cost accounts for both horizontal distance and elevation change: sqrt(horizontal_dist^2 + dz^2).

Parameters:

  • raster (xr.DataArray or xr.Dataset) – 2-D source raster. Target pixels are identified by non-zero finite values (or values in target_values).

  • elevation (xr.DataArray) – 2-D elevation surface. Must have the same shape as raster. NaN marks impassable barriers.

  • x (str, default='x') – Name of the x coordinate.

  • y (str, default='y') – Name of the y coordinate.

  • target_values (list, optional) – Specific pixel values in raster to treat as sources. If empty, all non-zero finite pixels are sources.

  • max_distance (float, default=np.inf) – Maximum surface distance. Pixels beyond this budget are NaN. A finite value enables efficient Dask parallelisation.

  • connectivity (int, default=8) – Pixel connectivity: 4 (cardinal) or 8 (cardinal + diagonal).

  • method (str, default='planar') – 'planar' uses cell sizes in map units. 'geodesic' computes great-circle horizontal distances from lat/lon coordinates (elevation in meters).

Returns:

2-D array of surface distance values (float32). Source pixels have distance 0. Unreachable pixels are NaN.

Return type:

xr.DataArray or xr.Dataset