.TH v.clean 1grass "" "GRASS 6.4.2" "Grass User's Manual"
.SH NAME
\fI\fBv.clean\fR\fR  - Toolset for cleaning topology of vector map.
.SH KEYWORDS
vector, topology
.SH SYNOPSIS
\fBv.clean\fR
.br
\fBv.clean help\fR
.br
\fBv.clean\fR [-\fBb\fR] \fBinput\fR=\fIname\fR \fBoutput\fR=\fIname\fR  [\fBtype\fR=\fIstring\fR[,\fIstring\fR,...]]   [\fBerror\fR=\fIname\fR]  \fBtool\fR=\fIstring\fR[,\fIstring\fR,...]  [\fBthresh\fR=\fIfloat\fR[,\fIfloat\fR,...]]   [--\fBoverwrite\fR]  [--\fBverbose\fR]  [--\fBquiet\fR] 
.SS Flags:
.IP "\fB-b\fR" 4m
.br
Don't build topology for the output vector
.IP "\fB--overwrite\fR" 4m
.br
Allow output files to overwrite existing files
.IP "\fB--verbose\fR" 4m
.br
Verbose module output
.IP "\fB--quiet\fR" 4m
.br
Quiet module output
.PP
.SS Parameters:
.IP "\fBinput\fR=\fIname\fR" 4m
.br
Name of input vector map
.IP "\fBoutput\fR=\fIname\fR" 4m
.br
Name for output vector map
.IP "\fBtype\fR=\fIstring[,\fIstring\fR,...]\fR" 4m
.br
Feature type
.br
Options: \fIpoint,line,boundary,centroid,area,face,kernel\fR
.br
Default: \fIpoint,line,boundary,centroid,area\fR
.IP "\fBerror\fR=\fIname\fR" 4m
.br
Name of output map where errors are written
.IP "\fBtool\fR=\fIstring[,\fIstring\fR,...]\fR" 4m
.br
Cleaning tool
.br
Options: \fIbreak,snap,rmdangle,chdangle,rmbridge,chbridge,rmdupl,rmdac,bpol,prune,rmarea,rmline,rmsa\fR
.br
\fBbreak\fR: break lines at each intersection
.br
\fBsnap\fR: snap lines to vertex in threshold
.br
\fBrmdangle\fR: remove dangles, threshold ignored if < 0
.br
\fBchdangle\fR: change the type of boundary dangle to line, threshold ignored if < 0, input line type is ignored
.br
\fBrmbridge\fR: remove bridges connecting area and island or 2 islands
.br
\fBchbridge\fR: change the type of bridges connecting area and island or 2 islands from boundary to line
.br
\fBrmdupl\fR: remove duplicate geometry features (pay attention to categories!)
.br
\fBrmdac\fR: remove duplicate area centroids ('type' option ignored)
.br
\fBbpol\fR: break (topologically clean) polygons (imported from non topological format, like ShapeFile). Boundaries are broken on each point shared between 2 and more polygons where angles of segments are different
.br
\fBprune\fR: remove vertices in threshold from lines and boundaries, boundary is pruned only if topology is not damaged (new intersection, changed attachement of centroid), first and last segment of the boundary is never changed
.br
\fBrmarea\fR: remove small areas, the longest boundary with adjacent area is removed
.br
\fBrmline\fR: remove all lines or boundaries of zero length, threshold is ignored
.br
\fBrmsa\fR: remove small angles between lines at nodes
.IP "\fBthresh\fR=\fIfloat[,\fIfloat\fR,...]\fR" 4m
.br
Threshold
.br
Threshold in map units, one value for each tool (default: 0.0[,0.0,...])
.PP
.SH DESCRIPTION
\fIv.clean\fR allows the user to automatically fix topology of vector 
maps.
.SS Break lines/boundaries
\fItool=break\fR
.PP
Threshold does not apply, use dummy value if \fIv.clean\fR is 
run with several tools.
.PP
The \fIbreak\fR tool breaks lines/boundaries at intersections and also 
breaks lines/boundaries forming a collapsed loop, for example 0.0;1.0;0.0 
is broken at 1.0.
.PP
Breaking lines should be followed by removing duplicates, e.g. 
\fIv.clean tool=break,rmdupl\fR.
.SS Remove duplicate geometry features
\fItool=rmdupl\fR
.PP
Threshold does not apply, use dummy value if \fIv.clean\fR is 
run with several tools.
.PP
The \fIrmdupl\fR tool removes geometry features with identical 
coordinates. Categories are merged. If a point and a centroid have 
identical coordinates, one of them will be removed if both points and 
centroids are selected with \fIv.clean type=point,centroid\fR. The 
same applies for lines and boundaries.
.PP
The \fIrmdupl\fR tool should be used after breaking lines and 
breaking polygons.
.SS Remove dangles or change boundary dangles to type line
\fItool=rmdangle\fR and \fItool=chdangle\fR
.PP
Threshold gives maximum line/boundary length in map units, degrees for 
latlon. Dangles shorter than \fIthresh\fR are removed sequentially. 
All dangles will be removed if \fIthresh\fR < 0.
.PP
A line/boundary is considered to be a dangle if no other line of given 
\fItype\fR is on at least one end node. If a dangle is formed by 
several lines, such a string of lines is taken as one dangle and line 
lengths are summarized. The \fIrmdangle\fR tool deletes a dangle if 
the (combined) length is shorter than \fIthres\fR or \fIthres\fR 
< 0. If the combined length is larger than \fIthresh\fR, nothing 
is deleted.
.PP
With \fIthresh\fR < 0, only closed loops and lines connecting 
loops will remain. This is useful to remove all incorrect boundaries 
after other cleaning operations with \fIthres\fR is < 0. Areas can 
then be successfully built. 
.PP
To preferentially remove shortest dangles first, a first pass with a 
small \fIthresh\fR value can be followed by subsequent passes with 
increasing \fIthresh\fR values.
.PP
The \fIchdangle\fR tool is similar to the \fIrmdangle\fR tool, but 
works only on boundaries and changes dangling boundaries to lines 
instead of removing dangles.
.SS Remove or change bridges connecting an area and an island or two islands
\fItool=rmbridge\fR and \fItool=chbridge\fR
.PP
Threshold does not apply, use dummy value if \fIv.clean\fR is 
run with several tools.
.PP
A bridge is an area type connection of an island (polygon in a polygon) 
to the outer polygon. This is topologically incorrect (but OGC Simple 
Features allow it). The \fIrmbridge\fR tool removes bridges and the 
\fIchbridge\fR tool changes bridges to type line:
\fC
.DS
.br
    +-------------+             +-------------+   +-------------+
