.TH v.distance 1grass "" "GRASS 6.4.4" "Grass User's Manual"
.SH NAME
\fI\fBv.distance\fR\fR  - Finds the nearest element in vector map 'to' for elements in vector map 'from'.
.SH KEYWORDS
vector, database, attribute table
.SH SYNOPSIS
\fBv.distance\fR
.br
\fBv.distance help\fR
.br
\fBv.distance\fR [\-\fBpa\fR] \fBfrom\fR=\fIname\fR \fBto\fR=\fIname\fR  [\fBfrom_type\fR=\fIstring\fR[,\fIstring\fR,...]]   [\fBto_type\fR=\fIstring\fR[,\fIstring\fR,...]]   [\fBfrom_layer\fR=\fIinteger\fR]   [\fBto_layer\fR=\fIinteger\fR]   [\fBoutput\fR=\fIname\fR]   [\fBdmax\fR=\fIfloat\fR]   [\fBdmin\fR=\fIfloat\fR]  \fBupload\fR=\fIstring\fR[,\fIstring\fR,...] \fBcolumn\fR=\fIname\fR[,\fIname\fR,...]  [\fBto_column\fR=\fIname\fR]   [\fBtable\fR=\fIname\fR]   [\-\-\fBoverwrite\fR]  [\-\-\fBverbose\fR]  [\-\-\fBquiet\fR] 
.SS Flags:
.IP "\fB\-p\fR" 4m
.br
Print output to stdout, don't update attribute table
.br
First column is always category of 'from' feature called from_cat
.IP "\fB\-a\fR" 4m
.br
Calculate distances to all features within the threshold
.br
Output is written to stdout but may be uploaded to a new table created by this module; multiple 'upload' options may be used.
.IP "\fB\-\-overwrite\fR" 4m
.br
Allow output files to overwrite existing files
.IP "\fB\-\-verbose\fR" 4m
.br
Verbose module output
.IP "\fB\-\-quiet\fR" 4m
.br
Quiet module output
.PP
.SS Parameters:
.IP "\fBfrom\fR=\fIname\fR" 4m
.br
Name of existing vector map (from)
.IP "\fBto\fR=\fIname\fR" 4m
.br
Name of existing vector map (to)
.IP "\fBfrom_type\fR=\fIstring[,\fIstring\fR,...]\fR" 4m
.br
Feature type (from)
.br
Feature type
.br
Options: \fIpoint,centroid\fR
.br
Default: \fIpoint\fR
.IP "\fBto_type\fR=\fIstring[,\fIstring\fR,...]\fR" 4m
.br
Feature type (to)
.br
Feature type
.br
Options: \fIpoint,line,boundary,centroid,area\fR
.br
Default: \fIpoint,line,area\fR
.IP "\fBfrom_layer\fR=\fIinteger\fR" 4m
.br
Layer number (from)
.br
A single vector map can be connected to multiple database tables. This number determines which table to use.
.br
Default: \fI1\fR
.IP "\fBto_layer\fR=\fIinteger\fR" 4m
.br
Layer number (to)
.br
A single vector map can be connected to multiple database tables. This number determines which table to use.
.br
Default: \fI1\fR
.IP "\fBoutput\fR=\fIname\fR" 4m
.br
Name for output vector map containing lines connecting nearest elements
.IP "\fBdmax\fR=\fIfloat\fR" 4m
.br
Maximum distance or -1 for no limit
.br
Default: \fI-1\fR
.IP "\fBdmin\fR=\fIfloat\fR" 4m
.br
Minimum distance or -1 for no limit
.br
Default: \fI-1\fR
.IP "\fBupload\fR=\fIstring[,\fIstring\fR,...]\fR" 4m
.br
Values describing the relation between two nearest features
.br
Options: \fIcat,dist,to_x,to_y,to_along,to_angle,to_attr\fR
.br
\fBcat\fR: category of the nearest feature
.br
\fBdist\fR: minimum distance to nearest feature
.br
\fBto_x\fR: x coordinate of the nearest point on the 'to' feature
.br
\fBto_y\fR: y coordinate of the nearest point on the 'to' feature
.br
\fBto_along\fR: distance to the nearest point on the 'to' feature along that linear feature
.br
\fBto_angle\fR: angle along the nearest linear feature in the 'to' map, measured CCW from the +x axis, in radians, between -Pi and Pi inclusive
.br
\fBto_attr\fR: attribute of nearest feature given by to_column option
.IP "\fBcolumn\fR=\fIname[,\fIname\fR,...]\fR" 4m
.br
Column name(s) where values specified by 'upload' option will be uploaded
.IP "\fBto_column\fR=\fIname\fR" 4m
.br
Column name of nearest feature (used with upload=to_attr)
.IP "\fBtable\fR=\fIname\fR" 4m
.br
Name of table created when the 'distance to all' flag is used
.PP
.SH DESCRIPTION
\fIv.distance\fR finds the nearest element in vector map
(\fIto\fR) for elements in vector map (\fIfrom\fR). Various
information about the vectors' relationships (distance, category, etc.) may be uploaded
to the attribute table attached to the first vector map, or printed to
\(cqstdout'.  A new vector map may be created where lines connecting
nearest points on features are written. \fIdmin\fR and/or \fIdmax\fR can be used to limit the search radius.
.SH NOTES
If a nearest feature does not have a category, the attribute column is updated
to \fInull\fR.  This is true also for areas, which means for example,
that if a point is in an island (area WITHOUT category), \fIv.distance\fR 
does not search for the nearest area WITH category; the island is identified 
as the nearest and category updated to null.
.PP
The upload \fIcolumn\fR(s) must already exist. Create one with \fIv.db.addcol\fR.
.PP
In lat-long locations \fIv.distance\fR gives distances (\fIdist\fR
and \fIto_along\fR) in meters not in degrees calculated as geodesic
distances on a sphere.
.SH EXAMPLES
.SS Find nearest lines
Find \fInearest lines\fR in vector map \fBln\fR for points from
vector map \fBpnt\fR within the given threshold and write related
line categories to column \fBlinecat\fR in an attribute table attached
to vector map \fBpnt\fR:
\fC
.DS
.br
v.distance from=pnt to=ln upload=cat column=linecat
.br
.DE
\fR
.SS Find nearest area
For each point from vector map \fBpnt\fR, find the \fInearest area\fR
from map \fBar\fR within the given threshold and write the related
area categories to column \fBareacat\fR in an attribute table attached
to vector map \fBpnt\fR (in the case that a point falls into a polygon area,
the distance is zero):
\fC
.DS
.br
v.distance from=pnt to=ar upload=cat column=areacat
.br
.DE
\fR
.SS Create a new vector map
Create a new vector map which contains \fIlines connecting nearest
features\fR of maps \fBpnt\fR and map \fBln\fR. The resulting
vector map can be used for example to connect points to a network as
needed for network analysis:
\fC
.DS
.br
v.distance \-p from=pnt to=ln out=connections upload=dist column=dist
.br
.DE
\fR
.SS Query information
Query information from selected point(s). \fIv.distance\fR takes
points from a vector map as input instead of stdin. A new vector map
with query points has to be created before the map can be analysed.
.PP
Create query map (if not present):
\fC
.DS
.br
echo "123456|654321|1" | v.in.ascii output=pnt
.br
.DE
\fR
Find nearest features:
\fC
.DS
.br
v.distance from=pnt to=map_to_query upload=cat col=somecol \-p
.br
.DE
\fR
.SS Point-in-polygon
The option \fIdmax=0\fR is here important because otherwise for
points not falling into any area, the category of the nearest area is
recorded.
.br
For each point from vector map \fBpnt\fR, find the \fIarea\fR from
vector map \fBar\fR in which the individual point falls, and
write the related area categories to column \fBareacat\fR into
the attribute table attached to vector map \fBpnt\fR:
\fC
.DS
.br
v.distance from=pnt to=ar dmax=0 upload=cat column=areacat
.br
.DE
\fR
.SS Univariate statistics on results
Create a vector map containing connecting lines and investigate mean
distance to targets. An alternative solution is to use
the v.distance upload=dist option to upload distances into
the \fIbugs\fR vector directly, then run v.univar on that. Also note
you can upload two columns at a time, e.g. v.distance
upload=cat,dist column=nearest_id,dist_to_nr.
\fC
.DS
.br
# create working copy
.br
g.copy vect=bugsites,bugs
.br
.br
# add new attribute column to hold nearest archsite category number
.br
v.db.addcol map=bugs column="nrst_arch INTEGER"
.br
.br
v.distance from=bugs to=archsites to_type=point upload=to_attr \(rs
.br
  to_column=cat column=nrst_arch out=vdistance_vectors_raw
.br
.br
# we need to give the lines category numbers, create a table, and create
.br
#  a column in that table to hold the distance data.
.br
v.category vdistance_vectors_raw out=vdistance_vectors type=line op=add
.br
g.remove v=vdistance_vectors_raw
.br
.br
v.db.addtable map=vdistance_vectors column="length DOUBLE"
.br
v.to.db map=vdistance_vectors option=length column=length
.br
.br
# calculcate statistics. Use v.univar.sh for extended statistics.
.br
v.univar vdistance_vectors column=length
.br
.DE
\fR
.SS Print distance matrix
\fC
.DS
.br
v.distance \-pa from=archsites to=archsites upload=dist col=dist
.br
.DE
\fR
Note: Matrix-like output is enabled only for flag \fI-a\fR and one
given upload option.
.SH SEE ALSO
\fI
r.distance,
v.db.addcol,
v.what.vect
\fR
.SH AUTHOR
Janne Soimasuo 1994, University of Joensuu, Faculty of Forestry, Finland
.br
Cmd line coordinates support: Markus Neteler, ITC-irst, Trento, Italy
.br
Updated for 5.1: Radim Blazek, ITC-irst, Trento, Italy
.br
Martix-like output by Martin Landa, FBK-irst, Trento, Italy
.PP
\fILast changed: $Date: 2011-11-08 12:29:50 +0100 (Tue, 08 Nov 2011) $\fR
.PP
Full index
.PP
© 2003-2014 GRASS Development Team