The following vector objects are defined:
This directory contains these files:
| Name | Type | Number | Description |
| Version_Major | C | 1 | file version (major) |
| Version_Minor | C | 1 | file version (minor) |
| Back_Major | C | 1 | supported from GRASS version (major) |
| Back_Minor | C | 1 | supported from GRASS version (minor) |
| byte_order | C | 1 | little or big endian flag |
| head_size | L | 1 | header size of coor file |
| with_z | C | 1 | 2D or 3D flag; zero for 2D |
| size | L | 1 | coor file size |
Body
The body consists of line records:
| Name | Type | Number | Description |
| record header | C | 1 |
|
| ncats | I | 1 | number of categories (written only if categories exist) |
| field | I | ncats | field identifier, distinguishes between more categories append to one feature (written only if categories exist; field is called "layer" at user level) |
| cat | I | ncats | category value (written only if categories exist) |
| ncoor | I | 1 | written for GV_LINES and GV_BOUNDARIES only |
| x | D | ncoor | x coordinate |
| y | D | ncoor | y coordinate |
| z | D | ncoor | z coordinate; present if with_z in head is set to 1 |
Types used in coor file
| Type | Name | Size in Bytes |
| D | Double | 8 |
| L | Long | 4 |
| I | Int | 4 |
| S | Short | 4 |
| C | Char | 1 |
| Name | Type | Number | Description |
| Version_Major | C | 1 | file version (major) |
| Version_Minor | C | 1 | file version (minor) |
| Back_Major | C | 1 | supported from GRASS version (major) |
| Back_Minor | C | 1 | supported from GRASS version (minor) |
| byte_order | C | 1 | 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 |
| head_size | L | 1 | header size |
| with_z | C | 1 | 2D or 3D flag; zero for 2D |
| box | D | 6 | Bounding box coordinates (N,S,E,W,T,B) |
| n_nodes, n_lines, etc. | I | 7 | Number of nodes, edges, lines, areas, isles, volumes and holes |
| n_plines, n_llines, etc. | I | 7 | Number of points, lines, boundaries, centroids, faces and kernels |
| Node_offset, Edge_offset, etc. | L | 7 | Offset value for nodes, edges, lines, areas, isles, volumes and holes |
| coor_size | L | 1 | File size |
| Name | Type | Number | Description |
| n_lines | I | 1 | Number of lines (0 for dead node) |
| lines | I | n_lines | Line ids |
| angles | D | n_lines | Angle value |
| n_edges | I | 1 | Reserved for edges (only for with_z) |
| x,y | D | 2 | Coordinate pair |
| z | D | 1 | Only for with_z |
| Name | Type | Number | Description |
| feature type | C | 1 | 0 for dead |
| offset | L | 1 | Line offset |
| N1 | I | 1 | First node id (only if feature type is GV_POINTS, GV_LINES or GV_KERNEL) |
| N2 | I | 1 | Second node id (only if feature type is GV_LINE or GV_BOUNDARY) |
| left | I | 1 | Left area id for feature type GV_BOUNDARY / Area id for feature type GV_CENTROID |
| right | I | 1 | Right area id (for feature type GV_BOUNDARY) |
| vol | I | 1 | Reserved for kernel (volume number, for feature type GV_KERNEL) |
| N,S,E,W | D | 4 | Line bounding box (for feature type GV_LINE, GV_BOUNDARY or GV_FACE) |
| T,B | D | 2 | Line bounding box for 3D (only if with_z=1) |
| Name | Type | Number | Description |
| n_lines | I | 1 | number of boundaries |
| lines | I | n_lines | Line ids |
| n_isles | I | 1 | Number of isles |
| isles | I | n_isles | Isle ids |
| centroid | I | 1 | Centroid id |
| N,S,E,W | D | 4 | Area bounding box |
| T,B | D | 2 | Area bounding box for 3D (only if with_z=1) |
| Name | Type | Number | Description |
| n_lines | I | 1 | number of boundaries |
| lines | I | n_lines | Line ids |
| area | I | 1 | Outer area id |
| N,S,E,W | D | 4 | Isle bounding box |
| T,B | D | 2 | Isle bounding box for 3D (only if with_z=1) |
It make sense to release the 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 \section vlib_categories_layers Vector library 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. Categories do not have to be continuous.
\section vlib_cidx Vector library category index
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
\verbatim
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 */
};
\endverbatim
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.
\section vlibtin Vector TINs
TINs are simply created as 2D/3D vector polygons consisting of
3 vertices. See Vect_tin_get_z().
\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 the
database is done through drivers based on DBMI library (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
driver+database+table+row.
The general DBMI settings are defined in the "MAPSET/VAR" text file
(maintained with db.connect 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 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, $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 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.
\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 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 grassdglib 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 ASCII format is (currently) explained in the
manual page of v.in.ascii, which is defined in the file:
vector/v.in.ascii/description.html
\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.
\subsection vectmodulesoper Modules operation 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.
\subsection vectmodulesopt Modules parameters/flags
-b do not build topo file; by default topo file is written
-t create new table, default
-u don't create new table
-z write 3D vector map (if input was 2D)
map= input vector map for modules without output
input= input vector map
output= output vector map
type= type of elements: point,line,boundary,centroid,area
cat= category or category list (example: 1,5,9-13,35)
layer= layer number
where= condition of SQL statement for selection of records
column= column name (in external table)
\section vlibfunc List of vector library functions
The Vect_*() functions are the programmer's API for GRASS vector
programming.
\section area 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 array Vector array functions
- Vect_new_varray()
- Vect_set_varray_from_cat_list()
- Vect_set_varray_from_cat_string()
- Vect_set_varray_from_db()
\section box 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 break_lines Vector break lines functions
- Vect_break_lines()
- Vect_break_lines_list()
\section break_polygons Vector break polygons functions
- Vect_break_polygons()
\section bridges Vector bridges functions
- Vect_chtype_bridges()
- Vect_remove_bridges()
\section buffer Vector buffer functions
- Vect_line_buffer()
- Vect_line_parallel()
\section build Vector build functions
- Vect_build()
- Vect_build_partial()
- Vect_get_built()
- Vect_save_spatial_index()
- Vect_save_topo()
- Vect_spatial_index_dump()
- Vect_topo_dump()
\subsection build_nat 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 build_ogr Vector build (OGR) functions
- Vect_build_ogr()
\section cats 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 cindex 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 clean_nodes Vector clean nodes functions
- Vect_clean_small_angles_at_nodes()
\section close Vector close functions
- Vect_close()
\section constraint Vector constraint functions
- Vect_get_constraint_box()
- Vect_remove_constraints()
- Vect_set_constraint_region()
- Vect_set_constraint_type()
\section dangles Vector dangles functions
- Vect_chtype_dangles()
- Vect_remove_dangles()
- Vect_select_dangles()
\section dbcolumns Vector dbcolumns functions
- Vect_get_column_names()
- Vect_get_column_names_types()
- Vect_get_column_types()
\section error Vector error functions
- Vect_get_fatal_error()
- Vect_set_fatal_error()
\section field 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_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 find Vector find functions
- Vect_find_area()
- Vect_find_island()
- Vect_find_line()
- Vect_find_line_list()
- Vect_find_node()
\section graph Vector graph functions
- Vect_graph_add_edge()
- Vect_graph_build()
- Vect_graph_init()
- Vect_graph_set_node_costs()
- Vect_graph_shortest_path()
\section header 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 hist Vector history functions
- Vect_hist_command()
- Vect_hist_copy()
- Vect_hist_read()
- Vect_hist_rewind()
- Vect_hist_write()
\section init_head Vector header functions
- Vect_copy_head_data()
\section intersect Vector intersection functions
- Vect_line_check_intersection()
- Vect_line_intersection()
- Vect_segment_intersection()
\section legal_vname Vector valid map name functions
- Vect_check_input_output_name()
- Vect_legal_filename()
\section level Vector level functions
- Vect_level()
\section level_two 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 line Vector feature functions
- 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 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 map 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 net 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 open Vector open functions
- 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 Vector overlay functions
- Vect_overlay()
- Vect_overlay_str_to_operator()
\section vpoly 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 read Vector read functions
\subsection read1_2 Level 1 and 2
- Vect_read_next_line()
\subsection read2 Level 2 only
- Vect_area_alive()
- Vect_isle_alive()
- Vect_line_alive()
- Vect_node_alive()
- Vect_read_line()
\section remove_areas Vector remove areas functions
- Vect_remove_small_areas()
\section remove_duplicates Vector remove duplicates functions
- Vect_line_check_duplicate()
- Vect_remove_duplicates()
\section rewind Vector rewind functions
- Vect_rewind()
\section select 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 sindex Vector spatial index functions
- Vect_build_sidx_from_topo()
- Vect_build_spatial_index()
- Vect_spatial_index_add_item()
- Vect_spatial_index_del_item()
- Vect_spatial_index_destroy()
- Vect_spatial_index_init()
- Vect_spatial_index_select()
\section snap Vector snap functions
- Vect_snap_lines()
- Vect_snap_lines_list()
\section tin Vector TIN functions
- Vect_tin_get_z()
\section type Vector type option functions
- Vect_option_to_types()
\section delete Vector delete functions
\subsection delete2 Level 2 only
- Vect_delete_line()
\section write Vector write functions
\subsection write1_2 Level 1 and 2
- Vect_write_line()
\subsection write2 Level 2 only
- Vect_rewrite_line()
\section vlibAuthors Authors
- Radim Blazek (vector architecture)