[GRASS-SVN] r52573 - grass/trunk/lib/vector
svn_grass at osgeo.org
svn_grass at osgeo.org
Tue Aug 7 05:40:44 PDT 2012
Author: mmetz
Date: 2012-08-07 05:40:43 -0700 (Tue, 07 Aug 2012)
New Revision: 52573
Modified:
grass/trunk/lib/vector/vectorlib.dox
Log:
vectorlib.dox: add examples, minor updates
Modified: grass/trunk/lib/vector/vectorlib.dox
===================================================================
--- grass/trunk/lib/vector/vectorlib.dox 2012-08-07 09:58:05 UTC (rev 52572)
+++ grass/trunk/lib/vector/vectorlib.dox 2012-08-07 12:40:43 UTC (rev 52573)
@@ -76,7 +76,9 @@
in a PostGIS database (accessible via OGR interface). This enables
users to maintain large data sets with simultaneous write
access. External GIS formats such as SHAPE-files may be used directly,
-without requiring format conversion.
+without requiring format conversion. All vector data accessed through
+the OGR interface have only pseudo-topology and only a limited subset
+of vector operations can be performed.
The current implementation includes:
@@ -103,16 +105,16 @@
x,y,z coordinate pairs. The two endpoints of an arc are called
<em>nodes</em>. Two consecutive x,y,z pairs define an arc segment. The
user specifies the type of input to GRASS; GRASS doesn't decide. GRASS
-allows for the feature definition which allows for multiple types to
-co-exist in the same map. Centroid are assigned to area it is
-within/inside (geometrically). An area is identified by an x,y,z
-centroid point geometrically inside with a category number. This
-identifies the area. Such centroids are stored in the same binary
+supports feature type definition which allows for multiple types to
+co-exist in the same map. A centroid is assigned to the area it is
+within/inside (geometrically). An area is defined by one or more
+boundaries that form a losed ring. The category to which an area belongs
+is stored with the centroid. Such centroids are stored in the same binary
'coor' file with other primitives. Each element may have none, one or
-more categories (cats). More cats are distinguished by field number
+more categories (cats). More cats can be distinguished by field number
(field, called "layer" at user level). Single and multi-category
-support on modules level are implemented. Z-coordinate is optional and
-both 2D and 3D files may be written.
+support on modules level are implemented. The z coordinate is optional
+and both 2D and 3D files may be written.
The following <em>vector feature types (primitives)</em> are defined
by the vector library (and holds by the coor file; see also \ref
@@ -155,20 +157,118 @@
level.
- <i>Level Two</i> provides full access to all the information
including topology information. This level requires more from the
- programmer, more memory, and longer startup time.
+ programmer, more memory, and longer startup time. Without this level,
+ areas are not available.
-Level of access is retured by Vect_open_old().
+The level of access is retured by Vect_open_old().
+<b>Example for sequential read access without topology:</b>
+\code
+int main
+{
+ int type, ltype;
+ struct Map_info Map;
+ struct line_pnts *Points;
+ struct line_cat *Cats;
+ const char *name, *mapset;
+
+ /* set open level to 1: no topology */
+ Vect_set_open_level(1);
+
+ if (Vect_open_old(&Map, name, mapset) < 1)
+ G_fatal_error(_("Failed to open vector '%s'"), name);
+
+ /* rewind vector file */
+ Vect_rewind(&Map);
+
+ Points = Vect_new_line_struct();
+ Cats = Vect_new_cats_struct();
+
+ while ((ltype = Vect_read_next_line(&Map, Points, Cats) > 0) {
+
+ /* check for desired type */
+ if (!(ltype & type))
+ continue;
+
+ /* process the feature */
+ }
+
+ exit(EXIT_SUCCESS);
+}
+\endcode
+
+<b>Example for random read access with topology:</b>
+\code
+int main
+{
+ int line, nlines, type, ltype;
+ struct Map_info Map;
+ struct line_pnts *Points;
+ struct line_cat *Cats;
+ const char *name, *mapset;
+
+ if (Vect_open_old(&Map, name, mapset) < 2)
+ G_fatal_error(_("Failed to open vector '%s'"), name);
+
+ Points = Vect_new_line_struct();
+ Cats = Vect_new_cats_struct();
+
+ nlines = Vect_get_num_lines(&Map);
+ for (line = 1; line <= nlines; line++) {
+
+ /* check for desired type */
+ if (!(Vect_get_line_type(&Map, line) & type))
+ continue;
+
+ Vect_read_line(&Map, points, cats, line);
+
+ /* process the feature */
+ }
+
+ exit(EXIT_SUCCESS);
+}
+\endcode
+
+
+<b>Example for working with areas (requires topology):</b>
+\code
+int main
+{
+ int area, nareas;
+ struct Map_info Map;
+ struct line_cat *Cats;
+ const char *name, *mapset;
+
+ if (Vect_open_old(&Map, name, mapset) < 2)
+ G_fatal_error(_("Failed to open vector '%s'"), name);
+
+ Points = Vect_new_line_struct();
+ Cats = Vect_new_cats_struct();
+
+ nareas = Vect_get_num_areas(&Map);
+ for (area = 1; area <= nareas; area++) {
+
+ /* process the area */
+ /* example: get area categories */
+ if (Vect_get_area_cats(&Map, area, Cats) == -1)
+ G_message(_("No catagory available for area %d"), area);
+ }
+
+ exit(EXIT_SUCCESS);
+}
+\endcode
+
+
<em>Note:</em> Higher level of access are planned, so when checking
success return codes for a particular level of access (when calling
Vect_open_old() for example), the programmer should use >= instead of
== for compatibility with future releases.
-An existing vector map can be open for reading by Vect_open_old(). New
-vector map can be created (or open for writing) by
+An existing vector map can be opened for reading by Vect_open_old().
+A new vector map can be created (or open for writing) by
Vect_open_new(). Vect_open_old() attempts to open a vector map at the
highest possible level of access. It will return the number of the
-level at which it opened. Vect_open_new() always opens at level 1
+level at which the map was opened. Vect_open_new() always opens at level 1
only. If you require that a vector map be opened at a lower level
(e.g. one), you can call the routine <tt>Vect_set_open_level(1)</tt>;
Vect_open_old() will then either open at level one or fail. If you
More information about the grass-commit
mailing list