[GRASS-SVN] r38545 - in grass/trunk/lib/vector: . vedit

svn_grass at osgeo.org svn_grass at osgeo.org
Fri Jul 31 07:02:14 EDT 2009


Author: martinl
Date: 2009-07-31 07:02:13 -0400 (Fri, 31 Jul 2009)
New Revision: 38545

Modified:
   grass/trunk/lib/vector/vectorlib.dox
   grass/trunk/lib/vector/vedit/veditlib.dox
Log:
vectorlib doxygen doc update


Modified: grass/trunk/lib/vector/vectorlib.dox
===================================================================
--- grass/trunk/lib/vector/vectorlib.dox	2009-07-31 10:51:49 UTC (rev 38544)
+++ grass/trunk/lib/vector/vectorlib.dox	2009-07-31 11:02:13 UTC (rev 38545)
@@ -9,14 +9,39 @@
 - \subpage background
 - \subpage intro
 - \subpage libraries
+ - \subpage vlib
+  - \subpage Directory_structure
+  - \subpage head_file_format
+  - \subpage Map_info
+  - \subpage Plus_head
+  - \subpage dig_head
+- \subpage feature_geom
+ - \subpage ftypes
+ - \subpage coor_file_format
+  - \subpage coor_file_head
+  - \subpage coor_file_body 
 - \subpage vlib_topology_management
+ - \subpage topo_file_format
+  - \subpage topo_file_header
+  - \subpage topo_file_body
+ - \subpage topo_levels
+ - \subpage topo_examples
+ - \subpage vlib_topo_memory
 - \subpage vlib_spidx
+ - \subpage sidx_file_format
 - \subpage vlib_categories_layers
+- \subpage vlib_cidx
+ - \subpage cidx_file_format
+  - \subpage cidx_file_head
+- \subpage vlib_tin
 - \subpage vlib_attributes
-- \subpage vlibtin
+- \subpage ogr_iface
+ - \subpage frmt_file_format
+ - \subpage fidx_file_format
 - \subpage grassdglib
-- \subpage vlibascii
-- \subpage vectmodulesoper
+- \subpage vlib_ascii
+- \subpage vectmodules
+ - \subpage vectmodules_oper
 
 \subpage vlibfunc
 
@@ -67,7 +92,7 @@
 - \subpage delete
 - \subpage write
 
-\subpage contacts
+\subpage authors
 
 \subpage references
 
@@ -82,24 +107,25 @@
 of topology, where besides the coordinates describing the location of
 the primitives (points, lines, boundaries, centroids, faces, and
 kernels), their spatial relations are also stored. In general,
-topological GIS require a data structure where the common boundary
+topological GIS requires a data structure where the common boundary
 between two adjacent areas is stored as a single line, simplifying the
-map maintenance.
+vector data maintenance.
 
 
 \section intro Introduction
 
-The GRASS 6/7 vector format is very similar to old GRASS 4.x (5.0/5.3)
-vector format.
+The GRASS 6/7 vector format is very similar to the previous GRASS 4.x
+(5.0/5.3) vector format.
 
 This description covers the new GRASS 6 vector library architecture.
 This new architecture overcomes the vector limitations of GRASS
 4.x-5.4.x by extending the vector support with attributes stored in
-external relational databases, and by new 3D capabilities. Besides
+the external relational databases, and by new 3D capabilities. Besides
 internal file based storage the geometry may alternatively be stored
-in a PostGIS database. This enables users to maintain large data sets
-with simultaneous write access. External GIS formats such as
-SHAPE-files may be used directly, without requiring format conversion.
+in a PostGIS database (accessible via OGR interface). This enables
+users to maintain large data sets with simultaneous write
+access. External GIS formats such as SHAPE-files may be used directly,
+without requiring format conversion.
 
 The current implementation includes:   
 
@@ -109,28 +135,28 @@
 - multi-format: external data formats supported (SHAPE-file, OGR sources etc.);
 - portability: platform independent internal format, read- and writable on 32bit,
       64bit etc. computer architectures;
-- integrated \ref dglib: support for vector network analysis;
-- spatial index: based on R-tree method for fast vector geometry access (see \ref vlib_spidx).
+- integrated \ref dglib - support for vector network analysis;
+- spatial index: based on R-tree method for fast vector geometry access (see \ref vlib_spidx);
 - multi-attribute: attributes saved in external Relational Database Management 
       System (RDBMS) connected through DBMI library and drivers (\ref vlib_attributes);
 
