1v.distance(1) Grass User's Manual v.distance(1)
2
6 v.distance - Finds the nearest element in vector map ’to’ for elements
7 in vector map ’from’.
8
10 vector, distance, database, attribute table
11
13 v.distance
14 v.distance --help
15 v.distance [-pa] from=name [from_layer=string]
16 [from_type=string[,string,...]] to=name [to_layer=string]
17 [to_type=string[,string,...]] [output=name] [dmax=float]
18 [dmin=float] [upload=string[,string,...]] [column=name[,name,...]]
19 [to_column=name] [table=name] [separator=character] [--overwrite]
20 [--help] [--verbose] [--quiet] [--ui]
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 Output may be written to stdout using the ’-p’ flag or uploaded to
30 a new table created by the ’table’ option; multiple ’upload’
31 options may be used.
32 --overwrite
34 Allow output files to overwrite existing files
35 --help
37 Print usage summary
38 --verbose
40 Verbose module output
41 --quiet
43 Quiet module output
44 --ui
46 Force launching GUI dialog
47 Parameters:
49 from=name [required]
50 Name of existing vector map (from)
51 Or data source for direct OGR access
52 from_layer=string
54 Layer number or name (from)
55 Vector features can have category values in different layers. This
56 number determines which layer to use. When used with direct OGR
57 access this is the layer name.
58 Default: 1
59 from_type=string[,string,...]
61 Feature type (from)
62 Input feature type
63 Options: point, line, boundary, centroid, area
64 Default: point,line,area
65 to=name [required]
67 Name of existing vector map (to)
68 Or data source for direct OGR access
69 to_layer=string
71 Layer number or name (to)
72 Vector features can have category values in different layers. This
73 number determines which layer to use. When used with direct OGR
74 access this is the layer name.
75 Default: 1
76 to_type=string[,string,...]
78 Feature type (to)
79 Input feature type
80 Options: point, line, boundary, centroid, area
81 Default: point,line,area
82 output=name
84 Name for output vector map containing lines connecting nearest ele‐
85 ments
86 dmax=float
88 Maximum distance or -1 for no limit
89 Map units, meters for ll
90 Default: -1
91 dmin=float
93 Minimum distance or -1 for no limit
94 Map units, meters for ll
95 Default: -1
96 upload=string[,string,...]
98 Values describing the relation between two nearest features
99 Options: cat, dist, to_x, to_y, to_along, to_angle, to_attr
100 cat: category of the nearest feature
101 dist: minimum distance to nearest feature
102 to_x: x coordinate of the nearest point on the ’to’ feature
103 to_y: y coordinate of the nearest point on the ’to’ feature
104 to_along: distance to the nearest point on the ’to’ feature along
105 that linear feature
106 to_angle: angle along the nearest linear feature in the ’to’ map,
107 measured CCW from the +x axis, in radians, between -Pi and Pi
108 inclusive
109 to_attr: attribute of nearest feature given by to_column option
110 column=name[,name,...]
112 Column name(s) where values specified by ’upload’ option will be
113 uploaded
114 to_column=name
116 Column name of nearest feature (used with upload=to_attr)
117 table=name
119 Name for new attribute table
120 separator=character
122 Field separator for printing output to stdout
123 Special characters: pipe, comma, space, tab, newline
124 Default: pipe
125
127 v.distance finds the nearest element in vector map (to) for elements in
128 vector map (from). Various information about the vectors’ relationships
129 (distance, category, etc.) may be uploaded to the attribute table
130 attached to the first vector map, or printed to ’stdout’. A new vector
131 map may be created where lines connecting nearest points on features
132 are written. dmin and/or dmax can be used to limit the search radius
133 (in lat-long locations to be given in meters since they are calculated
134 as geodesic distances on a sphere).
135 For lines to lines, say line A to line B, v.distance calculates the
137 shortest distance of each vertex in A with each segment (not vertex) in
138 B. The module then calculates the shortest distance of each vertex in B
139 to each segment in A. The overall shortest distance of A points to B
140 segments and B points to A segments is used. Additionally, v.distance
141 checks for intersections. In case of intersections, the first intersec‐
142 tion found is used and the distance set to zero.
143 For lines to areas, the distance is set to zero if a line is (par‐
145 tially) inside an area. The first point of the line that is inside the
146 area is used as common point. The distance is also set to zero if the
147 line intersects with the outer ring or any of the inner rings (isles),
148 in which case the fist intersection is used as common point.
149 For areas to areas, the module checks first for overlap or if one area
151 is (partially) inside the other area. This is computationally quite
152 intensive. If the outer rings of the two areas do not overlap, the dis‐
153 tance is calculated as above for lines to lines, treating the outer
154 rings as two lines. Again, the first point encountered falling into an
155 area is used as common point, or the first intersection point.
156 For anything else than points to lines, there can be several common
158 locations with zero distance, and the common location would then be the
159 result of an overlay consisting of several points, lines, or areas.
160 v.distance selects in these cases a single point, and does not create
161 an overlay like v.overlay. In this implementation, any shared point is
162 as good as any other. Calculating an intersection is costlier than to
163 check if a vertex is inside a polygon. For example, if a vertex of the
164 boundary of the ’to’ area is inside the ’from’ area, it is a common
165 location. For speed reasons, the distance is then set to zero and no
166 further tests are done.
167
169 If a nearest feature does not have a category, the attribute column is
170 updated to NULL.
171 The upload column(s) must already exist. Create one with v.db.addcol‐
173 umn.
174 In lat-long locations v.distance gives distances (dist, from_along, and
176 to_along) not in degrees but in meters calculated as geodesic distances
177 on a sphere.
178 If one or both of the input vector maps are 3D, the user is notified
180 accordingly.
181
183 Find nearest lines
184 Find nearest lines in vector map "ln" for points from vector map "pnt"
185 within the given threshold and write related line categories to column
186 "linecat" in an attribute table attached to vector map "pnt":
187 v.distance from=pnt to=ln upload=cat column=linecat
188 Find nearest area
190 For each point from vector map "pnt", find the nearest area from map
191 "ar" within the given threshold and write the related area categories
192 to column "areacat" in an attribute table attached to vector map "pnt"
193 (in the case that a point falls into an area, the distance is zero):
194 v.distance from=pnt to=ar upload=cat column=areacat
195 Create a new vector map
197 Create a new vector map which contains lines connecting nearest fea‐
198 tures of maps "pnt" and map "ln". The resulting vector map can be used
199 for example to connect points to a network as needed for network analy‐
200 sis:
201 v.distance from=pnt to=ln out=connections upload=dist column=dist
202 Create a new vector map with from and to categories in the attribute table
204 Create a new vector map that contains lines connecting nearest features
205 of maps "pnt" and map "ln", and a new attribute table that contains
206 distances, from and to categories from the input maps:
207 v.distance from=pnt to=ln out=connections upload=cat,dist column=to_cat,dist table=connections
208 Query information
210 Query information from selected point(s). v.distance takes points from
211 a vector map as input instead of stdin. A new vector map with query
212 points has to be created before the map can be analysed.
213 Create query map (if not present):
215 echo "123456|654321|1" | v.in.ascii output=pnt
216 Find nearest features:
217 v.distance -p from=pnt to=map_to_query upload=cat
218 Point-in-polygon
220 The option dmax=0 is here important because otherwise for points not
221 falling into any area, the category of the nearest area is recorded.
222 For each point from vector map "pnt", find the area from vector map
223 "ar" in which the individual point falls, and write the related area
224 categories to column "areacat" into the attribute table attached to
225 vector map "pnt":
226 v.distance from=pnt to=ar dmax=0 upload=cat column=areacat
227 Univariate statistics on results
229 Create a vector map containing connecting lines and investigate mean
230 distance to targets. An alternative solution is to use the v.distance
231 upload=dist option to upload distances into the bugs vector directly,
232 then run v.univar on that. Also note you can upload two columns at a
233 time, e.g. v.distance upload=cat,dist column=nearest_id,dist_to_nr.
234 # create working copy
235 g.copy vect=bugsites,bugs
236 # add new attribute column to hold nearest archsite category number
237 v.db.addcolumn map=bugs column="nrst_arch INTEGER"
238 v.distance from=bugs to=archsites to_type=point upload=to_attr \
239 to_column=cat column=nrst_arch out=vdistance_vectors_raw
240 # we need to give the lines category numbers, create a table, and create
241 # a column in that table to hold the distance data.
242 v.category vdistance_vectors_raw out=vdistance_vectors type=line op=add
243 g.remove -f type=vector name=vdistance_vectors_raw
244 v.db.addtable map=vdistance_vectors column="length DOUBLE"
245 v.to.db map=vdistance_vectors option=length column=length
246 # calculate statistics
247 v.univar vdistance_vectors column=length
248 Print distance between points
250 Example for a Latitude-longitude location (EPSG 4326):
251 # points along the equator
252 echo "0|-61|1" | v.in.ascii output=pnt1 input=-
253 echo "0|-58|1" | v.in.ascii output=pnt2 input=-
254 # here, distances are in degree units
255 v.distance -p --q from=pnt1 to=pnt2 upload=dist
256 from_cat|distance
257 1|3
258 Print distance matrix
260 Note: Matrix-style output is enabled only for flag -a and one given
261 upload option.
262 Spearfish sample data location:
264 v.distance -pa from=archsites to=archsites upload=dist
265 North Carolina sample data location:
267 v.distance -pa from=hospitals to=hospitals upload=dist separator=tab
268 from_cat to_cat dist
269 1 2 3 4 5 ...
270 1 0 7489.10 339112.17 70900.39 70406.23 ...
271 2 7489.10 0 345749.12 76025.46 75538.87 ...
272 3 339112.17 345749.12 0 274153.19 274558.98 ...
273 4 70900.39 76025.46 274153.19 0 501.11 ...
274 5 70406.23 75538.87 274558.98 501.11 0 ...
275 ...
276
278 r.distance, v.db.addcolumn, v.what.vect
279
281 Janne Soimasuo 1994, University of Joensuu, Faculty of Forestry, Fin‐
282 land
283 Cmd line coordinates support: Markus Neteler, ITC-irst, Trento, Italy
284 Updated for 5.1: Radim Blazek, ITC-irst, Trento, Italy
285 Matrix-like output by Martin Landa, FBK-irst, Trento, Italy
286 Improved processing speed: Markus Metz
287 Distance from any feature to any feature: Markus Metz
288 New table without the -p flag: Huidae Cho
289
291 Available at: v.distance source code (history)
292 Main index | Vector index | Topics index | Keywords index | Graphical
294 index | Full index
295 © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual
297GRASS 7.8.2 v.distance(1)