Debian Codegraph @

vector/v.clean/v.clean.html

raw
1 <h2>DESCRIPTION</h2>
2
3 <em>v.clean</em> allows the user to automatically fix topology of vector
4 maps. Several tools may be listed to be executed sequentially. In this
5 case, also the threshold parameter requires several values to be listed
6 accordingly. An error map is optionally written which stores the erroneous
7 geometries.
8
9 <h3>Break lines/boundaries</h3>
10 <em>tool=break</em>
11 <p>
12 The <em>break</em> tool breaks lines/boundaries at intersections and it
13 <!-- TODO: what is a collapsed loop?? self-intersecting? -->
14 also breaks lines/boundaries forming a collapsed loop.
15 <!-- TODO: this example is a complete mystery: -->
16 For example, 0.0;1.0;0.0 is broken at 1.0.
17 <p>
18 Threshold does not apply (it is ignored), use an arbitrary value (e.g., 0)
19 if <em>v.clean</em> is run with several tools.
20 <p>
21 Hint: Breaking lines should be followed by removing duplicates, e.g.
22 <em>v.clean ... tool=break,rmdupl</em>. If the <em>-c</em> flag is used with
23 <em>v.clean ... tool=break</em>, duplicates are automatically removed.
24
25 <h3>Remove duplicate geometry features</h3>
26 <em>tool=rmdupl</em>
27 <p>
28 The <em>rmdupl</em> tool removes geometry features with identical
29 coordinates. Categories are merged. If a point and a centroid have
30 identical coordinates, one of them will be removed if both points and
31 centroids are selected with <em>v.clean ... type=point,centroid</em>.
32 The same applies for lines and boundaries.
33 <p>
34 Threshold does not apply (it is ignored), use an arbitrary value (e.g., 0)
35 if <em>v.clean</em> is run with several tools.
36 <p>
37 The <em>rmdupl</em> tool should be used after breaking lines and
38 breaking polygons.
39
40 <h3>Remove dangles or change boundary dangles to type line</h3>
41 <em>tool=rmdangle</em> and <em>tool=chdangle</em>
42 <p>
43 A line/boundary is considered to be a dangle if no other line of given
44 <em>type</em> is on at least one end node. If a dangle is formed by
45 several lines, such a string of lines is taken as one dangle and line
46 lengths are summarized. The <em>rmdangle</em> tool deletes a dangle if
47 the (combined) length is shorter than <em>thresh</em> or <em>thresh</em>
48 &lt; 0. If the combined length is larger than <em>thresh</em>, nothing
49 is deleted.
50 <p>
51 Threshold has to be given as maximum line/boundary length in map units;
52 for latitude-longitude projects in degrees. Dangles shorter than
53 <em>thresh</em> are removed sequentially. All dangles will be removed if
54 <em>thresh</em> &lt; 0.
55 <p>
56 With <em>thresh</em> &lt; 0, only closed loops and lines connecting
57 loops will remain. This is useful to remove all incorrect boundaries
58 after other cleaning operations with <em>thres</em> is &lt; 0. Areas can
59 then be successfully built.
60 <p>
61 To preferentially remove shortest dangles first, a first pass with a
62 small <em>thresh</em> value can be followed by subsequent passes with
63 higher <em>thresh</em> values. This can be done as one <em>v.clean</em>
64 job by listing the tool several times and by defining a list of increasing
65 <em>thresh</em> values.
66 <p>
67 The <em>chdangle</em> tool is similar to the <em>rmdangle</em> tool, but
68 works only on boundaries and changes dangling boundaries to lines
69 instead of removing them.
70
71 <h3>Remove or change bridges connecting an area and an island or two islands</h3>
72 <em>tool=rmbridge</em> and <em>tool=chbridge</em>
73 <p>
74 A bridge is an area type connection of an island (polygon in a polygon)
75 to the outer polygon. This is topologically incorrect (but OGC Simple
76 Features allow it). The <em>rmbridge</em> tool removes bridges and the
77 <em>chbridge</em> tool changes bridges to type line:
78
79 <div class="code"><pre>
80 +-------------+ +-------------+ +-------------+
81 | P| P: polygon | P| | P|
82 | +---+ | I: island | +---+ | | +---+ |
83 | | I | | B: bridge | | I | | | | I | |
84 | | | | L: line | | | | | | | |
85 | +-+-+ | | +---+ | | +-.-+ |
86 | | | | | | . |
87 | | B | | | | . L |
88 | | | | | | . |
89 +------+------+ +-------------+ +-------------+
90 </pre></div>
91 <p>
92 Islands and areas must be already clean, i.e. without dangles or small
93 angles, e.g.
94 <em>v.clean ... type=boundary tool=rmdangle,rmsa,break,rmdupl,rmbridge
95 thresh=-1,0,0,0,0</em>.
96 <p>
97 Threshold does not apply (it is ignored), use an arbitrary value (e.g., 0)
98 if <em>v.clean</em> is run with several tools.
99
100 <h3>Snap lines to vertex in threshold</h3>
101 <em>tool=snap</em>
102 <p>
103 The <em>snap</em> tool snaps vertices to another vertex not farther away
104 than <em>thresh</em>. If there is no other vertex within <em>thresh</em>,
105 no snapping will be done. The <em>type</em> option can have a strong
106 influence on the result. A too large threshold and <em>type=boundary</em>
107 can severely damage area topology, beyond repair.
108 <p>
109 Threshold gives maximum distance to another vertex in map units,
110 for latitude-longitude projects in degrees.
111 <p>
112 Snapped boundaries may need to be cleaned with <em>break,rmdupl,rmsa</em>.
113 If the <em>-c</em> flag is used with <em>v.clean tool=snap</em>, the
114 sequence of <em>break,rmdupl,rmsa</em> is automatically repeated after
115 snapping until no more small angles a left. Additional cleaning with e.g.
116 <em>tool=rmdangle</em>may be necessary.
117
118 <h3>Remove duplicate area centroids</h3>
119 <em>tool=rmdac</em>
120 <p>
121 The <em>rmdac</em> tool removes duplicate area centroids that can result
122 from deleting boundaries.
123 <p>
124 Threshold does not apply (it is ignored), use an arbitrary value (e.g., 0)
125 if <em>v.clean</em> is run with several tools.
126
127 <h3>Break (topologically clean) areas (imported from a non topological
128 format like ShapeFile)</h3>
129 <em>tool=bpol</em>
130 <p>
131 The <em>bpol</em> tool breaks boundaries on each point shared between 2
132 and more areas where angles of boundary segments are different and on
133 all boundary nodes (start and end points of each boundary). The
134 <em>bpol</em> tool behaves similar to <em>break</em> for boundaries, but
135 does not break collapsed loops. The <em>bpol</em> tool is faster than
136 the <em>break</em> tool but needs more memory.
137 <p>
138 Threshold does not apply (it is ignored), use an arbitrary value (e.g., 0)
139 if <em>v.clean</em> is run with several tools.
140 <p>
141 The <em>bpol</em> tool should be followed by <em>rmdupl</em>. If the
142 <em>-c</em> flag is used with <em>v.clean ... tool=bpol</em>, duplicates are
143 automatically removed.
144
145 <h3>Remove vertices in threshold from lines and boundaries</h3>
146 <em>tool=prune</em>
147 <p>
148 The <em>prune</em> tool simplifies lines and boundaries by removing
149 vertices according to threshold. This tool preserves area topology,
150 areas are never deleted and centroid attachment is never changed.
151 <em><a href="v.generalize.html">v.generalize</a></em> offers much more
152 functionality for line simplification but does not preserve area
153 topology.
154
155 <h3>Remove small areas</h3>
156 <em>tool=rmarea</em>
157 <p>
158 The <em>rmarea</em> tool removes all areas &lt;= <em>thresh</em>. The
159 longest boundary with an adjacent area is removed or all boundaries if
160 there is no adjacent area. Area categories are not combined when a small
161 area is merged with a larger area.
162 <p>
163 Threshold must always be in square meters, also for latitude-longitude
164 projects or projects with units other than meters.
165
166 <h3>Remove all lines or boundaries of zero length</h3>
167 <em>tool=rmline</em>
168 <p>
169 The <em>rmline</em> tool removes all lines or boundaries of zero length
170 that may have resulted from other cleaning operations. Zero length
171 boundaries are redundant and do not influence area topology.
172 <p>
173 Threshold does not apply (it is ignored), use an arbitrary value (e.g., 0)
174 if <em>v.clean</em> is run with several tools.
175
176 <h3>Remove small angles between lines at nodes</h3>
177 <em>tool=rmsa</em>
178 <p>
179 The <em>rmsa</em> tool only concerns angles which are so small that the
180 calculated angle is 0. The following figure should help demonstrate what
181 the tool does.
182 <p>
183 Threshold does not apply, use dummy value if <em>v.clean</em> is
184 run with several tools.
185 <p>
186 <table><tr><td>
187 <img src="v_clean_rmsa.png" border="1">
188 </td></tr>
189 <tr><td align="center">
190 <font size="-1"><em>tool=rmsa</em></font>
191 </td></tr>
192 </table>
193 <p>
194 The <em>rmsa</em> tool should be followed by <em>break,rmdupl</em>. The
195 <em>rmsa</em> tool followed by <em>break,rmdupl</em> may need to be run
196 more than once to remove all small angles. If the <em>-c</em> flag is
197 used with <em>v.clean ... tool=rmsa</em>, the sequence of
198 <em>rmsa,break,rmdupl</em> is automatically repeated until no more small
199 angles a left.
200
201 <h2>NOTES</h2>
202
203 The user does <b>not</b> have to run <em><a href="v.build.html">v.build</a></em>
204 on the <em>output</em> vector, unless the <em>-b</em> flag was used. The
205 <em>-b</em> flag affects <b>only</b> the <em>output</em> vector -
206 topology is always built for <em>error</em> vector.
207
208 <h2>EXAMPLES</h2>
209
210 <h3>Snap lines to vertex in threshold</h3>
211 <div class="code"><pre>
212 v.clean input=testmap output=cleanmap tool=snap threshold=1
213 </pre></div>
214
215 <h3>Inspecting the topological errors visually</h3>
216
217 Both <em><a href="v.build.html">v.build</a></em> and <em>v.clean</em> can
218 collect the topological errors into a vector map:
219
220 <div class="code"><pre>
221 v.build -e map=imported error=build_errors
222 v.clean -c input=imported output=clean error=cleaning_errors tool=snap,rmdangle,rmbridge,chbridge,bpol,prune threshold=5
223 </pre></div>
224
225 The vector maps can be visualized together with the original data
226 by the following set of display commands:
227
228 <div class="code"><pre>
229 d.vect map=imported color=26:26:26 fill_color=77:77:77 width=5
230 d.vect map=build_errors color=255:33:36 fill_color=none width=5 icon=basic/point size=30
231 d.vect map=cleaning_errors color=255:33:36 fill_color=none width=5 icon=basic/point size=30
232 </pre></div>
233
234 <div align="center">
235 <img src="v_clean.png" alt="topological errors">
236 <br>
237 <i>Figure: Topological errors detected in the original data (left)
238 and cleaned data (right)</i>
239 </div>
240
241 <!--
242 v.in.ascii -b input=- output=imported format=standard <<EOF
243 VERTI:
244 C 1 1
245 20.10795595 60.54319764
246 1 1
247 C 1 1
248 51.86024171 61.9113356
249 1 2
250 B 10
251 40.0278379309 74.22082728
252 40.0278379309 62.1579269574
253 40.0278379309 55.8642398326
254 40.5523118579 46.7733584301
255 34.0838000908 42.5775670136
256 16.9509851399 45.1999366489
257 11.1817719422 58.8362587527
258 13.9789662199 72.1229315717
259 20.2726533447 75.9690737035
260 40.0278379309 74.22082728
261 B 12
262 37.3774872156 78.2907419083
263 38.0278379309 75.22082728
264 41.0278379309 61.1579269574
265 42.0278379309 56.8642398326
266 37.5523118579 45.7733584301
267 47.7201221945 39.7803727359
268 63.6291646489 52.3677469855
269 69.573202489 61.9831023151
270 64.3284632183 67.9271401551
271 57.6851268088 76.3187229882
272 45.7970511286 77.7173201271
273 37.3774872156 78.2907419083
274 L 3 1
275 23 30
276 23 23
277 23 9
278 1 3
279 L 2 1
280 65 23
281 20 23
282 1 4
283 EOF
284 # v.build shows different set than v.clean, so using both
285 v.build -e map=imported error=build_errors
286 v.clean -c input=imported output=clean error=cleaning_errors tool=snap,rmdangle,rmbridge,chbridge,bpol,prune threshold=5
287
288 g.region vector=imported e=e+5 w=w-5
289 d.mon start=cairo output=v_clean.png
290 d.frame frame=left at=0,100,0,50 -c
291 d.vect map=imported color=26:26:26 fill_color=77:77:77 width=5
292 d.vect map=build_errors color=255:33:36 fill_color=none width=5 icon=basic/point size=30
293 d.vect map=cleaning_errors color=255:33:36 fill_color=none width=5 icon=basic/point size=30
294 d.frame frame=right at=0,100,50,100 -c
295 d.vect map=clean color=26:26:26 fill_color=77:77:77 width=5
296 d.mon stop=cairo
297
298 mogrify -trim v_clean.png
299 pngnq -n 128 -s 3 v_clean.png
300 optipng -o5 v_clean-nq8.png
301 mv v_clean-nq8.png v_clean.png
302 -->
303
304 <h3>Cleaning OGR imported data (Simple Feature data) such as SHAPE file</h3>
305
306 The import of areas with <em><a href="v.in.ogr.html">v.in.ogr</a> -c</em>
307 (no cleaning) requires a subsequent run of <em>v.clean</em> to update
308 the map to a topologically valid structure (removal of duplicate
309 collinear lines etc). The tools used for that are <em>bpol</em> and
310 <em>rmdupl</em>:
311 <div class="code"><pre>
312 v.clean input=areamap output=areamap_clean tool=bpol,rmdupl type=boundary
313 </pre></div>
314
315 <h3>Extracting intersection points of vector lines</h3>
316 <div class="code"><pre>
317 v.clean input=lines1 output=lines2 err=points tool=break type=line
318 </pre></div>
319
320 Intersection points are written to 'points' map.
321
322 <h3>Break lines</h3>
323
324 <em>v.clean</em> will break the lines where they cross,
325 creating new node if needed. Example:
326
327 <div class="code"><pre>
328 v.in.ascii -n out=crossed_lines format=standard &lt;&lt; EOF
329 L 2
330 0 5
331 10 5
332 L 2
333 5 0
334 5 10
335 EOF
336
337 v.clean in=crossed_lines out=crossed_lines_brk \
338 error=intersection tool=break type=line
339 </pre></div>
340
341 <h3>Remove all lines of zero length</h3>
342
343 <div class="code"><pre>
344 v.out.ascii zero format=standard
345 L 2 1
346 -819832.09065589 -987825.2187231
347 -806227.28362601 -971104.80702988
348 1 1
349 L 2 1
350 -799165.24638913 -972974.16982788
351 -799165.24638913 -972974.16982788
352 1 2
353
354 v.clean input=zero output=zero_clean tool=rmline type=line
355
356 v.out.ascii zero_clean format=standard
357 L 2 1
358 -819832.09065589 -987825.2187231
359 -806227.28362601 -971104.80702988
360 1 1
361 </pre></div>
362 v.clean type=boundary would remove nothing.
363
364 <h3>Repeatedly remove dangling lines up to 50m length</h3>
365
366 <div class="code"><pre>
367 v.clean input=testmap output=cleanmap type=line \
368 tool=rmdangle,rmdangle,rmdangle,rmdangle threshold=5,10,20,50
369 </pre></div>
370
371 <h2>SEE ALSO</h2>
372
373 <em>
374 <a href="v.info.html">v.info</a>,
375 <a href="v.build.html">v.build</a>,
376 <a href="g.gui.vdigit.html">g.gui.vdigit</a>,
377 <a href="v.edit.html">v.edit</a>,
378 <a href="v.fill.holes.html">v.fill.holes</a>,
379 <a href="v.generalize.html">v.generalize</a>
380 </em>
381
382 <h2>AUTHORS</h2>
383
384 David Gerdes, U.S. Army Construction Engineering Research Laboratory<br>
385 Radim Blazek, ITC-irst, Trento, Italy<br>
386 Martin Landa, FBK-irst (formerly ITC-irst), Trento, Italy