[GRASS-SVN] r29614 - grass/branches/releasebranch_6_3/lib/vector
svn_grass at osgeo.org
svn_grass at osgeo.org
Tue Jan 8 08:44:31 EST 2008
Author: neteler
Date: 2008-01-08 08:44:30 -0500 (Tue, 08 Jan 2008)
New Revision: 29614
Modified:
grass/branches/releasebranch_6_3/lib/vector/vectorlib.dox
Log:
updated to HEAD
Modified: grass/branches/releasebranch_6_3/lib/vector/vectorlib.dox
===================================================================
--- grass/branches/releasebranch_6_3/lib/vector/vectorlib.dox 2008-01-08 13:43:39 UTC (rev 29613)
+++ grass/branches/releasebranch_6_3/lib/vector/vectorlib.dox 2008-01-08 13:44:30 UTC (rev 29614)
@@ -2,7 +2,7 @@
by GRASS Development Team
-http://grass.itc.it
+http://www.grass-gis.org
<h2>Table of contents</h2>
@@ -101,9 +101,9 @@
The current implementation includes:
<ul>
-<li> multi-layer: features in one vector may represent more layers and
+<li> multi-layer: features in one vector map may represent more layers and
may be linked to more external tables (\ref vlib_categories_layers);
-<li> 2D and 3D vector geometry with topology (see \ref vlib_topology_management);
+<li> 2D and 3D vector geometry with topology (see \ref vlib_topology_management);
<li> multi-format: external data formats supported (SHAPE-file, OGR sources etc.);
<li> portability: platform independent internal format, read- and writable on 32bit,
64bit etc. computer architectures;
@@ -128,8 +128,8 @@
"layer" at user level). Single and multi-category support on modules
level are implemented. Z-coordinate is optional and both 2D and 3D
files may be written.
-<P>
+<p>
The following vector objects are defined:
<ul>
@@ -139,12 +139,13 @@
<li> centroid: a point within a closed boundary;
<li> area: the topological composition of centroid and boundary;
<li> face: a 3D area;
-<li> kernel: a 3D centroid in a volume (not yet implemented);
-<li> volume: a 3D corpus, the topological composition of faces and kernel (not yet implemented).
+<li> kernel: a 3D centroid in a volume;
+<li> volume: a 3D corpus, the topological composition of faces and kernel.
</ul>
Note that all lines and boundaries can be polylines (with nodes in
between).
+
\section libraries Vector Libraries
Besides internal library functions there are two main libraries:
@@ -157,10 +158,8 @@
For historical reasons, there are two internal libraries for vector:
<ul>
-<li> diglib (with dig_*() functions), DIGLIB, libdig.a, digit library, GRASS 3.x/4.x,<BR>
-and
-<li> Vlib (with V1_*(), V2_*() and Vect_*() functions), VECTLIB_REAL,
- libvect.a, vector library, GRASS 4.x/5.x (except for the 5.7 interim version)
+<li> diglib (with dig_*() functions), GRASS 3.x/4.x
+<li> Vlib (with V1_*(), V2_*() and Vect_*() functions), GRASS 4.x/5.x (except for the 5.7 interim version)
</ul>
The Vlib Vector library was introduced in GRASS 4.0 to hide internal vector
@@ -182,7 +181,6 @@
functions ). All available Vect_*() functions are topological vector
functions.
-
\subsection vlib Introduction to Vlib (Vector library)
<i>Note: For details please read Blazek et al. 2002 (see below) as well as the
@@ -192,9 +190,10 @@
Directory structure and file names are changed with respect to
previous GRASS versions. All vector files for one vector map are
-stored in one directory:<BR>
+stored in one directory:<br>
- <B>$MAPSET/vector/vector_name/</B>
+<b>$MAPSET/vector/vector_name/</b>
+
<p>
This directory contains these files:
@@ -207,11 +206,11 @@
<li><b>hist</b> - text file, vector map change history
</ul>
-\subsubsection coor_file_format_specification coor file format specification
+\subsubsection coor_file_format_specification Coor file format specification
<ol>
<li> In the coor file the following is stored: 'line' (element) type,
- number of attributes and layer number for each category.
+ number of attributes and layer number for each category.
<li> Coordinates in binary file are stored as double (8 bytes).
</ol>
@@ -220,29 +219,34 @@
<TABLE border=2>
<TR><TD>Name</TD><TD>Type</TD><TD>Number</TD><TD>Description</TD></TR>
-<TR><TD>Version_Major </TD><TD>C</TD><TD>1</TD><TD> </TD></TR>
-<TR><TD>Version_Minor </TD><TD>C</TD><TD>1</TD><TD> </TD></TR>
-<TR><TD>Earliest_Major</TD><TD>C</TD><TD>1</TD><TD> </TD></TR>
-<TR><TD>Earliest_Minor</TD><TD>C</TD><TD>1</TD><TD> </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 read</TD></TR>
-<TR><TD>with_z</TD><TD>C</TD><TD>1</TD><TD>2D or 3D flag</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>size</TD><TD>L</TD><TD>1</TD><TD>coor file size</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>reserved</TD><TD>C</TD><TD>10</TD><TD>not used</TD></TR>
</TABLE>
-<P>
+<p>
+
<b>Body</b>
The body consists of line records:
-<BR>
+<br>
<TABLE border=2>
<TR><TD>Name</TD><TD>Type</TD><TD>Number</TD><TD>Description</TD></TR>
-<TR><TD>record header</TD><TD>I</TD><TD>1</TD><TD>
+<TR><TD>record header</TD><TD>C</TD><TD>1</TD><TD>
<UL>
<LI><B>0. bit</B> : 1 - alive, 0 - dead line
<LI><B>1. bit</B> : 1 - categories, 0 - no categories
@@ -251,22 +255,28 @@
<LI><B>4.-7. bit</B> : reserved, not used
</UL>
</TD></TR>
-<TR><TD>ncats</TD><TD>C</TD><TD>1</TD><TD>number of categories
+
+<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>S</TD><TD>ncats</TD><TD>Category identifier,
- distinguishes between more categories append to one line
- (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>field</TD><TD>I</TD><TD>ncats</TD><TD>field identifier,
+ distinguishes between more categories append to one line (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> </TD></TR>
-<TR><TD>y</TD><TD>D</TD><TD>ncoor</TD><TD> </TD></TR>
-<TR><TD>z</TD><TD>D</TD><TD>ncoor</TD><TD>present if with_z in head
- is set to 1</TD></TR>
-</TABLE>
+<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>
+
<P>
<B>Types used in coor file</B>
<TABLE border=2>
@@ -279,11 +289,11 @@
</TABLE>
-\subsubsection head_file_format head file format
+\subsubsection head_file_format Head file format
-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. Key words are:<BR>
+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. Key words are:<br>
\verbatim
ORGANIZATION
@@ -303,19 +313,105 @@
<ol>
<li> geometry and attributes are stored separately
(don't read both if it is not necessary (usually it is not))</li>
-<li> the format is topological (areas build from boundaries)
-</li>
+<li> the format is topological (areas build from boundaries)</li>
+<li>currently only 2D topology is supported
</ol>
-<P>
+<p>
Topology is written for native format while pseudo-topology is written
for OGR sources, SHAPE-link.
+\subsection topo_file_format Topo file format
-\subsection topo_file_format topo file format
+<b>Head</b>
-[detailed docs please insert!]
+<TABLE border=2>
+<TR><TD>Name</TD><TD>Type</TD><TD>Number</TD><TD>Description</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>head_size</TD><TD>L</TD><TD>1</TD><TD>header size</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>box</TD><TD>D</TD><TD>6</TD><TD>Bounding box coordinates (N,S,E,W,T,B)</TD></TR>
+
+<TR><TD>n_nodes, 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>n_plines, n_llines, etc.</TD><TD>I</TD><TD>7</TD><TD>Number of
+points, lines, boundaries, centroids, faces and kernels</TD></TR>
+
+<TR><TD>Node_offset, 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>coor_size</TD><TD>L</TD><TD>1</TD><TD>File size</TD></TR>
+</TABLE>
+
+<b>Body</b>
+
+For each node (n_nodes):
+
+<TABLE border=2>
+<TR><TD>Name</TD><TD>Type</TD><TD>Number</TD><TD>Description</TD></TR>
+<TR><TD>n_lines</TD><TD>I</TD><TD>1</TD><TD>Number of lines (0 for dead node)</TD></TR>
+<TR><TD>lines</TD><TD>I</TD><TD>n_lines</TD><TD>Line ids</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 with_z)</TD></TR>
+<TR><TD>x,y</TD><TD>D</TD><TD>2</TD><TD>Coordinate pair</TD></TR>
+<TR><TD>z</TD><TD>D</TD><TD>1</TD><TD>Only for with_z</TD></TR>
+</TABLE>
+
+For each line (n_lines):
+
+<TABLE border=2>
+<TR><TD>Name</TD><TD>Type</TD><TD>Number</TD><TD>Description</TD></TR>
+<TR><TD>feature type</TD><TD>C</TD><TD>1</TD><TD>0 for dead</TD></TR>
+<TR><TD>offset</TD><TD>L</TD><TD>1</TD><TD>Line offset</TD></TR>
+<TR><TD>N1</TD><TD>I</TD><TD>1</TD><TD>First node id (only if feature type is GV_POINTS, GV_LINES or GV_KERNEL)</TD></TR>
+<TR><TD>N2</TD><TD>I</TD><TD>1</TD><TD>Second node id (only if feature type is GV_LINE or GV_BOUNDARY)</TD></TR>
+<TR><TD>left</TD><TD>I</TD><TD>1</TD><TD>Left area id for feature type GV_BOUNDARY / Area id for feature type GV_CENTROID</TD></TR>
+<TR><TD>right</TD><TD>I</TD><TD>1</TD><TD>Right area id (for feature type GV_BOUNDARY)</TD></TR>
+<TR><TD>vol</TD><TD>I</TD><TD>1</TD><TD>Reserved for kernel (volume number, for feature type GV_KERNEL)</TD></TR>
+<TR><TD>N,S,E,W</TD><TD>D</TD><TD>4</TD><TD>Line bounding box (for feature type GV_LINE, GV_BOUNDARY or GV_FACE)</TD></TR>
+<TR><TD>T,B</TD><TD>D</TD><TD>2</TD><TD>Line bounding box for 3D (only if with_z=1)</TD></TR>
+</TABLE>
+
+For each area (n_areas):
+
+<TABLE border=2>
+<TR><TD>Name</TD><TD>Type</TD><TD>Number</TD><TD>Description</TD></TR>
+<TR><TD>n_lines</TD><TD>I</TD><TD>1</TD><TD>number of boundaries</TD></TR>
+<TR><TD>lines</TD><TD>I</TD><TD>n_lines</TD><TD>Line ids</TD></TR>
+<TR><TD>n_isles</TD><TD>I</TD><TD>1</TD><TD>Number of isles</TD></TR>
+<TR><TD>isles</TD><TD>I</TD><TD>n_isles</TD><TD>Isle ids</TD></TR>
+<TR><TD>centroid</TD><TD>I</TD><TD>1</TD><TD>Centroid id</TD></TR>
+<TR><TD>N,S,E,W</TD><TD>D</TD><TD>4</TD><TD>Area bounding box</TD></TR>
+<TR><TD>T,B</TD><TD>D</TD><TD>2</TD><TD>Area bounding box for 3D (only if with_z=1)</TD></TR>
+</TABLE>
+
+For each isle (n_isle):
+
+<TABLE border=2>
+<TR><TD>Name</TD><TD>Type</TD><TD>Number</TD><TD>Description</TD></TR>
+<TR><TD>n_lines</TD><TD>I</TD><TD>1</TD><TD>number of boundaries</TD></TR>
+<TR><TD>lines</TD><TD>I</TD><TD>n_lines</TD><TD>Line ids</TD></TR>
+<TR><TD>area</TD><TD>I</TD><TD>1</TD><TD>Area id</TD></TR>
+<TR><TD>N,S,E,W</TD><TD>D</TD><TD>4</TD><TD>Area bounding box</TD></TR>
+<TR><TD>T,B</TD><TD>D</TD><TD>2</TD><TD>Area bounding box for 3D (only if with_z=1)</TD></TR>
+</TABLE>
+
+<b>Feature types:</b>
+
\verbatim
/* Vector types used in memory on run time - may change */
#define GV_POINT 0x01
@@ -572,7 +668,7 @@
(one or few features), always by Vect_cidx_*() functions.
To create cidx, it will be necessary to rebuild topology for all existing vectors.
-This is an opportunity to make (hopefully) last changes in 'topo', 'sidx' formats.
+This is an opportunity to make (hopefully) last changes in 'topo', 'cidx' formats.
\section vlibtin Vector TINs
@@ -646,6 +742,7 @@
\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
@@ -654,6 +751,7 @@
\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<BR><BR>
@@ -663,6 +761,7 @@
trans* 1 roads key basedb odbc
trans* 5 rails
\endverbatim
+
These definitions define more layers (called "field" in the API) for one map
i.e. in one map may be more features linked to more tables. Definitions on
first 2 rows are applied for example on maps water1, water2, ... so that more
@@ -671,6 +770,7 @@
\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.
@@ -687,16 +787,17 @@
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 grassdglib DGLib (Directed Graph Library)
-The Directed Graph Library or DGLib (Micarelli 2002,
-\ref dglib , http://grass.itc.it/dglib/) provides functionality for vector network
-analysis. This library released under GPL is hosted by the GRASS project (in
-the CVS server within the GRASS source code). As a stand-alone library it
+The Directed Graph Library or DGLib (Micarelli 2002, \ref dglib ,
+http://grass.itc.it/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
@@ -740,7 +841,7 @@
Each module which modifies and writes data must read from input= and
write to output= so that data may not be lost. For example v.spag
-works on map= at in grass5.0 but if program (system) crashes or treshold was
+works on map= at in grass5.0 but if program (system) crashes or threshold was
specified incorrectly and vector was not backuped, data were lost.
In this case map= option should be replaced by input= and output=
<P>
@@ -750,22 +851,20 @@
There are a few modules which change the dimension on purpose.
\subsection vectmodulesopt Modules parameters/flags
-<B>--o</B> overwrite existing files <BR>
+
<B>-b</B> do not build topo file; by default topo file is written <BR>
-<B>-q</B> quiet <BR>
-<B>-v</B> run verbosely [either -q or -v!]<BR>
-<B>-t</B> create new table, default ??? <BR>
-<B>-u</B> don't create new table ??? <BR>
-<B>-z</B> write 3D file (if input was 2D) <BR>
+<B>-t</B> create new table, default<BR>
+<B>-u</B> don't create new table<BR>
+<B>-z</B> write 3D vector map (if input was 2D) <BR>
<BR>
-<B>map=</B> input vector for modules without output <BR>
-<B>input=</B> input vector <BR>
-<B>output=</B> output vector <BR>
+<B>map=</B> input vector map for modules without output <BR>
+<B>input=</B> input vector map <BR>
+<B>output=</B> output vector map <BR>
<B>type=</B> type of elements: point,line,boundary,centroid,area <BR>
<B>cat=</B> category or category list (example: 1,5,9-13,35) <BR>
<B>layer=</B> layer number <BR>
<B>where=</B> condition of SQL statement for selection of records <BR>
-<B>col=</B> column name (in external table)
+<B>column=</B> column name (in external table)
\section vlibfunc List of vector library functions
@@ -1385,7 +1484,7 @@
\section contacts Contacts
- Radim Blazek (vector architecture) <ramin.blazek at gmail.com>
+ Radim Blazek (vector architecture) <radim.blazek at gmail.com>
Roberto Micarelli (DGLib) <mi.ro at iol.it>
@@ -1397,7 +1496,6 @@
Trento, Italy, 11-13 September 2002. University of Trento, Italy, 2002.
<a href="http://www.ing.unitn.it/~grass/conferences/GRASS2002/proceedings/proceedings/pdfs/Blazek_Radim.pdf">http://www.ing.unitn.it/~grass/conferences/GRASS2002/proceedings/proceedings/pdfs/Blazek_Radim.pdf</a>
-
\section seealso See Also
DBMI - Database Management Interface: \ref DataBase_Management_Interface
More information about the grass-commit
mailing list