r.distance(1)

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

KEYWORDS
raster, distance

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

  Flags:

-l
    Include category labels in the output

-o
    Report zero distance if rasters are overlapping

-n
    Report null objects as *

--help
    Print usage summary

--verbose
    Verbose module output

--quiet
    Quiet module output

--ui
    Force launching GUI dialog

  Parameters:

map=name1,name2[,name1,name2,...] [required]
    Name of two input raster maps for computing inter-class distances

separator=character
    Field separator
    Special characters: pipe, comma, space, tab, newline

sort=string
    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

format=name [required]
    Output format
    Options: plain, csv, json
    Default: plain
    plain: Human readable text output
    csv: CSV (Comma Separated Values)
    json: JSON (JavaScript Object Notation)

DESCRIPTION
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:

cat1:cat2:distance:east1:north1:east2:north2

cat1
    Category number from map1

cat2
    Category number from map2

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

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

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

  Flags
-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.

NOTES
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 v.in.ascii:

r.distance map=map1,map2 | \
  awk -F: ’{print $4,$5}’ | v.in.ascii format=point output=name separator=space

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

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

SOURCE CODE

Available at: r.distance source code (history)

Latest change: Saturday Oct 11 04:38:40 2025 in commit: 3dd71f5fab83b72a2db2da959fe075c5b3b52200

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

© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual