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 intersection found is used and the distance set to zero.
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.
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.
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. 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 location. For speed reasons, the distance is then set to zero and no further tests are done.
The upload column(s) must already exist. Create one with v.db.addcolumn.
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.
The -p 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 -s flag.
v.distance from=pnt to=ln upload=cat column=linecat
v.distance from=pnt to=ar upload=cat column=areacat
v.distance from=pnt to=ln out=connections upload=dist column=dist
v.distance from=pnt to=ln out=connections upload=cat,dist column=to_cat,dist table=connections
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
v.distance from=pnt to=ar dmax=0 upload=cat column=areacat
# 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
# 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
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 ... ...