-GRASS vector maps are stored in an arc-node representation, consisting
-of curves called arcs. An arc is stored as a series of x,y,z
-coordinate pairs. The two endpoints of an arc are called nodes. Two
-consecutive x,y,z pairs define an arc segment. The user specifies the
-type of input to GRASS; GRASS doesn't decide. GRASS allows for the
-line definition which allows for multiple types to co-exist in the
-same map. Centroid are assigned to area it is within/inside
-(geometrically). An area is identified by an x,y,z centroid point
-geometrically inside with a category number (ID). This identifies the
-area. Such centroids are stored in the same binary 'coor' file with
-other primitives. Each element may have none, one or more categories
-(cats). More cats are distinguished by field number (field, called
-"layer" at user level).  Single and multi-category support on modules
-level are implemented. Z-coordinate is optional and both 2D and 3D
-files may be written.
+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
+x,y,z coordinate pairs. The two endpoints of an arc are called
+<em>nodes</em>. Two consecutive x,y,z pairs define an arc segment. The
+user specifies the type of input to GRASS; GRASS doesn't decide. GRASS
+allows for the feature definition which allows for multiple types to
+co-exist in the same map. Centroid are assigned to area it is
+within/inside (geometrically). An area is identified by an x,y,z
+centroid point geometrically inside with a category number (ID). This
+identifies the area. Such centroids are stored in the same binary
+'coor' file with other primitives. Each element may have none, one or
+more categories (cats). More cats are distinguished by field number
+(field, called "layer" at user level).  Single and multi-category
+support on modules level are implemented. Z-coordinate is optional and
+both 2D and 3D files may be written.
 
-The following vector objects are defined:
+The following vector features are defined (see \ref ftypes):
 
 - point: a point;
 - line: a directed sequence of connected vertices with two endpoints called nodes;
@@ -154,7 +180,7 @@
 - Vlib (Vector library), see \ref vlib
 - DGLib (Directed Graph Library), see \ref dglib
 
-For historical reasons, there are two internal libraries for vector:
+For historical reasons, there are two internal libraries:
 
 - diglib (with dig_*() functions), GRASS 3.x/4.x
 - Vlib (with V1_*(), V2_*() and Vect_*() functions), GRASS 4.x/5.x (except for the 5.7 interim version)
@@ -187,28 +213,335 @@
 
 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:
 
-<b>$MAPSET/vector/vector_name/</b>
+\verbatim
+$MAPSET/vector/vector_name/
+\endverbatim
 
 This directory contains these files:
 
-- <b>coor</b> - binary file, coordinates [former dig/ file]
-- <b>topo</b> - binary file, topology [former dig_plus/ file]
-- <b>sidx</b> - binary file, spatial index 
-- <b>cidx</b> - binary file, category index 
-- <b>head</b> - text file, header information [former part of dig/ file]
+- <b>coor</b> - binary file, coordinates [former dig/ file] (see \ref coor_file_format)
+- <b>topo</b> - binary file, topology [former dig_plus/ file] (see \ref topo_file_format)
+- <b>sidx</b> - binary file, spatial index (see \ref sidx_file_format)
+- <b>cidx</b> - binary file, category index (see \ref cidx_file_format)
+- <b>head</b> - text file, header information [former part of dig/ file] (see \ref head_file_format)
 - <b>dbln</b> - text file, link(s) to attribute table(s)
 - <b>hist</b> - text file, vector map change history
+- <b>frmt</b> - text file, format description (external format only)
+- <b>fidx</b> - binary file, feature index (OGR format only)
 
-\subsubsection coor_file_format_specification Coor file format specification
+\subsubsection head_file_format Head file format
 
--# 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).
+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>
 
-<b>Head</b>
+\verbatim
+ORGANIZATION
+DIGIT DATE
+DIGIT NAME
+MAP NAME
+MAP DATE
+MAP SCALE
+OTHER INFO
+ZONE
+MAP THRESH
+\endverbatim
 