.br
    |            P|  P: polygon |            P|   |            P|
.br
    |    +---+    |  I: island  |    +---+    |   |    +---+    |
.br
    |    | I |    |  B: bridge  |    | I |    |   |    | I |    |
.br
    |    |   |    |  L: line    |    |   |    |   |    |   |    |
.br
    |    +-+-+    |             |    +---+    |   |    +-.-+    |
.br
    |      |      |             |             |   |      .      |
.br
    |      | B    |             |             |   |      . L    |
.br
    |      |      |             |             |   |      .      |
.br
    +------+------+             +-------------+   +-------------+
.br
.DE
\fR
.PP
Islands and areas must be already clean, i.e. without dangles or small 
angles, e.g. \fIv.clean type=boundary tool=rmdangle,rmsa,break,rmdupl,rmbridge 
thresh=-1,0,0,0,0\fR.
.SS Snap lines to vertex in threshold
\fItool=snap\fR
.PP
Threshold gives maximum distance to another vertex in map units, 
degrees for latlon. 
.PP
The \fIsnap\fR tool snaps vertices to another vertex not farther away 
than \fIthresh\fR. If there is no other vertex within \fIthresh\fR, 
no snapping will be done. The \fItype\fR option can have a strong 
influence on the result. A too large threshold and \fItype=boundary\fR
can severely damage area topology, beyond repair.
.PP
Snapped boundaries may need to be cleaned with \fIbreak,rmdupl,rmsa\fR.
.SS Remove duplicate area centroids
\fItool=rmdac\fR
.PP
Threshold does not apply, use dummy value if \fIv.clean\fR is 
run with several tools.
.PP
The \fIrmdac\fR tool removes duplicate area centroids that can result 
from deleting boundaries.
.SS Break (topologically clean) areas (imported from a non topological 
format like ShapeFile)
\fItool=bpol\fR
.PP
Threshold does not apply, use dummy value if \fIv.clean\fR is 
run with several tools.
.PP
The \fIbpol\fR tool breaks boundaries on each point shared between 2 
and more areas where angles of boundary segments are different and on 
all boundary nodes (start and end points of each boundary). The 
\fIbpol\fR tool behaves similar to \fIbreak\fR for boundaries, but 
does not break collapsed loops. The \fIbpol\fR tool is faster than 
the \fIbreak\fR tool but needs more memory.
.PP
The \fIbpol\fR tool should be followed by \fIrmdupl\fR.
.SS Remove vertices in threshold from lines and boundaries
\fItool=prune\fR
.PP
The \fIprune\fR tool simplifies lines and boundaries by removing
vertices according to threshold. This tool preserves area topology,
areas are never deleted and centroid attachment is never changed.
\fIv.generalize\fR offers much more
functionality for line simplification but does not preserve area
topology.
.SS Remove small areas
\fItool=rmarea\fR
.PP
Threshold gives area size in map units, square meters for latlon.
.PP
The \fIrmarea\fR tool removes all areas <= \fIthresh\fR. The 
longest boundary with an adjacent area is removed or all boundaries if 
there is no adjacent area. Area categories are not combined when a small 
area is merged with a larger area.
.SS Remove all lines or boundaries of zero length
\fItool=rmline\fR
.PP
Threshold does not apply, use dummy value if \fIv.clean\fR is 
run with several tools.
.PP
The \fIrmline\fR tool removes all lines or boundaries of zero length 
that may have resulted from other cleaning operations. Zero length 
boundaries are redundant and do not influence area topology.
.SS Remove small angles between lines at nodes
\fItool=rmsa\fR
.PP
Threshold does not apply, use dummy value if \fIv.clean\fR is 
run with several tools.
.PP
The \fIrmsa\fR tool only concerns angles which are so small that the 
calculated angle is 0. The following figure should help demonstrate what 
the tool does.
.PP
.br
	| 
