[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>&nbsp;</TD></TR>
-<TR><TD>Version_Minor </TD><TD>C</TD><TD>1</TD><TD>&nbsp;</TD></TR>
-<TR><TD>Earliest_Major</TD><TD>C</TD><TD>1</TD><TD>&nbsp;</TD></TR>
-<TR><TD>Earliest_Minor</TD><TD>C</TD><TD>1</TD><TD>&nbsp;</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>&nbsp;</TD></TR>
-<TR><TD>y</TD><TD>D</TD><TD>ncoor</TD><TD>&nbsp;</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