+\subsubsection Map_info Map_info structure
+
+<tt>Map_info</tt> structure holds basic information about open vector map.
+
+\code
+struct Map_info
+{
+    /* common info for all formats */
+    int format;			/* format (native, ogr) */
+    int temporary;		/* temporary file flag, not yet used */
+
+    struct dblinks *dblnk;	/* info about db links */
+
+    struct Plus_head plus;	/* topo file head info */
+
+    /* graph-related section */
+    int graph_line_type;	/* line type used to build the graph */
+    dglGraph_s graph;		/* graph structure */
+    dglSPCache_s spCache;	/* shortest path cache */
+    double *edge_fcosts;	/* costs used for graph, (dglGetEdge()
+    	   			   is not supported for _DGL_V1) */
+    double *edge_bcosts;
+    double *node_costs;		/* node costs */
+    int cost_multip;		/* edge and node costs
+				   multiplicator */
+
+    /* All of these apply only to runtime, and none get written out
+       to the dig_plus file 
+    */
+    int open;			/* should be 0x5522AA22 if opened correctly
+				   or        0x22AA2255 if closed          
+				   anything else implies that structure has
+				   never been initialized
+				*/
+    int mode;			/* Open mode - read, write, rw */
+    int level;			/* Topology level - 1, 2, (3) */
+    int head_only;		/* only header is opened */
+    int support_updated;	/* support files were updated */
+    plus_t next_line;		/* for level 2 sequential reads */
+
+    char *name;			/* for 4.0  just name, and mapset */
+    char *mapset;               /* mapset name */
+    /* location and gisdbase is usefull if changed (v.proj or external apps) */
+    char *location;		/* location name */
+    char *gisdbase;		/* gisdbase path */
+
+    /* constraints for reading in lines  (not polys yet) */
+    int Constraint_region_flag;
+    int Constraint_type_flag;
+    double Constraint_N;
+    double Constraint_S;
+    double Constraint_E;
+    double Constraint_W;
+    double Constraint_T;
+    double Constraint_B;
+    int Constraint_type;
+    int proj;
+
+    /* format specific */
+    /* native */
+    struct gvfile dig_fp;	/* dig file pointer */
+    struct dig_head head;	/* coor file head */
+
+    /* non native */
+    struct Format_info fInfo;	/* format information */
+
+    /* history file */
+    FILE *hist_fp;
+
+    /* temporary solution for sites */
+    struct site_att *site_att;	/* array of attributes loaded from db */
+    int n_site_att;		/* number of attributes in site_att array */
+    int n_site_dbl;		/* number of double attributes for one site */
+    int n_site_str;		/* number of string attributes for one site */
+};
+\endcode
+
+\subsubsection Plus_head Plus_head structure
+
+<tt>Plus_head</tt> holds basic topology-related information about vector map.
+
+\code
+struct Plus_head
+{
+    int Version_Major;		 /* version codes */
+    int Version_Minor;
+    int Back_Major;		 /* earliest version that can use this data format */
+    int Back_Minor;
+
+    int spidx_Version_Major;	 /* version codes for spatial index */
+    int spidx_Version_Minor;
+    int spidx_Back_Major;	 /* earliest version that can use this data format */
+    int spidx_Back_Minor;
+
+    int cidx_Version_Major;	 /* version codes for category index */
+    int cidx_Version_Minor;
+    int cidx_Back_Major;	 /* earliest version that can use this data format */
+    int cidx_Back_Minor;
+
+    int with_z;                  /* 2D/3D vector data */
+    int spidx_with_z;            /* 2D/3D spatial index */
+
+    int off_t_size;              /* offset size here because Plus_head
+				    is available to all releveant
+				    functions */
+
+    long head_size;		 /* topo header size */
+    long spidx_head_size;	 /* spatial index header size */
+    long cidx_head_size;	 /* category index header size */
+
+    int release_support;	 /* release memory occupied by support
+				    (topo, spatial, category) */
+
+    struct Port_info port;	 /* portability information */
+    struct Port_info spidx_port; /* portability information for
+				    spatial index */
+    struct Port_info cidx_port;	 /* portability information for
+				    category index */
+    int mode;			 /* read, write, RW */
+
+    int built;			 /* the highest level of topology
+				    currently available
+				    (GV_BUILD_*) */
+
+    struct bound_box box;	 /* vector map bounding box */
+
+    /* topology info */
+    struct P_node **Node;	 /* struct P_node array of pointers 
+				    1st item is 1 for  */
+    struct P_line **Line;	 /* struct P_line array of pointers 
+				    all these (not 0) */
+    struct P_area **Area;
+    struct P_isle **Isle;
+                                 /* add here P_FACE, P_VOLUME, P_HOLE */
+
+    plus_t n_nodes;		 /* current number of nodes */
+    plus_t n_edges;		 /* current number of edges */
+    plus_t n_lines;	 	 /* current number of lines */
+    plus_t n_areas;		 /* current number of areas */
+    plus_t n_isles;		 /* current number of isles */
+    plus_t n_faces;		 /* current number of faces */
+    plus_t n_volumes;	         /* current number of volumes */
+    plus_t n_holes;		 /* current number of holes */
+
+    plus_t n_plines;		 /* current number of points */
+    plus_t n_llines;		 /* current number of lines */
+    plus_t n_blines;		 /* current number of boundaries */
+    plus_t n_clines;		 /* current number of centroids */
+    plus_t n_flines;		 /* current number of faces */
+    plus_t n_klines;		 /* current number of kernels*/
+    plus_t n_vfaces;		 /* current number of volumes */
+    plus_t n_hfaces;		 /* current number of hole faces */
+
+    plus_t alloc_nodes;		 /* number of nodes we have alloc'ed
+				    space for i.e. array size - 1 */
+    plus_t alloc_edges;          /* number of edges we have alloc'ed space for */
+    plus_t alloc_lines;		 /* number of lines we have alloc'ed space for */
+    plus_t alloc_areas;		 /* number of areas we have alloc'ed space for */
+    plus_t alloc_isles;		 /* number of isles we have alloc'ed space for */
+    plus_t alloc_faces;		 /* number of faces we have alloc'ed space for */
+    plus_t alloc_volumes;	 /* number of volumes we have alloc'ed space for */
+    plus_t alloc_holes;		 /* number of holes we have alloc'ed space for */
+
+    off_t Node_offset;		 /* offset of array of nodes in topo file */
+    off_t Edge_offset;           /* offset of array of edges in topo file */
+    off_t Line_offset;           /* offset of array of lines in topo file */
+    off_t Area_offset;           /* offset of array of areas in topo file */
+    off_t Isle_offset;           /* offset of array of isles in topo file */
+    off_t Volume_offset;         /* offset of array of volumes in topo file */
+    off_t Hole_offset;           /* offset of array of holes in topo file */
+
+    int Spidx_built;		 /* set to 1 if spatial index is available */
+    int Spidx_new;               /* set to 1 if new spatial index will be generated */
+
+    struct gvfile spidx_fp;	 /* spatial index file pointer */
+    
+    char *spidx_node_fname;      /* node spatial index file name */
+
+    off_t Node_spidx_offset;	 /* offset of nodes in sidx file */
+    off_t Line_spidx_offset;     /* offset of lines in sidx file */
+    off_t Area_spidx_offset;     /* offset of areas in sidx file */
+    off_t Isle_spidx_offset;     /* offset of isles in sidx file */
+    off_t Face_spidx_offset;     /* offset of faces in sidx file */
+    off_t Volume_spidx_offset;   /* offset of volumes in sidx file */
+    off_t Hole_spidx_offset;     /* offset of holes in sidx file */
+
+    struct RTree *Node_spidx;     /* node spatial index */
+    struct RTree *Line_spidx;     /* line spatial index */
+    struct RTree *Area_spidx;     /* area spatial index */
+    struct RTree *Isle_spidx;     /* isle spatial index */
+    struct RTree *Face_spidx;     /* face spatial index */
+    struct RTree *Volume_spidx;   /* volume spatial index */
+    struct RTree *Hole_spidx;     /* hole spatial index */
+
+    /* Category index
+       By default, category index is not updated */
+    int update_cidx;		  /* update category index if vector is modified */
+
+    int n_cidx;			  /* number of cat indexes (one for each field) */
+    int a_cidx;			  /* allocated space for cat indexes */
+    struct Cat_index *cidx;	  /* array of category indexes */
+    int cidx_up_to_date;	  /* set to 1 when cidx is created and reset to 0 whenever any line is changed */
+
+    off_t coor_size;		  /* size of coor file */
+    long coor_mtime;		  /* time of last coor modification */
+
+    /* Level2 update: list of lines and nodes updated (topo info for
+       the line was changed) by last write/rewrite/delete operation.
+       Lines/nodes in the list may be deleted (e.g. delete boundary:
+       first added for delete area and then delete */
+    int do_uplist;		  /* used internaly in diglib to know if list is maintained */
+
+    int *uplines;		  /* array of updated lines */
+    int alloc_uplines;		  /* allocated array */
+    int n_uplines;		  /* number of updated lines */
+    int *upnodes;		  /* array of updated nodes */
+    int alloc_upnodes;		  /* allocated array */
+    int n_upnodes;		  /* number of updated nodes */
+};
+\endcode
+
+\subsubsection dig_head dig_head structure
+
+<tt>dig_head</tt> holds header data of vector map (see \ref Map_info).
+
+\code
+struct dig_head
+{
+    /* elements */
+    char *organization;         /* orgranization name */
+    char *date;                 /* map date */
+    char *your_name;            /* user name */
+    char *map_name;             /* map name */
+    char *source_date;          /* source date */
+    long orig_scale;            /* original scale */
+    char *line_3;               /* comments */
+    int plani_zone;             /* zone */
+    double digit_thresh;        /* threshold for digitization */
+
+    /* Programmers should NOT touch any thing below here */
+    /* Library takes care of everything for you          */
+
+    /* coor elements */
+    int Version_Major;          /* backward compatibility info */
+    int Version_Minor;
+    int Back_Major;
+    int Back_Minor;
+    int with_z;                 /* 2D/3D vector data */
+
+    off_t size;			/* coor file size */
+    long head_size;		/* coor header size */
+
+    struct Port_info port;	/* portability information */
+
+    off_t last_offset;		/* offset of last read line */
+
+    struct recycle *recycle;    /* recycle dead line, not implemented yet */
+
+    struct Map_info *Map;	/* X-ref to Map_info struct (needed?) */
+};
+\endcode
+
+\section feature_geom Vector library feature geometry
+
+\subsection ftypes Feature types
+
+\code
+#define GV_POINT      0x01
+#define GV_LINE	      0x02
+#define GV_BOUNDARY   0x04
+#define GV_CENTROID   0x08
+#define GV_FACE       0x10
+#define GV_KERNEL     0x20
+#define GV_AREA	      0x40
+#define GV_VOLUME     0x80
+
+#define GV_POINTS (GV_POINT | GV_CENTROID )
+#define GV_LINES (GV_LINE | GV_BOUNDARY )
+\endcode
+
+Face and kernel are 3D equivalents of boundary and centroid, but there
+is no support (yet) for 3D topology (volumes). Faces are used in a
+couple of modules including NVIZ to visualize 3D buildings and other
+volumetric figures.
+
+\subsection coor_file_format 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).
+
+\subsubsection coor_file_head Header
+
 <table border="1" style="border-collapse: collapse">
 <tr><td>Name</td><td>Type</td><td>Number</td><td>Description</td></tr>
 
