<h2>DESCRIPTION</h2>

<em>v.distance</em> finds the nearest element in vector map (<b>to</b>)
for elements in vector map (<b>from</b>). 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. <b>dmin</b> and/or
<b>dmax</b> can be used to limit the search radius (in lat-long projects
to be given in meters since they are calculated as geodesic distances on
a sphere).

<p>
For lines to lines, say line A to line B, <em>v.distance</em> 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,
<em>v.distance</em> checks for intersections. In case of intersections,
the first intersection found is used and the distance set to zero.

<p>
For lines to areas, the distance is set to zero if a line is (partially)
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.

<p>
For areas to areas, the module checks first for overlap or if one area
is (partially) inside the other area. This is computationally quite
intensive. If the outer rings of the two areas do not overlap, the
distance 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.

<p>
For anything else than points to lines, there can be several common
locations with zero distance, and the common location would then be the
result of an overlay consisting of several points, lines, or areas.
<em>v.distance</em> selects in these cases a single point, and does
not create an overlay
like <em><a href="v.overlay.html">v.overlay</a></em>. 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 location. For speed reasons,
the distance is then set to zero and no further tests are done.

<h2>NOTES</h2>

If a nearest feature does not have a category, the attribute column is
updated to NULL.

<p>The upload <b>column</b>(s) must already exist. Create one with
<em><a href="v.db.addcolumn.html">v.db.addcolumn</a></em>.

<p>In lat-long projects <em>v.distance</em> gives distances
(<em>dist</em>, <em>from_along</em>, and <em>to_along</em>) not in
degrees but in meters calculated as geodesic distances on a sphere.

<p>
If one or both of the input vector maps are 3D, the user is notified
accordingly.

<p>The <em>-p</em> flag prints the results to standard output. By default the
output is in form of a linear matrix. If only only variable is upploaded and
a square matrix is desired, the user can set the <em>-s</em> flag.

<h2>EXAMPLES</h2>

<h3>Find nearest lines</h3>

Find <em>nearest lines</em> in vector map &quot;ln&quot; for points from
vector map &quot;pnt&quot; within the given threshold and write related
line categories to column &quot;linecat&quot; in an attribute table attached
to vector map &quot;pnt&quot;:

<div class="code"><pre>
v.distance from=pnt to=ln upload=cat column=linecat
</pre></div>

<h3>Find nearest area</h3>

For each point from vector map &quot;pnt&quot;, find the <em>nearest area</em>
from map &quot;ar&quot; within the given threshold and write the related
area categories to column &quot;areacat&quot; in an attribute table attached
to vector map &quot;pnt&quot; (in the case that a point falls into an area,
the distance is zero):

<div class="code"><pre>
v.distance from=pnt to=ar upload=cat column=areacat
</pre></div>

<h3>Create a new vector map</h3>

Create a new vector map which contains <em>lines connecting nearest
features</em> of maps &quot;pnt&quot; and map &quot;ln&quot;. The resulting
vector map can be used for example to connect points to a network as
needed for network analysis:

<div class="code"><pre>
v.distance from=pnt to=ln out=connections upload=dist column=dist
</pre></div>

<h3>Create a new vector map with from and to categories in the attribute table</h3>

Create a new vector map that contains <em>lines connecting nearest
features</em> of maps &quot;pnt&quot; and map &quot;ln&quot;, and a new
attribute table that contains distances, from and to categories from the
input maps:

<div class="code"><pre>
v.distance from=pnt to=ln out=connections upload=cat,dist column=to_cat,dist table=connections
</pre></div>

<h3>Query information</h3>

Query information from selected point(s). <em>v.distance</em> 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.
<p>

Create query map (if not present):

<div class="code"><pre>
echo "123456|654321|1" | v.in.ascii output=pnt
</pre></div>

Find nearest features:

<div class="code"><pre>
v.distance -p from=pnt to=map_to_query upload=cat
</pre></div>

<h3>Point-in-polygon</h3>

The option <b>dmax=0</b> is here important because otherwise for
points not falling into any area, the category of the nearest area is
recorded.
<br>
For each point from vector map &quot;pnt&quot;, find the <em>area</em> from
vector map &quot;ar&quot; in which the individual point falls, and
write the related area categories to column &quot;areacat&quot; into
the attribute table attached to vector map &quot;pnt&quot;:

<div class="code"><pre>
v.distance from=pnt to=ar dmax=0 upload=cat column=areacat
</pre></div>

<h3>Univariate statistics on results</h3>

Create a vector map containing connecting lines and investigate mean
distance to targets. An alternative solution is to use
the <code>v.distance upload=dist</code> option to upload distances into
the <i>bugs</i> vector directly, then run v.univar on that. Also note
you can upload two columns at a time, e.g. <code>v.distance
upload=cat,dist column=nearest_id,dist_to_nr</code>.

<div class="code"><pre>
# 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
</pre></div>

<h3>Print distance between points</h3>

Example for a Latitude-longitude project (EPSG 4326):
<div class="code"><pre>
# 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
</pre></div>

<h3>Print distance matrix</h3>

North Carolina sample data

<p>As linear matrix:
<div class="code"><pre>
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
</pre></div>

<p>As square matrix (only possible with single upload option):
<div class="code"><pre>
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 ...
...
</pre></div>

<h2>SEE ALSO</h2>

<em>
<a href="r.distance.html">r.distance</a>,
<a href="v.db.addcolumn.html">v.db.addcolumn</a>,
<a href="v.what.vect.html">v.what.vect</a>
</em>

<h2>AUTHORS</h2>

Janne Soimasuo 1994, University of Joensuu, Faculty of Forestry, Finland<br>
Cmd line coordinates support: Markus Neteler, ITC-irst, Trento, Italy<br>
Updated for 5.1: Radim Blazek, ITC-irst, Trento, Italy<br>
Matrix-like output by Martin Landa, FBK-irst, Trento, Italy<br>
Improved processing speed: Markus Metz<br>
Distance from any feature to any feature: Markus Metz<br>
New table without the -p flag: Huidae Cho
Make linear matrix the default for all outputs: Moritz Lennert