.TH r.distance
.SH NAME
\fIr.distance\fR \- Locates the closest points between "objects" in two raster maps.
.br
.I "(GRASS Raster Program)"
.SH SYNOPSIS
\fBr.distance\fR
.br
\fBr.distance help\fR
.br
\fBr.distance\fR [\fB\-lq\fR] \fBmaps=\fImap1,map2\fR \fB[fs=\fIname]\fR
.SH DESCRIPTION
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 output is an ascii list, one line per pair of objects

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

.IP cat1
Category number from map1
.IP cat2
Category number from map2
.IP distance
The distance in meters between "cat1" and "cat2"
.IP east1,north1
The coordinates of the grid cell "cat1" which is closest to "cat2"
.IP east2,north2
The coordinates of the grid cell "cat2" which is closest to "cat1"

.SH "COMMAND LINE OPTIONS"
.LP
Flags
.IP \fI-l\fR
include category labels in the output
.IP \fI-q\fR
run quietly
.LP
Parameters
.IP \fImaps\fR
maps for computing inter-class distances
.IP \fIfs\fR
output field separator
.br
default is a colon (:)

.SH 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.mapgraph:

.nf
.ti +5
r.distance maps=map1,map2 | \e
.ti +10
awk -F':' '{print "move",$4,$5" draw",$6,$7}' | d.mapgraph
.fi

To create a site list of all the "map1" coordinates, filter the output
into awk and then into s.in.ascii:

.nf
.ti +5
r.distance maps=map1,map2 | \e
.ti +10
awk -F: '{print $4,$5}' | s.in.ascii sites=name
.fi
.SH "SEE ALSO"
r.buffer, r.cost, r.drain

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