[GRASS-SVN] r43632 - grass/branches/releasebranch_6_4/lib/vector

[svn_grass at osgeo.org]

Author: neteler
Date: 2010-09-22 20:11:06 +0000 (Wed, 22 Sep 2010)
New Revision: 43632

Modified:
   grass/branches/releasebranch_6_4/lib/vector/vectorlib.dox
Log:
backport: topology explanations

Modified: grass/branches/releasebranch_6_4/lib/vector/vectorlib.dox
===================================================================
--- grass/branches/releasebranch_6_4/lib/vector/vectorlib.dox	2010-09-22 20:08:47 UTC (rev 43631)
+++ grass/branches/releasebranch_6_4/lib/vector/vectorlib.dox	2010-09-22 20:11:06 UTC (rev 43632)
@@ -108,7 +108,7 @@
 <ul>
 <li> multi-layer: features in one vector map may represent more layers and 
     may be linked to more external tables (see \ref vlib_categories_layers);
-<li> 2D and 3D vector geometry with topology (see \ref vlib_topology_management);
+<li> 2D and 3D vector geometry with full topology support for 2D and partial topology support for 3D (see \ref vlib_topology_management);
 <li> multi-format: external data formats supported (SHAPE-file, OGR sources etc.);
 <li> portability: platform independent internal format, read- and writable on 32bit,
       64bit etc. computer architectures;
@@ -143,13 +143,18 @@
 <li> boundary: the border line to describe an area;
 <li> centroid: a point within a closed boundary;
 <li> area: the topological composition of a closed ring of boundaries and optionally a centroid;
-<li> face: a 3D area;
+<li> face: a 3D boundary;
 <li> kernel: a 3D centroid in a volume;
 <li> volume: a 3D corpus, the topological composition of faces and kernel.
 </ul>
 
-Note that all lines and boundaries can have multiple vertices and segments. 
+Note that all lines and boundaries can be polylines (with nodes in
+between).
 
+Area topology also holds information about isles. Isles are located within an area, not
+touching the boundaries of the outer area. Isles consist of one or more areas
+and are used internally by the vector libraries to maintain correct topology of areas.
+
 \section libraries Vector libraries
 
 Besides internal library functions there are two main libraries:
@@ -163,7 +168,7 @@
 
 <ul>
 <li> diglib (with dig_*() functions), GRASS 3.x/4.x
-<li> Vlib (with V1_*(), V2_*() and Vect_*() functions), GRASS 6.x (except for the 5.7 interim version)
+<li> Vlib (with V1_*(), V2_*() and Vect_*() functions), since GRASS 4.x (except for the 5.7 interim version)
 </ul>
 
 The vector library was introduced in GRASS 4.0 to hide internal vector
@@ -402,9 +407,9 @@
 <TR><TD>Name</TD><TD>Type</TD><TD>Number</TD><TD>Description</TD></TR>
 <TR><TD>n_lines</TD><TD>I</TD><TD>1</TD><TD>number of boundaries</TD></TR>
 <TR><TD>lines</TD><TD>I</TD><TD>n_lines</TD><TD>Line ids</TD></TR>
-<TR><TD>area</TD><TD>I</TD><TD>1</TD><TD>Area id</TD></TR>
-<TR><TD>N,S,E,W</TD><TD>D</TD><TD>4</TD><TD>Area bounding box</TD></TR>
-<TR><TD>T,B</TD><TD>D</TD><TD>2</TD><TD>Area bounding box for 3D (only if with_z=1)</TD></TR>
+<TR><TD>area</TD><TD>I</TD><TD>1</TD><TD>Outer area id</TD></TR>
+<TR><TD>N,S,E,W</TD><TD>D</TD><TD>4</TD><TD>Isle bounding box</TD></TR>
+<TR><TD>T,B</TD><TD>D</TD><TD>2</TD><TD>Isle bounding box for 3D (only if with_z=1)</TD></TR>
 </TABLE>
 
 <b>Feature types:</b>
@@ -486,15 +491,37 @@
 +---------+
 \endverbatim
 
-In GRASS, whenever an 'inner' ring touches the boundary of an outside
-area, even in one point, it is no longer an 'inner' ring (Isle in
-GRASS topology), it is simply another area. A, B above can never be
-exported from GRASS as polygon A with inner ring B because there are
-only 2 areas A and B and one island formed by A and B together.
+In GRASS, whenever an 'inner' ring touches the boundary of an outside area, even in
+one point, it is no longer an 'inner' ring (Isle in GRASS topology), it is
+simply another area. A, B above can never be exported from GRASS as polygon A
+with inner ring B because there are only 2 areas A and B and one island
+formed by A and B together.
 
 
 \subsection Topology_Example_3 Topology Example 3:
 
+This is handled correctly in GRASS: Areas A1, A2, and A3 can be filled differently.
+
+\verbatim
++---------------------+
+|  A1                 |
++   +------+------+   |
+|   |  A2  |  A3  |   |
++   +------+------+   |
+|          I1         |
++---------------------+
+\endverbatim
+
+In GRASS, whenever an 'inner' ring does not touch the boundary of an outside area,
+also not in one point, it is an 'inner' ring (Isle). The areas A2 and A3 form a
+single Isle I1 located within area A1. The size of Isle I1 is substracted from
+the size of Area A1 when calculating the size of Area A1. Any centroids falling
+into Isle I1 are excluded when searching for a centroid that can be attached to
+Area A1. A1 above can be exported from GRASS as polygon A1 with inner ring I1.
+
+
+\subsection Topology_Example_4 Topology Example 4:
+
 v.in.ogr/v.clean can identify dangles and change the type from boundary
 to line (in TIGER data for example). 
 Distinction between line and boundary isn't important only for dangles. Example: