/*! \page Vector_Library GRASS 6 Vector Architecture by GRASS Development Team http://grass.itc.it \section background Background Generally, the vector data model is used to describe geographic phenomena which may be represented by geometric entities (primitives) like points, lines, and areas. The GRASS vector data model includes the description of topology, where besides the coordinates which are describing the location of the points, lines, boundaries and centroids also their spatial relations are stored. In general, topological GIS require a data structure where common boundary between two adjacent areas is stored as a single line, simplifying the map maintenance. \section intro Introduction The GRASS 6 vector format is very similar to old 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 internal file based storage the geometry may alternatively be stored in 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 necessity of format conversion. Current implemented are: The following vector objects are available: 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 on input to GRASS, GRASS doesn't decide. GRASS allows for the line definition which allows for the multiple type 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). Single and multi-category support on modules level is implemented. Z-coordinate is optional and both 2d and 3d files may be written. \section libraries Libraries Besides internal library functions there are two main libraries: For historical reasons, there are internally two libraries for vector: The Vlib Vector library was introduced in grass4.0 to hide vector files' formats and structures. In GRASS 6 everything is accessed via Vect_*() functions, for example: Old 4.x code: \verbatim xx = Map.Att[Map.Area[area_num].att].x; \endverbatim New 6.x functions: \verbatim Vect_get_area_centroid() Vect_get_centroid_coor() \endverbatim \subsection vlib Introduction to Vlib (Vector library) Note: For details please read Blazek et al. 2002 (see below) as well as the references in this document. \subsubsection Directory_structure Directory structure 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:
$MAPSET/vector/vector_name/

This directory contains these files:

\subsubsection coor_file_format_specification coor file format specification
  1. In the coor file the following is stored: 'line' (element) type, number of attributes and layer number for each category.
  2. Coordinates in binary file are stored as double (8 bytes).
Head
NameTypeNumberDescription
Version_Major C1 
Version_Minor C1 
Earliest_MajorC1 
Earliest_MinorC1 
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
with_zC12D or 3D flag
sizeL1coor file size
reservedC10not used

Body The body consists of line records:
NameTypeNumberDescription
record headerI1
  • 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
ncatsC1number of categories (written only if categories exist)
fieldSncatsCategory identifier, distinguishes between more categories append to one line (written only if categories exist)
catIncatscategory value (written only if categories exist)
ncoorI1written for GV_LINES and GV_BOUNDARIES only
xDncoor 
yDncoor 
zDncoorpresent 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
\subsubsection head_file_format head file format The file is unordered list of key/value entries. The key is a string separated from value by a colon and optional whitespace. Key words are:
\verbatim ORGANIZATION DIGIT DATE DIGIT NAME MAP NAME MAP DATE MAP SCALE OTHER INFO ZONE MAP THRESH \endverbatim \subsection vlib_topology_management Vector library Topology management Topology general characteristics:

  1. geometry and attributes are stored separately (don't read both if it is not necessary (usually it is not))
  2. the format is topological (areas build from boundaries)

Topology is written for native format while pseudo-topology is written for OGR sources, SHAPE-link. \subsubsection topo_file_format topo file format [detailed docs missing] \verbatim /* 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 \endverbatim \verbatim #define GV_POINTS (GV_POINT | GV_CENTROID ) #define GV_LINES (GV_LINE | GV_BOUNDARY ) \endverbatim Face and kernel are 3D equivalents of boundary and centroid, but there is no support (yet) for 3D topology (volumes). The only current use of face is possibility to display vertical planes in NVIZ. \verbatim /* 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_ALL GV_BUILD_CENTROIDS \endverbatim GV_BOUNDARY contains geometry and it is used to build areas. GV_LINE cannot form an area. \verbatim struct line_cats { int *field; /* pointer to array of fields */ int *cat; /* pointer to array of categories */ int n_cats; /* number of vector categories attached to element */ int alloc_cats; /* allocated space */ }; \endverbatim \subsubsection 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. \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 Topology_Example_2 Topology Example 2: This is handled correctly in GRASS: A can be filled, B filled differently. \verbatim +---------+ | A | +-----+ | | B | | +-----+ | | | +---------+ \endverbatim In GRASS, whenever 'inner' ring touches the boundary of outside area, even in one point, it is no more 'inner' ring, 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. \subsubsection Topology_Example_3 Topology Example 3: 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. \subsubsection vlib_topo_memory 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 is needed to build topology. Topology is also necessary for points in case of vector network because the graph is built using topology informations about lines and points. The topology structure does not only store the topology but also '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. \subsubsection vlib_spidx Vector library spatial index management Spatial index (based on R-tree) is calculated on the fly. Spatial index occupies a lot of memory but it is necessary for topology building. Also, it takes 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 module (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 long time on large files. Currently most of the modules do not release the memory occupied for spatial index and work like this (pseudocode): \verbatim int main { Vect_open_new() //writing new vector Vect_build() Vect_close() // memory is not released } \endverbatim In general it is possible to free the memory with Vect_set_release_support() such as: \verbatim int main { Vect_open_new() // writing new vector Vect_build() Vect_set_release_support() Vect_close() // memory is released } \endverbatim but it only takes longer time.

