1v.distance(1) GRASS GIS 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 [-pas] 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’ op‐
31 tions may be used.
32 -s
34 Print output as square matrix (only possible for one single upload
35 variable)
36 --overwrite
38 Allow output files to overwrite existing files
39 --help
41 Print usage summary
42 --verbose
44 Verbose module output
45 --quiet
47 Quiet module output
48 --ui
50 Force launching GUI dialog
51 Parameters:
53 from=name [required]
54 Name of existing vector map (from)
55 Or data source for direct OGR access
56 from_layer=string
58 Layer number or name (from)
59 Vector features can have category values in different layers. This
60 number determines which layer to use. When used with direct OGR ac‐
61 cess this is the layer name.
62 Default: 1
63 from_type=string[,string,...]
65 Feature type (from)
66 Input feature type
67 Options: point, line, boundary, centroid, area
68 Default: point,line,area
69 to=name [required]
71 Name of existing vector map (to)
72 Or data source for direct OGR access
73 to_layer=string
75 Layer number or name (to)
76 Vector features can have category values in different layers. This
77 number determines which layer to use. When used with direct OGR ac‐
78 cess this is the layer name.
79 Default: 1
80 to_type=string[,string,...]
82 Feature type (to)
83 Input feature type
84 Options: point, line, boundary, centroid, area
85 Default: point,line,area
86 output=name
88 Name for output vector map containing lines connecting nearest ele‐
89 ments
90 dmax=float
92 Maximum distance or -1 for no limit
93 Map units, meters for ll
94 Default: -1
95 dmin=float
97 Minimum distance or -1 for no limit
98 Map units, meters for ll
99 Default: -1
100 upload=string[,string,...]Â [required]
102 Values describing the relation between two nearest features
103 Options: cat, dist, to_x, to_y, to_along, to_angle, to_attr
104 cat: category of the nearest feature
105 dist: minimum distance to nearest feature
106 to_x: x coordinate of the nearest point on the ’to’ feature
107 to_y: y coordinate of the nearest point on the ’to’ feature
108 to_along: distance to the nearest point on the ’to’ feature along
109 that linear feature
110 to_angle: angle along the nearest linear feature in the ’to’ map,
111 measured CCW from the +x axis, in radians, between -Pi and Pi in‐
112 clusive
113 to_attr: attribute of nearest feature given by to_column option
114 column=name[,name,...]
116 Column name(s) where values specified by ’upload’ option will be
117 uploaded
118 to_column=name
120 Column name of nearest feature (used with upload=to_attr)
121 table=name
123 Name for new attribute table
124 separator=character
126 Field separator for printing output to stdout
127 Special characters: pipe, comma, space, tab, newline
128 Default: pipe
129
131 v.distance finds the nearest element in vector map (to) for elements in
132 vector map (from). Various information about the vectors’ relationships
133 (distance, category, etc.) may be uploaded to the attribute table at‐
134 tached to the first vector map, or printed to ’stdout’. A new vector
135 map may be created where lines connecting nearest points on features
136 are written. dmin and/or dmax can be used to limit the search radius
137 (in lat-long locations to be given in meters since they are calculated
138 as geodesic distances on a sphere).
139 For lines to lines, say line A to line B, v.distance calculates the
141 shortest distance of each vertex in A with each segment (not vertex) in
142 B. The module then calculates the shortest distance of each vertex in B
143 to each segment in A. The overall shortest distance of A points to B
144 segments and B points to A segments is used. Additionally, v.distance
145 checks for intersections. In case of intersections, the first intersec‐
146 tion found is used and the distance set to zero.
147 For lines to areas, the distance is set to zero if a line is (par‐
149 tially) inside an area. The first point of the line that is inside the
150 area is used as common point. The distance is also set to zero if the
151 line intersects with the outer ring or any of the inner rings (isles),
152 in which case the fist intersection is used as common point.
153 For areas to areas, the module checks first for overlap or if one area
155 is (partially) inside the other area. This is computationally quite in‐
156 tensive. If the outer rings of the two areas do not overlap, the dis‐
157 tance is calculated as above for lines to lines, treating the outer
158 rings as two lines. Again, the first point encountered falling into an
159 area is used as common point, or the first intersection point.
160 For anything else than points to lines, there can be several common lo‐
162 cations with zero distance, and the common location would then be the
163 result of an overlay consisting of several points, lines, or areas.
164 v.distance selects in these cases a single point, and does not create
165 an overlay like v.overlay. In this implementation, any shared point is
166 as good as any other. Calculating an intersection is costlier than to
167 check if a vertex is inside a polygon. For example, if a vertex of the
168 boundary of the ’to’ area is inside the ’from’ area, it is a common lo‐
169 cation. For speed reasons, the distance is then set to zero and no fur‐
170 ther tests are done.
171
173 If a nearest feature does not have a category, the attribute column is
174 updated to NULL.
175 The upload column(s) must already exist. Create one with v.db.addcol‐
177 umn.
178 In lat-long locations v.distance gives distances (dist, from_along, and
180 to_along) not in degrees but in meters calculated as geodesic distances
181 on a sphere.
182 If one or both of the input vector maps are 3D, the user is notified
184 accordingly.
185 The -p flag prints the results to standard output. By default the out‐
187 put is in form of a linear matrix. If only only variable is upploaded
188 and a square matrix is desired, the user can set the -s flag.
189
191 Find nearest lines
192 Find nearest lines in vector map "ln" for points from vector map "pnt"
193 within the given threshold and write related line categories to column
194 "linecat" in an attribute table attached to vector map "pnt":
195 v.distance from=pnt to=ln upload=cat column=linecat
196 Find nearest area
198 For each point from vector map "pnt", find the nearest area from map
199 "ar" within the given threshold and write the related area categories
200 to column "areacat" in an attribute table attached to vector map "pnt"
201 (in the case that a point falls into an area, the distance is zero):
202 v.distance from=pnt to=ar upload=cat column=areacat
203 Create a new vector map
205 Create a new vector map which contains lines connecting nearest fea‐
206 tures of maps "pnt" and map "ln". The resulting vector map can be used
207 for example to connect points to a network as needed for network analy‐
208 sis:
209 v.distance from=pnt to=ln out=connections upload=dist column=dist
210 Create a new vector map with from and to categories in the attribute table
212 Create a new vector map that contains lines connecting nearest features
213 of maps "pnt" and map "ln", and a new attribute table that contains
214 distances, from and to categories from the input maps:
215 v.distance from=pnt to=ln out=connections upload=cat,dist column=to_cat,dist table=connections
216 Query information
218 Query information from selected point(s). v.distance takes points from
219 a vector map as input instead of stdin. A new vector map with query
220 points has to be created before the map can be analysed.
221 Create query map (if not present):
223 echo "123456|654321|1" | v.in.ascii output=pnt
224 Find nearest features:
225 v.distance -p from=pnt to=map_to_query upload=cat
226 Point-in-polygon
228 The option dmax=0 is here important because otherwise for points not
229 falling into any area, the category of the nearest area is recorded.
230 For each point from vector map "pnt", find the area from vector map
231 "ar" in which the individual point falls, and write the related area
232 categories to column "areacat" into the attribute table attached to
233 vector map "pnt":
234 v.distance from=pnt to=ar dmax=0 upload=cat column=areacat
235 Univariate statistics on results
237 Create a vector map containing connecting lines and investigate mean
238 distance to targets. An alternative solution is to use the v.distance
239 upload=dist option to upload distances into the bugs vector directly,
240 then run v.univar on that. Also note you can upload two columns at a
241 time, e.g. v.distance upload=cat,dist column=nearest_id,dist_to_nr.
242 # create working copy
243 g.copy vect=bugsites,bugs
244 # add new attribute column to hold nearest archsite category number
245 v.db.addcolumn map=bugs column="nrst_arch INTEGER"
246 v.distance from=bugs to=archsites to_type=point upload=to_attr \
247 to_column=cat column=nrst_arch out=vdistance_vectors_raw
248 # we need to give the lines category numbers, create a table, and create
249 # a column in that table to hold the distance data.
250 v.category vdistance_vectors_raw out=vdistance_vectors type=line op=add
251 g.remove -f type=vector name=vdistance_vectors_raw
252 v.db.addtable map=vdistance_vectors column="length DOUBLE"
253 v.to.db map=vdistance_vectors option=length column=length
254 # calculate statistics
255 v.univar vdistance_vectors column=length
256 Print distance between points
258 Example for a Latitude-longitude location (EPSG 4326):
259 # points along the equator
260 echo "0|-61|1" | v.in.ascii output=pnt1 input=-
261 echo "0|-58|1" | v.in.ascii output=pnt2 input=-
262 # here, distances are in degree units
263 v.distance -p --q from=pnt1 to=pnt2 upload=dist
264 from_cat|distance
265 1|3
266 Print distance matrix
268 North Carolina sample data location
269 As linear matrix:
271 v.distance -pa from=hospitals to=hospitals upload=dist,to_attr to_column=NAME separator=tab
272 from_cat to_cat dist to_attr
273 1 1 0 Cherry Hospital
274 1 2 7489.1043632983983 Wayne Memorial Hospital
275 1 3 339112.17046729225 Watauga Medical Center
276 1 4 70900.392145909267 Central Prison Hospital
277 1 5 70406.227393921712 Dorothea Dix Hospital
278 As square matrix (only possible with single upload option):
280 v.distance -pas from=hospitals to=hospitals upload=dist separator=tab
281 from_cat to_cat dist
282 1 2 3 4 5 ...
283 1 0 7489.10 339112.17 70900.39 70406.23 ...
284 2 7489.10 0 345749.12 76025.46 75538.87 ...
285 3 339112.17 345749.12 0 274153.19 274558.98 ...
286 4 70900.39 76025.46 274153.19 0 501.11 ...
287 5 70406.23 75538.87 274558.98 501.11 0 ...
288 ...
289
291 r.distance, v.db.addcolumn, v.what.vect
292
294 Janne Soimasuo 1994, University of Joensuu, Faculty of Forestry, Fin‐
295 land
296 Cmd line coordinates support: Markus Neteler, ITC-irst, Trento, Italy
297 Updated for 5.1: Radim Blazek, ITC-irst, Trento, Italy
298 Matrix-like output by Martin Landa, FBK-irst, Trento, Italy
299 Improved processing speed: Markus Metz
300 Distance from any feature to any feature: Markus Metz
301 New table without the -p flag: Huidae Cho Make linear matrix the de‐
302 fault for all outputs: Moritz Lennert
303
305 Available at: v.distance source code (history)
306 Accessed: Saturday Oct 28 18:18:31 2023
308 Main index | Vector index | Topics index | Keywords index | Graphical
310 index | Full index
311 © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
313GRASS 8.3.1 v.distance(1)