Scroll to navigation

r.distance(1grass) GRASS GIS User's Manual r.distance(1grass)


r.distance - Locates the closest points between objects in two raster maps.


raster, distance


r.distance --help
r.distance [-lon] map=name1,name2[,name1,name2,...] [separator=character] [sort=string] [--help] [--verbose] [--quiet] [--ui]


Include category labels in the output

Report zero distance if rasters are overlapping

Report null objects as *

Print usage summary

Verbose module output

Quiet module output

Force launching GUI dialog


Name of two input raster maps for computing inter-class distances

Field separator
Special characters: pipe, comma, space, tab, newline
Default: :

Sort output by distance
Default: sorted by categories
Options: asc, desc
asc: Sort by distance in ascending order
desc: Sort by distance in descending order


r.distance locates the closest points between "objects" in two raster maps. An "object" is defined as all the grid cells that have the same category number, and closest means having the shortest "straight-line" distance. The cell centers are considered for the distance calculation (two adjacent grid cells have the distance between their cell centers).

The output is an ascii list, one line per pair of objects, in the following form:


Category number from map1

Category number from map2

The distance in meters between "cat1" and "cat2"

The coordinates of the grid cell "cat1" which is closest to "cat2"

The coordinates of the grid cell "cat2" which is closest to "cat1"


-l The -l flag outputs the category labels of the matched raster objects at the beginning of the line, if they exist.

-o The -o flag reports zero distance if the input rasters are overlapping.


The output format lends itself to filtering. For example, to "see" lines connecting each of the category pairs in two maps, filter the output using awk and then into d.graph:

r.distance map=map1,map2 | \

awk -F: ’{print "move",$4,$5,"\ndraw",$6,$7}’ | d.graph -m

To create a vector map of all the "map1" coordinates, filter the output into awk and then into

r.distance map=map1,map2 | \

awk -F: ’{print $4,$5}’ | format=point output=name separator=space


r.buffer, r.cost, r.drain, r.grow, r.grow.distance, v.distance


Michael Shapiro, U.S. Army Construction Engineering Research Laboratory


Available at: r.distance source code (history)

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2021 GRASS Development Team, GRASS GIS 7.8.6 Reference Manual

GRASS 7.8.6