r.distance - GRASS manual
Author: GRASS Development Team
Description: r.distance: Locates the closest points between objects in two raster maps.
Keywords: raster, distance

## 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)

Accessed: Monday May 11 17:54:03 2026

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

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual