[GRASS-SVN] r46962 - grass/trunk/lib/vector
svn_grass at osgeo.org
svn_grass at osgeo.org
Mon Jul 4 06:52:04 EDT 2011
Author: mmetz
Date: 2011-07-04 03:52:03 -0700 (Mon, 04 Jul 2011)
New Revision: 46962
Modified:
grass/trunk/lib/vector/vectorlib.dox
Log:
update vetorlib documentation
Modified: grass/trunk/lib/vector/vectorlib.dox
===================================================================
--- grass/trunk/lib/vector/vectorlib.dox 2011-07-04 10:50:45 UTC (rev 46961)
+++ grass/trunk/lib/vector/vectorlib.dox 2011-07-04 10:52:03 UTC (rev 46962)
@@ -622,23 +622,25 @@
- the format is topological (areas build from boundaries)
- currently only 2D topology is supported
-Topology is written for native format while pseudo-topology (polygons
-constracted from boundaries) is written for OGR sources, see
+Topology is written for native format while pseudo-topology (boundaries
+constructed from polygons) is written for OGR sources, see
<tt>v.external</tt> module.
The following rules apply to the vector data:
-- Lines should not cross each other (i.e., lines which would cross must
- be split at their intersection to form distict lines).
-- Linear primitives which share nodes at exactly same points (i.e.,
- must be snapped together). This is particulary important since nodes
- are not exactly represented in the coor file, but only implicitly as
- endpoints of lines.
+- Boundaries should not cross each other (i.e., boundaries which would
+ cross must be split at their intersection to form distict boundaries).
+ Lines can cross each other, e.g. bridges over rivers.
+- Lines and boundaries share nodes only if their endpoints are identical.
+ Lines or boundaries canbe forced to share a common node by snapping
+ them together. This is particulary important since nodes
+ are not represented in the coor file, but only implicitly as
+ endpoints of lines and boundaries.
- Common area boundaries should appear only once (i.e., should not be
double digitized).
- Areas must be explicitly closed. This means that it must be possible
to complete each area by following one or more boundaries that are
- connected by common nodes, and that such tracings result is closed
+ connected by common nodes, and that such tracings result in closed
areas.
- It is recommended that area features and linear features be placed
in separate layers. However if area features and linear features
@@ -647,7 +649,7 @@
field boundary), should be digitized as a boundary to complete the
area. The area feature should be labeled by a centroid as an
area. Additionally, the common boundary itself (i.e., the boundary
- which is also a line) should be labeled as a line by a distict
+ which is also a line) should be labeled as a line by a distinct
category number.
Vector map topology can be cleaned at user level by <tt>v.clean</tt>
@@ -659,7 +661,7 @@
\subsubsection vlibTopoFileHead Header
-<i>Note:</i> <tt>plus</tt> is instance of \ref Plus_head data structure.
+<i>Note:</i> <tt>plus</tt> is an instance of \ref Plus_head data structure.
<table border="1" style="border-collapse: collapse" cellpadding="5">
<tr><td><b>Name</b></td><td><b>Type</b></td><td><b>Number</b></td><td><b>Description</b></td></tr>
@@ -719,13 +721,11 @@
<tr><td><b>Name</b></td><td><b>Type</b></td><td><b>Number</b></td><td><b>Description</b></td></tr>
<tr><td>feature type</td><td>C</td><td>1</td><td>0 for dead</td></tr>
<tr><td>offset</td><td>L</td><td>1</td><td>Line offset</td></tr>
-<tr><td>N1</td><td>I</td><td>1</td><td>First node id (only if feature type is GV_POINTS, GV_LINES or GV_KERNEL)</td></tr>
+<tr><td>N1</td><td>I</td><td>1</td><td>First node id (only if feature type is GV_LINE or GV_BOUNDARY)</td></tr>
<tr><td>N2</td><td>I</td><td>1</td><td>Second node id (only if feature type is GV_LINE or GV_BOUNDARY)</td></tr>
<tr><td>left</td><td>I</td><td>1</td><td>Left area id for feature type GV_BOUNDARY / Area id for feature type GV_CENTROID</td></tr>
<tr><td>right</td><td>I</td><td>1</td><td>Right area id (for feature type GV_BOUNDARY)</td></tr>
<tr><td>vol</td><td>I</td><td>1</td><td>Reserved for kernel (volume number, for feature type GV_KERNEL)</td></tr>
-<tr><td>N,S,E,W</td><td>D</td><td>4</td><td>Line bounding box (for feature type GV_LINE, GV_BOUNDARY or GV_FACE)</td></tr>
-<tr><td>T,B</td><td>D</td><td>2</td><td>Line bounding box for 3D (only if with_z=1)</td></tr>
</table>
See \ref P_line data structure.
@@ -741,8 +741,6 @@
<tr><td>n_isles</td><td>I</td><td>1</td><td>Number of isles</td></tr>
<tr><td>isles</td><td>I</td><td>n_isles</td><td>Isle ids</td></tr>
<tr><td>centroid</td><td>I</td><td>1</td><td>Centroid 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>
</table>
See \ref P_area data structure.
@@ -756,8 +754,6 @@
<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>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>
See \ref P_isle data structure.
@@ -774,8 +770,8 @@
- GV_BUILD_CENTROIDS
- GV_BUILD_ALL
-<i>Note:</i> GV_BOUNDARY contains geometry and it is used to build
-areas. GV_LINE cannot form an area.
+<i>Note:</i> Only the geometry type GV_BOUNDARY is used to build
+areas. The geometry type GV_LINE cannot form an area.
\subsection vlibTopoExamples Topology examples
@@ -798,7 +794,6 @@
\verbatim
line = 1, type = 1, offset = 18 n1 = 1, n2 = 1, left/area = 0, right = 0
-N,S,E,W,T,B: 225105.223577, 225105.223577, 631286.707172, 631286.707172, 0.000000, 0.000000
\endverbatim
<b>Lines</b>
@@ -829,19 +824,18 @@
\verbatim
line = 1, type = 2, offset = 18 n1 = 1, n2 = 2, left/area = 0, right = 0
-N,S,E,W,T,B: 223557.302231, 221667.849899, 638677.484787, 634624.746450, 0.000000, 0.000000
\endverbatim
<b>Areas without holes</b>
\verbatim
-One line (nodes: 2, lines: 2, areas: 1, isles: 1)
+Two lines (nodes: 1, lines: 2, areas: 1, isles: 1)
+N1
/ \
/ \
/ \
- / +N2/L2 \
+ / +L2 \
/ \
-------L1------
\endverbatim
@@ -854,32 +848,22 @@
line = -1, type = 4, angle = -0.842926
\endverbatim
-%Node N2 (see \ref P_Node)
-
-\verbatim
-node = 2, n_lines = 1, xyz = 635779.454021, 223100.127232, 0.000000
- line = 2, type = 8, angle = -9.000000
-\endverbatim
-
Line L1 (see \ref P_Line)
\verbatim
line = 1, type = 4, offset = 18 n1 = 1, n2 = 1, left/area = 1, right = -1
-N,S,E,W,T,B: 225063.387424, 222188.133874, 638184.584178, 633419.878296, 0.000000, 0.000000
\endverbatim
Line L2 (see \ref P_Line)
\verbatim
line = 2, type = 8, offset = 87 n1 = 2, n2 = 2, left/area = 1, right = 0
-N,S,E,W,T,B: 223100.127232, 223100.127232, 635779.454021, 635779.454021, 0.000000, 0.000000
\endverbatim
Area A1 (see \ref P_Area)
\verbatim
area = 1, n_lines = 1, n_isles = 0 centroid = 2
-N,S,E,W,T,B: 225063.387424, 222188.133874, 638184.584178, 633419.878296, 0.000000, 0.000000
line = -1
\endverbatim
@@ -887,23 +871,22 @@
\verbatim
isle = 1, n_lines = 1 area = 0
-N,S,E,W,T,B: 225063.387424, 222188.133874, 638184.584178, 633419.878296, 0.000000, 0.000000
line = 1
\endverbatim
<b>Areas with holes</b>
\verbatim
-One line (nodes: 3, lines: 3, areas: 2, isles: 2)
+Three lines (nodes: 2, lines: 3, areas: 2, isles: 2)
+N1
/ \
/ \
/ \
/ \
- / +N2/L2 \
+ / +L2 \
/ \
- / +N3 \
+ / +N2 \
/ /\ \
/ / \ \
/ / \ \
@@ -923,13 +906,6 @@
%Node N2 (see \ref P_Node)
\verbatim
-node = 2, n_lines = 1, xyz = 635779.454021, 223100.127232, 0.000000
- line = 2, type = 8, angle = -9.000000
-\endverbatim
-
-%Node N3 (see \ref P_Node)
-
-\verbatim
node = 3, n_lines = 2, xyz = 636788.032454, 223173.935091, 0.000000
line = 3, type = 4, angle = -2.245537
line = -3, type = 4, angle = -0.866302
@@ -939,28 +915,24 @@
\verbatim
line = 1, type = 4, offset = 18 n1 = 1, n2 = 1, left/area = 1, right = -1
-N,S,E,W,T,B: 225063.387424, 222188.133874, 638184.584178, 633419.878296, 0.000000, 0.000000
\endverbatim
Line L2 (see \ref P_Line)
\verbatim
line = 2, type = 8, offset = 87 n1 = 2, n2 = 2, left/area = 1, right = 0
-N,S,E,W,T,B: 223100.127232, 223100.127232, 635779.454021, 635779.454021, 0.000000, 0.000000
\endverbatim
Line L3 (see \ref P_Line)
\verbatim
line = 3, type = 4, offset = 197 n1 = 3, n2 = 3, left/area = 2, right = -2
-N,S,E,W,T,B: 223173.935091, 222626.267748, 637253.549696, 636349.898580, 0.000000, 0.000000
\endverbatim
Area A1 (see \ref P_Area)
\verbatim
area = 1, n_lines = 1, n_isles = 1 centroid = 2
-N,S,E,W,T,B: 225063.387424, 222188.133874, 638184.584178, 633419.878296, 0.000000, 0.000000
line = -1
isle = 2
\endverbatim
@@ -969,7 +941,6 @@
\verbatim
area = 2, n_lines = 1, n_isles = 0 centroid = 0
-N,S,E,W,T,B: 223173.935091, 222626.267748, 637253.549696, 636349.898580, 0.000000, 0.000000
line = -3
\endverbatim
@@ -977,7 +948,6 @@
\verbatim
isle = 1, n_lines = 1 area = 0
-N,S,E,W,T,B: 225063.387424, 222188.133874, 638184.584178, 633419.878296, 0.000000, 0.000000
line = 1
\endverbatim
@@ -985,13 +955,12 @@
\verbatim
isle = 2, n_lines = 1 area = 1
-N,S,E,W,T,B: 223173.935091, 222626.267748, 637253.549696, 636349.898580, 0.000000, 0.000000
line = 3
\endverbatim
<b>Example 1</b>
-A polygon may be formed by many boundaries (more primitives but connected).
+A polygon may be formed by many boundaries (several connected primitives).
One boundary is shared by adjacent areas.
\verbatim
@@ -1098,12 +1067,14 @@
\section vlibSpidx Vector library spatial index management
-Spatial index (based on R-tree) is created with topology, see \ref
+Spatial index (based on R*-tree) is created with topology, see \ref
RTree data structure.
Spatial index occupies a lot of memory but it is necessary for
-topology building. Also, it takes a long time to release the memory
-occupied by spatial index (see dig_spidx_free()).
+topology building. Also, it takes some time to release the memory
+occupied by spatial index (see dig_spidx_free()). The spatial index can
+also be built in file to save memory by setting the environment variable
+GRASS_VECTOR_LOWMEM.
The function building topology - Vect_build() - is usually called at
the end of modules (before Vect_close()) so it is faster to call
@@ -1111,7 +1082,7 @@
faster. By default the memory is not released.
It is possible to call Vect_set_release_support() before Vect_close()
-to enforce memory release, but it takes a long time on large files.
+to enforce memory release, but it takes some time on large files.
The spatial index is stored in file and not loaded for old vectors that
are not updated, saving a lot of memory. Spatial queries are done in
@@ -1146,7 +1117,7 @@
}
\endcode
-but it takes longer.
+but it takes a bit longer.
It makes sense to release the spatial index if it is used only at the beginning
of a module or in permanently running programs like QGIS. Note that this
@@ -1328,7 +1299,8 @@
work properly for adjacent areas or areas within areas.
Full topology is only available for native GRASS vectors or can only
-be built after all polygons are cleaned as done by <tt>v.in.ogr</tt>.
+be built after all polygons are converted to areas and cleaned as done
+by <tt>v.in.ogr</tt>.
\subsection vlibFrmtFileFormat Frmt file format specification
@@ -1391,10 +1363,10 @@
The Directed Graph Library library provides functionality to assign
costs to lines and/or nodes. That means that costs can be accumulated
while traveling along polylines. The user can assign individual costs
-to all lines and/or nodes of a vector map and later calculate shortest
+to all lines and/or nodes of a vector map and later calculate least costly
path connections based on the accumulated costs. Applications are
transport analysis, connectivity and more. Implemented applications
-cover shortest path, traveling salesman (round trip), allocation of
+cover shortest/fastest path, traveling salesman (round trip), allocation of
sources (creation of subnetworks), minimum Steiner trees (star-like
connections), and iso-distances (from centers).
@@ -2096,7 +2068,23 @@
- Vect_val_in_list()
+ - Vect_destroy_boxlist()
+ - Vect_boxlist_append()
+
+ - Vect_boxlist_append_boxlist()
+
+ - Vect_boxlist_delete()
+
+ - Vect_boxlist_delete_boxlist()
+
+ - Vect_new_boxlist()
+
+ - Vect_reset_boxlist()
+
+ - Vect_val_in_boxlist()
+
+
\section vlibMap Vector map functions
- Vect_copy()
@@ -2114,6 +2102,11 @@
- Vect_rename()
+\section vlibMergeLines Vector merge line functions
+
+ - Vect_merge_lines()
+
+
\section vlibNet Vector network functions
- Vect_net_build_graph()
@@ -2326,7 +2319,7 @@
Updates for GRASS 7:
-- Markus Metz (file-based spatial index)
+- Markus Metz (file-based spatial index, vector topology)
- Martin Landa (GEOS support, direct OGR read access) <landa.martin gmail.com>
More information about the grass-commit
mailing list