1v.distance(1) Grass User's Manual v.distance(1)
2
6 v.distance - Finds the nearest element in vector 'to' for elements in
7 vector 'from'. Various information about this relation may be uploaded
8 to the attribute table of input vector 'from' or printed to stdout.
9
11 vector, database, attribute table
12
14 v.distance
15 v.distance help
16 v.distance [-pa] from=name to=name [from_type=string[,string,...]]
17 [to_type=string[,string,...]] [from_layer=integer] [to_layer=inte‐
18 ger] [output=name] [dmax=float] upload=string[,string,...] col‐
19 umn=name[,name,...] [to_column=name] [table=name] [--overwrite]
20 [--verbose] [--quiet]
21 Flags:
23 -p
24 Print output to stdout, don't update attribute table
25 First column is always category of 'from' feature called from_cat
26 -a
28 Calculate distances to all features within the threshold
29 The output is written to stdout but may be uploaded to a new table
30 created by this module. From categories are may be multiple.
31 --overwrite
33 Allow output files to overwrite existing files
34 --verbose
36 Verbose module output
37 --quiet
39 Quiet module output
40 Parameters:
42 from=name
43 Name of existing vector map
44 to=name
46 Name of existing vector map
47 from_type=string[,string,...]
49 From type
50 Feature type(s)
51 Options: point,centroid
52 Default: point
53 to_type=string[,string,...]
55 To type
56 Feature type(s)
57 Options: point,line,boundary,centroid,area
58 Default: point,line,area
59 from_layer=integer
61 From layer
62 A single vector map can be connected to multiple database tables.
63 This number determines which table to use.
64 Default: 1
65 to_layer=integer
67 To layer
68 A single vector map can be connected to multiple database tables.
69 This number determines which table to use.
70 Default: 1
71 output=name
73 Name for output vector map containing lines connecting nearest ele‐
74 ments
75 dmax=float
77 Maximum distance or -1 for no limit
78 Default: -1
79 upload=string[,string,...]
81 Values describing the relation between two nearest features
82 Options: cat,dist,to_x,to_y,to_along,to_angle,to_attr
83 cat: category of the nearest feature
84 dist: minimum distance to nearest feature
85 to_x: x coordinate of the nearest point on 'to' feature
86 to_y: y coordinate of the nearest point on 'to' feature
87 to_along: distance between points/centroids in 'from' map and the
88 linear feature's start point in 'to' map, along this linear feature
89 to_angle: angle between the linear feature in 'to' map and the pos‐
90 itive x axis, at the location of point/centroid in 'from' map,
91 counterclockwise, in radians, which is between -PI and PI inclusive
92 to_attr: attribute of nearest feature given by to_column option
93 column=name[,name,...]
95 Column name(s) where values specified by 'upload' option will be
96 uploaded
97 to_column=name
99 Column name of nearest feature (used with upload=to_attr)
100 table=name
102 Name of table created for output when the distance to all flag is
103 used
104
106 v.distance finds the nearest element in vector map (to) for elements in
107 vector map (from). Various information about the vectors' relationships
108 (distance, category, etc.) may be uploaded to the attribute table
109 attached to the first vector map, or printed to ’stdout'. A new vector
110 map may be created where lines connecting nearest points on features
111 are written.
112
114 If a nearest feature does not have a category, the attribute column is
115 updated to null. This is true also for areas, which means for example,
116 that if a point is in an island (area WITHOUT category), v.distance
117 does not search for the nearest area WITH category; the island is iden‐
118 tified as the nearest and category updated to null.
119 The upload column(s) must already exist. Create one with v.db.addcol.
121 In lat-long locations v.distance gives distances (dist and to_along) in
123 meters not in degrees calculated as geodesic distances on a sphere.
124
126 Find nearest lines
127 Find nearest lines in vector map ln for points from vector map pnt
128 within the given threshold and write related line categories to column
129 linecat in an attribute table attached to vector map pnt:
130 v.distance from=pnt to=ln upload=cat column=linecat
131 Find nearest area
134 For each point from vector map pnt, find nearest area from map ar
135 within the given threshold and write the related area categories to
136 column areacat in an attribute table attached to vector map pnt (in the
137 case that a point falls into a polygon area, the distance is zero):
138 v.distance from=pnt to=ar upload=cat column=areacat
139 Create a new vector map
142 Create a new vector map which contains lines connecting nearest fea‐
143 tures of maps pnt and map ln. The resulting vector map can be used for
144 example to connect points to a network as needed for network analysis:
145 v.distance -p from=pnt to=ln out=connections upload=dist column=dist
146 Query information
149 Query information from selected point(s). v.distance takes points from
150 a vector map as input instead of stdin. A new vector map with query
151 points has to be created before the map can be analysed.
152 Create query map (if not present):
154 echo "123456|654321|1" | v.in.ascii output=pnt
155 Find nearest features:
156 v.distance from=pnt to=map_to_query upload=cat col=somecol -p
157 Point-in-polygon
160 Find area from vector map ar for each point from vector map pnt in
161 which the individual point falls, and write the related area categories
162 to column areacat into the attribute table attached to vector map pnt:
163 v.distance from=pnt to=ar dmax=0 upload=cat column=areacat
164 Univariate statistics on results
167 Create a vector map containing connecting lines and investigate mean
168 distance to targets. An alternative solution is to use the v.distance
169 upload=dist option to upload distances into the bugs vector directly,
170 then run v.univar on that. Also note you can upload two columns at a
171 time, e.g. v.distance upload=cat,dist column=nearest_id,dist_to_nr.
172 # create working copy
173 g.copy vect=bugsites,bugs
174 # add new attribute column to hold nearest archsite category number
175 v.db.addcol map=bugs column="nrst_arch INTEGER"
176 v.distance from=bugs to=archsites to_type=point upload=to_attr \
177 to_column=cat column=nrst_arch out=vdistance_vectors_raw
178 # we need to give the lines category numbers, create a table, and cre‐
179 ate
180 # a column in that table to hold the distance data.
181 v.category vdistance_vectors_raw out=vdistance_vectors type=line op=add
182 g.remove v=vdistance_vectors_raw
183 v.db.addtable map=vdistance_vectors column="length DOUBLE"
184 v.to.db map=vdistance_vectors option=length column=length
185 # calculcate statistics. Use v.univar.sh for extended statistics.
186 v.univar vdistance_vectors column=length
187 Print distance matrix
190 v.distance -pa from=archsites to=archsites upload=dist col=dist
192 Note: Matrix-like output is enabled only for flag -a and one given
193 upload option.
194
196 r.distance, v.db.addcol, v.what.vect
197
199 Janne Soimasuo 1994, University of Joensuu, Faculty of Forestry, Fin‐
200 land
201 Cmd line coordinates support: Markus Neteler, ITC-irst, Trento, Italy
202 Updated for 5.1: Radim Blazek, ITC-irst, Trento, Italy
203 Martix-like output by Martin Landa, FBK-irst, Trento, Italy
204 Last changed: $Date: 2008-01-16 21:10:07 +0100 (Wed, 16 Jan 2008) $
206 Full index
208 © 2003-2008 GRASS Development Team
210GRASS 6.3.0 v.distance(1)