Skip to content

r.distance

Locates the closest points between objects in two raster maps.

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

Example:

r.distance map=name1,name2 format=plain

grass.script.parse_command("r.distance", map, separator=None, sort=None, format="plain", flags=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.parse_command("r.distance", map="name1,name2", format="json")

grass.tools.Tools.r_distance(map, separator=None, sort=None, format="plain", flags=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.r_distance(map="name1,name2", format="json")

This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

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
    Allowed values: asc, desc
    asc: Sort by distance in ascending order
    desc: Sort by distance in descending order
format=name [required]
    Output format
    Allowed values: plain, csv, json
    Default: plain
    plain: Human readable text output
    csv: CSV (Comma Separated Values)
    json: JSON (JavaScript Object Notation)
-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
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

map : list[tuple[str, str]] | tuple[str, str] | list[str] | str, required
    Name of two input raster maps for computing inter-class distances
    Used as: input, raster, name1,name2
separator : str, optional
    Field separator
    Special characters: pipe, comma, space, tab, newline
    Used as: input, separator, character
sort : str, optional
    Sort output by distance
    Default: sorted by categories
    Allowed values: asc, desc
    asc: Sort by distance in ascending order
    desc: Sort by distance in descending order
format : str, required
    Output format
    Used as: name
    Allowed values: plain, csv, json
    plain: Human readable text output
    csv: CSV (Comma Separated Values)
    json: JSON (JavaScript Object Notation)
    Default: plain
flags : str, optional
    Allowed values: l, o, n
    l
        Include category labels in the output
    o
        Report zero distance if rasters are overlapping
    n
        Report null objects as *
verbose: bool, optional
    Verbose module output
    Default: None
quiet: bool, optional
    Quiet module output
    Default: None
superquiet: bool, optional
    Very quiet module output
    Default: None

map : list[tuple[str, str]] | tuple[str, str] | list[str] | str, required
    Name of two input raster maps for computing inter-class distances
    Used as: input, raster, name1,name2
separator : str, optional
    Field separator
    Special characters: pipe, comma, space, tab, newline
    Used as: input, separator, character
sort : str, optional
    Sort output by distance
    Default: sorted by categories
    Allowed values: asc, desc
    asc: Sort by distance in ascending order
    desc: Sort by distance in descending order
format : str, required
    Output format
    Used as: name
    Allowed values: plain, csv, json
    plain: Human readable text output
    csv: CSV (Comma Separated Values)
    json: JSON (JavaScript Object Notation)
    Default: plain
flags : str, optional
    Allowed values: l, o, n
    l
        Include category labels in the output
    o
        Report zero distance if rasters are overlapping
    n
        Report null objects as *
verbose: bool, optional
    Verbose module output
    Default: None
quiet: bool, optional
    Quiet module output
    Default: None
superquiet: bool, optional
    Very quiet module output
    Default: None

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:

from_category:to_category:distance:from_easting:from_northing:to_easting:to_northing

from_category
Category number from map1

to_category
Category number from map2

distance
The distance in meters between "from_category" and "to_category"

from_easting,from_northing
The coordinates of the grid cell "from_category" which is closest to "to_category"

to_easting,to_northing
The coordinates of the grid cell "to_category" which is closest to "from_category"

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

EXAMPLES

Using JSON output with Pandas to locate closest points

import pandas as pd
import grass.script as gs

result = gs.parse_command(
    "r.distance", map=["zipcodes", "lakes"], flags="l", format="json"
)
df = pd.json_normalize(result)
print(df)

Possible output:

        distance  from_cell.category  from_cell.easting  from_cell.northing from_cell.label  to_cell.category  to_cell.easting  to_cell.northing to_cell.label
0   11158.870911               27511             632605              223295            CARY             34300           640585            215495      Dam/Weir
1    1037.304198               27511             631735              222695            CARY             39000           632315            221835     Lake/Pond
2    2277.059507               27511             630015              221605            CARY             43600           630765            219455     Reservoir
..           ...                 ...                ...                 ...             ...               ...              ...               ...           ...
36   4922.600939               27610             642975              219815         RALEIGH             34300           640615            215495      Dam/Weir
37     50.000000               27610             642655              222765         RALEIGH             39000           642705            222765     Lake/Pond
38  11368.069317               27610             642305              220945         RALEIGH             43600           631035            219455     Reservoir

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: Tuesday Aug 19 00:42:36 2025 in commit 638c4f2