| 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 |
< 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> < 0. |
| 55 |
<p> |
| 56 |
With <em>thresh</em> < 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 < 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 <= <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 << 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 |