.br
	| 
\fItool=rmsa\fR
.PP
The \fIrmsa\fR tool should be followed by \fIbreak,rmdupl\fR. The 
\fIrmsa\fR tool followed by \fIbreak,rmdupl\fR may need to be run 
more than once to remove all small angles.
.SH NOTES
The user does \fBnot\fR have to run \fIv.build\fR
on the \fIoutput\fR vector, unless the \fI-b\fR flag was used. The
\fI-b\fR flag affects \fBonly\fR the \fIoutput\fR vector - 
topology is always built for \fIerror\fR vector.
.SH EXAMPLES
.SS Snap lines to vertex in threshold
\fC
.DS
.br
v.clean input=testmap output=cleanmap tool=snap thresh=1
.br
.DE
\fR
.SS Cleaning OGR imported data (Simple Feature data)
The import of areas with \fIv.in.ogr -c\fR
(no cleaning) requires a subsequent run of \fIv.clean\fR to update 
the map to a topologically valid structure (removal of duplicate 
collinear lines etc). The tools used for that are \fIbpol\fR and 
\fIrmdupl\fR:
\fC
.DS
.br
v.clean input=areamap output=areamap_clean tool=bpol,rmdupl type=boundary
.br
.DE
\fR
.SS Extracting intersection points of vector lines
\fC
.DS
.br
v.clean input=lines1 output=lines2 err=points tool=break type=line
.br
.DE
\fR
Intersection points are written to 'points' map.
.SS Break lines
\fIv.clean\fR will break the lines where they cross, 
creating new node if needed. Example:
\fC
.DS
.br
v.in.ascii -n out=crossed_lines format=standard << EOF
.br
L 2
.br
 0 5
.br
 10 5
.br
L 2
.br
 5 0
.br
 5 10
.br
EOF
.br
.br
v.clean in=crossed_lines out=crossed_lines_brk \(rs
.br
        error=intersection tool=break type=line
.br
.DE
\fR
.SS Remove all lines of zero length
\fC
.DS
.br
v.out.ascii zero format=standard 
.br
L  2 1
.br
 -819832.09065589 -987825.2187231
.br
 -806227.28362601 -971104.80702988
.br
 1     1         
.br
L  2 1
.br
 -799165.24638913 -972974.16982788
.br
 -799165.24638913 -972974.16982788
.br
 1     2         
.br
.br
v.clean input=zero output=zero_clean tool=rmline type=line
.br
.br
v.out.ascii zero_clean format=standard 
.br
L  2 1
.br
 -819832.09065589 -987825.2187231
.br
 -806227.28362601 -971104.80702988
.br
 1     1         
.br
.DE
\fR
v.clean type=boundary would remove nothing.
.SS Repeatedly remove dangling lines up to 50m length
\fC
.DS
.br
v.clean input=testmap output=cleanmap type=line tool=rmdangle,rmdangle,rmdangle,rmdangle thresh=5,10,20,50
.br
.DE
\fR
.SH SEE ALSO
\fI
v.info,
v.build,
v.digit,
v.edit
\fR
.SH AUTHORS
David Gerdes, U.S. Army Construction Engineering Research Laboratory
.br
Radim Blazek, ITC-irst, Trento, Italy
.br
Martin Landa, FBK-irst (formerly ITC-irst), Trento, Italy
.br
.PP
\fILast changed: $Date: 2011-11-08 12:29:50 +0100 (Tue, 08 Nov 2011) $\fR
.PP
Full index
.PP
© 2003-2011 GRASS Development Team