DESCRIPTION
v.distance finds the nearest element in vector map
(to) for elements in vector map (from). 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
'stdout'. A new vector map may be created where lines connecting
nearest points on features are written. dmin and/or dmax can be used to limit the search radius.
NOTES
If a nearest feature does not have a category, the attribute column is updated
to null. This is true also for areas, which means for example,
that if a point is in an island (area WITHOUT category), v.distance
does not search for the nearest area WITH category; the island is identified
as the nearest and category updated to null.
The upload column(s) must already exist. Create one with v.db.addcol.
In lat-long locations v.distance gives distances (dist
and to_along) in meters not in degrees calculated as geodesic
distances on a sphere.
EXAMPLES
Find nearest lines
Find nearest lines in vector map ln for points from
vector map pnt within the given threshold and write related
line categories to column linecat in an attribute table attached
to vector map pnt:
v.distance from=pnt to=ln upload=cat column=linecat
Find nearest area
For each point from vector map pnt, find the nearest area
from map ar within the given threshold and write the related
area categories to column areacat in an attribute table attached
to vector map pnt (in the case that a point falls into a polygon area,
the distance is zero):
v.distance from=pnt to=ar upload=cat column=areacat
Create a new vector map
Create a new vector map which contains lines connecting nearest
features of maps pnt and map ln. The resulting
vector map can be used for example to connect points to a network as
needed for network analysis:
v.distance -p from=pnt to=ln out=connections upload=dist column=dist
Query information
Query information from selected point(s). v.distance 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.
Create query map (if not present):
echo "123456|654321|1" | v.in.ascii output=pnt
Find nearest features:
v.distance from=pnt to=map_to_query upload=cat col=somecol -p
Point-in-polygon
The option dmax=0 is here important because otherwise for
points not falling into any area, the category of the nearest area is
recorded.
For each point from vector map pnt, find the area from
vector map ar in which the individual point falls, and
write the related area categories to column areacat into
the attribute table attached to vector map pnt:
v.distance from=pnt to=ar dmax=0 upload=cat column=areacat
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 bugs 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.
# create working copy
g.copy vect=bugsites,bugs
# add new attribute column to hold nearest archsite category number
v.db.addcol map=bugs column="nrst_arch INTEGER"
v.distance from=bugs to=archsites to_type=point upload=to_attr \
to_column=cat column=nrst_arch out=vdistance_vectors_raw
# we need to give the lines category numbers, create a table, and create
# a column in that table to hold the distance data.
v.category vdistance_vectors_raw out=vdistance_vectors type=line op=add
g.remove v=vdistance_vectors_raw
v.db.addtable map=vdistance_vectors column="length DOUBLE"
v.to.db map=vdistance_vectors option=length column=length
# calculcate statistics. Use v.univar.sh for extended statistics.
v.univar vdistance_vectors column=length
Print distance matrix
v.distance -pa from=archsites to=archsites upload=dist col=dist
Note: Matrix-like output is enabled only for flag -a and one
given upload option.
SEE ALSO
r.distance,
v.db.addcol,
v.what.vect
AUTHOR
Janne Soimasuo 1994, University of Joensuu, Faculty of Forestry, Finland
Cmd line coordinates support: Markus Neteler, ITC-irst, Trento, Italy
Updated for 5.1: Radim Blazek, ITC-irst, Trento, Italy
Martix-like output by Martin Landa, FBK-irst, Trento, Italy
Last changed: $Date$