@@ -230,7 +563,7 @@
 
 </table>
 
-<b>Body</b>
+\subsubsection coor_file_body Body
 
 The body consists of line records:
 
@@ -277,25 +610,6 @@
 <tr><td>C</td><td>Char  </td><td>1</td></tr>
 </table>
 
-
-\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>
-
-\verbatim
-ORGANIZATION
-DIGIT DATE
-DIGIT NAME
-MAP NAME
-MAP DATE
-MAP SCALE
-OTHER INFO
-ZONE
-MAP THRESH
-\endverbatim
-
 \section vlib_topology_management Vector library topology management
 
 Topology general characteristics:
@@ -308,44 +622,50 @@
 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 specification
 
-<b>Head</b>
+Topo file is read by Vect_open_topo().
 
+\subsubsection topo_file_header Header
+
+Note: <tt>plus</tt> is instance of <tt>Plus_head</tt> structure.
+
 <table border="1" style="border-collapse: collapse">
 <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>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>byte_order</td><td>C</td><td>1</td><td>little or big endian
+<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>head_size</td><td>L</td><td>1</td><td>header size</td></tr>
+<tr><td>plus->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>plus->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>plus->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
+<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>n_plines, n_llines, etc.</td><td>I</td><td>7</td><td>Number of
+<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>Node_offset, Edge_offset,
+<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>coor_size</td><td>L</td><td>1</td><td>File size</td></tr>
+<tr><td>plus->coor_size</td><td>L</td><td>1</td><td>File size</td></tr>
 </table>
 
