## NAME

v.distance - Find the nearest element in vector 'to' for elements in vector 'from'. Various information about this relation may be uploaded to the attribute table of input vector 'from' or printed to stdout.

## SYNOPSIS

v.distance
v.distance help
v.distance [-pa] from=string to=string [from_type=string[,string,...]] [to_type=string[,string,...]] [from_layer=integer] [to_layer=integer] [output=string] [dmax=float] upload=string[,string,...] column=string[,string,...] [table=string]

### 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. The output is written to stdout but may be uploaded to a new table created by this module. From categories are may be multiple.

### Parameters:

from=string
  Name of existing vector file.
to=string
  Name of existing vector file.
from_type=string[,string,...]
  From type
  Options: point,centroid
  Default: point
to_type=string[,string,...]
  To type
  Options: point,line,boundary,centroid,area
  Default: point,line,area
from_layer=integer
  From layer
  Default: 1
to_layer=integer
  To layer
  Default: 1
output=string
  New vector map containing lines connecting nearest elements
dmax=float
  Maximum distance or -1 for no limit.
  Default: -1
upload=string[,string,...]
  Values describing the relation between two nearest features:
  cat - category of the nearest feature
  dist - minimum distance to nearest feature
  to_x - x coordinate of the nearest point on 'to' feature
  to_y - y coordinate of the nearest point on 'to' feature
  to_along - distance to the nearest point on 'from' feature along linear feature
  to_angle - angle of linear feature in nearest point, counterclockwise from positive x axis, in radians, which is between -PI and PI inclusive.
  Options: cat,dist,to_x,to_y,to_along,to_angle
column=string[,string,...]
  Column name(s) where values specified by 'upload' option will be uploaded
table=string
  The name of the table created for output when -a flag is used

## DESCRIPTION

v.distance finds features from one vector (from=) feature to another vector (to=) nearest feature. Various information about relation (distance, ...) may be uploaded to attribute table attached to first vector map or printed to 'stdout'. A new vector map may be created where lines connecting nearest points on features are written.

## EXAMPLES

1) 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 attribute table attached to vector map pnt:
`v.distance from=pnt to=ln upload=cat column=linecat`

2) For each point from vector map pnt find nearest area from map ar within the given threshold and write the related area categories to column areacat in attribute table attached to vector map pnt. In case a point falls into a polygon area, the distance is zero:
`v.distance from=pnt to=ar upload=cat column=areacat`

3) 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`

4) Query information from selected point(s). v.distance takes points from vector as input instead of stdin. First new vector map with query points, has to be created, then 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`

5) Point-in-polygon: Find area from vector map ar for each point from vector map pnt in which the individual point falls into and write the related area categories to column areacat into attribute table attached to vector map pnt:
`v.distance from=pnt to=ar max=0 upload=cat column=areacat`

## NOTES

If a nearest feature does not have a category, column is updated to null. This is true also for areas, which means for example, that if point is in island (area WITHOUT category), v.distance does not search for nearest area WITH category, island is identified as nearest and category updated to null.

## SEE ALSO

r.distance

## AUTHOR

Janne Soimasuo 1994, Finland
University of Joensuu, Faculty of Forestry, Finland

5.0 cmd line coordinates support: Markus Neteler, ITC-irst, Trento, Italy

5.1 update Radim Blazek, ITC-irst, Trento, Italy

Last changed: $Date: 2004/03/16 14:47:22 $

Help Index