[GRASS-SVN] r52585 - in grass/trunk: . lib/vector
svn_grass at osgeo.org
svn_grass at osgeo.org
Tue Aug 7 10:45:22 PDT 2012
Author: wenzeslaus
Date: 2012-08-07 10:45:22 -0700 (Tue, 07 Aug 2012)
New Revision: 52585
Added:
grass/trunk/lib/vector/vectorlib_ascii.dox
grass/trunk/lib/vector/vectorlib_files.dox
grass/trunk/lib/vector/vectorlib_libraries.dox
grass/trunk/lib/vector/vectorlib_ogr.dox
grass/trunk/lib/vector/vectorlib_spatialindex.dox
grass/trunk/lib/vector/vectorlib_tin.dox
grass/trunk/lib/vector/vectorlib_topology.dox
Modified:
grass/trunk/grasslib.dox
grass/trunk/lib/vector/vectorlib.dox
Log:
vectorlib.dox: splitted to several pages (files), proper usage of subpage
Modified: grass/trunk/grasslib.dox
===================================================================
--- grass/trunk/grasslib.dox 2012-08-07 16:36:40 UTC (rev 52584)
+++ grass/trunk/grasslib.dox 2012-08-07 17:45:22 UTC (rev 52585)
@@ -108,10 +108,11 @@
\subsection vectoribs Vector Libraries
+ - %vector: \ref vectorlib
+ - dglib: \ref dglib
+ - vedit: \ref veditlib - %vector editing
+ - neta: \ref netalib
- sites: Old Sites library, now interfaced to \ref vectorlib - \ref sites
- - %vector: \ref vectorlib (GRASS Vector and Direct Graph Library)
- - vedit: \ref veditlib - %vector editing
- - neta: \ref netalib
\subsection dblibs Database Management Libraries
Modified: grass/trunk/lib/vector/vectorlib.dox
===================================================================
--- grass/trunk/lib/vector/vectorlib.dox 2012-08-07 16:36:40 UTC (rev 52584)
+++ grass/trunk/lib/vector/vectorlib.dox 2012-08-07 17:45:22 UTC (rev 52585)
@@ -2,53 +2,33 @@
by GRASS Development Team (http://grass.osgeo.org)
-<b>Table of contents</b>
+\par Table of contents
+- \ref vlibBackground
+- \ref vlibIntro
+- \ref vlibVectorMap
+- \ref vlibVectorLevels
+- \ref vlibCategoriesLayers
+- \ref vlibAttributes
+- \ref vlibGeometry
+ - \ref vlibFeatureTypes
+- \ref vlibStructures
+- \ref vlibFunc
+- \ref vlibAuthors
+- \ref vlibReferences
+- \ref vlibSeealso
-- \subpage vlibBackground
-- \subpage vlibIntro
- - \subpage vlibVectorMap
- - \subpage vlibVectorLevels
- - \subpage vlibDirectoryStructure
- - \subpage vlibHeadFileFormat
- - \subpage vlibCategoriesLayers
- - \subpage vlibAttributes
- - \subpage vlibDblnFileFormat
+\par Subpages
- \subpage vlibs
- - \subpage vlibHistory
-- \subpage vlibStructures
-- \subpage vlibGeometry
- - \subpage vlibFeatureTypes
- - \subpage vlibCoorFileFormat
- - \subpage vlibCoorFileHead
- - \subpage vlibCoorFileBody
-- \subpage vlibTopoManagement
- - \subpage vlibTopoFileFormat
- - \subpage vlibTopoFileHead
- - \subpage vlibTopoFileBody
- - \subpage vlibTopoLevels
- - \subpage vlibTopoExamples
- - \subpage vlibTopoMemory
-- \subpage vlibSpidx
- - \subpage vlibSidxFileFormat
-- \subpage vlibCidx
- - \subpage vlibCidxFileFormat
- - \subpage vlibCidxFileHead
-- \subpage vlibTin
-- \subpage vlibOgrIface
- - \subpage vlibFrmtFileFormat
- - \subpage vlibFidxFileFormat
-- \subpage vlibDglib
+- \subpage vlibFormat
+- \subpage vlibTopology
+- \subpage vlibSpatialIndex
- \subpage vlibAscii
+- \subpage vlibOgr
+- \subpage vlibTin
+- \subpage veditlib
+- \subpage dglib
+- \subpage netalib
-- \subpage vlibFunc
-
-- \subpage vlibAuthors
-
-- \subpage vlibReferences
-
-- \subpage vlibSeealso
-
-
\section vlibBackground Background
Generally, the vector data model is used to describe geographic
@@ -98,7 +78,7 @@
Database Management System (RDBMS) connected through DBMI
library and drivers (see \ref vlibAttributes)
-\subsection vlibVectorMap Vector map definition (native format)
+\section vlibVectorMap Vector map definition (native format)
GRASS vector maps are stored in an <em>arc-node</em> representation,
consisting of curves called arcs. An arc is stored as a series of
@@ -148,7 +128,7 @@
area. Isles consist of one or more areas and are used internally by
the vector library to maintain correct topology of areas.
-\subsubsection vlibVectorLevels Levels of read access
+\section vlibVectorLevels Levels of read access
There are two levels of read access to the vector data:
@@ -278,52 +258,10 @@
level at which you need access. This allows for future levels to work
without need for module change.
-\subsubsection vlibDirectoryStructure Directory structure
-Vector map is stored in a number of data files. Vector map directory
-structure and file names were changed in GRASS 6 with respect to
-previous GRASS versions. All vector files for one vector map are
-stored in one directory:
-\verbatim
-$MAPSET/vector/vector_name/
-\endverbatim
+\section vlibCategoriesLayers Categories and Layers
-This directory contains these files:
-
-- <b>coor</b> - binary file, coordinates [former dig/ file] (see \ref vlibCoorFileFormat)
-- <b>topo</b> - binary file, topology [former dig_plus/ file] (see \ref vlibTopoFileFormat)
-- <b>sidx</b> - binary file, spatial index (see \ref vlibSidxFileFormat)
-- <b>cidx</b> - binary file, category index (see \ref vlibCidxFileFormat)
-- <b>head</b> - text file, header information [former part of dig/ file] (see \ref vlibHeadFileFormat)
-- <b>dbln</b> - text file, link(s) to attribute table(s) (see \ref vlibDblnFileFormat)
-- <b>hist</b> - text file, vector map change history
-- <b>frmt</b> - text file, format description (external formats only)
-- <b>fidx</b> - binary file, feature index (OGR format only)
-
-\subsubsection vlibHeadFileFormat Header file format specification
-
-The header contains meta information, a description of the
-vector map and many other information. The file is an unordered list
-of key/value entries. The <i>key</i> is a string separated from
-<i>value</i> by a colon and optional whitespace.
-
-Keywords are:
-
-- ORGANIZATION - organization that digitized the data
-- DIGIT DATE - date the data was digitized
-- DIGIT NAME - person who digitized the data
-- MAP NAME - title of the original source map
-- MAP DATE - date of the original source map
-- MAP SCALE - scale of the original source map
-- OTHER INFO - other comments about the map
-- ZONE - zone of the map (e.g., UTM zone)
-- MAP THRESH - digitizing threshold
-
-This information holds \ref dig_head data structure.
-
-\subsection vlibCategoriesLayers Categories and Layers
-
<i>Note: "layer" was called "field" in earlier version.</i>
In GRASS, a "category" or "category number" is a vector feature ID
@@ -354,8 +292,9 @@
Information about categories holds \ref line_cats data structure.
-\subsection vlibAttributes Attributes
+\section vlibAttributes Attributes
+
The old GRASS 4.x 'dig_cats' files are not used any more and vectors'
attributes are stored in external database. Connection with the
database is done through drivers based on \ref dbmilib. Records in a
@@ -376,198 +315,7 @@
The general DBMI settings are defined in the '$MAPSET/VAR' text file
(maintained with <tt>db.connect</tt> command at user level).
-\subsection vlibDblnFileFormat DB link file format specification
-Each vector maps has its own DBMI settings stored in the
-'$MAPSET/vector/vector_name/dbln' text file. For each pair <em>vector map +
-layer</em>, all of <em>table, key column, database, driver</em> must be
-defined in a new row. This definition must be written to
-'$MAPSET/vector/vector_name/dbln' text file. Each row in the 'dbln'
-file contains names separated by spaces in following order ([ ] -
-optional):
-
-\verbatim
-map[@mapset] layer table [key [database [driver]]]
-\endverbatim
-
-If key, database or driver are omitted (on second and higher row only)
-the last definition is used. When reading a vector map from another
-mapset (if mapset is specified along with map name), definitions in
-the related "dbln" file may overwrite the DBMI definition in the
-current mapset. This means that the map-wise definition is always
-"stronger".
-
-Wild cards <b>*</b> and <b>?</b> may be used in map and mapset names.
-
-Variables $GISDBASE, $LOCATION_NAME, $MAPSET, and $MAP may be used in
-table, key, database and driver names (function
-Vect_subst_var()). Note that $MAPSET is not the current mapset but
-mapset of the map the rule is defined for.
-
-Note that vector features in GRASS vector maps may have attributes in
-different tables or may be without attributes. Boundaries form areas
-but it may happen that some boundaries are not closed (such boundaries
-would not appear in polygon layer). Boundaries may have
-attributes. All types may be mixed in one vector map.
-
-The link to the table is permanent and it is stored in 'dbln' file in
-vector directory. Tables are considered to be a part of the vector and
-the command <tt>g.remove</tt>, for example, deletes linked tables of
-the vector. Attributes must be joined with geometry.
-
-Information about database links holds \ref dblinks data structure.
-
-<b>Examples:</b>
-
-Examples are written mostly for the DBF driver, where database is full
-path to the directory with dbf files and table name is the name of dbf
-file without .dbf extension:
-
-\verbatim
-* 1 mytable id $GISDBASE/$LOCATION_NAME/$MAPSET/vector/$MAP dbf
-\endverbatim
-
-This definition says that entities with category of layer 1 are linked
-to dbf tables with names "mytable.dbf" saved in vector directories of
-each map. The attribute column containing the category numbers is
-called "id".
-
-\verbatim
-* 1 $MAP id $GISDBASE/$LOCATION_NAME/$MAPSET/dbf dbf
-\endverbatim
-
-Similar as above but all dbf files are in one directory dbf/ in mapset
-and names of dbf files are $MAP.dbf
-
-\verbatim
-water* 1 rivers id /home/grass/dbf dbf
-water* 2 lakes lakeid /home/guser/mydb
-trans* 1 roads key basedb odbc
-trans* 5 rails
-\endverbatim
-
-These definitions define more layers (called "field" in the API) for
-one vector map i.e. in one vector map may be more features linked to
-more attribute tables. Definitions on first 2 rows are applied for
-example on maps water1, water2, ... so that more maps may share one
-table.
-
-\verbatim
-water at PERMANENT 1 myrivers id /home/guser/mydbf dbf
-\endverbatim
-
-This definion overwrites the definition saved in PERMANENT/VAR and
-links the water map from PERMANENT mapset to the user's table.
-
-Modules should be written so that connections to databases for each
-vector layer are independent. It should be possible to read attributes
-of an input vector map from one database and write to some other and
-even with some other driver (should not be a problem).
-
-There are open questions, however. For one, how does one distinguish when
-new tables should be written and when not? For example, definitions:
-
-\verbatim
-river 1 river id water odbc
-river.backup* 1 NONE
-\endverbatim
-
-could be used to say that tables should not be copied for backups of
-map river because table is stored in a reliable RDBMS.
-
-\section vlibs Vector libraries
-
-Besides internal library functions there are two main libraries:
-
-- Vlib (Vector library), see \ref vlibIntro
-- DGLib (Directed Graph Library), see \ref vlibDglib
-
-For historical reasons, there are two internal libraries:
-
-- diglib (with dig_*() functions), GRASS 3.x/4.x
-- Vlib (with V1_*(), V2_*() and Vect_*() functions), since GRASS 4.x
- (except for the 5.7 interim version)
-
-The vector library was introduced in GRASS 4.0 to hide internal vector
-files' formats and structures. In GRASS 6/7, everything is accessed via
-Vect_*() functions, for example:
-
-Old 4.x code:
-
-\code
- xx = Map.Att[Map.Area[area_num].att].x;
-\endcode
-
-New 6.x/7.x functions:
-
-\code
- centroid = Vect_get_area_centroid(Map, area_num);
- Vect_read_line(Map, line_p, NULL, centroid);
- Vect_line_get_point(line_p, 0, &xx, NULL, NULL);
-\endcode
-
-In GRASS 6/7, all internal, mostly non-topological vector functions are
-hidden from the modules' API (mainly dig_*(), V1_*() and V2_*()
-functions). All available Vect_*() functions are topological vector
-functions.
-
-
-The following include file contains definitions and structures
-required by some of the routines in this library. The programmer
-should therefore include this file in any code that uses the vector
-library:
-
-\code
-#include <grass/vector.h>
-\endcode
-
-<i>Note: For details please read Blazek et al. 2002 (see below) as
-well as the references in this document.</i>
-
-\subsection vlibHistory Historical notes
-
-The vector library in GRASS 4.0 changed significantly from the
-<em>Digit Library</em> (diglib) used in GRASS 3.1. Below is an
-overview of why the changes were made.
-
-The Digit Library was a collage of subroutines created for developing
-the map development programs. Few of these subroutines were actually
-designed as a user access library. They required individuals to assume
-too much responsibility and control over what happened to the data
-file. Thus when it came time to change vector data file formats for
-GRASS 4.0, many modules also required modification. The two different
-access levels for 3.0 vector files provided very different ways of
-calling the library; they offered little consistency for the user.
-
-The Digit Library was originally designed to only have one file open
-for read or write at a time. Although it was possible in some cases to
-get around this, one restriction was the global head structure. Since
-there was only one instance of this, there could only be one copy of
-that information, and thus, only one open vector file.
-
-The solution to these problems was to design a new user library as an
-interface to the vector data files. This new library was designed to
-provide a simple consistent interface, which hides as much of the
-details of the data format as possible. It also could be extended for
-future enhancements without the need to change existing programs.
-
-The new vector library in GRASS 4 provided routines for opening,
-closing, reading, and writing vector files, as well as several support
-functions. The Digit Library has been replaced, so that all existing
-modules was converted to use the new library. Those routines that
-existed in the Digit Library and were not affected by these changes
-continue to exist in unmodified form, and were included in the vector
-library. Most of the commonly used routines have been discarded, and
-replaced by the new vector routines.
-
-Instead the global head structure was used own local version of
-it. The structure that replaced structure head is structure \ref
-dig_head. There were still two levels of interface to the vector files
-(future releases may include more). Level one provided access only to
-arc (i.e. polyline) information and to the type of line (AREA, LINE,
-DOT). Level two provided access to polygons (areas), attributes, and
-network topology.
-
\section vlibStructures Vector library data structures
All data structure used by the vector library are defined in
@@ -647,945 +395,7 @@
couple of modules including NVIZ to visualize 3D buildings and other
volumetric figures.
-\subsection vlibCoorFileFormat Coor file format specification
-In the coor file the following is stored: 'line' (element) type,
-number of attributes and layer number for each category. Coordinates
-in binary file are stored as double (8 bytes). See \ref Coor_info data
-structure.
-
-\subsubsection vlibCoorFileHead Header
-
-<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>
-<tr><td>Version_Major</td> <td>C</td> <td>1</td> <td>file version (major)</td></tr>
-<tr><td>Version_Minor</td> <td>C</td> <td>1</td> <td>file version (minor)</td></tr>
-<tr><td>Back_Major</td> <td>C</td> <td>1</td> <td>supported from GRASS version (major)</td></tr>
-<tr><td>Back_Minor</td> <td>C</td> <td>1</td> <td>supported from GRASS version (minor)</td></tr>
-<tr><td>byte_order</td> <td>C</td> <td>1</td> <td>little or big endian flag</td></tr>
-<tr><td>head_size</td> <td>L</td> <td>1</td> <td>header size of coor file</td></tr>
-<tr><td>with_z</td> <td>C</td> <td>1</td> <td>2D or 3D flag; zero for 2D</td></tr>
-<tr><td>size</td> <td>L</td> <td>1</td> <td>coor file size</td></tr>
-</table>
-
-\subsubsection vlibCoorFileBody Body
-
-The body consists of line records:
-
-<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>
-<tr><td>record header</td><td>C</td><td>1</td><td>
- - 0. bit: 1 - alive, 0 - dead line
- - 1. bit: 1 - categories, 0 - no categories
- - 2.-3. bit: type - one of: GV_POINT, GV_LINE, GV_BOUNDARY, GV_CENTROID, GV_FACE, GV_KERNEL
- - 4.-7. bit: reserved, not used
-</td></tr>
-
-<tr><td>ncats</td><td>I</td><td>1</td><td>number of categories
- (written only if categories exist) </td></tr>
-
-<tr><td>field</td><td>I</td><td>ncats</td><td>field identifier,
- distinguishes between more categories append to one feature (written
- only if categories exist; field is called "layer" at user
- level)</td></tr>
-
-<tr><td>cat</td><td>I</td><td>ncats</td><td>category value (written
- only if categories exist)</td></tr>
-
-<tr><td>ncoor</td><td>I</td><td>1</td><td>written for GV_LINES and GV_BOUNDARIES
- only</td></tr>
-
-<tr><td>x</td><td>D</td><td>ncoor</td><td>x coordinate</td></tr>
-
-<tr><td>y</td><td>D</td><td>ncoor</td><td>y coordinate</td></tr>
-
-<tr><td>z</td><td>D</td><td>ncoor</td><td>z coordinate; present if
- with_z in head is set to 1</td></tr> </table>
-
-Types used in coor file:
-
-<table border="1" style="border-collapse: collapse" cellpadding="5">
-<tr><td><b>Type</b></td><td><b>Name</b></td><td><b>Size in Bytes</b></td></tr>
-<tr><td>D</td><td>Double</td><td>8</td></tr>
-<tr><td>L</td><td>Long </td><td>4</td></tr>
-<tr><td>I</td><td>Int </td><td>4</td></tr>
-<tr><td>S</td><td>Short </td><td>4</td></tr>
-<tr><td>C</td><td>Char </td><td>1</td></tr>
-</table>
-
-\section vlibTopoManagement Vector library topology management
-
-Topology general characteristics:
-
-- geometry and attributes are stored separately
- (don't read both if it is not necessary - usually it is not)
-- the format is topological (areas build from boundaries)
-- currently only 2D topology is supported
-
-Topology is written for native GRASS vector format; in case of
-linked OGR sources (see <tt>v.external</tt> module), only
-pseudo-topology (boundaries constructed from polygons) is written.
-
-The following rules apply to the vector data:
-
-- Boundaries should not cross each other (i.e., boundaries which would
- cross must be split at their intersection to form distict boundaries).
- On the contrary, lines can cross each other, e.g. bridges over rivers.
-- Lines and boundaries share nodes only if their endpoints are identical.
- Lines or boundaries can be 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 in closed
- areas.
-- It is recommended that area features and linear features be placed
- in separate layers. However if area features and linear features
- must appear in one layer, common boundaries should be digitized only
- once. For example, a boundary that is also a line (e.g., a road which
- is also a field boundary), should be digitized as a boundary to
- complete the area(s), and a boundary which is functionally 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>
-command.
-
-\subsection vlibTopoFileFormat Topo file format specification
-
-Topo file is read by Vect_open_topo().
-
-\subsubsection vlibTopoFileHead Header
-
-<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>
-
-<tr><td>plus->Version_Major </td><td>C</td><td>1</td><td>file version (major)</td></tr>
-<tr><td>plus->Version_Minor </td><td>C</td><td>1</td><td>file version (minor)</td></tr>
-<tr><td>plus->Back_Major</td><td>C</td><td>1</td><td>supported from GRASS version (major)</td></tr>
-<tr><td>plus->Back_Minor</td><td>C</td><td>1</td><td>supported from GRASS version (minor)</td></tr>
-
-<tr><td>plus->port->byte_order</td><td>C</td><td>1</td><td>little or big endian
- flag; files are written in machine native order but
- files in both little and big endian order may be
- readl; zero for little endian</td></tr>
-
-<tr><td>plus->head_size</td><td>L</td><td>1</td><td>header size</td></tr>
-
-<tr><td>plus->with_z</td><td>C</td><td>1</td><td>2D or 3D flag; zero for 2D</td></tr>
-
-<tr><td>plus->box</td><td>D</td><td>6</td><td>Bounding box coordinates (N,S,E,W,T,B)</td></tr>
-
-<tr><td>plus->n_nodes, plus->n_lines, etc.</td><td>I</td><td>7</td><td>Number of
-nodes, edges, lines, areas, isles, volumes and holes</td></tr>
-
-<tr><td>plus->n_plines, plus->n_llines, etc.</td><td>I</td><td>7</td><td>Number of
-points, lines, boundaries, centroids, faces and kernels</td></tr>
-
-<tr><td>plus->Node_offset, plus->Edge_offset,
-etc.</td><td>L</td><td>7</td><td>Offset value for nodes, edges, lines,
-areas, isles, volumes and holes</td></tr>
-
-<tr><td>plus->coor_size</td><td>L</td><td>1</td><td>File size</td></tr>
-</table>
-
-\subsubsection vlibTopoFileBody Body (nodes, lines, areas, isles)
-
-<b>Nodes</b>
-
-For each node (plus->n_nodes):
-
-<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>
-<tr><td>n_lines</td><td>I</td><td>1</td><td>Number of lines (0 for dead node)</td></tr>
-<tr><td>lines</td><td>I</td><td>n_lines</td><td>Line ids (negative id for line which ends at the node)</td></tr>
-<tr><td>angles</td><td>D</td><td>n_lines</td><td>Angle value</td></tr>
-<tr><td>n_edges</td><td>I</td><td>1</td><td>Reserved for edges (only for <tt>with_z</tt>)</td></tr>
-<tr><td>x,y</td><td>D</td><td>2</td><td>Coordinate pair (2D)</td></tr>
-<tr><td>z</td><td>D</td><td>1</td><td>Only for <tt>with_z</tt> (3D)</td></tr>
-</table>
-
-See \ref P_node data structure.
-
-<b>Lines</b>
-
-For each line (plus->n_lines):
-
-<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>
-<tr><td>feature type</td><td>C</td><td>1</td><td>0 for dead line</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>Start 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>End 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>
-</table>
-
-See \ref P_line data structure.
-
-<b>Areas</b>
-
-For each area (plus->n_areas):
-
-<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>
-<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 forming exterior boundary (clockwise order, negative id for backward direction)</td></tr>
-<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>
-</table>
-
-See \ref P_area data structure.
-
-<b>Isles</b>
-
-For each isle (plus->n_isle):
-
-<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>
-<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 forming exterior boundary (counter-clockwise order, negative id for backward direction)</td></tr>
-<tr><td>area</td><td>I</td><td>1</td><td>Outer area id</td></tr>
-</table>
-
-See \ref P_isle data structure.
-
-\subsection vlibTopoLevels Topology levels
-
-The vector library defines more <i>topology levels</i> (only for level
-of access 2):
-
-- GV_BUILD_NONE
-- GV_BUILD_BASE
-- GV_BUILD_AREAS
-- GV_BUILD_ATTACH_ISLES
-- GV_BUILD_CENTROIDS
-- GV_BUILD_ALL
-
-<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
-
-<b>Points</b>
-
-\verbatim
-One point (nodes: 0, lines: 1, areas: 0, isles: 0)
-
- + N1/L1
-\endverbatim
-
-Line L1 (see \ref P_line)
-
-\verbatim
-line = 1, type = 1 (GV_POINT)
-\endverbatim
-
-<b>Lines</b>
-
-\verbatim
-One line (nodes: 2, lines: 1, areas: 0, isles: 0)
-
-
- +----L1----+
- N1 N2
-\endverbatim
-
-%Node N1 (see \ref P_node)
-
-\verbatim
-node = 1, n_lines = 1, xyz = 634624.746450, 223557.302231, 0.000000
- line = 1, type = 2 (GV_LINE), angle = -0.436257
-\endverbatim
-
-%Node N2 (see \ref P_node)
-
-\verbatim
-node = 2, n_lines = 1, xyz = 638677.484787, 221667.849899, 0.000000
- line = -1, type = 2 (GV_LINE), angle = 2.705335
-\endverbatim
-
-Line L1 (see \ref P_line)
-
-\verbatim
-line = 1, type = 2 (GV_LINE), n1 = 1, n2 = 2
-\endverbatim
-
-<b>Areas without holes</b>
-
-\verbatim
-Two lines (nodes: 1, lines: 2, areas: 1, isles: 1)
-
- +N1
- / \
- / \
- / \
- / +L2 \
- / \
- -------L1------
-\endverbatim
-
-%Node N1 (see \ref P_node)
-
-\verbatim
-node = 1, n_lines = 2, xyz = 635720.081136, 225063.387424, 0.000000
- line = 1, type = 4 (GV_BOUNDARY), angle = -2.245537
- line = -1, type = 4 (GV_BOUNDARY), angle = -0.842926
-\endverbatim
-
-Line L1 (see \ref P_line)
-
-\verbatim
-line = 1, type = 4 (GV_BOUNDARY), n1 = 1, n2 = 1, left = 1, right = -1
-\endverbatim
-
-Line L2 (see \ref P_line)
-
-\verbatim
-line = 2, type = 8 (GV_CENTROID), area = 1
-\endverbatim
-
-Area A1 (see \ref P_area)
-
-\verbatim
-area = 1, n_lines = 1, n_isles = 0 centroid = 2
- line = -1
-\endverbatim
-
-Isle I1 (see \ref P_isle)
-
-\verbatim
-isle = 1, n_lines = 1 area = 0
- line = 1
-\endverbatim
-
-<b>Areas with holes</b>
-
-\verbatim
-Three lines (nodes: 2, lines: 3, areas: 2, isles: 2)
-
- +N1
- / \
- / \
- / \
- / \
- / +L2 \
- / \
- / +N2 \
- / /\ \
- / / \ \
- / / \ \
- / ---L3-- \
- / \
-------------L1-------------
-\endverbatim
-
-%Node N1 (see \ref P_node)
-
-\verbatim
-node = 1, n_lines = 2, xyz = 635720.081136, 225063.387424, 0.000000
- line = 1, type = 4 (GV_BOUNDARY), angle = -2.245537
- line = -1, type = 4 (GV_BOUNDARY), angle = -0.842926
-\endverbatim
-
-%Node N2 (see \ref P_node)
-
-\verbatim
-node = 2, n_lines = 2, xyz = 636788.032454, 223173.935091, 0.000000
- line = 3, type = 4 (GV_BOUNDARY), angle = -2.245537
- line = -3, type = 4 (GV_BOUNDARY), angle = -0.866302
-\endverbatim
-
-Line L1 (see \ref P_line)
-
-\verbatim
-line = 1, type = 4 (GV_BOUNDARY), n1 = 1, n2 = 1, left = 1, right = -1
-\endverbatim
-
-Line L2 (see \ref P_line)
-
-\verbatim
-line = 2, type = 8 (GV_CENTROID), area = 1
-\endverbatim
-
-Line L3 (see \ref P_line)
-
-\verbatim
-line = 3, type = 4 (GV_BOUNDARY), n1 = 3, n2 = 3, left = 2, right = -2
-\endverbatim
-
-Area A1 (see \ref P_area)
-
-\verbatim
-area = 1, n_lines = 1, n_isles = 1 centroid = 2
- line = -1
- isle = 2
-\endverbatim
-
-Area A2 (see \ref P_area)
-
-\verbatim
-area = 2, n_lines = 1, n_isles = 0 centroid = 0
- line = -3
-\endverbatim
-
-Isle I1 (see \ref P_isle)
-
-\verbatim
-isle = 1, n_lines = 1 area = 0
- line = 1
-\endverbatim
-
-Isle I2 (see \ref P_isle)
-
-\verbatim
-isle = 2, n_lines = 1 area = 1
- line = 3
-\endverbatim
-
-<b>Example 1</b>
-
-A polygon may be formed by many boundaries (several connected primitives).
-One boundary is shared by adjacent areas.
-
-\verbatim
-+--1--+--5--+
-| | |
-2 A 4 B 6
-| | |
-+--3--+--7--+
-
-1,2,3,4,5,6,7 = 7 boundaries (primitives)
-A,B = 2 areas
-A+B = 1 isle
-\endverbatim
-
-<b>Example 2</b>
-
-This is handled correctly in GRASS: A can be filled, B filled differently.
-
-\verbatim
-+---------+
-| A |
-+-----+ |
-| B | |
-+-----+ |
-| |
-+---------+
-
-A, B = 2 areas
-A+B = 1 isle
-\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.
-
-<b>Example 3</b>
-
-This is handled correctly in GRASS: Areas A1, A2, and A3 can be filled differently.
-
-\verbatim
-+---------------------+
-| A1 |
-+ +------+------+ |
-| | A2 | A3 | |
-+ +------+------+ |
-| I1 |
-+---------------------+
-
-A1,A2,A3 = 3 areas
-A1,A2+A3 = 2 isles
-\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.
-
-<b>Example 4</b>
-
-<tt>v.in.ogr/v.clean</tt> 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:
-
-\verbatim
-+-----+-----+
-| . |
-| . |
-+.....+.....+
-| . |
-| x . |
-+-----+-----+
-
----- road + boundary of one parcel => type boundary
-.... road => type line
-x parcel centroid (identifies whole area)
-\endverbatim
-
-Because lines are not used to build areas, we have only one
-area/centroid, instead of 4 which would be necessary in TIGER.
-
-\subsection vlibTopoMemory Topology memory management
-
-Topology is generated for all kinds of vector types. Memory is not
-released by default. The programmer can force the library to release
-the memory by using Vect_set_release_support(). But: The programmer
-cannot run Vect_set_release_support() in mid process because all
-vectors are needed in the spatial index, which is needed to build topology.
-
-Topology is also necessary for points in case of a vector network
-because the graph is built using topology information about lines
-and points.
-
-The topology structure does not only store the topology but also
-the 'line' bounding box and line offset in coor file (index).
-The existing spatial index is using line ID in 'topology' structure
-to identify lines in 'coor' file. Currently it is not possible to build
-spatial index without topology.
-
-
-\section vlibSpidx Vector library spatial index management
-
-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 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
-<tt>exit()</tt> and operating system releases all the memory much
-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 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
-file.
-
-Currently most of the modules do not release the memory occupied for
-spatial index and work like this (pseudocode):
-
-\code
-int main
-{
- Vect_open_new();
- /* writing new vector */
-
- Vect_build();
- Vect_close(); /* memory is not released */
-}
-\endcode
-
-In general it is possible to free the memory with Vect_set_release_support()
-such as:
-
-\code
-int main
-{
- Vect_open_new();
- /* writing new vector */
-
- Vect_build();
- Vect_set_release_support();
- Vect_close(); /* memory is released */
-}
-\endcode
-
-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
-applies only when creating a new vector or updating an old vector.
-For example:
-
-\code
-int main
-{
- Vect_open_update();
- /* select features using spatial index, e.g. Vect_select_lines_by_box() */
- Vect_set_release_support();
- Vect_close(); /* memory is released */
-
- /* do some processing which needs memory */
-}
-\endcode
-
-See also \ref spatial_index data structure.
-
-\subsection vlibSidxFileFormat Sidx file format specification
-
-Spatial index file ('sidx') is read by Vect_open_sidx().
-
-\subsubsection vlibSidxFileHead Header
-
-Note: <tt>plus</tt> is instance of \ref Plus_head 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>
-
-<tr><td>plus->spidx_Version_Major </td><td>C</td><td>1</td><td>file version (major)</td></tr>
-<tr><td>plus->spidx_Version_Minor </td><td>C</td><td>1</td><td>file version (minor)</td></tr>
-<tr><td>plus->spidx_Back_Major</td><td>C</td><td>1</td><td>supported from GRASS version (major)</td></tr>
-<tr><td>plus->spidx_Back_Minor</td><td>C</td><td>1</td><td>supported from GRASS version (minor)</td></tr>
-
-<tr><td>plus->spidx_port->byte_order</td><td>C</td><td>1</td><td>little or big endian
- flag; files are written in machine native order but
- files in both little and big endian order may be
- readl; zero for little endian</td></tr>
-
-<tr><td>plus->spidx_port.off_t_size</td><td>C</td><td>1</td><td>off_t size (LFS)</td></tr>
-
-<tr><td>plus->spidx_head_size</td><td>L</td><td>1</td><td>header size</td></tr>
-
-<tr><td>plus->spidx_with_z</td><td>C</td><td>1</td><td>2D/3D vector data</td></tr>
-
-<tr><td>ndims</td><td>C</td><td>1</td><td>Number of dimensions</td></tr>
-
-<tr><td>nsides</td><td>C</td><td>1</td><td>Number of sides</td></tr>
-
-<tr><td>nodesize</td><td>I</td><td>1</td><td>%Node size</td></tr>
-
-<tr><td>nodecard</td><td>I</td><td>1</td><td>%Node card (?)</td></tr>
-
-<tr><td>leafcard</td><td>I</td><td>1</td><td>Leaf card (?)</td></tr>
-
-<tr><td>min_node_fill</td><td>I</td><td>1</td><td>Minimum node fill (?)</td></tr>
-
-<tr><td>min_leaf_fill</td><td>I</td><td>1</td><td>Minimum leaf fill (?)</td></tr>
-
-<tr><td>plus->Node_spidx->n_nodes</td><td>I</td><td>1</td><td>Number of nodes</td></tr>
-
-<tr><td>plus->Node_spidx->n_leafs</td><td>I</td><td>1</td><td>Number of leafs</td></tr>
-
-<tr><td>plus->Node_spidx->n_levels</td><td>I</td><td>1</td><td>Number of levels</td></tr>
-
-<tr><td>plus->Node_spidx_offset</td><td>O</td><td>1</td><td>%Node offset</td></tr>
-
-<tr><td>plus->Line_spidx->n_nodes</td><td>I</td><td>1</td><td>Number of nodes</td></tr>
-
-<tr><td>plus->Line_spidx->n_leafs</td><td>I</td><td>1</td><td>Number of leafs</td></tr>
-
-<tr><td>plus->Line_spidx->n_levels</td><td>I</td><td>1</td><td>Number of levels</td></tr>
-
-<tr><td>plus->Line_spidx_offset</td><td>O</td><td>1</td><td>Line offset</td></tr>
-
-<tr><td>plus->Area_spidx->n_nodes</td><td>I</td><td>1</td><td>Number of nodes</td></tr>
-
-<tr><td>plus->Area_spidx->n_leafs</td><td>I</td><td>1</td><td>Number of leafs</td></tr>
-
-<tr><td>plus->Area_spidx->n_levels</td><td>I</td><td>1</td><td>Number of levels</td></tr>
-
-<tr><td>plus->Area_spidx_offset</td><td>O</td><td>1</td><td>Area offset</td></tr>
-
-<tr><td>plus->Isle_spidx->n_nodes</td><td>I</td><td>1</td><td>Number of nodes</td></tr>
-
-<tr><td>plus->Isle_spidx->n_leafs</td><td>I</td><td>1</td><td>Number of leafs</td></tr>
-
-<tr><td>plus->Isle_spidx->n_levels</td><td>I</td><td>1</td><td>Number of levels</td></tr>
-
-<tr><td>plus->Isle_spidx_offset</td><td>O</td><td>1</td><td>Isle offset</td></tr>
-
-<tr><td>plus->Face_spidx_offset</td><td>O</td><td>1</td><td>Face offset</td></tr>
-
-<tr><td>plus->Volume_spidx_offset</td><td>O</td><td>1</td><td>Volume offset</td></tr>
-
-<tr><td>plus->Hole_spidx_offset</td><td>O</td><td>1</td><td>Hole offset</td></tr>
-
-<tr><td>plus->coor_size</td><td>O</td><td>1</td><td>Coor file size</td></tr>
-</table>
-
-\section vlibCidx Vector library category index management
-
-The category index (stored in the cidx file) improves the performance
-of all selections by cats/attributes (SQL, e.g. <tt>d.vect
-cats=27591</tt>, <tt>v.extract list=20000-21000</tt>). This avoids
-that all selections have to be made by looping through all vector
-lines. Category index is also essential for simple feature
-representation of GRASS vectors.
-
-Category index is created for each field. In memory, it is stored in
-\ref Cat_index data structure.
-
-Category index is built with topology, but it is <b>not updated</b> if
-vector is edited on level 2. Category index is stored in 'cidx' file,
-'cat' array is written/read by one call of dig__fwrite_port_I() or
-dig__fread_port_I().
-
-Stored values can be retrieved either by index in 'cat' array (if all
-features of given field are required) or by category value (one or few
-features), always by <tt>Vect_cidx_*()</tt> functions.
-
-To create category index, it will be necessary to rebuild topology for
-all existing vectors. This is an opportunity to make (hopefully) last
-changes in 'topo', 'cidx' formats.
-
-\subsection vlibCidxFileFormat Cidx file format specification
-
-Category index file ('cidx') is read by Vect_cidx_open().
-
-\subsubsection vlibCidxFileHead Header
-
-Note: <tt>plus</tt> is instance of \ref Plus_head 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>
-
-<tr><td>plus->cpidx_Version_Major </td><td>C</td><td>1</td><td>file version (major)</td></tr>
-<tr><td>plus->cpidx_Version_Minor </td><td>C</td><td>1</td><td>file version (minor)</td></tr>
-<tr><td>plus->cpidx_Back_Major</td><td>C</td><td>1</td><td>supported from GRASS version (major)</td></tr>
-<tr><td>plus->cpidx_Back_Minor</td><td>C</td><td>1</td><td>supported from GRASS version (minor)</td></tr>
-
-<tr><td>plus->cidx_port->byte_order</td><td>C</td><td>1</td><td>little or big endian
- flag; files are written in machine native order but
- files in both little and big endian order may be
- readl; zero for little endian</td></tr>
-
-<tr><td>plus->cidx_head_size</td><td>L</td><td>1</td><td>cidx head size</td></tr>
-
-<tr><td>plus->n_cidx</td><td>I</td><td>1</td><td>number of fields</td></tr>
-
-<tr><td>field</td><td>I</td><td>n_cidx</td><td>field number</td></tr>
-
-<tr><td>n_cats</td><td>I</td><td>n_cidx</td><td>number of categories</td></tr>
-
-<tr><td>n_ucats</td><td>I</td><td>n_cidx</td><td>number of unique categories</td></tr>
-
-<tr><td>n_types</td><td>I</td><td>n_cidx</td><td>number of feature types</td></tr>
-
-<tr><td>rtype</td><td>I</td><td>n_cidx * n_types</td><td>Feature type</td></tr>
-
-<tr><td>type[t]</td><td>I</td><td>n_cidx * n_types</td><td>Number of items</td></tr>
-
-</table>
-
-\section vlibTin Vector TINs
-
-TINs are simply created as 2D/3D vector polygons consisting of
-3 vertices. See Vect_tin_get_z().
-
-
-\section vlibOgrIface OGR interface
-
-\subsection vLibPseudoTopo Pseudo-topology
-
-Reduced topology: each boundary is attached to one area only,
-i.e. smoothing, simplification, removing small areas etc. will not
-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 converted to areas and cleaned as done
-by <tt>v.in.ogr</tt>.
-
-\subsection vlibFrmtFileFormat Frmt file format specification
-
-Frmt is a plain text file which contains basic information about
-external format of linked vector map. Each line contains key, value
-pairs separated by comma.
-
-OGR specific format is described by:
-
- - FORMAT - ogr
- - DSN - OGR datasource name
- - LAYER - OGR layer name
-
-Example:
-
-\verbatim
-FORMAT: ogr
-DSN: /path/to/shapefiles
-LAYER: cities
-\endverbatim
-
-OGR layer can be linked via <tt>v.external</tt> command. When linking
-OGR layer pseudo-topology ('topo') is built including spatial index
-file ('sidx') and category index file ('cidx'). Additionally also
-feature index file (see \ref vlibFidxFileFormat) is created.
-
-\subsection vlibFidxFileFormat Fidx file format specification
-
-Note: <tt>finfo</tt> is an instance of \ref Format_info 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>
-
-<tr><td>Version_Major </td><td>C</td><td>1</td><td>file version (major)</td></tr>
-<tr><td>Version_Minor </td><td>C</td><td>1</td><td>file version (minor)</td></tr>
-<tr><td>Back_Major</td><td>C</td><td>1</td><td>supported from GRASS version (major)</td></tr>
-<tr><td>Back_Minor</td><td>C</td><td>1</td><td>supported from GRASS version (minor)</td></tr>
-
-<tr><td>byte_order</td><td>C</td><td>1</td><td>little or big endian
- flag; files are written in machine native order but
- files in both little and big endian order may be
- readl; zero for little endian</td></tr>
-
-<tr><td>length</td><td>L</td><td>1</td><td>header size</td></tr>
-
-<tr><td>fInfo.ogr.offset_num</td><td>I</td><td>1</td><td>number of records</td></tr>
-
-<tr><td>fInfo.ogr.offset</td><td>I</td><td>offset_num</td><td>offsets</td></tr>
-
-</table>
-
-\section vlibDglib DGLib (Directed Graph Library)
-
-\ref dglib or DGLib (Micarelli 2002, http://grass.osgeo.org/dglib/)
-provides functionality for vector network analysis. This library
-released under GPL is hosted by the GRASS project (within the GRASS
-source code). As a stand-alone library it may also be used by other
-software projects.
-
-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 least costly
-path connections based on the accumulated costs. Applications are
-transport analysis, connectivity and more. Implemented applications
-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).
-
-For details, please read Blazek et al. 2002 (see below).
-
-Related vector functions are:
- Vect_graph_add_edge(),
- Vect_graph_init(),
- Vect_graph_set_node_costs(),
- Vect_graph_shortest_path(),
- Vect_net_build_graph(),
- Vect_net_nearest_nodes(),
- Vect_net_shortest_path(), and
- Vect_net_shortest_path_coor().
-
-\section vlibAscii Vector ASCII Format Specifications
-
-The GRASS ASCII vector map format may contain a mix of primitives
-including points, lines, boundaries, centroids, faces, and
-kernels. The format may also contain a header with various metadata
-(see example below).
-
-Vector map can be converted to the ASCII representation at user level
-by <tt>v.out.ascii format=standard</tt> command.
-
-See \ref vlibAsciiFn for list of related functions.
-
-The header is similar as the head file of vector binary format (see
-\ref vlibHeadFileFormat) but contains bounding box also. Keywords are:
-
-\verbatim
-ORGANIZATION
-DIGIT DATE
-DIGIT NAME
-MAP NAME
-MAP DATE
-MAP SCALE
-OTHER INFO
-ZONE
-WEST EDGE
-EAST EDGE
-SOUTH EDGE
-NORTH EDGE
-MAP THRESH
-\endverbatim
-
-Example:
-
-\verbatim
-ORGANIZATION: NC OneMap
-DIGIT DATE:
-DIGIT NAME: helena
-MAP NAME: North Carolina selected bridges (points map)
-MAP DATE: Mon Nov 6 15:32:39 2006
-MAP SCALE: 1
-OTHER INFO:
-ZONE: 0
-MAP THRESH: 0.000000
-\endverbatim
-
-The body begins with the row:
-
-\verbatim
-VERTI:
-\endverbatim
-
-followed by records of primitives:
-
-\verbatim
-TYPE NUMBER_OF_COORDINATES [NUMBER_OF_CATEGORIES]
- X Y [Z]
-....
- X Y [Z]
-[ LAYER CATEGORY]
-....
-[ LAYER CATEGORY]
-\endverbatim
-
-Everything above in <tt>[]</tt> is optional.
-
-The primitive codes are as follows:
-
-- 'P': point
-- 'L': line
-- 'B': boundary
-- 'C': centroid
-- 'F': face (3D boundary)
-- 'K': kernel (3D centroid)
-- 'A': area (boundary) - better use 'B'; kept only for backward
-compatibility
-
-The coordinates are listed following the initial line containing the
-primitive code, the total number of vectors in the series, and (optionally)
-the number of categories (1 for a single layer, higher for multiple layers).
-Below that 1 or several lines follow to indicate the layer number and
-the category number (ID).
-
-The order of coordinates is
-\verbatim
- X Y [Z]
-\endverbatim
-
-Note: The points are stored as y, x (i.e., east, north), which is the
-reserve of the way GRASS usually represents geographic coordinates.
-
-Example:
-
-\verbatim
-P 1 1
- 375171.4992779 317756.72097616
- 1 1
-B 5
- 637740 219580
- 639530 219580
- 639530 221230
- 637740 221230
- 637740 219580
-C 1 1
- 638635 220405
- 1 2
-\endverbatim
-
-In this example, the first vector feature is a point with category
-number 1. The second vector feature is a boundary composed by 5
-points. The third feature is a centroid with category number 2. The
-boundary and the centroid form an area with category number 2. All
-vector feature mentioned above are located in layer 1.
-
\section vlibFunc List of vector library functions
The vector library provides the GRASS programmer with routines to
@@ -1604,57 +414,6 @@
The Vect_*() functions are the programmer's API for GRASS vector
programming. The programmer should use only routines with this prefix.
-- \subpage vlibArea
-- \subpage vlibArray
-- \subpage vlibBox
-- \subpage vlibBreakLines
-- \subpage vlibBreakPolygons
-- \subpage vlibBridges
-- \subpage vlibBuffer
-- \subpage vlibBuild
-- \subpage vlibBuildNat
-- \subpage vlibBuildOgr
-- \subpage vlibCats
-- \subpage vlibCindex
-- \subpage vlibCleanNodes
-- \subpage vlibClose
-- \subpage vlibConstraint
-- \subpage vlibDangles
-- \subpage vlibDbcolumns
-- \subpage vlibError
-- \subpage vlibField
-- \subpage vlibFind
-- \subpage vlibGraph
-- \subpage vlibHeader
-- \subpage vlibHist
-- \subpage vlibInitHead
-- \subpage vlibIntersect
-- \subpage vlibLegalVname
-- \subpage vlibLevel
-- \subpage vlibLevelTwo
-- \subpage vlibLine
-- \subpage vlibList
-- \subpage vlibMap
-- \subpage vlibNet
-- \subpage vlibOpen
-- \subpage vlibOverlay
-- \subpage vlibVpoly
-- \subpage vlibRead
-- \subpage vlibRemoveAreas
-- \subpage vlibRemoveDuplicates
-- \subpage vlibRewind
-- \subpage vlibSelect
-- \subpage vlibSindex
-- \subpage vlibSnap
-- \subpage vlibTin
-- \subpage vlibType
-- \subpage vlibDelete
-- \subpage vlibWrite
-- \subpage vlibAsciiFn
-- \subpage vlibSFAFn
-- \subpage vlibGeosFn
-- \subpage vlibPgFn
-
\section vlibArea Vector area functions
- Vect_get_area_area()
@@ -2333,7 +1092,7 @@
- Vect_snap_lines_list()
-\section vlibTin Vector TIN functions
+\section vlibTinFuns Vector TIN functions
- Vect_tin_get_z()
Added: grass/trunk/lib/vector/vectorlib_ascii.dox
===================================================================
--- grass/trunk/lib/vector/vectorlib_ascii.dox (rev 0)
+++ grass/trunk/lib/vector/vectorlib_ascii.dox 2012-08-07 17:45:22 UTC (rev 52585)
@@ -0,0 +1,118 @@
+/*! \page vlibAscii Vector ASCII Format
+
+by GRASS Development Team (http://grass.osgeo.org)
+
+\section vlibAsciiMain Vector ASCII Format Specifications
+
+The GRASS ASCII vector map format may contain a mix of primitives
+including points, lines, boundaries, centroids, faces, and
+kernels. The format may also contain a header with various metadata
+(see example below).
+
+Vector map can be converted to the ASCII representation at user level
+by <tt>v.out.ascii format=standard</tt> command.
+
+See \ref vlibAsciiFn for list of related functions.
+
+The header is similar as the head file of vector binary format (see
+\ref vlibHeadFileFormat) but contains bounding box also. Keywords are:
+
+\verbatim
+ORGANIZATION
+DIGIT DATE
+DIGIT NAME
+MAP NAME
+MAP DATE
+MAP SCALE
+OTHER INFO
+ZONE
+WEST EDGE
+EAST EDGE
+SOUTH EDGE
+NORTH EDGE
+MAP THRESH
+\endverbatim
+
+Example:
+
+\verbatim
+ORGANIZATION: NC OneMap
+DIGIT DATE:
+DIGIT NAME: helena
+MAP NAME: North Carolina selected bridges (points map)
+MAP DATE: Mon Nov 6 15:32:39 2006
+MAP SCALE: 1
+OTHER INFO:
+ZONE: 0
+MAP THRESH: 0.000000
+\endverbatim
+
+The body begins with the row:
+
+\verbatim
+VERTI:
+\endverbatim
+
+followed by records of primitives:
+
+\verbatim
+TYPE NUMBER_OF_COORDINATES [NUMBER_OF_CATEGORIES]
+ X Y [Z]
+....
+ X Y [Z]
+[ LAYER CATEGORY]
+....
+[ LAYER CATEGORY]
+\endverbatim
+
+Everything above in <tt>[]</tt> is optional.
+
+The primitive codes are as follows:
+
+- 'P': point
+- 'L': line
+- 'B': boundary
+- 'C': centroid
+- 'F': face (3D boundary)
+- 'K': kernel (3D centroid)
+- 'A': area (boundary) - better use 'B'; kept only for backward
+compatibility
+
+The coordinates are listed following the initial line containing the
+primitive code, the total number of vectors in the series, and (optionally)
+the number of categories (1 for a single layer, higher for multiple layers).
+Below that 1 or several lines follow to indicate the layer number and
+the category number (ID).
+
+The order of coordinates is
+\verbatim
+ X Y [Z]
+\endverbatim
+
+Note: The points are stored as y, x (i.e., east, north), which is the
+reserve of the way GRASS usually represents geographic coordinates.
+
+Example:
+
+\verbatim
+P 1 1
+ 375171.4992779 317756.72097616
+ 1 1
+B 5
+ 637740 219580
+ 639530 219580
+ 639530 221230
+ 637740 221230
+ 637740 219580
+C 1 1
+ 638635 220405
+ 1 2
+\endverbatim
+
+In this example, the first vector feature is a point with category
+number 1. The second vector feature is a boundary composed by 5
+points. The third feature is a centroid with category number 2. The
+boundary and the centroid form an area with category number 2. All
+vector feature mentioned above are located in layer 1.
+
+*/
Added: grass/trunk/lib/vector/vectorlib_files.dox
===================================================================
--- grass/trunk/lib/vector/vectorlib_files.dox (rev 0)
+++ grass/trunk/lib/vector/vectorlib_files.dox 2012-08-07 17:45:22 UTC (rev 52585)
@@ -0,0 +1,319 @@
+/*! \page vlibFormat Vector format description
+
+by GRASS Development Team (http://grass.osgeo.org)
+
+\par Table of contents
+
+- \ref vlibDirectoryStructure
+- \ref vlibDblnFileFormat
+- \ref vlibCoorFileFormat
+ - \ref vlibCoorFileHead
+ - \ref vlibCoorFileBody
+
+\section vlibDirectoryStructure Directory structure
+
+Vector map is stored in a number of data files. Vector map directory
+structure and file names were changed in GRASS 6 with respect to
+previous GRASS versions. All vector files for one vector map are
+stored in one directory:
+
+\verbatim
+$MAPSET/vector/vector_name/
+\endverbatim
+
+This directory contains these files:
+
+- <b>coor</b> - binary file, coordinates [former dig/ file] (see \ref vlibCoorFileFormat)
+- <b>topo</b> - binary file, topology [former dig_plus/ file] (see \ref vlibTopoFileFormat)
+- <b>sidx</b> - binary file, spatial index (see \ref vlibSidxFileFormat)
+- <b>cidx</b> - binary file, category index (see \ref vlibCidxFileFormat)
+- <b>head</b> - text file, header information [former part of dig/ file] (see \ref vlibHeadFileFormat)
+- <b>dbln</b> - text file, link(s) to attribute table(s) (see \ref vlibDblnFileFormat)
+- <b>hist</b> - text file, vector map change history
+- <b>frmt</b> - text file, format description (external formats only)
+- <b>fidx</b> - binary file, feature index (OGR format only)
+
+\section vlibHeadFileFormat Header file format specification
+
+The header contains meta information, a description of the
+vector map and many other information. The file is an unordered list
+of key/value entries. The <i>key</i> is a string separated from
+<i>value</i> by a colon and optional whitespace.
+
+Keywords are:
+
+- ORGANIZATION - organization that digitized the data
+- DIGIT DATE - date the data was digitized
+- DIGIT NAME - person who digitized the data
+- MAP NAME - title of the original source map
+- MAP DATE - date of the original source map
+- MAP SCALE - scale of the original source map
+- OTHER INFO - other comments about the map
+- ZONE - zone of the map (e.g., UTM zone)
+- MAP THRESH - digitizing threshold
+
+This information holds \ref dig_head data structure.
+
+
+\section vlibDblnFileFormat DB link file format specification
+
+Each vector maps has its own DBMI settings stored in the
+'$MAPSET/vector/vector_name/dbln' text file. For each pair <em>vector map +
+layer</em>, all of <em>table, key column, database, driver</em> must be
+defined in a new row. This definition must be written to
+'$MAPSET/vector/vector_name/dbln' text file. Each row in the 'dbln'
+file contains names separated by spaces in following order ([ ] -
+optional):
+
+\verbatim
+map[@mapset] layer table [key [database [driver]]]
+\endverbatim
+
+If key, database or driver are omitted (on second and higher row only)
+the last definition is used. When reading a vector map from another
+mapset (if mapset is specified along with map name), definitions in
+the related "dbln" file may overwrite the DBMI definition in the
+current mapset. This means that the map-wise definition is always
+"stronger".
+
+Wild cards <b>*</b> and <b>?</b> may be used in map and mapset names.
+
+Variables $GISDBASE, $LOCATION_NAME, $MAPSET, and $MAP may be used in
+table, key, database and driver names (function
+Vect_subst_var()). Note that $MAPSET is not the current mapset but
+mapset of the map the rule is defined for.
+
+Note that vector features in GRASS vector maps may have attributes in
+different tables or may be without attributes. Boundaries form areas
+but it may happen that some boundaries are not closed (such boundaries
+would not appear in polygon layer). Boundaries may have
+attributes. All types may be mixed in one vector map.
+
+The link to the table is permanent and it is stored in 'dbln' file in
+vector directory. Tables are considered to be a part of the vector and
+the command <tt>g.remove</tt>, for example, deletes linked tables of
+the vector. Attributes must be joined with geometry.
+
+Information about database links holds \ref dblinks data structure.
+
+<b>Examples:</b>
+
+Examples are written mostly for the DBF driver, where database is full
+path to the directory with dbf files and table name is the name of dbf
+file without .dbf extension:
+
+\verbatim
+* 1 mytable id $GISDBASE/$LOCATION_NAME/$MAPSET/vector/$MAP dbf
+\endverbatim
+
+This definition says that entities with category of layer 1 are linked
+to dbf tables with names "mytable.dbf" saved in vector directories of
+each map. The attribute column containing the category numbers is
+called "id".
+
+\verbatim
+* 1 $MAP id $GISDBASE/$LOCATION_NAME/$MAPSET/dbf dbf
+\endverbatim
+
+Similar as above but all dbf files are in one directory dbf/ in mapset
+and names of dbf files are $MAP.dbf
+
+\verbatim
+water* 1 rivers id /home/grass/dbf dbf
+water* 2 lakes lakeid /home/guser/mydb
+trans* 1 roads key basedb odbc
+trans* 5 rails
+\endverbatim
+
+These definitions define more layers (called "field" in the API) for
+one vector map i.e. in one vector map may be more features linked to
+more attribute tables. Definitions on first 2 rows are applied for
+example on maps water1, water2, ... so that more maps may share one
+table.
+
+\verbatim
+water at PERMANENT 1 myrivers id /home/guser/mydbf dbf
+\endverbatim
+
+This definion overwrites the definition saved in PERMANENT/VAR and
+links the water map from PERMANENT mapset to the user's table.
+
+Modules should be written so that connections to databases for each
+vector layer are independent. It should be possible to read attributes
+of an input vector map from one database and write to some other and
+even with some other driver (should not be a problem).
+
+There are open questions, however. For one, how does one distinguish when
+new tables should be written and when not? For example, definitions:
+
+\verbatim
+river 1 river id water odbc
+river.backup* 1 NONE
+\endverbatim
+
+could be used to say that tables should not be copied for backups of
+map river because table is stored in a reliable RDBMS.
+
+\section vlibs Vector libraries
+
+Besides internal library functions there are two main libraries:
+
+- Vlib (Vector library), see \ref vlibIntro
+- DGLib (Directed Graph Library), see \ref vlibDglib
+
+For historical reasons, there are two internal libraries:
+
+- diglib (with dig_*() functions), GRASS 3.x/4.x
+- Vlib (with V1_*(), V2_*() and Vect_*() functions), since GRASS 4.x
+ (except for the 5.7 interim version)
+
+The vector library was introduced in GRASS 4.0 to hide internal vector
+files' formats and structures. In GRASS 6/7, everything is accessed via
+Vect_*() functions, for example:
+
+Old 4.x code:
+
+\code
+ xx = Map.Att[Map.Area[area_num].att].x;
+\endcode
+
+New 6.x/7.x functions:
+
+\code
+ centroid = Vect_get_area_centroid(Map, area_num);
+ Vect_read_line(Map, line_p, NULL, centroid);
+ Vect_line_get_point(line_p, 0, &xx, NULL, NULL);
+\endcode
+
+In GRASS 6/7, all internal, mostly non-topological vector functions are
+hidden from the modules' API (mainly dig_*(), V1_*() and V2_*()
+functions). All available Vect_*() functions are topological vector
+functions.
+
+
+The following include file contains definitions and structures
+required by some of the routines in this library. The programmer
+should therefore include this file in any code that uses the vector
+library:
+
+\code
+#include <grass/vector.h>
+\endcode
+
+<i>Note: For details please read Blazek et al. 2002 (see below) as
+well as the references in this document.</i>
+
+\subsection vlibHistory Historical notes
+
+The vector library in GRASS 4.0 changed significantly from the
+<em>Digit Library</em> (diglib) used in GRASS 3.1. Below is an
+overview of why the changes were made.
+
+The Digit Library was a collage of subroutines created for developing
+the map development programs. Few of these subroutines were actually
+designed as a user access library. They required individuals to assume
+too much responsibility and control over what happened to the data
+file. Thus when it came time to change vector data file formats for
+GRASS 4.0, many modules also required modification. The two different
+access levels for 3.0 vector files provided very different ways of
+calling the library; they offered little consistency for the user.
+
+The Digit Library was originally designed to only have one file open
+for read or write at a time. Although it was possible in some cases to
+get around this, one restriction was the global head structure. Since
+there was only one instance of this, there could only be one copy of
+that information, and thus, only one open vector file.
+
+The solution to these problems was to design a new user library as an
+interface to the vector data files. This new library was designed to
+provide a simple consistent interface, which hides as much of the
+details of the data format as possible. It also could be extended for
+future enhancements without the need to change existing programs.
+
+The new vector library in GRASS 4 provided routines for opening,
+closing, reading, and writing vector files, as well as several support
+functions. The Digit Library has been replaced, so that all existing
+modules was converted to use the new library. Those routines that
+existed in the Digit Library and were not affected by these changes
+continue to exist in unmodified form, and were included in the vector
+library. Most of the commonly used routines have been discarded, and
+replaced by the new vector routines.
+
+Instead the global head structure was used own local version of
+it. The structure that replaced structure head is structure \ref
+dig_head. There were still two levels of interface to the vector files
+(future releases may include more). Level one provided access only to
+arc (i.e. polyline) information and to the type of line (AREA, LINE,
+DOT). Level two provided access to polygons (areas), attributes, and
+network topology.
+
+
+\subsection vlibCoorFileFormat Coor file format specification
+
+In the coor file the following is stored: 'line' (element) type,
+number of attributes and layer number for each category. Coordinates
+in binary file are stored as double (8 bytes). See \ref Coor_info data
+structure.
+
+\subsubsection vlibCoorFileHead Header
+
+<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>
+<tr><td>Version_Major</td> <td>C</td> <td>1</td> <td>file version (major)</td></tr>
+<tr><td>Version_Minor</td> <td>C</td> <td>1</td> <td>file version (minor)</td></tr>
+<tr><td>Back_Major</td> <td>C</td> <td>1</td> <td>supported from GRASS version (major)</td></tr>
+<tr><td>Back_Minor</td> <td>C</td> <td>1</td> <td>supported from GRASS version (minor)</td></tr>
+<tr><td>byte_order</td> <td>C</td> <td>1</td> <td>little or big endian flag</td></tr>
+<tr><td>head_size</td> <td>L</td> <td>1</td> <td>header size of coor file</td></tr>
+<tr><td>with_z</td> <td>C</td> <td>1</td> <td>2D or 3D flag; zero for 2D</td></tr>
+<tr><td>size</td> <td>L</td> <td>1</td> <td>coor file size</td></tr>
+</table>
+
+\section vlibCoorFileBody Body
+
+The body consists of line records:
+
+<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>
+<tr><td>record header</td><td>C</td><td>1</td><td>
+ - 0. bit: 1 - alive, 0 - dead line
+ - 1. bit: 1 - categories, 0 - no categories
+ - 2.-3. bit: type - one of: GV_POINT, GV_LINE, GV_BOUNDARY, GV_CENTROID, GV_FACE, GV_KERNEL
+ - 4.-7. bit: reserved, not used
+</td></tr>
+
+<tr><td>ncats</td><td>I</td><td>1</td><td>number of categories
+ (written only if categories exist) </td></tr>
+
+<tr><td>field</td><td>I</td><td>ncats</td><td>field identifier,
+ distinguishes between more categories append to one feature (written
+ only if categories exist; field is called "layer" at user
+ level)</td></tr>
+
+<tr><td>cat</td><td>I</td><td>ncats</td><td>category value (written
+ only if categories exist)</td></tr>
+
+<tr><td>ncoor</td><td>I</td><td>1</td><td>written for GV_LINES and GV_BOUNDARIES
+ only</td></tr>
+
+<tr><td>x</td><td>D</td><td>ncoor</td><td>x coordinate</td></tr>
+
+<tr><td>y</td><td>D</td><td>ncoor</td><td>y coordinate</td></tr>
+
+<tr><td>z</td><td>D</td><td>ncoor</td><td>z coordinate; present if
+ with_z in head is set to 1</td></tr> </table>
+
+Types used in coor file:
+
+<table border="1" style="border-collapse: collapse" cellpadding="5">
+<tr><td><b>Type</b></td><td><b>Name</b></td><td><b>Size in Bytes</b></td></tr>
+<tr><td>D</td><td>Double</td><td>8</td></tr>
+<tr><td>L</td><td>Long </td><td>4</td></tr>
+<tr><td>I</td><td>Int </td><td>4</td></tr>
+<tr><td>S</td><td>Short </td><td>4</td></tr>
+<tr><td>C</td><td>Char </td><td>1</td></tr>
+</table>
+
+
+
+*/
Added: grass/trunk/lib/vector/vectorlib_libraries.dox
===================================================================
--- grass/trunk/lib/vector/vectorlib_libraries.dox (rev 0)
+++ grass/trunk/lib/vector/vectorlib_libraries.dox 2012-08-07 17:45:22 UTC (rev 52585)
@@ -0,0 +1,106 @@
+/*! \page vlibs Vector libraries
+
+by GRASS Development Team (http://grass.osgeo.org)
+
+\tableofcontents
+
+\par Table of contents
+
+- \ref vlibsAboutIntro
+- \ref vlibsHistory
+
+\section vlibsAboutIntro Introduction
+
+Besides internal library functions there are two main libraries:
+
+- Vlib (Vector library), see \ref vlibIntro
+- DGLib (Directed Graph Library), see \ref dglib
+
+For historical reasons, there are two internal libraries:
+
+- diglib (with dig_*() functions), GRASS 3.x/4.x
+- Vlib (with V1_*(), V2_*() and Vect_*() functions), since GRASS 4.x
+ (except for the 5.7 interim version)
+
+The vector library was introduced in GRASS 4.0 to hide internal vector
+files' formats and structures. In GRASS 6/7, everything is accessed via
+Vect_*() functions, for example:
+
+Old 4.x code:
+
+\code
+ xx = Map.Att[Map.Area[area_num].att].x;
+\endcode
+
+New 6.x/7.x functions:
+
+\code
+ centroid = Vect_get_area_centroid(Map, area_num);
+ Vect_read_line(Map, line_p, NULL, centroid);
+ Vect_line_get_point(line_p, 0, &xx, NULL, NULL);
+\endcode
+
+In GRASS 6/7, all internal, mostly non-topological vector functions are
+hidden from the modules' API (mainly dig_*(), V1_*() and V2_*()
+functions). All available Vect_*() functions are topological vector
+functions.
+
+
+The following include file contains definitions and structures
+required by some of the routines in this library. The programmer
+should therefore include this file in any code that uses the vector
+library:
+
+\code
+#include <grass/vector.h>
+\endcode
+
+<i>Note: For details please read Blazek et al. 2002 (see below) as
+well as the references in this document.</i>
+
+\section vlibsHistory Historical notes
+
+The vector library in GRASS 4.0 changed significantly from the
+<em>Digit Library</em> (diglib) used in GRASS 3.1. Below is an
+overview of why the changes were made.
+
+The Digit Library was a collage of subroutines created for developing
+the map development programs. Few of these subroutines were actually
+designed as a user access library. They required individuals to assume
+too much responsibility and control over what happened to the data
+file. Thus when it came time to change vector data file formats for
+GRASS 4.0, many modules also required modification. The two different
+access levels for 3.0 vector files provided very different ways of
+calling the library; they offered little consistency for the user.
+
+The Digit Library was originally designed to only have one file open
+for read or write at a time. Although it was possible in some cases to
+get around this, one restriction was the global head structure. Since
+there was only one instance of this, there could only be one copy of
+that information, and thus, only one open vector file.
+
+The solution to these problems was to design a new user library as an
+interface to the vector data files. This new library was designed to
+provide a simple consistent interface, which hides as much of the
+details of the data format as possible. It also could be extended for
+future enhancements without the need to change existing programs.
+
+The new vector library in GRASS 4 provided routines for opening,
+closing, reading, and writing vector files, as well as several support
+functions. The Digit Library has been replaced, so that all existing
+modules was converted to use the new library. Those routines that
+existed in the Digit Library and were not affected by these changes
+continue to exist in unmodified form, and were included in the vector
+library. Most of the commonly used routines have been discarded, and
+replaced by the new vector routines.
+
+Instead the global head structure was used own local version of
+it. The structure that replaced structure head is structure \ref
+dig_head. There were still two levels of interface to the vector files
+(future releases may include more). Level one provided access only to
+arc (i.e. polyline) information and to the type of line (AREA, LINE,
+DOT). Level two provided access to polygons (areas), attributes, and
+network topology.
+
+
+*/
Added: grass/trunk/lib/vector/vectorlib_ogr.dox
===================================================================
--- grass/trunk/lib/vector/vectorlib_ogr.dox (rev 0)
+++ grass/trunk/lib/vector/vectorlib_ogr.dox 2012-08-07 17:45:22 UTC (rev 52585)
@@ -0,0 +1,74 @@
+/*! \page vlibOgr OGR interface
+
+by GRASS Development Team (http://grass.osgeo.org)
+
+\par Table of contents
+
+- \ref vlibOgrIface
+ - \ref vlibFrmtFileFormat
+ - \ref vlibFidxFileFormat
+
+
+\section vlibOgrIface OGR interface
+
+\subsection vLibPseudoTopo Pseudo-topology
+
+Reduced topology: each boundary is attached to one area only,
+i.e. smoothing, simplification, removing small areas etc. will not
+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 converted to areas and cleaned as done
+by <tt>v.in.ogr</tt>.
+
+\subsection vlibFrmtFileFormat Frmt file format specification
+
+Frmt is a plain text file which contains basic information about
+external format of linked vector map. Each line contains key, value
+pairs separated by comma.
+
+OGR specific format is described by:
+
+ - FORMAT - ogr
+ - DSN - OGR datasource name
+ - LAYER - OGR layer name
+
+Example:
+
+\verbatim
+FORMAT: ogr
+DSN: /path/to/shapefiles
+LAYER: cities
+\endverbatim
+
+OGR layer can be linked via <tt>v.external</tt> command. When linking
+OGR layer pseudo-topology ('topo') is built including spatial index
+file ('sidx') and category index file ('cidx'). Additionally also
+feature index file (see \ref vlibFidxFileFormat) is created.
+
+\subsection vlibFidxFileFormat Fidx file format specification
+
+Note: <tt>finfo</tt> is an instance of \ref Format_info 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>
+
+<tr><td>Version_Major </td><td>C</td><td>1</td><td>file version (major)</td></tr>
+<tr><td>Version_Minor </td><td>C</td><td>1</td><td>file version (minor)</td></tr>
+<tr><td>Back_Major</td><td>C</td><td>1</td><td>supported from GRASS version (major)</td></tr>
+<tr><td>Back_Minor</td><td>C</td><td>1</td><td>supported from GRASS version (minor)</td></tr>
+
+<tr><td>byte_order</td><td>C</td><td>1</td><td>little or big endian
+ flag; files are written in machine native order but
+ files in both little and big endian order may be
+ readl; zero for little endian</td></tr>
+
+<tr><td>length</td><td>L</td><td>1</td><td>header size</td></tr>
+
+<tr><td>fInfo.ogr.offset_num</td><td>I</td><td>1</td><td>number of records</td></tr>
+
+<tr><td>fInfo.ogr.offset</td><td>I</td><td>offset_num</td><td>offsets</td></tr>
+
+</table>
+
+*/
Added: grass/trunk/lib/vector/vectorlib_spatialindex.dox
===================================================================
--- grass/trunk/lib/vector/vectorlib_spatialindex.dox (rev 0)
+++ grass/trunk/lib/vector/vectorlib_spatialindex.dox 2012-08-07 17:45:22 UTC (rev 52585)
@@ -0,0 +1,234 @@
+/*! \page vlibSpatialIndex Spatial index
+
+by GRASS Development Team (http://grass.osgeo.org)
+
+\par Table of contents
+
+- \ref vlibSpidx
+ - \ref vlibSidxFileFormat
+- \ref vlibCidx
+ - \ref vlibCidxFileFormat
+ - \ref vlibCidxFileHead
+
+
+\section vlibSpidx Vector library spatial index management
+
+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 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
+<tt>exit()</tt> and operating system releases all the memory much
+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 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
+file.
+
+Currently most of the modules do not release the memory occupied for
+spatial index and work like this (pseudocode):
+
+\code
+int main
+{
+ Vect_open_new();
+ /* writing new vector */
+
+ Vect_build();
+ Vect_close(); /* memory is not released */
+}
+\endcode
+
+In general it is possible to free the memory with Vect_set_release_support()
+such as:
+
+\code
+int main
+{
+ Vect_open_new();
+ /* writing new vector */
+
+ Vect_build();
+ Vect_set_release_support();
+ Vect_close(); /* memory is released */
+}
+\endcode
+
+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
+applies only when creating a new vector or updating an old vector.
+For example:
+
+\code
+int main
+{
+ Vect_open_update();
+ /* select features using spatial index, e.g. Vect_select_lines_by_box() */
+ Vect_set_release_support();
+ Vect_close(); /* memory is released */
+
+ /* do some processing which needs memory */
+}
+\endcode
+
+See also \ref spatial_index data structure.
+
+\subsection vlibSidxFileFormat Sidx file format specification
+
+Spatial index file ('sidx') is read by Vect_open_sidx().
+
+\subsubsection vlibSidxFileHead Header
+
+Note: <tt>plus</tt> is instance of \ref Plus_head 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>
+
+<tr><td>plus->spidx_Version_Major </td><td>C</td><td>1</td><td>file version (major)</td></tr>
+<tr><td>plus->spidx_Version_Minor </td><td>C</td><td>1</td><td>file version (minor)</td></tr>
+<tr><td>plus->spidx_Back_Major</td><td>C</td><td>1</td><td>supported from GRASS version (major)</td></tr>
+<tr><td>plus->spidx_Back_Minor</td><td>C</td><td>1</td><td>supported from GRASS version (minor)</td></tr>
+
+<tr><td>plus->spidx_port->byte_order</td><td>C</td><td>1</td><td>little or big endian
+ flag; files are written in machine native order but
+ files in both little and big endian order may be
+ readl; zero for little endian</td></tr>
+
+<tr><td>plus->spidx_port.off_t_size</td><td>C</td><td>1</td><td>off_t size (LFS)</td></tr>
+
+<tr><td>plus->spidx_head_size</td><td>L</td><td>1</td><td>header size</td></tr>
+
+<tr><td>plus->spidx_with_z</td><td>C</td><td>1</td><td>2D/3D vector data</td></tr>
+
+<tr><td>ndims</td><td>C</td><td>1</td><td>Number of dimensions</td></tr>
+
+<tr><td>nsides</td><td>C</td><td>1</td><td>Number of sides</td></tr>
+
+<tr><td>nodesize</td><td>I</td><td>1</td><td>%Node size</td></tr>
+
+<tr><td>nodecard</td><td>I</td><td>1</td><td>%Node card (?)</td></tr>
+
+<tr><td>leafcard</td><td>I</td><td>1</td><td>Leaf card (?)</td></tr>
+
+<tr><td>min_node_fill</td><td>I</td><td>1</td><td>Minimum node fill (?)</td></tr>
+
+<tr><td>min_leaf_fill</td><td>I</td><td>1</td><td>Minimum leaf fill (?)</td></tr>
+
+<tr><td>plus->Node_spidx->n_nodes</td><td>I</td><td>1</td><td>Number of nodes</td></tr>
+
+<tr><td>plus->Node_spidx->n_leafs</td><td>I</td><td>1</td><td>Number of leafs</td></tr>
+
+<tr><td>plus->Node_spidx->n_levels</td><td>I</td><td>1</td><td>Number of levels</td></tr>
+
+<tr><td>plus->Node_spidx_offset</td><td>O</td><td>1</td><td>%Node offset</td></tr>
+
+<tr><td>plus->Line_spidx->n_nodes</td><td>I</td><td>1</td><td>Number of nodes</td></tr>
+
+<tr><td>plus->Line_spidx->n_leafs</td><td>I</td><td>1</td><td>Number of leafs</td></tr>
+
+<tr><td>plus->Line_spidx->n_levels</td><td>I</td><td>1</td><td>Number of levels</td></tr>
+
+<tr><td>plus->Line_spidx_offset</td><td>O</td><td>1</td><td>Line offset</td></tr>
+
+<tr><td>plus->Area_spidx->n_nodes</td><td>I</td><td>1</td><td>Number of nodes</td></tr>
+
+<tr><td>plus->Area_spidx->n_leafs</td><td>I</td><td>1</td><td>Number of leafs</td></tr>
+
+<tr><td>plus->Area_spidx->n_levels</td><td>I</td><td>1</td><td>Number of levels</td></tr>
+
+<tr><td>plus->Area_spidx_offset</td><td>O</td><td>1</td><td>Area offset</td></tr>
+
+<tr><td>plus->Isle_spidx->n_nodes</td><td>I</td><td>1</td><td>Number of nodes</td></tr>
+
+<tr><td>plus->Isle_spidx->n_leafs</td><td>I</td><td>1</td><td>Number of leafs</td></tr>
+
+<tr><td>plus->Isle_spidx->n_levels</td><td>I</td><td>1</td><td>Number of levels</td></tr>
+
+<tr><td>plus->Isle_spidx_offset</td><td>O</td><td>1</td><td>Isle offset</td></tr>
+
+<tr><td>plus->Face_spidx_offset</td><td>O</td><td>1</td><td>Face offset</td></tr>
+
+<tr><td>plus->Volume_spidx_offset</td><td>O</td><td>1</td><td>Volume offset</td></tr>
+
+<tr><td>plus->Hole_spidx_offset</td><td>O</td><td>1</td><td>Hole offset</td></tr>
+
+<tr><td>plus->coor_size</td><td>O</td><td>1</td><td>Coor file size</td></tr>
+</table>
+
+\section vlibCidx Vector library category index management
+
+The category index (stored in the cidx file) improves the performance
+of all selections by cats/attributes (SQL, e.g. <tt>d.vect
+cats=27591</tt>, <tt>v.extract list=20000-21000</tt>). This avoids
+that all selections have to be made by looping through all vector
+lines. Category index is also essential for simple feature
+representation of GRASS vectors.
+
+Category index is created for each field. In memory, it is stored in
+\ref Cat_index data structure.
+
+Category index is built with topology, but it is <b>not updated</b> if
+vector is edited on level 2. Category index is stored in 'cidx' file,
+'cat' array is written/read by one call of dig__fwrite_port_I() or
+dig__fread_port_I().
+
+Stored values can be retrieved either by index in 'cat' array (if all
+features of given field are required) or by category value (one or few
+features), always by <tt>Vect_cidx_*()</tt> functions.
+
+To create category index, it will be necessary to rebuild topology for
+all existing vectors. This is an opportunity to make (hopefully) last
+changes in 'topo', 'cidx' formats.
+
+\subsection vlibCidxFileFormat Cidx file format specification
+
+Category index file ('cidx') is read by Vect_cidx_open().
+
+\subsubsection vlibCidxFileHead Header
+
+Note: <tt>plus</tt> is instance of \ref Plus_head 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>
+
+<tr><td>plus->cpidx_Version_Major </td><td>C</td><td>1</td><td>file version (major)</td></tr>
+<tr><td>plus->cpidx_Version_Minor </td><td>C</td><td>1</td><td>file version (minor)</td></tr>
+<tr><td>plus->cpidx_Back_Major</td><td>C</td><td>1</td><td>supported from GRASS version (major)</td></tr>
+<tr><td>plus->cpidx_Back_Minor</td><td>C</td><td>1</td><td>supported from GRASS version (minor)</td></tr>
+
+<tr><td>plus->cidx_port->byte_order</td><td>C</td><td>1</td><td>little or big endian
+ flag; files are written in machine native order but
+ files in both little and big endian order may be
+ readl; zero for little endian</td></tr>
+
+<tr><td>plus->cidx_head_size</td><td>L</td><td>1</td><td>cidx head size</td></tr>
+
+<tr><td>plus->n_cidx</td><td>I</td><td>1</td><td>number of fields</td></tr>
+
+<tr><td>field</td><td>I</td><td>n_cidx</td><td>field number</td></tr>
+
+<tr><td>n_cats</td><td>I</td><td>n_cidx</td><td>number of categories</td></tr>
+
+<tr><td>n_ucats</td><td>I</td><td>n_cidx</td><td>number of unique categories</td></tr>
+
+<tr><td>n_types</td><td>I</td><td>n_cidx</td><td>number of feature types</td></tr>
+
+<tr><td>rtype</td><td>I</td><td>n_cidx * n_types</td><td>Feature type</td></tr>
+
+<tr><td>type[t]</td><td>I</td><td>n_cidx * n_types</td><td>Number of items</td></tr>
+
+</table>
+
+
+*/
Added: grass/trunk/lib/vector/vectorlib_tin.dox
===================================================================
--- grass/trunk/lib/vector/vectorlib_tin.dox (rev 0)
+++ grass/trunk/lib/vector/vectorlib_tin.dox 2012-08-07 17:45:22 UTC (rev 52585)
@@ -0,0 +1,13 @@
+/*! \page vlibTin Vector TINs
+
+by GRASS Development Team (http://grass.osgeo.org)
+
+<em>This page needs to be enhanced.</em>
+
+\section vlibTinIntro Short introduction
+
+TINs are simply created as 2D/3D vector polygons consisting of
+3 vertices. See Vect_tin_get_z().
+
+
+*/
Added: grass/trunk/lib/vector/vectorlib_topology.dox
===================================================================
--- grass/trunk/lib/vector/vectorlib_topology.dox (rev 0)
+++ grass/trunk/lib/vector/vectorlib_topology.dox 2012-08-07 17:45:22 UTC (rev 52585)
@@ -0,0 +1,460 @@
+/*! \page vlibTopology Topology
+
+by GRASS Development Team (http://grass.osgeo.org)
+
+\par Table of contents
+
+- \ref vlibTopoManagement
+ - \ref vlibTopoFileFormat
+ - \ref vlibTopoFileHead
+ - \ref vlibTopoFileBody
+ - \ref vlibTopoLevels
+ - \ref vlibTopoExamples
+ - \ref vlibTopoMemory
+
+
+
+\section vlibTopoManagement Vector library topology management
+
+Topology general characteristics:
+
+- geometry and attributes are stored separately
+ (don't read both if it is not necessary - usually it is not)
+- the format is topological (areas build from boundaries)
+- currently only 2D topology is supported
+
+Topology is written for native GRASS vector format; in case of
+linked OGR sources (see <tt>v.external</tt> module), only
+pseudo-topology (boundaries constructed from polygons) is written.
+
+The following rules apply to the vector data:
+
+- Boundaries should not cross each other (i.e., boundaries which would
+ cross must be split at their intersection to form distict boundaries).
+ On the contrary, lines can cross each other, e.g. bridges over rivers.
+- Lines and boundaries share nodes only if their endpoints are identical.
+ Lines or boundaries can be 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 in closed
+ areas.
+- It is recommended that area features and linear features be placed
+ in separate layers. However if area features and linear features
+ must appear in one layer, common boundaries should be digitized only
+ once. For example, a boundary that is also a line (e.g., a road which
+ is also a field boundary), should be digitized as a boundary to
+ complete the area(s), and a boundary which is functionally 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>
+command.
+
+\subsection vlibTopoFileFormat Topo file format specification
+
+Topo file is read by Vect_open_topo().
+
+\subsubsection vlibTopoFileHead Header
+
+<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>
+
+<tr><td>plus->Version_Major </td><td>C</td><td>1</td><td>file version (major)</td></tr>
+<tr><td>plus->Version_Minor </td><td>C</td><td>1</td><td>file version (minor)</td></tr>
+<tr><td>plus->Back_Major</td><td>C</td><td>1</td><td>supported from GRASS version (major)</td></tr>
+<tr><td>plus->Back_Minor</td><td>C</td><td>1</td><td>supported from GRASS version (minor)</td></tr>
+
+<tr><td>plus->port->byte_order</td><td>C</td><td>1</td><td>little or big endian
+ flag; files are written in machine native order but
+ files in both little and big endian order may be
+ readl; zero for little endian</td></tr>
+
+<tr><td>plus->head_size</td><td>L</td><td>1</td><td>header size</td></tr>
+
+<tr><td>plus->with_z</td><td>C</td><td>1</td><td>2D or 3D flag; zero for 2D</td></tr>
+
+<tr><td>plus->box</td><td>D</td><td>6</td><td>Bounding box coordinates (N,S,E,W,T,B)</td></tr>
+
+<tr><td>plus->n_nodes, plus->n_lines, etc.</td><td>I</td><td>7</td><td>Number of
+nodes, edges, lines, areas, isles, volumes and holes</td></tr>
+
+<tr><td>plus->n_plines, plus->n_llines, etc.</td><td>I</td><td>7</td><td>Number of
+points, lines, boundaries, centroids, faces and kernels</td></tr>
+
+<tr><td>plus->Node_offset, plus->Edge_offset,
+etc.</td><td>L</td><td>7</td><td>Offset value for nodes, edges, lines,
+areas, isles, volumes and holes</td></tr>
+
+<tr><td>plus->coor_size</td><td>L</td><td>1</td><td>File size</td></tr>
+</table>
+
+\subsubsection vlibTopoFileBody Body (nodes, lines, areas, isles)
+
+<b>Nodes</b>
+
+For each node (plus->n_nodes):
+
+<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>
+<tr><td>n_lines</td><td>I</td><td>1</td><td>Number of lines (0 for dead node)</td></tr>
+<tr><td>lines</td><td>I</td><td>n_lines</td><td>Line ids (negative id for line which ends at the node)</td></tr>
+<tr><td>angles</td><td>D</td><td>n_lines</td><td>Angle value</td></tr>
+<tr><td>n_edges</td><td>I</td><td>1</td><td>Reserved for edges (only for <tt>with_z</tt>)</td></tr>
+<tr><td>x,y</td><td>D</td><td>2</td><td>Coordinate pair (2D)</td></tr>
+<tr><td>z</td><td>D</td><td>1</td><td>Only for <tt>with_z</tt> (3D)</td></tr>
+</table>
+
+See \ref P_node data structure.
+
+<b>Lines</b>
+
+For each line (plus->n_lines):
+
+<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>
+<tr><td>feature type</td><td>C</td><td>1</td><td>0 for dead line</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>Start 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>End 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>
+</table>
+
+See \ref P_line data structure.
+
+<b>Areas</b>
+
+For each area (plus->n_areas):
+
+<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>
+<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 forming exterior boundary (clockwise order, negative id for backward direction)</td></tr>
+<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>
+</table>
+
+See \ref P_area data structure.
+
+<b>Isles</b>
+
+For each isle (plus->n_isle):
+
+<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>
+<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 forming exterior boundary (counter-clockwise order, negative id for backward direction)</td></tr>
+<tr><td>area</td><td>I</td><td>1</td><td>Outer area id</td></tr>
+</table>
+
+See \ref P_isle data structure.
+
+\subsection vlibTopoLevels Topology levels
+
+The vector library defines more <i>topology levels</i> (only for level
+of access 2):
+
+- GV_BUILD_NONE
+- GV_BUILD_BASE
+- GV_BUILD_AREAS
+- GV_BUILD_ATTACH_ISLES
+- GV_BUILD_CENTROIDS
+- GV_BUILD_ALL
+
+<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
+
+<b>Points</b>
+
+\verbatim
+One point (nodes: 0, lines: 1, areas: 0, isles: 0)
+
+ + N1/L1
+\endverbatim
+
+Line L1 (see \ref P_line)
+
+\verbatim
+line = 1, type = 1 (GV_POINT)
+\endverbatim
+
+<b>Lines</b>
+
+\verbatim
+One line (nodes: 2, lines: 1, areas: 0, isles: 0)
+
+
+ +----L1----+
+ N1 N2
+\endverbatim
+
+%Node N1 (see \ref P_node)
+
+\verbatim
+node = 1, n_lines = 1, xyz = 634624.746450, 223557.302231, 0.000000
+ line = 1, type = 2 (GV_LINE), angle = -0.436257
+\endverbatim
+
+%Node N2 (see \ref P_node)
+
+\verbatim
+node = 2, n_lines = 1, xyz = 638677.484787, 221667.849899, 0.000000
+ line = -1, type = 2 (GV_LINE), angle = 2.705335
+\endverbatim
+
+Line L1 (see \ref P_line)
+
+\verbatim
+line = 1, type = 2 (GV_LINE), n1 = 1, n2 = 2
+\endverbatim
+
+<b>Areas without holes</b>
+
+\verbatim
+Two lines (nodes: 1, lines: 2, areas: 1, isles: 1)
+
+ +N1
+ / \
+ / \
+ / \
+ / +L2 \
+ / \
+ -------L1------
+\endverbatim
+
+%Node N1 (see \ref P_node)
+
+\verbatim
+node = 1, n_lines = 2, xyz = 635720.081136, 225063.387424, 0.000000
+ line = 1, type = 4 (GV_BOUNDARY), angle = -2.245537
+ line = -1, type = 4 (GV_BOUNDARY), angle = -0.842926
+\endverbatim
+
+Line L1 (see \ref P_line)
+
+\verbatim
+line = 1, type = 4 (GV_BOUNDARY), n1 = 1, n2 = 1, left = 1, right = -1
+\endverbatim
+
+Line L2 (see \ref P_line)
+
+\verbatim
+line = 2, type = 8 (GV_CENTROID), area = 1
+\endverbatim
+
+Area A1 (see \ref P_area)
+
+\verbatim
+area = 1, n_lines = 1, n_isles = 0 centroid = 2
+ line = -1
+\endverbatim
+
+Isle I1 (see \ref P_isle)
+
+\verbatim
+isle = 1, n_lines = 1 area = 0
+ line = 1
+\endverbatim
+
+<b>Areas with holes</b>
+
+\verbatim
+Three lines (nodes: 2, lines: 3, areas: 2, isles: 2)
+
+ +N1
+ / \
+ / \
+ / \
+ / \
+ / +L2 \
+ / \
+ / +N2 \
+ / /\ \
+ / / \ \
+ / / \ \
+ / ---L3-- \
+ / \
+------------L1-------------
+\endverbatim
+
+%Node N1 (see \ref P_node)
+
+\verbatim
+node = 1, n_lines = 2, xyz = 635720.081136, 225063.387424, 0.000000
+ line = 1, type = 4 (GV_BOUNDARY), angle = -2.245537
+ line = -1, type = 4 (GV_BOUNDARY), angle = -0.842926
+\endverbatim
+
+%Node N2 (see \ref P_node)
+
+\verbatim
+node = 2, n_lines = 2, xyz = 636788.032454, 223173.935091, 0.000000
+ line = 3, type = 4 (GV_BOUNDARY), angle = -2.245537
+ line = -3, type = 4 (GV_BOUNDARY), angle = -0.866302
+\endverbatim
+
+Line L1 (see \ref P_line)
+
+\verbatim
+line = 1, type = 4 (GV_BOUNDARY), n1 = 1, n2 = 1, left = 1, right = -1
+\endverbatim
+
+Line L2 (see \ref P_line)
+
+\verbatim
+line = 2, type = 8 (GV_CENTROID), area = 1
+\endverbatim
+
+Line L3 (see \ref P_line)
+
+\verbatim
+line = 3, type = 4 (GV_BOUNDARY), n1 = 3, n2 = 3, left = 2, right = -2
+\endverbatim
+
+Area A1 (see \ref P_area)
+
+\verbatim
+area = 1, n_lines = 1, n_isles = 1 centroid = 2
+ line = -1
+ isle = 2
+\endverbatim
+
+Area A2 (see \ref P_area)
+
+\verbatim
+area = 2, n_lines = 1, n_isles = 0 centroid = 0
+ line = -3
+\endverbatim
+
+Isle I1 (see \ref P_isle)
+
+\verbatim
+isle = 1, n_lines = 1 area = 0
+ line = 1
+\endverbatim
+
+Isle I2 (see \ref P_isle)
+
+\verbatim
+isle = 2, n_lines = 1 area = 1
+ line = 3
+\endverbatim
+
+<b>Example 1</b>
+
+A polygon may be formed by many boundaries (several connected primitives).
+One boundary is shared by adjacent areas.
+
+\verbatim
++--1--+--5--+
+| | |
+2 A 4 B 6
+| | |
++--3--+--7--+
+
+1,2,3,4,5,6,7 = 7 boundaries (primitives)
+A,B = 2 areas
+A+B = 1 isle
+\endverbatim
+
+<b>Example 2</b>
+
+This is handled correctly in GRASS: A can be filled, B filled differently.
+
+\verbatim
++---------+
+| A |
++-----+ |
+| B | |
++-----+ |
+| |
++---------+
+
+A, B = 2 areas
+A+B = 1 isle
+\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.
+
+<b>Example 3</b>
+
+This is handled correctly in GRASS: Areas A1, A2, and A3 can be filled differently.
+
+\verbatim
++---------------------+
+| A1 |
++ +------+------+ |
+| | A2 | A3 | |
++ +------+------+ |
+| I1 |
++---------------------+
+
+A1,A2,A3 = 3 areas
+A1,A2+A3 = 2 isles
+\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.
+
+<b>Example 4</b>
+
+<tt>v.in.ogr/v.clean</tt> 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:
+
+\verbatim
++-----+-----+
+| . |
+| . |
++.....+.....+
+| . |
+| x . |
++-----+-----+
+
+---- road + boundary of one parcel => type boundary
+.... road => type line
+x parcel centroid (identifies whole area)
+\endverbatim
+
+Because lines are not used to build areas, we have only one
+area/centroid, instead of 4 which would be necessary in TIGER.
+
+\subsection vlibTopoMemory Topology memory management
+
+Topology is generated for all kinds of vector types. Memory is not
+released by default. The programmer can force the library to release
+the memory by using Vect_set_release_support(). But: The programmer
+cannot run Vect_set_release_support() in mid process because all
+vectors are needed in the spatial index, which is needed to build topology.
+
+Topology is also necessary for points in case of a vector network
+because the graph is built using topology information about lines
+and points.
+
+The topology structure does not only store the topology but also
+the 'line' bounding box and line offset in coor file (index).
+The existing spatial index is using line ID in 'topology' structure
+to identify lines in 'coor' file. Currently it is not possible to build
+spatial index without topology.
+
+
+*/
More information about the grass-commit
mailing list