-<b>Body</b>
+\subsubsection topo_file_body Body (nodes, lines, areas, isles)
 
+<b>Nodes</b>
+
 For each node (n_nodes):
 
 <table border="1" style="border-collapse: collapse">
@@ -358,6 +678,29 @@
 <tr><td>z</td><td>D</td><td>1</td><td>Only for with_z</td></tr>
 </table>
 
+\code
+struct P_node
+{
+    double x;			/* X coordinate */
+    double y;			/* Y coordinate */
+    double z;			/* Z coordinate */
+    plus_t alloc_lines;         /* allocated space for lines */
+    plus_t n_lines;		/* number of attached lines (size of
+				   lines, angle). If 0, then is
+				   degenerate node, for snappingi ???
+				*/
+    plus_t *lines;		/* list of connected lines */
+    float *angles;		/* respected angles; angles for
+				   lines/boundaries are in radians
+				   between -PI and PI. Value for
+				   points or lines with identical
+				   points (degenerated) is set to
+				   -9. */
+};
+\endcode
+
+<b>Lines</b>
+
 For each line (n_lines):
 
 <table border="1" style="border-collapse: collapse">
@@ -373,6 +716,32 @@
 <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>
 
+\code
+struct P_line
+{
+    plus_t N1;			/* start node */
+    plus_t N2;			/* end node   */
+    plus_t left;		/* area/isle number to left, negative
+				   for isle area number for centroid,
+				   negative for duplicate centroid 
+				*/
+    plus_t right;		/* area/isle number to right, negative
+				 * for isle */
+
+    double N;			/* line bounding Box */
+    double S;
+    double E;
+    double W;
+    double T;			/* top */
+    double B;			/* bottom */
+
+    off_t offset;		/* offset in coor file for line */
+    int type;                   /* line type */
+};
+\endcode
+
+<b>Areas</b>
+
 For each area (n_areas):
 
 <table border="1" style="border-collapse: collapse">
@@ -386,6 +755,32 @@
 <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>
 
+\code
+struct P_area
+{
+    double N;			/* area bounding Box */
+    double S;
+    double E;
+    double W;
+    double T;			/* top */
+    double B;			/* bottom */
+    plus_t n_lines;		/* number of boundary lines */
+    plus_t alloc_lines;         /* allocated space */
+    plus_t *lines;		/* list of boundary lines, negative
+				   means direction N2 to N1, lines are
+				   in clockwise order */
+
+    /*********  Above this line is compatible with P_isle **********/
+    plus_t centroid;		/* number of first centroid within area */
+
+    plus_t n_isles;		/* number of islands inside */
+    plus_t alloc_isles;
+    plus_t *isles;		/* 1st generation interior islands */
+};
+\endcode
+
+<b>Isles</b>
+
 For each isle (n_isle):
 
 <table border="1" style="border-collapse: collapse">
@@ -397,56 +792,44 @@
 <tr><td>T,B</td><td>D</td><td>2</td><td>Isle bounding box for 3D (only if with_z=1)</td></tr>
 </table>
 
-<b>Feature types:</b>
-
 \code
-/* Vector types used in memory on run time - may change */
-#define GV_POINT      0x01
-#define GV_LINE       0x02
-#define GV_BOUNDARY   0x04
-#define GV_CENTROID   0x08
-#define GV_FACE       0x10
-#define GV_KERNEL     0x20
-#define GV_AREA       0x40
-#define GV_VOLUME     0x80
-\endcode
+struct P_isle
+{
+    double N;			/* isle bounding Box */
+    double S;
+    double E;
+    double W;
+    double T;			/* top */
+    double B;			/* bottom */
+    plus_t n_lines;		/* number of boundary lines */
+    plus_t alloc_lines;
+    plus_t *lines;		/* list of boundary lines, negative
+				   means direction N2 to N1, lines are
+				   in counter clockwise order */
 
-\code
-#define GV_POINTS (GV_POINT | GV_CENTROID )
-#define GV_LINES (GV_LINE | GV_BOUNDARY )
+    /*********  Above this line is compatible with P_area **********/
+    plus_t area;		/* area it exists w/in, if any */
+};
 \endcode
 
-Face and kernel are 3D equivalents of boundary and centroid, but there 
-is no support (yet) for 3D topology (volumes). Faces are used in a
-couple of modules including NVIZ to visualize 3D buildings and other
-volumetric figures.
+\subsection topo_levels Topology levels
 
 \code
