GRASS GIS manual: v.distance

Note: A new GRASS GIS stable version has been released: GRASS GIS 7. Go directly to the new manual page here

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

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 between points

Example for a Latitude-longitude location (EPSG 4326):

# points along the equator
echo "0|-60|1" | v.in.ascii output=pnt1
echo "0|-59|1" | v.in.ascii output=pnt2

v.distance from=pnt1 to=pnt2 upload=dist col=distance -p --q
from_cat|distance
1|111403.734218

Print distance matrix

Note: Matrix-style output is enabled only for flag -a and one given upload option.

Spearfish sample data location:

v.distance -pa from=archsites to=archsites upload=dist col=dist

North Carolina sample data location:

v.distance -pa from=hospitals to=hospitals upload=dist col=dist

AUTHORS

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: 2014-08-25 22:42:30 -0700 (Mon, 25 Aug 2014) $

Main index - vector index - Full index