v.distance(1grass) GRASS GIS User's Manual v.distance(1grass)
NAME
v.distance - Finds the nearest element in vector map ’to’ for elements
in vector map ’from’.
KEYWORDS
vector, distance, database, attribute table
SYNOPSIS
v.distance
v.distance --help
v.distance [-pa] from=name [from_layer=string]
[from_type=string[,string,...]] to=name [to_layer=string]
[to_type=string[,string,...]] [output=name] [dmax=float]
[dmin=float] [upload=string[,string,...]] [column=name[,name,...]]
[to_column=name] [table=name] [separator=character] [--overwrite]
[--help] [--verbose] [--quiet] [--ui]
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 may be written to stdout using the ’-p’ flag or uploaded to
a new table created by the ’table’ option; multiple ’upload’ op-
tions may be used.
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog
Parameters:
from=name [required]
Name of existing vector map (from)
Or data source for direct OGR access
from_layer=string
Layer number or name (from)
Vector features can have category values in different layers. This
number determines which layer to use. When used with direct OGR ac-
cess this is the layer name.
Default: 1
from_type=string[,string,...]
Feature type (from)
Input feature type
Options: point, line, boundary, centroid, area
Default: point,line,area
to=name [required]
Name of existing vector map (to)
Or data source for direct OGR access
to_layer=string
Layer number or name (to)
Vector features can have category values in different layers. This
number determines which layer to use. When used with direct OGR ac-
cess this is the layer name.
Default: 1
to_type=string[,string,...]
Feature type (to)
Input feature type
Options: point, line, boundary, centroid, area
Default: point,line,area
output=name
Name for output vector map containing lines connecting nearest ele-
ments
dmax=float
Maximum distance or -1 for no limit
Map units, meters for ll
Default: -1
dmin=float
Minimum distance or -1 for no limit
Map units, meters for ll
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 in-
clusive
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 for new attribute table
separator=character
Field separator for printing output to stdout
Special characters: pipe, comma, space, tab, newline
Default: pipe
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 at-
tached 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
(in lat-long locations to be given in meters since they are calculated
as geodesic distances on a sphere).
For lines to lines, say line A to line B, v.distance calculates the
shortest distance of each vertex in A with each segment (not vertex) in
B. The module then calculates the shortest distance of each vertex in B
to each segment in A. The overall shortest distance of A points to B
segments and B points to A segments is used. Additionally, v.distance
checks for intersections. In case of intersections, the first intersec-
tion found is used and the distance set to zero.
For lines to areas, the distance is set to zero if a line is (par-
tially) inside an area. The first point of the line that is inside the
area is used as common point. The distance is also set to zero if the
line intersects with the outer ring or any of the inner rings (isles),
in which case the fist intersection is used as common point.
For areas to areas, the module checks first for overlap or if one area
is (partially) inside the other area. This is computationally quite in-
tensive. If the outer rings of the two areas do not overlap, the dis-
tance is calculated as above for lines to lines, treating the outer
rings as two lines. Again, the first point encountered falling into an
area is used as common point, or the first intersection point.
For anything else than points to lines, there can be several common lo-
cations with zero distance, and the common location would then be the
result of an overlay consisting of several points, lines, or areas.
v.distance selects in these cases a single point, and does not create
an overlay like v.overlay. In this implementation, any shared point is
as good as any other. Calculating an intersection is costlier than to
check if a vertex is inside a polygon. For example, if a vertex of the
boundary of the ’to’ area is inside the ’from’ area, it is a common lo-
cation. For speed reasons, the distance is then set to zero and no fur-
ther tests are done.
NOTES
If a nearest feature does not have a category, the attribute column is
updated to NULL.
The upload column(s) must already exist. Create one with v.db.addcol-
umn.
In lat-long locations v.distance gives distances (dist, from_along, and
to_along) not in degrees but in meters calculated as geodesic distances
on a sphere.
If one or both of the input vector maps are 3D, the user is notified
accordingly.
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 an 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 fea-
tures 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 analy-
sis:
v.distance from=pnt to=ln out=connections upload=dist column=dist
Create a new vector map with from and to categories in the attribute table
Create a new vector map that contains lines connecting nearest features
of maps "pnt" and map "ln", and a new attribute table that contains
distances, from and to categories from the input maps:
v.distance from=pnt to=ln out=connections upload=cat,dist column=to_cat,dist table=connections
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 -p from=pnt to=map_to_query upload=cat
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.addcolumn 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 -f type=vector name=vdistance_vectors_raw
v.db.addtable map=vdistance_vectors column="length DOUBLE"
v.to.db map=vdistance_vectors option=length column=length
# calculate statistics
v.univar vdistance_vectors column=length
Print distance between points
Example for a Latitude-longitude location (EPSG 4326):
# points along the equator
echo "0|-61|1" | v.in.ascii output=pnt1 input=-
echo "0|-58|1" | v.in.ascii output=pnt2 input=-
# here, distances are in degree units
v.distance -p --q from=pnt1 to=pnt2 upload=dist
from_cat|distance
1|3
Print distance matrix
Note: Matrix-style output is enabled only for flag -a and one given up-
load option.
Spearfish sample data location:
v.distance -pa from=archsites to=archsites upload=dist
North Carolina sample data location:
v.distance -pa from=hospitals to=hospitals upload=dist separator=tab
from_cat to_cat dist
1 2 3 4 5 ...
1 0 7489.10 339112.17 70900.39 70406.23 ...
2 7489.10 0 345749.12 76025.46 75538.87 ...
3 339112.17 345749.12 0 274153.19 274558.98 ...
4 70900.39 76025.46 274153.19 0 501.11 ...
5 70406.23 75538.87 274558.98 501.11 0 ...
...
SEE ALSO
r.distance, v.db.addcolumn, v.what.vect
AUTHORS
Janne Soimasuo 1994, University of Joensuu, Faculty of Forestry, Fin-
land
Cmd line coordinates support: Markus Neteler, ITC-irst, Trento, Italy
Updated for 5.1: Radim Blazek, ITC-irst, Trento, Italy
Matrix-like output by Martin Landa, FBK-irst, Trento, Italy
Improved processing speed: Markus Metz
Distance from any feature to any feature: Markus Metz
New table without the -p flag: Huidae Cho
SOURCE CODE
Available at: v.distance source code (history)
Accessed: unknown
Main index | Vector index | Topics index | Keywords index | Graphical
index | Full index
© 2003-2022 GRASS Development Team, GRASS GIS 7.8.7 Reference Manual
GRASS 7.8.7 v.distance(1grass)
Generated by dwww version 1.14 on Sat Dec 21 09:40:01 CET 2024.