-/* Topology level details */
 #define GV_BUILD_NONE         0
 #define GV_BUILD_BASE         1
 #define GV_BUILD_AREAS        2
-#define GV_BUILD_ATTACH_ISLES 3  /* Attach islands to areas */
-#define GV_BUILD_CENTROIDS    4 /* Assign centroids to areas */
+#define GV_BUILD_ATTACH_ISLES 3
+#define GV_BUILD_CENTROIDS    4
 #define GV_BUILD_ALL          GV_BUILD_CENTROIDS
 \endcode
 
 GV_BOUNDARY contains geometry and it is used to build areas.
 GV_LINE cannot form an area.
 
-\code
-struct line_cats
-{
-      int *field;	/* pointer to array of fields a.k.a. layer*/
-      int *cat;		/* pointer to array of categories */
-      int n_cats;	/* number of vector categories attached to element */
-      int alloc_cats;	/* allocated space */
-};
-\endcode
+\subsection topo_examples Topology examples
 
+\subsubsection Topology_Example_1 Topology Example 1
 
-\subsection Topology_Example_1 Topology Example 1:
-
 A polygon may be formed by many boundaries (more primitives but connected).
 One boundary is shared by adjacent areas.
 
@@ -462,7 +845,7 @@
 \endverbatim
 
 
-\subsection Topology_Example_2 Topology Example 2:
+\subsubsection Topology_Example_2 Topology Example 2
 
 This is handled correctly in GRASS: A can be filled, B filled differently.
 
@@ -476,13 +859,14 @@
 +---------+
 \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 no island.
+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 no island.
 
 
-\subsection Topology_Example_3 Topology Example 3:
+\subsubsection Topology_Example_3 Topology Example 3
 
 This is handled correctly in GRASS: Areas A1, A2, and A3 can be filled differently.
 
@@ -496,15 +880,16 @@
 +---------------------+
 \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.
+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.
 
 
-\subsection Topology_Example_4 Topology Example 4:
+\subsubsection Topology_Example_4 Topology Example 4
 
 v.in.ogr/v.clean can identify dangles and change the type from boundary
 to line (in TIGER data for example). 
@@ -524,8 +909,8 @@
 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.
+Because lines are not used to build areas, we have only one
+area/centroid, instead of 4 which would be necessary in TIGER.
 
 
 \subsection vlib_topo_memory Topology memory management
@@ -574,10 +959,10 @@
 int main
 {
      Vect_open_new();
-     //writing new vector
+     /* writing new vector */
 
      Vect_build();
-     Vect_close();  // memory is not released
+     Vect_close();  /* memory is not released */
 }
 \endcode
 
@@ -588,16 +973,16 @@
 int main
 {
      Vect_open_new();
-     // writing new vector
+     /* writing new vector */
 
      Vect_build();
      Vect_set_release_support();
-     Vect_close();  // memory is released
+     Vect_close();  /* memory is released */
 }
 \endcode
 
 but it takes longer. 
-<P>
+
 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.
@@ -607,16 +992,98 @@
 int main
 {
      Vect_open_update();
-     // select features using spatial index, e.g.  Vect_select_lines_by_box()
+     /* select features using spatial index, e.g.  Vect_select_lines_by_box() */
      Vect_set_release_support();
-     Vect_close();  // memory is released
+     Vect_close();  /* memory is released */
 
-     // do some processing which needs memory
+     /* do some processing which needs memory */
 }
 \endcode
 
+\subsection sidx_file_format Sidx file format specification
 
+Spatial index file ('sidx') is read by Vect_open_sidx().
 
+\subsubsection sidx_file_header Header
+
+Note: <tt>plus</tt> is instance of <tt>Plus_head</tt> structure.
+
+<table border="1" style="border-collapse: collapse">
+<tr><td>Name</td><td>Type</td><td>Number</td><td>Description</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 vlib_categories_layers Vector library categories and layers
 
 <i>Note: "layer" was called "field" in earlier version.</i>
@@ -627,11 +1094,11 @@
 vector geometry as well as a "cat" column (integer type) in each
 attribute database table. The category number is used to lookup an
 attribute assigned to a vector object. At user level, category numbers
-can be assigned to vector objects with the v.category command.
+can be assigned to vector objects with the <tt>v.category</tt> command.
 
 In order to assign multiple attributes in different tables to vector
 objects, each map can hold multiple category numbers. This is achieved
-by assigning more than one "layer" to the map (v.db.connect
+by assigning more than one "layer" to the map (<tt>v.db.connect</tt>
 command). The layer number determines which table to be used for
 attribute queries. For example, a cadastrial vector area map can be
 assigned on layer 1 to an attribute table containing landuse
@@ -642,11 +1109,13 @@
 Each vector feature inside a vector map has zero, one or more
 &lt;layer,category&gt; tuple(s). A user can (but not must) create
 attribute tables which are referenced by the layer, and rows which are
-essentially referenced by the &lt;layer,category&gt; pair.  <P>
-Categories start with 1. Categories do not have to be continuous.
+essentially referenced by the &lt;layer,category&gt; pair.
 
-\section vlib_cidx Vector library category index
+Categories start with 1 (category '0' is allowed for OGR
+layers). Categories do not have to be continuous.
 
+\section vlib_cidx 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. 'd.vect cats=27591', 'v.extract list=20000-21000').
 This avoids that all selections have to be made by looping through all vector lines.
