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]   [--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
           Default: :

       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

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)

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

       © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual