Euclidean Distance

Draft: written, not yet checked by a person Operation · euclidean-distance

A raster giving, for every cell, the straight-line distance to the nearest target cell.

Pitfall. Engines disagree on what a target is (any cell with a value, any non-zero cell, or listed values), so a background of zeros instead of nodata can make every cell a target.

Pitfall. Some engines give distances in cells unless told to use the CRS's units.

Pitfall. In a geographic CRS the distance is in degrees unless the engine measures on the ellipsoid.

About this operation
Also called	proximity, distance raster, Euclidean Distance (Spatial Analyst), proximity raster, distance accumulation
Group	`raster/distance`
Checks	`crs.measure, raster.nodata`
Pitfalls	3 listed above
Columbus tool	Not stated
Notes	Not stated
Status	active
Broader	Not stated
Narrower	Not stated
Related	`buffer` `nearest-join`

Parameters

Not stated

Inputs and outputs

Direction	Name	Type	Geometry	Note
Input	`raster`	raster	Not stated	Target cells hold a value; every other cell is nodata.
Output	`output`	raster	Not stated	Not stated

In each engine

Engine	Tool	Parameters	Differences
`gdal`	`gdal raster proximity`	`raster` → `input` `output` → `output`	Targets are non-zero cells unless target-values lists them; nodata cells are not zero, so on a background of nodata every cell is a target (all distances 0), and with target values listed the background cells get 65535 instead of a distance: give the background as 0. Distances are in cells unless distance-units is geo (set by this mapping). Preset: `{"distance-units":"geo"}`
`grass`	`r.grow.distance`	`raster` → `input` `output` → `distance`	Targets are all cells that are not NULL, zeros included: on a background of 0 every cell is a target. metric also offers squared, maximum, Manhattan and geodesic distances.
`qgis`	`gdal:proximity`	`raster` → `INPUT` `output` → `OUTPUT`	Runs GDAL's proximity. Targets are non-zero cells unless VALUES lists them; nodata cells are not zero, so on a background of nodata every cell is a target (all distances 0), and with target values listed the background cells get 65535 instead of a distance: give the background as 0. UNITS 1 (the default) gives distances in cells, 0 in the CRS's units (set by this mapping). Preset: `{"UNITS":0}`
`terra`	`terra::distance`	`raster` → `x`	Targets are cells that are not NA, so on a background of 0 every cell is a target unless target = 0 names the background; distances are in metres, unit can change that. Longitude/latitude rasters are measured on the ellipsoid.
`whiteboxtools`	`EuclideanDistance`	`raster` → `input` `output` → `output`	Targets are cells with a value greater than zero; cells that are nodata in the input stay nodata in the output, so give the background as 0.
`xarray-spatial`	`xrspatial.proximity`	`raster` → `raster`	Takes an xarray DataArray; targets are non-zero cells unless target_values lists them. distance_metric also offers Great Circle and Manhattan.