It make sense to release spatial index if it is used only at the beginning of a module or in permanently running programs like QGIS. For example: \verbatim int main { Vect_open_old() // 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 } \endverbatim \subsubsection vlib_categories_layers Vector library categories and layers

Note: "layer" was called "field" in earlier version.

In GRASS a "category" is a feature ID used to link geometry with attributes stored in one or many (external) database table(s). 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. \subsection vlibtin Vector TINs TINs are created as 2D/3D vector polygons consisting of 3 vertices. \section vlib_attributes Vector library and Attributes The old GRASS 4.x 'dig_cats' files are not used any more and vectors' attributes are stored in external database. Connection with database is done through drivers based on DBMI library (odbc, dbf, PostgreSQL and MySQL drivers are available at this time). Records in table are linked to vector entities by field and category number. The field identifies table and the category identifies record. I.e., for unique combination map+mapset+field+category exists one unique combination driver+database+table+row.

For each pair map + field must be defined table, key column, database, driver. This definition must be written to $MAPSET/DB text file. Each row in DB file contains names separated by spaces in following order ([] - optional):

\verbatim map[@mapset] field table [key [database [driver]]] \endverbatim If key, database or driver are omited (on second and higher row only) last definition is used. Definition from DB file in other mapset may be overwritten by definition in current mapset if mapset is specified with map name.

Wild cards * and ? may be used in map and mapset names.

Variables $GISDBASE, $LOCATION, $MAPSET, $MAP, $FIELD may be used in table, key, database and driver names. Note that $MAPSET is not current mapset but mapset of the map the rule is defined for.

Note that features in GRASS vector may have attributes in different tables or may be without attributes. Boundaries forms 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.

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 g.remove, for example, deletes linked tables of the vector. Attributes must be joined with geometry.

Examples: Examples are written mostly for dbf driver where database is full path to directory with dbf files and table name is name of dbf file without .dbf extension.

\verbatim * 1 tbl id $GISDBASE/$LOCATION/$MAPSET/vector/$MAP dbf \endverbatim This definition says that entities with category of field 1 are linked to dbf tables with names tbl.dbf saved in vector directories of each map.

\verbatim * 1 $MAP id $GISDBASE/$LOCATION/$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 defines more fields for one map i.e. in one map may be more features linked to more tables. Definition 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 definition saved in PERMANENT/DB and links map from PERMANENT mapset to user's table.

Modules should be written so that connections to database for each vector field are independent. It should be possible to read attributes of input map from one database and write to some other and even with some other driver (should not be such problem).

There are open questions however. For example how to distinguish when new table 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 reliable RDBMS. \section dglib DGLib (Directed Graph Library) The Directed Graph Library or DGLib (Micarelli 2002, http://grass.itc.it/dglib/) provides functionality for vector network analysis. This library released under GPL is hosted by the GRASS project (in the CVS server within the GRASS source code). As stand-alone library it may also be used by other software project. 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. For details please read Blazek et al. 2002 (see below). \section vlibfunc List of vector library functions The Vect_*() functions are the programmer's API for GRASS vector programming. \section area area Vect_get_area_area(); Vect_get_area_boundaries(); Vect_get_area_centroid(); Vect_get_area_isle(); Vect_get_area_num_isles(); Vect_get_area_points(); Vect_get_isle_area(); Vect_get_isle_boundaries(); Vect_get_isle_points(); Vect_point_in_area(); \section array array Vect_new_varray(); Vect_set_varray_from_cat_list(); Vect_set_varray_from_cat_string(); Vect_set_varray_from_db(); \section box box Vect_box_copy(); 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 break_lines break_lines Vect_break_lines(); \section break_polygons break_polygons Vect_break_polygons(); \section bridges bridges Vect_remove_bridges(); \section buffer buffer Vect_line_buffer(); Vect_line_parallel(); \section build build Vect_build(); Vect_build_partial(); Vect_get_built(); Vect_save_spatial_index(); Vect_save_topo(); Vect_spatial_index_dump(); Vect_topo_dump(); \section build_nat build_nat Vect_attach_centroids(); Vect_attach_isle(); Vect_attach_isles(); Vect_build_line_area(); Vect_build_nat(); Vect_isle_find_area(); \section build_ogr build_ogr Vect_build_ogr(); \section cats cats 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_new_cat_list(); Vect_new_cats_struct(); Vect_reset_cats(); Vect_str_to_cat_list(); \section cindex cindex Vect_cidx_dump(); Vect_cidx_find_next(); 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(); \section clean_nodes clean_nodes Vect_clean_small_angles_at_nodes(); \section close close Vect_close(); \section constraint constraint Vect_get_constraint_box(); Vect_remove_constraints(); Vect_set_constraint_region(); Vect_set_constraint_type(); \section dangles dangles Vect_chtype_dangles(); Vect_remove_dangles(); \section dbcolumns dbcolumns Vect_get_column_names(); Vect_get_column_names_types(); Vect_get_column_types(); \section error error Vect_get_fatal_error(); Vect_set_fatal_error(); \section field field Vect_add_dblink(); Vect_check_dblink(); Vect_default_field_info(); Vect_get_dblink(); Vect_get_field(); Vect_map_add_dblink(); Vect_map_check_dblink(); Vect_map_del_dblink(); Vect_new_dblinks_struct(); Vect_read_dblinks(); Vect_reset_dblinks(); Vect_subst_var(); Vect_write_dblinks(); \section find find Vect_find_area(); Vect_find_island(); Vect_find_line(); Vect_find_node(); \section graph graph Vect_graph_add_edge(); Vect_graph_init(); Vect_graph_set_node_costs(); Vect_graph_shortest_path(); \section header header Vect_get_comment(); 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_zone(); Vect_is_3d(); Vect_print_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(); \section hist hist Vect_hist_command(); Vect_hist_copy(); Vect_hist_read(); Vect_hist_rewind(); Vect_hist_write(); \section init_head init_head Vect_copy_head_data(); \section intersect intersect Vect_line_check_intersection(); Vect_segment_intersection(); \section legal_vname legal_vname Vect_check_input_output_name(); \section level level Vect_level(); \section level_two level_two 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_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(); \section line line Vect_append_point(); Vect_append_points(); Vect_copy_pnts_to_xyz(); Vect_copy_xyz_to_pnts(); Vect_destroy_line_struct(); Vect_line_box(); Vect_line_delete_point(); Vect_line_distance(); Vect_line_geodesic_length(); 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 list list Vect_destroy_list(); Vect_list_append(); Vect_list_append_list(); Vect_list_delete(); Vect_list_delete_list(); Vect_reset_list(); Vect_val_in_list(); \section map map Vect_copy(); Vect_copy_map_lines(); Vect_copy_table(); Vect_copy_table_by_cats(); Vect_copy_tables(); Vect_delete(); Vect_rename(); \section net net Vect_net_build_graph(); Vect_net_nearest_nodes(); Vect_net_shortest_path(); Vect_net_shortest_path_coor(); \section open open Vect_coor_info(); Vect_maptype_info(); Vect_open_new(); Vect__open_old(); Vect_open_old(); Vect_open_old_head(); Vect_open_spatial_index(); Vect_open_topo(); Vect_open_update(); Vect_open_update_head(); Vect_set_open_level(); \section overlay overlay Vect_overlay(); Vect_overlay_and(); Vect_overlay_str_to_operator(); \section poly poly Vect_find_poly_centroid(); Vect_get_point_in_area(); Vect_get_point_in_poly(); Vect_get_point_in_poly_isl(); \section read read Vect_area_alive(); Vect_isle_alive(); Vect_line_alive(); Vect_node_alive(); Vect_read_line(); Vect_read_next_line(); \section remove_areas remove_areas Vect_remove_small_areas(); \section remove_duplicates remove_duplicates Vect_remove_duplicates(); \section rewind rewind Vect_rewind(); \section rewind_nat rewind_nat \section rewind_ogr rewind_ogr \section select select 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 sindex sindex Vect_spatial_index_add_item(); Vect_spatial_index_del_item(); Vect_spatial_index_destroy(); Vect_spatial_index_init(); Vect_spatial_index_select(); \section snap snap Vect_snap_lines(); \section tin tin Vect_tin_get_z(); \section type type Vect_option_to_types(); \section write write Vect_rewrite_line(); Vect_write_line(); \section contacts Contacts Radim Blazek (vector architecture) Roberto Micarelli (DGLib) \section references 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 seealso See Also DBMI - Database Management Interface: \ref DataBase_Management_Interface Last change: $Date$ */