Provided by: grass-doc_7.0.3-1build1_all bug

NAME

       v.distance   -  Finds  the  nearest  element in vector map ’to’ for elements in vector map
       ’from’.

KEYWORDS

       vector, distance, database, attribute table

SYNOPSIS

       v.distance
       v.distance --help
       v.distance [-pa] from=name  [from_layer=string]   [from_type=string[,string,...]]  to=name
       [to_layer=string]       [to_type=string[,string,...]]      [output=name]      [dmax=float]
       [dmin=float]   upload=string[,string,...]    [column=name[,name,...]]     [to_column=name]
       [table=name]    [separator=character]    [--overwrite]   [--help]   [--verbose]  [--quiet]
       [--ui]

   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

       --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
           Default: -1

       dmin=float
           Minimum distance or -1 for no limit
           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 of table created when the ’distance to all’ flag is used

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

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.

       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.

NOTES

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

       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.

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 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 -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.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
       # 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|-61|1" | v.in.ascii output=pnt1 input=-
       echo "0|-58|1" | v.in.ascii output=pnt2 input=-
       # here, distances is in degree units
       v.distance from=pnt1 to=pnt2 upload=dist col=distance -p --q
       from_cat|distance
       1|3

   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 separator=comma
       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 ...
       ...

SEE ALSO

        r.distance, v.db.addcolumn, v.what.vect

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
       Matrix-like output by Martin Landa, FBK-irst, Trento, Italy
       Improved processing speed: Markus Metz
       Distance from any feature to any feature: Markus Metz

       Last changed: $Date: 2015-10-07 10:15:43 +0200 (Wed, 07 Oct 2015) $

       Main index | Vector index | Topics index | Keywords index | Full index

       © 2003-2016 GRASS Development Team, GRASS GIS 7.0.3 Reference Manual