@@ -655,15 +1124,19 @@
 Category index is created for each field. In memory, it is stored in
 
 \code
-struct Cat_index {
-    int field;     /* field number a.k.a. layer*/
-    int n_cats;    /* number of items in cat array */
-    int a_cats;    /* allocated space in cat array */
-    int (*cat)[3]; /* array of cats (cat,type, lines/area) */
-    int n_ucats;   /* number of unique cats (not updated) */
-    int n_types;   /* number of types in type */
-    int type[7][2];/* number of elements for each type (point, line, boundary, centroid, area, face, kernel) */
-    long offset;   /* offset of the beginning of this index in cidx file */
+struct Cat_index
+{
+    int field;			/* field number */
+    int n_cats;			/* number of items in cat array */
+    int a_cats;			/* allocated space in cat array */
+    int (*cat)[3];		/* array of cats (cat, type, lines/area) */
+    int n_ucats;		/* number of unique cats (not updated) */
+    int n_types;		/* number of types in type */
+    int type[7][2];		/* number of elements for each type
+				 * (point, line, boundary, centroid,
+				 * area, face, kernel) */
+    off_t offset;		/* offset of the beginning of this
+				 * index in cidx file */
 };
 \endcode
 
@@ -679,9 +1152,47 @@
 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 cidx_file_format Cidx file format specification
 
-\section vlibtin Vector TINs
+Category index file ('cidx') is read by Vect_cidx_open().
 
+\subsubsection cidx_file_head Header
+
+Note: <tt>plus</tt> is instance of <tt>Plus_head</tt> structure.
+
+<table border="1" style="border-collapse: collapse">
+<tr><td>Name</td><td>Type</td><td>Number</td><td>Description</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 vlib_tin Vector TINs
+
 TINs are simply created as 2D/3D vector polygons consisting of 
 3 vertices. See Vect_tin_get_z().
 
@@ -690,24 +1201,40 @@
 
 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 DBMI library (DBF, SQLite,
+database is done through drivers based on \ref dbmilib (DBF, SQLite,
 PostgreSQL, MySQL and ODBC drivers are available at this
 time). Records in a table are linked to vector entities by layer and
 category number. The layer identifies table and the category
 identifies record.  I.e., for any unique combination
-map+mapset+layer+category, there exists one unique combination
+\verbatim
+map+mapset+layer+category,
+\endverbatim
+there exists one unique combination
+\verbatim
 driver+database+table+row.
+\endverbatim
 
-The general DBMI settings are defined in the "MAPSET/VAR" text file
-(maintained with db.connect command at user level).
+Information about database links holds <tt>dblinks</tt> structure.
 
+\code
+struct dblinks
+{
+    struct field_info *field;   /* pointer to the first field_info structure */
+    int alloc_fields;           /* number of allocated slots */
+    int n_fields;               /* number of available fields */
+};
+\endcode
+
+The general DBMI settings are defined in the '$MAPSET/VAR' text file
+(maintained with <tt>db.connect</tt> command at user level).
+
 Each vector maps has its own DBMI settings stored in the
-"MAPSET/vector/vector_name/dbln" text file. For each pair <B>map +
-layer</B>, all of <B>table, key column, database, driver</B> must be
+'$MAPSET/vector/vector_name/dbln' text file. For each pair <b>map +
+layer</b>, all of <b>table, key column, database, driver</b> 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): <BR><BR>
+'$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]]]
@@ -727,22 +1254,23 @@
 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.
+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 g.remove, for example, deletes linked tables of the vector.
-Attributes must be joined with geometry.
+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.
 
-<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:
+<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
@@ -769,7 +1297,7 @@
 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
-maps may share one table.<BR><BR>
+maps may share one table.
 
 \verbatim
 water at PERMANENT 1 myrivers id /home/guser/mydbf dbf
@@ -780,8 +1308,8 @@
 
 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 map from one database and write to some other and even with
-some other driver (should not be a problem). 
+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:<BR>
@@ -793,10 +1321,61 @@
 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 ogr_iface OGR interface
 
+\subsection frmt_file_format 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 - datasource name
+ - LAYER - OGR layer name
+
+Example:
+
+\verbatim
+FORMAT: ogr
+DSN: /home/martin/src/grass_trunk
+LAYER: p
+\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 fidx_file_format) is created.
+
+\subsection fidx_file_format Fidx file format specification
+
+Note: <tt>finfo</tt> is an instance of <tt>Format_info</tt> structure.
+
+<table border="1" style="border-collapse: collapse">
+<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>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 grassdglib DGLib (Directed Graph Library)
 
