1v.clean(1) GRASS GIS User's Manual v.clean(1)
2
3
4
6 v.clean - Toolset for cleaning topology of vector map.
7
9 vector, topology, geometry, snapping
10
12 v.clean
13 v.clean --help
14 v.clean [-bc] input=name [layer=string] [type=string[,string,...]]
15 output=name [error=name] tool=string[,string,...] [thresh‐
16 old=float[,float,...]] [--overwrite] [--help] [--verbose]
17 [--quiet] [--ui]
18
19 Flags:
20 -b
21 Do not build topology for the output vector
22
23 -c
24 Combine tools with recommended follow-up tools
25
26 --overwrite
27 Allow output files to overwrite existing files
28
29 --help
30 Print usage summary
31
32 --verbose
33 Verbose module output
34
35 --quiet
36 Quiet module output
37
38 --ui
39 Force launching GUI dialog
40
41 Parameters:
42 input=name [required]
43 Name of input vector map
44 Or data source for direct OGR access
45
46 layer=string
47 Layer number or name (’-1’ for all layers)
48 A single vector map can be connected to multiple database tables.
49 This number determines which table to use. When used with direct
50 OGR access this is the layer name.
51 Default: -1
52
53 type=string[,string,...]
54 Input feature type
55 Options: point, line, boundary, centroid, area, face, kernel
56 Default: point,line,boundary,centroid,area,face,kernel
57
58 output=name [required]
59 Name for output vector map
60
61 error=name
62 Name of output map where errors are written
63
64 tool=string[,string,...]Â [required]
65 Cleaning tool
66 Options: break, snap, rmdangle, chdangle, rmbridge, chbridge,
67 rmdupl, rmdac, bpol, prune, rmarea, rmline, rmsa
68 break: break lines at each intersection
69 snap: snap lines to vertex in threshold
70 rmdangle: remove dangles, threshold ignored if < 0
71 chdangle: change the type of boundary dangle to line, threshold ig‐
72 nored if < 0, input line type is ignored
73 rmbridge: remove bridges connecting area and island or 2 islands
74 chbridge: change the type of bridges connecting area and island or
75 2 islands from boundary to line
76 rmdupl: remove duplicate geometry features (pay attention to cate‐
77 gories!)
78 rmdac: remove duplicate area centroids (’type’ option ignored)
79 bpol: break (topologically clean) polygons (imported from non topo‐
80 logical format, like ShapeFile). Boundaries are broken on each
81 point shared between 2 and more polygons where angles of segments
82 are different
83 prune: remove vertices in threshold from lines and boundaries,
84 boundary is pruned only if topology is not damaged (new intersec‐
85 tion, changed attachment of centroid), first and last segment of
86 the boundary is never changed
87 rmarea: remove small areas, the longest boundary with adjacent area
88 is removed
89 rmline: remove all lines or boundaries of zero length, threshold is
90 ignored
91 rmsa: remove small angles between lines at nodes
92
93 threshold=float[,float,...]
94 Threshold in map units, one value for each tool
95 Default: 0.0[,0.0,...])
96
98 v.clean allows the user to automatically fix topology of vector maps.
99 Several tools may be listed to be executed sequentially. In this case,
100 also the threshold parameter requires several values to be listed ac‐
101 cordingly. An error map is optionally written which stores the erro‐
102 neous geometries.
103
104 Break lines/boundaries
105 tool=break
106
107 The break tool breaks lines/boundaries at intersections and it also
108 breaks lines/boundaries forming a collapsed loop. For example,
109 0.0;1.0;0.0 is broken at 1.0.
110
111 Threshold does not apply (it is ignored), use an arbitrary value (e.g.,
112 0) if v.clean is run with several tools.
113
114 Hint: Breaking lines should be followed by removing duplicates, e.g.
115 v.clean ... tool=break,rmdupl. If the -c flag is used with v.clean ...
116 tool=break, duplicates are automatically removed.
117
118 Remove duplicate geometry features
119 tool=rmdupl
120
121 The rmdupl tool removes geometry features with identical coordinates.
122 Categories are merged. If a point and a centroid have identical coordi‐
123 nates, one of them will be removed if both points and centroids are se‐
124 lected with v.clean ... type=point,centroid. The same applies for
125 lines and boundaries.
126
127 Threshold does not apply (it is ignored), use an arbitrary value (e.g.,
128 0) if v.clean is run with several tools.
129
130 The rmdupl tool should be used after breaking lines and breaking poly‐
131 gons.
132
133 Remove dangles or change boundary dangles to type line
134 tool=rmdangle and tool=chdangle
135
136 A line/boundary is considered to be a dangle if no other line of given
137 type is on at least one end node. If a dangle is formed by several
138 lines, such a string of lines is taken as one dangle and line lengths
139 are summarized. The rmdangle tool deletes a dangle if the (combined)
140 length is shorter than thresh or thresh < 0. If the combined length is
141 larger than thresh, nothing is deleted.
142
143 Threshold has to be given as maximum line/boundary length in map units;
144 for latitude-longitude locations in degree. Dangles shorter than thresh
145 are removed sequentially. All dangles will be removed if thresh < 0.
146
147 With thresh < 0, only closed loops and lines connecting loops will re‐
148 main. This is useful to remove all incorrect boundaries after other
149 cleaning operations with thres is < 0. Areas can then be successfully
150 built.
151
152 To preferentially remove shortest dangles first, a first pass with a
153 small thresh value can be followed by subsequent passes with higher
154 thresh values. This can be done as one v.clean job by listing the tool
155 several times and by defining a list of increasing thresh values.
156
157 The chdangle tool is similar to the rmdangle tool, but works only on
158 boundaries and changes dangling boundaries to lines instead of removing
159 them.
160
161 Remove or change bridges connecting an area and an island or two islands
162 tool=rmbridge and tool=chbridge
163
164 A bridge is an area type connection of an island (polygon in a polygon)
165 to the outer polygon. This is topologically incorrect (but OGC Simple
166 Features allow it). The rmbridge tool removes bridges and the chbridge
167 tool changes bridges to type line:
168 +-------------+ +-------------+ +-------------+
169 | P| P: polygon | P| | P|
170 | +---+ | I: island | +---+ | | +---+ |
171 | | I | | B: bridge | | I | | | | I | |
172 | | | | L: line | | | | | | | |
173 | +-+-+ | | +---+ | | +-.-+ |
174 | | | | | | . |
175 | | B | | | | . L |
176 | | | | | | . |
177 +------+------+ +-------------+ +-------------+
178
179 Islands and areas must be already clean, i.e. without dangles or small
180 angles, e.g. v.clean ... type=boundary tool=rmdan‐
181 gle,rmsa,break,rmdupl,rmbridge thresh=-1,0,0,0,0.
182
183 Threshold does not apply (it is ignored), use an arbitrary value (e.g.,
184 0) if v.clean is run with several tools.
185
186 Snap lines to vertex in threshold
187 tool=snap
188
189 The snap tool snaps vertices to another vertex not farther away than
190 thresh. If there is no other vertex within thresh, no snapping will be
191 done. The type option can have a strong influence on the result. A too
192 large threshold and type=boundary can severely damage area topology,
193 beyond repair.
194
195 Threshold gives maximum distance to another vertex in map units, for
196 latitude-longitude locations in degree.
197
198 Snapped boundaries may need to be cleaned with break,rmdupl,rmsa. If
199 the -c flag is used with v.clean tool=snap, the sequence of
200 break,rmdupl,rmsa is automatically repeated after snapping until no
201 more small angles a left. Additional cleaning with e.g. tool=rmdangle‐
202 may be necessary.
203
204 Remove duplicate area centroids
205 tool=rmdac
206
207 The rmdac tool removes duplicate area centroids that can result from
208 deleting boundaries.
209
210 Threshold does not apply (it is ignored), use an arbitrary value (e.g.,
211 0) if v.clean is run with several tools.
212
213 Break (topologically clean) areas (imported from a non topological
214 format like ShapeFile) tool=bpol
215
216 The bpol tool breaks boundaries on each point shared between 2 and more
217 areas where angles of boundary segments are different and on all bound‐
218 ary nodes (start and end points of each boundary). The bpol tool be‐
219 haves similar to break for boundaries, but does not break collapsed
220 loops. The bpol tool is faster than the break tool but needs more mem‐
221 ory.
222
223 Threshold does not apply (it is ignored), use an arbitrary value (e.g.,
224 0) if v.clean is run with several tools.
225
226 The bpol tool should be followed by rmdupl. If the -c flag is used with
227 v.clean ... tool=bpol, duplicates are automatically removed.
228
229 Remove vertices in threshold from lines and boundaries
230 tool=prune
231
232 The prune tool simplifies lines and boundaries by removing vertices ac‐
233 cording to threshold. This tool preserves area topology, areas are
234 never deleted and centroid attachment is never changed. v.generalize
235 offers much more functionality for line simplification but does not
236 preserve area topology.
237
238 Remove small areas
239 tool=rmarea
240
241 The rmarea tool removes all areas <= thresh. The longest boundary with
242 an adjacent area is removed or all boundaries if there is no adjacent
243 area. Area categories are not combined when a small area is merged with
244 a larger area.
245
246 Threshold must always be in square meters, also for latitude-longitude
247 locations or locations with units other than meters.
248
249 Remove all lines or boundaries of zero length
250 tool=rmline
251
252 The rmline tool removes all lines or boundaries of zero length that may
253 have resulted from other cleaning operations. Zero length boundaries
254 are redundant and do not influence area topology.
255
256 Threshold does not apply (it is ignored), use an arbitrary value (e.g.,
257 0) if v.clean is run with several tools.
258
259 Remove small angles between lines at nodes
260 tool=rmsa
261
262 The rmsa tool only concerns angles which are so small that the calcu‐
263 lated angle is 0. The following figure should help demonstrate what the
264 tool does.
265
266 Threshold does not apply, use dummy value if v.clean is run with sev‐
267 eral tools.
268
269
270
271 tool=rmsa
272
273
274 The rmsa tool should be followed by break,rmdupl. The rmsa tool fol‐
275 lowed by break,rmdupl may need to be run more than once to remove all
276 small angles. If the -c flag is used with v.clean ... tool=rmsa, the
277 sequence of rmsa,break,rmdupl is automatically repeated until no more
278 small angles a left.
279
281 The user does not have to run v.build on the output vector, unless the
282 -b flag was used. The -b flag affects only the output vector - topology
283 is always built for error vector.
284
286 Snap lines to vertex in threshold
287 v.clean input=testmap output=cleanmap tool=snap threshold=1
288
289 Inspecting the topological errors visually
290 Both v.build and v.clean can collect the topological errors into a vec‐
291 tor map:
292 v.build -e map=imported error=build_errors
293 v.clean -c input=imported output=clean error=cleaning_errors tool=snap,rmdangle,rmbridge,chbridge,bpol,prune threshold=5
294 The vector maps can be visualized together with the original data by
295 the following set of display commands:
296 d.vect map=imported color=26:26:26 fill_color=77:77:77 width=5
297 d.vect map=build_errors color=255:33:36 fill_color=none width=5 icon=basic/point size=30
298 d.vect map=cleaning_errors color=255:33:36 fill_color=none width=5 icon=basic/point size=30
299 Figure: Topological errors detected in the original data (left) and
300 cleaned data (right)
301
302 Cleaning OGR imported data (Simple Feature data) such as SHAPE file
303 The import of areas with v.in.ogr -c (no cleaning) requires a subse‐
304 quent run of v.clean to update the map to a topologically valid struc‐
305 ture (removal of duplicate collinear lines etc). The tools used for
306 that are bpol and rmdupl:
307 v.clean input=areamap output=areamap_clean tool=bpol,rmdupl type=boundary
308
309 Extracting intersection points of vector lines
310 v.clean input=lines1 output=lines2 err=points tool=break type=line
311 Intersection points are written to ’points’ map.
312
313 Break lines
314 v.clean will break the lines where they cross, creating new node if
315 needed. Example:
316 v.in.ascii -n out=crossed_lines format=standard << EOF
317 L 2
318 0 5
319 10 5
320 L 2
321 5 0
322 5 10
323 EOF
324 v.clean in=crossed_lines out=crossed_lines_brk \
325 error=intersection tool=break type=line
326
327 Remove all lines of zero length
328 v.out.ascii zero format=standard
329 L 2 1
330 -819832.09065589 -987825.2187231
331 -806227.28362601 -971104.80702988
332 1 1
333 L 2 1
334 -799165.24638913 -972974.16982788
335 -799165.24638913 -972974.16982788
336 1 2
337 v.clean input=zero output=zero_clean tool=rmline type=line
338 v.out.ascii zero_clean format=standard
339 L 2 1
340 -819832.09065589 -987825.2187231
341 -806227.28362601 -971104.80702988
342 1 1
343 v.clean type=boundary would remove nothing.
344
345 Repeatedly remove dangling lines up to 50m length
346 v.clean input=testmap output=cleanmap type=line \
347 tool=rmdangle,rmdangle,rmdangle,rmdangle threshold=5,10,20,50
348
350 v.info, v.build, g.gui.vdigit, v.edit, v.generalize
351
353 David Gerdes, U.S. Army Construction Engineering Research Laboratory
354 Radim Blazek, ITC-irst, Trento, Italy
355 Martin Landa, FBK-irst (formerly ITC-irst), Trento, Italy
356
358 Available at: v.clean source code (history)
359
360 Accessed: Saturday Oct 28 18:18:27 2023
361
362 Main index | Vector index | Topics index | Keywords index | Graphical
363 index | Full index
364
365 © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
366
367
368
369GRASS 8.3.1 v.clean(1)