NAME¶
v.distance - Finds the nearest element in vector map 'to' for
elements in vector map 'from'.
KEYWORDS¶
vector, database, attribute table
SYNOPSIS¶
v.distance
v.distance help
v.distance [-
pa]
from=
name to=
name
[
from_type=
string[,
string,...]]
[
to_type=
string[,
string,...]]
[
from_layer=
integer] [
to_layer=
integer]
[
output=
name] [
dmax=
float]
[
dmin=
float]
upload=
string[,
string,...]
column=
name[,
name,...] [
to_column=
name]
[
table=
name] [--
overwrite] [--
verbose]
[--
quiet]
Flags:¶
- -p
-
Print output to stdout, don't update attribute table
First column is always category of 'from' feature called from_cat
- -a
-
Calculate distances to all features within the threshold
Output is written to stdout but may be uploaded to a new table created by
this module; multiple 'upload' options may be used.
- --overwrite
-
Allow output files to overwrite existing files
- --verbose
-
Verbose module output
- --quiet
-
Quiet module output
Parameters:¶
- from=name
-
Name of existing vector map (from)
- to=name
-
Name of existing vector map (to)
- from_type=string[,string,...]
-
Feature type (from)
Feature type
Options: point,centroid
Default: point
- to_type=string[,string,...]
-
Feature type (to)
Feature type
Options: point,line,boundary,centroid,area
Default: point,line,area
- from_layer=integer
-
Layer number (from)
A single vector map can be connected to multiple database tables. This
number determines which table to use.
Default: 1
- to_layer=integer
-
Layer number (to)
A single vector map can be connected to multiple database tables. This
number determines which table to use.
Default: 1
- output=name
-
Name for output vector map containing lines connecting nearest elements
- dmax=float
-
Maximum distance or -1 for no limit
Default: -1
- dmin=float
-
Minimum distance or -1 for no limit
Default: -1
- upload=string[,string,...]
-
Values describing the relation between two nearest features
Options: cat,dist,to_x,to_y,to_along,to_angle,to_attr
cat: category of the nearest feature
dist: minimum distance to nearest feature
to_x: x coordinate of the nearest point on the 'to' feature
to_y: y coordinate of the nearest point on the 'to' feature
to_along: distance to the nearest point on the 'to' feature along
that linear feature
to_angle: angle along the nearest linear feature in the 'to' map,
measured CCW from the +x axis, in radians, between -Pi and Pi inclusive
to_attr: attribute of nearest feature given by to_column option
- column=name[,name,...]
-
Column name(s) where values specified by 'upload' option will be
uploaded
- to_column=name
-
Column name of nearest feature (used with upload=to_attr)
- table=name
-
Name of table created when the 'distance to all' flag is used
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 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: 2011-11-08 12:29:50 +0100 (Tue, 08 Nov 2011) $
Full index
© 2003-2014 GRASS Development Team