-The Directed Graph Library or DGLib (Micarelli 2002, \ref dglib ,
+<b>The Directed Graph Library</b> or DGLib (Micarelli 2002, \ref dglib ,
 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
@@ -807,8 +1386,8 @@
 along polylines. The user can assign individual costs to all lines and/or
 nodes of a vector map and later calculate shortest path connections based on
 the accumulated costs. Applications are transport analysis, connectivity and
-more. Implemented applications cover Shortest path, Traveling salesman (round trip),
-Allocation of sources (creation of subnetworks), Minimum Steiner trees 
+more. Implemented applications cover shortest 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).
@@ -824,49 +1403,121 @@
  Vect_net_shortest_path_coor().
 
 
-\section vlibascii Vector ASCII Format Specifications
+\section vlib_ascii Vector ASCII Format Specifications
 
-The ASCII format is (currently) explained in the
-manual page of v.in.ascii, which is defined in the file:
+<b>The GRASS ASCII vector map format</b> may contain a mix of primitives
+including points, lines, boundaries, centroids, areas, faces, and
+kernels. The GRASS ASCII vector format may contain a header with
+various metadata (see example below).
 
-vector/v.in.ascii/description.html
+The header is similar as the head file of vector binary format but
+contains bounding box also. Key words 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
+
+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
+
 \section vectmodules Vector modules and their parameters/flags
 
-See also grass5/documents/parameter_proposal.txt
+A module is a GRASS command invoked by the user.
 
-<I>A module is a GRASS command invoked by the user.</I>
+\subsection vectmodules_oper Modules operation
 
-\subsection vectmodulesoper Modules operation
+Each module which modifies and writes data must read from
+<b>input=</b> and write to <b>output=</b> so that data may not be
+lost. For example <tt>v.spag</tt> works on <b>map=</b> at in GRASS GIS
+5.0 but if program (system) crashes or threshold was specified
+incorrectly and vector was not backuped, data were lost. In this case
+</b>map=</b> option should be replaced by <b>input=</b> and
+<b>output=</b>.
 
-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 threshold was 
-specified incorrectly and vector was not backuped, data were lost. 
-In this case map= option should be replaced by input= and output=
-
 Topology is always built by default if the coor file was modified.
 
-Dimensionality is generally kept. Input 2D vector is written as 2D, 3D as 3D.
-There are a few modules which change the dimension on purpose.
+Dimensionality is generally kept. Input 2D vector is written as 2D, 3D
+as 3D. There are a few modules which change the dimension on purpose.
 
 \subsection vectmodulesopt Modules parameters/flags
 
-<B>-b</B> do not build topo file; by default topo file is written <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 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>column=</B> column name (in external table)
+<b>-b</b> do not build topo file; by default topo file is written
 
+<b>-t</b> create new table, default
 
+<b>-u</b> don't create new table
+
+<b>-z</b> write 3D vector map (if input was 2D)
+
+
+<b>map=</b> input vector map for modules without output
+
+<b>input=</b> input vector map
+
+<b>output=</b> output vector map
+
+<b>type=</b>  type of elements:  point,line,boundary,centroid,area
+
+<b>cat=</b> category or category list (example: 1,5,9-13,35)
+
+<b>layer=</b> layer number
+
+<b>where=</b> condition of SQL statement for selection of records
+
+<b>column=</b> column name (in external table)
+
+
 \section vlibfunc List of vector library functions
 
 The Vect_*() functions are the programmer's API for GRASS vector
@@ -1129,6 +1780,8 @@
 
  - Vect_get_field()
 
+ - Vect_get_field_by_name()
+
  - Vect_map_add_dblink()
 
  - Vect_map_check_dblink()
@@ -1561,14 +2214,18 @@
 
  - Vect_line_to_geos()
 
+ - Vect_get_area_points_geos()
 
-\section contacts Contacts
+ - Vect_get_isle_points_geos()
 
- Radim Blazek (vector architecture) <radim.blazek at gmail.com>
 
- Roberto Micarelli (DGLib) <mi.ro at iol.it>
+\section authors Authors
 
+ Radim Blazek (vector architecture) <radim.blazek gmail.com>
 
+ Roberto Micarelli (DGLib) <mi.ro iol.it>
+
+
 \section references References
 
 Text based on: R. Blazek, M. Neteler, and R. Micarelli. The new GRASS 5.1

Modified: grass/trunk/lib/vector/vedit/veditlib.dox
===================================================================
--- grass/trunk/lib/vector/vedit/veditlib.dox	2009-07-31 10:51:49 UTC (rev 38544)
+++ grass/trunk/lib/vector/vedit/veditlib.dox	2009-07-31 11:02:13 UTC (rev 38545)
@@ -1,17 +1,14 @@
 /*! \page veditlib GRASS Vedit Library
 
-by GRASS Development Team
+by GRASS Development Team (http://grass.osgeo.org)
 
-http://grass.osgeo.org
-
 \section veditIntro Introduction to Vedit Library
 
 This library contains higher level functions for editing %vector
 geometry (see \ref vectorlib). Currently only 2D primitives are
 supported (points, lines, boundaries and centroids).
 
-<p>
-The library is used by v.edit module and wxGUI %vector digitizer.
+The library is used by <tt>v.edit</tt> module and wxGUI %vector digitizer.
 
 \section veditFn Functions
 
@@ -65,7 +62,7 @@
 
  - Vedit_bulk_labeling()
 
-\section contacts Contacts
+\section authors Authors
 
  Martin Landa <landa.martin gmail.com>
 



More information about the grass-commit mailing list