This directory contains these files:
| Name | Type | Number | Description |
| Version_Major | C | 1 | |
| Version_Minor | C | 1 | |
| Earliest_Major | C | 1 | |
| Earliest_Minor | C | 1 | |
| 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 read |
| with_z | C | 1 | 2D or 3D flag |
| size | L | 1 | coor file size |
| reserved | C | 10 | not used |
Body
The body consists of line records:
| Name | Type | Number | Description |
| record header | I | 1 |
|
| ncats | C | 1 | number of categories (written only if categories exist) |
| field | S | ncats | Category identifier, distinguishes between more categories append to one line (written only if categories exist) |
| cat | I | ncats | category value (written only if categories exist) |
| ncoor | I | 1 | written for GV_LINES and GV_BOUNDARIES only |
| x | D | ncoor | |
| y | D | ncoor | |
| z | D | ncoor | 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 |
Topology is written for native format while pseudo-topology is written for OGR sources, SHAPE-link. \subsection topo_file_format topo file format [detailed docs please insert!] \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). Faces are used in a couple of modules including NVIZ to visualize 3D buildings and other volumetric figures. \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 \subsection Topology_Example_1 Topology Example 1: A polygon may be formed by many boundaries (more primitives but connected). One boundary is shared by adjacent areas. \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 \subsection 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 an 'inner' ring touches the boundary of an outside area, even in one point, it is no longer an '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. \subsection 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. \subsection 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, 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 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 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. 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 takes longer.
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" 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. \section vlibtin Vector TINs TINs are simply created as 2D/3D vector polygons consisting of 3 vertices. \section vlib_attributes Vector library and Attributes
Note: "layer" was called "field" in earlier version.
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 (odbc, dbf, PostgreSQL and MySQL drivers are available at this time). Records in a table are linked to vector entities by field and category number. The field identifies table and the category identifies record. I.e., for any unique combination map+mapset+field+category, there exists one unique combination driver+database+table+row.
For each pair map + field, all of table, key column,
database, driver must be defined. This definition must be written to $MAPSET/DB text file.
Each row in the 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 omitted (on second and higher row only)
the last definition is used. Definitions from DB file in other mapsets
may be overwritten by a definition in the 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 the current mapset but mapset of the map the rule is defined for.
Note that features in GRASS vectors 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.
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 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 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 define more fields 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/DB 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 field 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 such 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 reliable RDBMS.
\section grassdglib DGLib (Directed Graph Library)
The Directed Graph Library or DGLib (Micarelli 2002,
\ref dglib , http://grass.itc.it/dglib/) provides functionality for vector network
analysis. This library released under GPL is hosted by the GRASS project (in
the CVS server within the GRASS source code). As a stand-alone library it
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 treshold 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
--o overwrite existing files
-b do not build topo file; by default topo file is written
-q quiet
-v run verbosely [either -q or -v!]
-t create new table, default ???
-u don't create new table ???
-z write 3D file (if input was 2D)
map= input vector for modules without output
input= input vector
output= output vector
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
col= 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_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 box functions
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 Vector break lines functions
Vect_break_lines();
\section break_polygons Vector break_polygons functions
Vect_break_polygons();
\section bridges Vector bridges functions
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();
\section build_nat Vector build_nat functions
Vect_attach_centroids();
Vect_attach_isle();
Vect_attach_isles();
Vect_build_line_area();
Vect_build_nat();
Vect_isle_find_area();
\section build_ogr Vector build_ogr functions
Vect_build_ogr();
\section cats Vector cats 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_new_cat_list();
Vect_new_cats_struct();
Vect_reset_cats();
Vect_str_to_cat_list();
\section cindex Vector cindex functions
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 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();
\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
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 Vector find functions
Vect_find_area();
Vect_find_island();
Vect_find_line();
Vect_find_node();
\section graph Vector graph functions
Vect_graph_add_edge();
Vect_graph_init();
Vect_graph_set_node_costs();
Vect_graph_shortest_path();
\section header Vector header functions
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 Vector hist functions
Vect_hist_command();
Vect_hist_copy();
Vect_hist_read();
Vect_hist_rewind();
Vect_hist_write();
\section init_head Vector init_head functions
Vect_copy_head_data();
\section intersect Vector intersect functions
Vect_line_check_intersection();
Vect_segment_intersection();
\section legal_vname Vector legal_vname functions
Vect_check_input_output_name();
\section level Vector level functions
Vect_level();
\section level_two Vector level_two (topological) 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_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 Vector line 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_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 net functions
Vect_net_build_graph();
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_and();
Vect_overlay_str_to_operator();
\section poly Vector poly functions
Vect_find_poly_centroid();
Vect_get_point_in_area();
Vect_get_point_in_poly();
Vect_get_point_in_poly_isl();
\section read Vector read functions
Vect_area_alive();
Vect_isle_alive();
Vect_line_alive();
Vect_node_alive();
Vect_read_line();
Vect_read_next_line();
\section remove_areas Vector remove_areas functions
Vect_remove_small_areas();
\section remove_duplicates Vector remove_duplicates functions
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_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();
\section tin Vector tin functions
Vect_tin_get_z();
\section type Vector type functions
Vect_option_to_types();
\section write Vector write functions
Vect_rewrite_line();
Vect_write_line();
\section contacts Contacts
Radim Blazek (vector architecture)