/*! \page vectorlib GRASS Vector Library by GRASS Development Team (http://grass.osgeo.org) Table of contents - \subpage vlibBackground - \subpage vlibIntro - \subpage vlibVectorMap - \subpage vlibVectorLevels - \subpage vlibDirectoryStructure - \subpage vlibHeadFileFormat - \subpage vlibCategoriesLayers - \subpage vlibAttributes - \subpage vlibDblnFileFormat - \subpage vlibs - \subpage vlibHistory - \subpage vlibStructures - \subpage vlibMap_info - \subpage vlibPlus_head - \subpage vlibDig_head - \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 vlibAscii - \subpage vlibFunc - \subpage vlibAuthors - \subpage vlibReferences - \subpage vlibSeealso \section vlibBackground Background Generally, the vector data model is used to describe geographic phenomena which may be represented by geometric entities like points, lines, and areas. The GRASS vector data model includes the description 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 requires a data structure where the common boundary between two adjacent areas is stored as a single line, simplifying the vector data maintenance. \section vlibIntro Introduction 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 the external relational databases, and by new 3D capabilities. Besides internal file based storage the geometry may alternatively be stored 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: - multi-layer: features in one vector map may represent more layers and may be linked to more external tables (see \ref vlibCategoriesLayers); - 2D and 3D vector geometry with full topology support for 2D and partial topology support for 3D (see \ref vlibTopoManagement); - 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 vlibDglib - support for vector network analysis; - spatial index: based on R-tree method for fast vector geometry access (see \ref vlibSpidx); - multi-attribute: attributes saved in external Relational Database Management System (RDBMS) connected through DBMI library and drivers (\ref vlibAttributes); \subsection vlibVectorMap Vector map 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 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 feature types (primitives) are defined by the vector library (and holds by the coor file; see also \ref vlibFeatureTypes): - point: a point (2D or 3D); - line: a directed sequence of connected vertices with two endpoints called nodes (2D or 3D); - boundary: the border line to describe an area (2D only); - centroid: a point within a closed boundary(ies) to describe an area (2D only); - face: a 3D boundary (not implemented yet); - kernel: a 3D centroid in a volume. From vector feature types mentioned above are derived: - node: start/endpoints of lines and boundaries (2D or 3D); - area: the topological composition of a closed ring of boundary(ies) and optionally a centroid (2D only, 3D coordinates supported but ignored); - isle: an area within area, not touching the boundaries of the outer area (2D only, 3D coordinates supported but ignored); - edge: a 3D node connecting faces (not implemented yet) - volume: a 3D corpus, the topological composition of faces and kernel (not implemented yet); - hole: a volume within volume, 3D equivalent to isle within area (not implemented yet). Note that all lines and boundaries can consist of multiple segments. Area topology also holds information about isles. Isles are located within an area, not touching the boundaries of the outer area. Isles consist of one or more areas and are used internally by the vector libraries to maintain correct topology of areas. \subsubsection vlibVectorLevels Levels of read access There are two levels of read access to the vector data: - Level One provides simple access to the vector feature information. There is no access to topology information at this level. - Level Two provides full access to all the information including topology information. This level requires more from the programmer, more momory, and longer startup time. Level of access is retured by Vect_open_old(). Note: Higher level of access are planned, so when checking success return codes for a particular level of access (when calling Vect_open_old() for example), the programmer should use >= instead of == for compatibility with future releases. An existing vector map can be open for reading by Vect_open_old(). New vector map can be created (or open for writing) by Vect_open_new(). Vect_open_old() attempts to open a vector map at the highest possible level of access. It will return the number of the level at which it opened. Vect_open_new() always opens at level 1 only. If you require that a vector map be opened at a lower level (e.g. one), you can call the routine Vect_set_open_level(1); Vect_open_old() will then either open at level one or fail. If you instead require the highest level access possible, you should not use Vect_set_open_level(), but instead check the return value of Vect_open_old() to make sure it is greater than or equal to the lowest 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 This directory contains these files: - coor - binary file, coordinates [former dig/ file] (see \ref vlibCoorFileFormat) - topo - binary file, topology [former dig_plus/ file] (see \ref vlibTopoFileFormat) - sidx - binary file, spatial index (see \ref vlibSidxFileFormat) - cidx - binary file, category index (see \ref vlibCidxFileFormat) - head - text file, header information [former part of dig/ file] (see \ref vlibHeadFileFormat) - dbln - text file, link(s) to attribute table(s) (see \ref vlibDblnFileFormat) - hist - text file, vector map change history - frmt - text file, format description (external format only) - fidx - binary file, feature index (OGR format only) \subsubsection vlibHeadFileFormat Head file format specification The header contains historical information, a description of the vector map and many other information. The file is an unordered list of key/value entries. The key is a string separated from value by a colon and optional whitespace. Keywords are:
ORGANIZATIONorganization that digitized the data
DIGIT DATEdate the data was digitized
DIGIT NAMEperson who digitized the data
MAP NAMEtitle of the original source map
MAP DATEdate of the original source map
MAP SCALEscale of the original source map
OTHER INFOother comments about the map
ZONEzone of the map (e.g., UTM zone)
MAP THRESHdigitizing threshold
\subsection vlibCategoriesLayers Categories and layers Note: "layer" was called "field" in earlier version. In GRASS, a "category" or "category number" is a vector feature ID used to link geometry to attributes which are stored in one or several (external) database table(s). This category number is stored into the 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. 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 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 descriptions which are maintained by department A while layer 2 is assigned to an attribute table containing owner descriptions which are maintained by department B. Each vector feature inside a vector map has zero, one or more <layer,category> 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 <layer,category> pair. Categories start with 1 (category '0' is allowed for OGR layers). Categories do not have to be continuous. \subsection 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 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 \verbatim map+mapset+layer+category \endverbatim there exists one unique combination \verbatim driver+database+table+row \endverbatim Information about database links holds dblinks 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 db.connect command at user level). \subsection vlibDblnFileFormat Dbln file format specification Each vector maps has its own DBMI settings stored in the '$MAPSET/vector/vector_name/dbln' text file. For each pair vector map + layer, all of table, key column, database, driver 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 * and ? 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 g.remove, for example, deletes linked tables of the vector. Attributes must be joined with geometry. Examples: 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@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 \endcode Note: For details please read Blazek et al. 2002 (see below) as well as the references in this document. \subsection vlibHistory Historical notes The vector library in GRASS 4.0 changed significantly from the Digit Library (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 struct head is struct 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 structures \subsection vlibMap_info Map_info structure The token that is used to identify each vector map is the Map_info structure. It maintains all information about an individual open vector map. The structure must be passed to the mosy vector library routines. \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 \subsection vlibPlus_head Plus_head structure Plus_head 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 \subsection vlibDig_head dig_head structure dig_head holds header data of vector map (see \ref vlibMap_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 vlibGeometry Vector library feature geometry \subsection vlibFeatureTypes 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 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). \subsubsection vlibCoorFileHead Header
NameTypeNumberDescription
Version_Major C1file version (major)
Version_Minor C1file version (minor)
Back_MajorC1supported from GRASS version (major)
Back_MinorC1supported from GRASS version (minor)
byte_orderC1little or big endian flag; files are written in machine native order but files in both little and big endian order may be read; zero for little endian
sizeL1coor file size
with_zC12D or 3D flag; zero for 2D
reservedC10not used
\subsubsection vlibCoorFileBody Body The body consists of line records:
NameTypeNumberDescription
record headerC1
  • 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
  • 4.-7. bit : reserved, not used
ncatsI1number of categories (written only if categories exist)
fieldIncatsfield identifier, distinguishes between more categories append to one feature (written only if categories exist; field is called "layer" at user level)
catIncatscategory value (written only if categories exist)
ncoorI1written for GV_LINES and GV_BOUNDARIES only
xDncoorx coordinate
yDncoory coordinate
zDncoorz coordinate; present if with_z in head is set to 1
Types used in coor file
TypeNameSize in Bytes
DDouble8
LLong 4
IInt 4
SShort 4
CChar 1
\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 format while pseudo-topology is written for OGR sources, SHAPE-link. The following rules apply to the vector data: - Lines should not cross each other (i.e., lines which would cross must be split at their intersection to form distict lines). - Linear primitives which share nodes at exactly same points (i.e., must be snapped together). This is particulary important since nodes are not exactly represented in the coor file, but only implicitly as endpoints of lines. - 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 is 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. 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. The area feature should be labeled by a centroid as an area. Additionally, the common boundary itself (i.e., the boundary which is also a line) should be labeled as a line by a distict category number. Vector map topology can be cleaned at user level by v.clean command. \subsection vlibTopoFileFormat Topo file format specification Topo file is read by Vect_open_topo(). \subsubsection vlibTopoFileHead Header Note: plus is instance of Plus_head structure.
NameTypeNumberDescription
plus->Version_Major C1file version (major)
plus->Version_Minor C1file version (minor)
plus->Back_MajorC1supported from GRASS version (major)
plus->Back_MinorC1supported from GRASS version (minor)
plus->port->byte_orderC1little 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
plus->head_sizeL1header size
plus->with_zC12D or 3D flag; zero for 2D
plus->boxD6Bounding box coordinates (N,S,E,W,T,B)
plus->n_nodes, plus->n_lines, etc.I7Number of nodes, edges, lines, areas, isles, volumes and holes
plus->n_plines, plus->n_llines, etc.I7Number of points, lines, boundaries, centroids, faces and kernels
plus->Node_offset, plus->Edge_offset, etc.L7Offset value for nodes, edges, lines, areas, isles, volumes and holes
plus->coor_sizeL1File size
\subsubsection vlibTopoFileBody Body (nodes, lines, areas, isles) Nodes For each node (n_nodes):
NameTypeNumberDescription
n_linesI1Number of lines (0 for dead node)
linesIn_linesLine ids
anglesDn_linesAngle value
n_edgesI1Reserved for edges (only for with_z)
x,yD2Coordinate pair
zD1Only for with_z
\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 Lines For each line (n_lines):
NameTypeNumberDescription
feature typeC10 for dead
offsetL1Line offset
N1I1First node id (only if feature type is GV_POINTS, GV_LINES or GV_KERNEL)
N2I1Second node id (only if feature type is GV_LINE or GV_BOUNDARY)
leftI1Left area id for feature type GV_BOUNDARY / Area id for feature type GV_CENTROID
rightI1Right area id (for feature type GV_BOUNDARY)
volI1Reserved for kernel (volume number, for feature type GV_KERNEL)
N,S,E,WD4Line bounding box (for feature type GV_LINE, GV_BOUNDARY or GV_FACE)
T,BD2Line bounding box for 3D (only if with_z=1)
\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 Areas For each area (n_areas):
NameTypeNumberDescription
n_linesI1number of boundaries
linesIn_linesLine ids
n_islesI1Number of isles
islesIn_islesIsle ids
centroidI1Centroid id
N,S,E,WD4Area bounding box
T,BD2Area bounding box for 3D (only if with_z=1)
\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 Isles For each isle (n_isle):
NameTypeNumberDescription
n_linesI1number of boundaries
linesIn_linesLine ids
areaI1Outer area id
N,S,E,WD4Isle bounding box
T,BD2Isle bounding box for 3D (only if with_z=1)
\code 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 */ /********* Above this line is compatible with P_area **********/ plus_t area; /* area it exists w/in, if any */ }; \endcode \subsection vlibTopoLevels Topology levels The vector library defines more topology levels (only for level of access 2): \code #define GV_BUILD_NONE 0 #define GV_BUILD_BASE 1 #define GV_BUILD_AREAS 2 #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. \subsection vlibTopoExamples Topology examples \subsubsection vlibTopoExample1 Topology Example 1 A polygon may be formed by many boundaries (more primitives but connected). 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 \endverbatim \subsubsection vlibTopoExample2 Topology Example 2 This is handled correctly in GRASS: A can be filled, B filled differently. \verbatim +---------+ | A | +-----+ | | B | | +-----+ | | | +---------+ \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. \subsubsection vlibTopoExample3 Topology Example 3 This is handled correctly in GRASS: Areas A1, A2, and A3 can be filled differently. \verbatim +---------------------+ | A1 | + +------+------+ | | | A2 | A3 | | + +------+------+ | | I1 | +---------------------+ \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. \subsubsection vlibTopoExample4 Topology Example 4 v.in.ogr/v.clean 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. Spatial index occupies a lot of memory but it is necessary for topology building. Also, it takes a long time to release the memory occupied by spatial index (dig_spidx_free()). The function building topology (Vect_build()) is usually called at the end of modules (before Vect_close()) so it is faster to call exit() 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 a long 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 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 \subsection vlibSidxFileFormat Sidx file format specification Spatial index file ('sidx') is read by Vect_open_sidx(). \subsubsection vlibSidxFileHead Header Note: plus is instance of Plus_head structure.
NameTypeNumberDescription
plus->spidx_Version_Major C1file version (major)
plus->spidx_Version_Minor C1file version (minor)
plus->spidx_Back_MajorC1supported from GRASS version (major)
plus->spidx_Back_MinorC1supported from GRASS version (minor)
plus->spidx_port->byte_orderC1little 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
plus->spidx_port.off_t_sizeC1off_t size (LFS)
plus->spidx_head_sizeL1header size
plus->spidx_with_zC12D/3D vector data
ndimsC1Number of dimensions
nsidesC1Number of sides
nodesizeI1Node size
nodecardI1Node card (?)
leafcardI1Leaf card (?)
min_node_fillI1Minimum node fill (?)
min_leaf_fillI1Minimum leaf fill (?)
plus->Node_spidx->n_nodesI1Number of nodes
plus->Node_spidx->n_leafsI1Number of leafs
plus->Node_spidx->n_levelsI1Number of levels
plus->Node_spidx_offsetO1Node offset
plus->Line_spidx->n_nodesI1Number of nodes
plus->Line_spidx->n_leafsI1Number of leafs
plus->Line_spidx->n_levelsI1Number of levels
plus->Line_spidx_offsetO1Line offset
plus->Area_spidx->n_nodesI1Number of nodes
plus->Area_spidx->n_leafsI1Number of leafs
plus->Area_spidx->n_levelsI1Number of levels
plus->Area_spidx_offsetO1Area offset
plus->Isle_spidx->n_nodesI1Number of nodes
plus->Isle_spidx->n_leafsI1Number of leafs
plus->Isle_spidx->n_levelsI1Number of levels
plus->Isle_spidx_offsetO1Isle offset
plus->Face_spidx_offsetO1Face offset
plus->Volume_spidx_offsetO1Volume offset
plus->Hole_spidx_offsetO1Hole offset
plus->coor_sizeO1Coor file size
\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. 'd.vect cats=27591', 'v.extract list=20000-21000'). 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 \code 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 Category index is built with topology, but it is not updated 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( (int *)ci->cat, 3 * ci->n_cats, fp) or dig__fread_port_I( (int *)ci->cat, 3 * ci->n_cats, fp). 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 Vect_cidx_*() 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: plus is instance of Plus_head structure.
NameTypeNumberDescription
plus->cpidx_Version_Major C1file version (major)
plus->cpidx_Version_Minor C1file version (minor)
plus->cpidx_Back_MajorC1supported from GRASS version (major)
plus->cpidx_Back_MinorC1supported from GRASS version (minor)
plus->cidx_port->byte_orderC1little 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
plus->cidx_head_sizeL1cidx head size
plus->n_cidxI1number of fields
fieldIn_cidxfield number
n_catsIn_cidxnumber of categories
n_ucatsIn_cidxnumber of unique categories
n_typesIn_cidxnumber of feature types
rtypeIn_cidx * n_typesFeature type
type[t]In_cidx * n_typesNumber of items
\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 cleaned as done by v.in.ogr. \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 - 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 v.external 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: finfo is an instance of Format_info structure.
NameTypeNumberDescription
Version_Major C1file version (major)
Version_Minor C1file version (minor)
Back_MajorC1supported from GRASS version (major)
Back_MinorC1supported from GRASS version (minor)
byte_orderC1little 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
lengthL1header size
fInfo.ogr.offset_numI1number of records
fInfo.ogr.offsetIoffset_numoffsets
\section vlibDglib DGLib (Directed Graph Library) The Directed Graph Library 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 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 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 (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 v.out.ascii format=standard 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 [] 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 process vector data. The routines in the vector library are presented in functional groupings, rather than in alphabetical order. The order of presentation will, it is hoped, provide better understanding of how the library is to be used, as well as show the interrelationships among the various routines. Note that a good way to understand how to use these routines is to look at the source code for GRASS modules which use them. Note: All routines start with one of following prefixes Vect_, V1_, V2_ or dig_. To avoid name conficts, programmers should not create variables or routines in their own modules which use this prefix. 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 \section vlibArea Vector area functions - Vect_get_area_area() - Vect_get_area_boundaries() - Vect_get_area_centroid() - Vect_get_area_isle() - Vect_get_area_num_isles() - Vect_area_perimeter() - Vect_get_area_points() - Vect_get_isle_area() - Vect_get_isle_boundaries() - Vect_get_isle_points() - Vect_point_in_area() \section vlibArray Vector array functions - Vect_new_varray() - Vect_set_varray_from_cat_list() - Vect_set_varray_from_cat_string() - Vect_set_varray_from_db() \section vlibBox Vector bounding box functions - Vect_box_copy() - Vect_box_clip() - Vect_box_extend() - Vect_box_overlap() - Vect_get_area_box() - Vect_get_isle_box() - Vect_get_line_box() - Vect_get_map_box() - Vect_point_in_box() - Vect_region_box() \section vlibBreakLines Vector break lines functions - Vect_break_lines() - Vect_break_lines_list() \section vlibBreakPolygons Vector break polygons functions - Vect_break_polygons() \section vlibBridges Vector bridges functions - Vect_chtype_bridges() - Vect_remove_bridges() \section vlibBuffer Vector buffer functions - Vect_line_buffer() - Vect_line_parallel() \section vlibBuild Vector build functions - Vect_build() - Vect_build_partial() - Vect_get_built() - Vect_build_sidx_from_topo() - Vect_build_sidx() - Vect_save_sidx() - Vect_save_topo() - Vect_sidx_dump() - Vect_topo_dump() \subsection vlibBuildNat Vector build (native) functions - Vect_attach_centroids() - Vect_attach_isle() - Vect_attach_isles() - Vect_build_line_area() - Vect_build_nat() - Vect_isle_find_area() \subsection vlibBuildOgr Vector build (OGR) functions - Vect_build_ogr() \section vlibCats Vector categories functions - Vect_array_to_cat_list() - Vect_cat_del() - Vect_cat_get() - Vect_cat_in_array() - Vect_cat_in_cat_list() - Vect_cat_set() - Vect_destroy_cat_list() - Vect_destroy_cats_struct() - Vect_field_cat_del() - Vect_get_area_cats() - Vect_get_area_cat() - Vect_get_line_cat() - Vect_new_cat_list() - Vect_new_cats_struct() - Vect_reset_cats() - Vect_str_to_cat_list() \section vlibCindex Vector category index functions (note: vector layer is historically called "field") - Vect_cidx_dump() - Vect_cidx_find_next() - Vect_cidx_find_all() - Vect_cidx_get_cat_by_index() - Vect_cidx_get_field_index() - Vect_cidx_get_field_number() - Vect_cidx_get_num_cats_by_index() - Vect_cidx_get_num_fields() - Vect_cidx_get_num_types_by_index() - Vect_cidx_get_num_unique_cats_by_index() - Vect_cidx_get_type_count() - Vect_cidx_get_type_count_by_index() - Vect_cidx_open() - Vect_cidx_save() - Vect_set_category_index_update() \section vlibCleanNodes Vector clean nodes functions - Vect_clean_small_angles_at_nodes() \section vlibClose Vector close functions - Vect_close() \section vlibConstraint Vector constraint functions - Vect_get_constraint_box() - Vect_remove_constraints() - Vect_set_constraint_region() - Vect_set_constraint_type() \section vlibDangles Vector dangles functions - Vect_chtype_dangles() - Vect_remove_dangles() - Vect_select_dangles() \section vlibDbcolumns Vector dbcolumns functions - Vect_get_column_names() - Vect_get_column_names_types() - Vect_get_column_types() \section vlibError Vector error functions - Vect_get_fatal_error() - Vect_set_fatal_error() \section vlibField Vector field functions (note: vector layer is historically called "field") - Vect_add_dblink() - Vect_check_dblink() - Vect_default_field_info() - Vect_get_dblink() - Vect_get_field() - Vect_get_field_by_name() - Vect_map_add_dblink() - Vect_map_check_dblink() - Vect_map_del_dblink() - Vect_new_dblinks_struct() - Vect_read_dblinks() - Vect_reset_dblinks() - Vect_set_db_updated() - Vect_subst_var() - Vect_write_dblinks() \section vlibFind Vector find functions - Vect_find_area() - Vect_find_island() - Vect_find_line() - Vect_find_line_list() - Vect_find_node() \section vlibGraph Vector graph functions - Vect_graph_add_edge() - Vect_graph_build() - Vect_graph_init() - Vect_graph_set_node_costs() - Vect_graph_shortest_path() \section vlibHeader Vector header functions - Vect_get_comment() - Vect_get_constraint_box() - Vect_get_date() - Vect_get_full_name() - Vect_get_map_date() - Vect_get_map_name() - Vect_get_mapset() - Vect_get_name() - Vect_get_organization() - Vect_get_person() - Vect_get_proj() - Vect_get_proj_name() - Vect_get_scale() - Vect_get_thresh() - Vect_get_zone() - Vect_is_3d() - Vect_print_header() - Vect_read_header() - Vect_set_comment() - Vect_set_date() - Vect_set_map_date() - Vect_set_map_name() - Vect_set_organization() - Vect_set_person() - Vect_set_scale() - Vect_set_thresh() - Vect_set_zone() - Vect_write_header() \section vlibHist Vector history functions - Vect_hist_command() - Vect_hist_copy() - Vect_hist_read() - Vect_hist_rewind() - Vect_hist_write() \section vlibInitHead Vector header functions - Vect_copy_head_data() \section vlibIntersect Vector intersection functions - Vect_line_check_intersection() - Vect_line_intersection() - Vect_segment_intersection() \section vlibLegalVname Vector valid map name functions - Vect_check_input_output_name() - Vect_legal_filename() \section vlibLevel Vector level functions - Vect_level() \section vlibLevelTwo Vector topological (level 2) functions - Vect_get_centroid_area() - Vect_get_line_areas() - Vect_get_line_nodes() - Vect_get_node_coor() - Vect_get_node_line() - Vect_get_node_line_angle() - Vect_get_node_n_lines() - Vect_get_num_areas() - Vect_get_num_dblinks() - Vect_get_num_faces() - Vect_get_num_islands() - Vect_get_num_lines() - Vect_get_num_nodes() - Vect_get_num_primitives() - Vect_get_num_updated_lines() - Vect_get_num_updated_nodes() - Vect_get_updated_line() - Vect_get_updated_node() - Vect_set_release_support() \section vlibLine Vector feature functions - Vect_append_point() - Vect_append_points() - Vect_copy_pnts_to_xyz() - Vect_copy_xyz_to_pnts() - Vect_destroy_line_struct() - Vect_get_num_line_points() - Vect_line_box() - Vect_line_delete_point() - Vect_line_distance() - Vect_line_geodesic_length() - Vect_line_get_point() - Vect_line_insert_point() - Vect_line_length() - Vect_line_prune() - Vect_line_prune_thresh() - Vect_line_reverse() - Vect_line_segment() - Vect_new_line_struct() - Vect_point_on_line() - Vect_points_distance() - Vect_reset_line() \section vlibList Vector list functions - Vect_destroy_list() - Vect_list_append() - Vect_list_append_list() - Vect_list_delete() - Vect_list_delete_list() - Vect_new_list() - Vect_reset_list() - Vect_val_in_list() \section vlibMap Vector map functions - Vect_copy() - Vect_copy_map_lines() - Vect_copy_table() - Vect_copy_table_by_cats() - Vect_copy_tables() - Vect_delete() - Vect_rename() \section vlibNet Vector network functions - Vect_net_build_graph() - Vect_net_get_line_cost() - Vect_net_get_node_cost() - Vect_net_nearest_nodes() - Vect_net_shortest_path() - Vect_net_shortest_path_coor() \section vlibOpen Vector open functions - Vect_coor_info() - Vect_maptype_info() - Vect_maptype() - Vect_open_new() - Vect__open_old() - Vect_open_old() - Vect_open_old_head() - Vect_open_sidx() - Vect_open_topo() - Vect_open_update() - Vect_open_update_head() - Vect_set_open_level() \section vlibOverlay Vector overlay functions - Vect_overlay() - Vect_overlay_str_to_operator() \section vlibVpoly Vector polygon functions - Vect_find_poly_centroid() - Vect_get_point_in_area() - Vect_point_in_area_outer_ring() - Vect_point_in_island() - Vect_get_point_in_poly() - Vect_get_point_in_poly_isl() \section vlibRead Vector read functions \subsection vlibread1_2 Level 1 and 2 - Vect_read_next_line() \subsection vlibRead2 Level 2 only - Vect_area_alive() - Vect_isle_alive() - Vect_line_alive() - Vect_node_alive() - Vect_read_line() \section vlibRemoveAreas Vector remove areas functions - Vect_remove_small_areas() \section vlibRemoveDuplicates Vector remove duplicates functions - Vect_line_check_duplicate() - Vect_remove_duplicates() \section vlibRewind Vector rewind functions - Vect_rewind() \section vlibSelect Vector select functions - Vect_select_areas_by_box() - Vect_select_areas_by_polygon() - Vect_select_isles_by_box() - Vect_select_lines_by_box() - Vect_select_lines_by_polygon() - Vect_select_nodes_by_box() \section vlibSindex Vector spatial index functions - Vect_spatial_index_add_item() - Vect_spatial_index_del_item() - Vect_spatial_index_destroy() - Vect_spatial_index_init() - Vect_spatial_index_select() \section vlibSnap Vector snap functions - Vect_snap_lines() - Vect_snap_lines_list() \section vlibTin Vector TIN functions - Vect_tin_get_z() \section vlibType Vector type option functions - Vect_option_to_types() \section vlibDelete Vector delete functions \subsection vlibDelete2 Level 2 only - Vect_delete_line() \section vlibWrite Vector write functions \subsection vlibWrite1_2 Level 1 and 2 - Vect_write_line() \subsection vlibWrite2 Level 2 only - Vect_rewrite_line() \subsection vlibAsciiFn Vector ASCII functions - Vect_read_ascii() - Vect_read_ascii_head() - Vect_write_ascii() - Vect_write_ascii_head() \subsection vlibSFAFn Vector Simple Feature Access API Functions from GRASS Simple Feature API (in progress, incomplete). - Vect_sfa_get_line_type() - Vect_sfa_check_line_type() - Vect_sfa_line_dimension() - Vect_sfa_line_geometry_type() - Vect_sfa_line_astext() - Vect_sfa_is_line_simple() - Vect_sfa_is_line_closed() \section vlibGeosFn Vector GEOS functions Note: The functions are available only if GRASS is compiled with --with-geos switch. - Vect_read_line_geos() - Vect_read_area_geos() - Vect_line_to_geos() - Vect_get_area_points_geos() - Vect_get_isle_points_geos() \section vlibAuthors Authors - Radim Blazek (vector architecture) - Roberto Micarelli (DGLib) Updates for GRASS 7: - Markus Metz (file-based spatial index) - Martin Landa (GEOS support, direct OGR read access) \section vlibReferences References Text based on: R. Blazek, M. Neteler, and R. Micarelli. The new GRASS 5.1 vector architecture. In Open source GIS - GRASS users conference 2002, Trento, Italy, 11-13 September 2002. University of Trento, Italy, 2002. http://www.ing.unitn.it/~grass/conferences/GRASS2002/proceedings/proceedings/pdfs/Blazek_Radim.pdf \section vlibSeealso See Also - \ref dglib - \ref dbmilib - \ref veditlib Last change: $Date$ */