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’ options may be used.

-s

Print output as square matrix (only possible for one single upload variable)

--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 access 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 access 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 elements

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,...] [required]

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 for new attribute table

separator=character

Field separator for printing output to stdout
Special characters: pipe, comma, space, tab, newline
Default: pipe

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

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¶

North Carolina sample data location

As linear matrix:

v.distance -pa from=hospitals to=hospitals upload=dist,to_attr to_column=NAME separator=tab
from_cat    to_cat  dist    to_attr
1   1   0   Cherry Hospital
1   2   7489.1043632983983  Wayne Memorial Hospital
1   3   339112.17046729225  Watauga Medical Center
1   4   70900.392145909267  Central Prison Hospital
1   5   70406.227393921712  Dorothea Dix Hospital

As square matrix (only possible with single upload option):

v.distance -pas 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 ...
...