GRASS Programmer's Manual  6.5.svn(2014)-r66266
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
GRASS 6 Vector Architecture

by GRASS Development Team

Table of contents


List of vector library functions



See Also


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 require a data structure where the common boundary between two adjacent areas is stored as a single line, simplifying the map maintenance.


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 a PostGIS database. This enables users to maintain large data sets with simultaneous write access. External GIS formats such as SHAPE-files may be used directly, without requiring format conversion.

The current implementation includes:

  • multi-layer: features in one vector map may represent more layers and may be linked to more external tables (see Vector library categories and layers);
  • 2D and 3D vector geometry with full topology support for 2D and partial topology support for 3D (see Vector library topology management);
  • 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 dglib: support for vector network analysis;
  • spatial index: based on R-tree method for fast vector geometry access (see Vector library spatial index management).
  • multi-attribute: attributes saved in external Relational Database Management System (RDBMS) connected through DBMI library and drivers (Vector library and attributes);

GRASS vector maps are stored in an arc-node representation, consisting of curves called arcs. An arc is stored as a series of x,y,z coordinate pairs. The two endpoints of an arc are called nodes. Two consecutive x,y,z pairs define an arc segment. The user specifies the type of input to GRASS; GRASS doesn't decide. GRASS allows for the line definition which allows for multiple types to co-exist in the same map. Centroid are assigned to area it is within/inside (geometrically). An area is identified by an x,y,z centroid point geometrically inside with a category number (ID). This identifies the area. Such centroids are stored in the same binary 'coor' file with other primitives. Each element may have none, one or more categories (cats). More cats are distinguished by field number (field, called "layer" at user level). Single and multi-category support on modules level are implemented. Z-coordinate is optional and both 2D and 3D files may be written.

The following vector objects are defined:

  • point: a point;
  • line: a directed sequence of connected vertices with two endpoints called nodes;
  • boundary: the border line to describe an area;
  • centroid: a point within a closed boundary;
  • area: the topological composition of a closed ring of boundaries and optionally a centroid;
  • face: a 3D boundary;
  • kernel: a 3D centroid in a volume;
  • volume: a 3D corpus, the topological composition of faces and kernel.

Note that all lines and boundaries can be polylines (with nodes in between).

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.

Vector libraries

Besides internal library functions there are two main libraries:

For historical reasons, there are two internal libraries for vector:

  • 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, everything is accessed via Vect_*() functions, for example:

Old 4.x code:

    xx = Map.Att[Map.Area[area_num].att].x;

New 6.x functions:


In GRASS 6, 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.

Introduction to Vlib (Vector library)

Note: For details please read Blazek et al. 2002 (see below) as well as the references in this document.

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:


This directory contains these files:

  • coor - binary file, coordinates [former dig/ file]
  • topo - binary file, topology [former dig_plus/ file]
  • cidx - binary file, category index
  • head - text file, header information [former part of dig/ file]
  • dbln - text file, link(s) to attribute table(s)
  • hist - text file, vector map change history

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).




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


The body consists of line records:

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


number of categories (written only if categories exist)


field identifier, distinguishes between more categories append to one feature (written only if categories exist; field is called "layer" at user level)


category value (written only if categories exist)


written for GV_LINES and GV_BOUNDARIES only


x coordinate


y coordinate

zDncoorz coordinate; present if with_z in head is set to 1

Types used in coor file

TypeNameSize in Bytes
LLong 4
IInt 4
SShort 4
CChar 1

Head file format

The file is an unordered list of key/value entries. The key is a string separated from value by a colon and optional whitespace. Key words are:


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 GRASS vector format; in case of linked OGR sources (see v.external module), only pseudo-topology (boundaries constructed from polygons) is written.

The following rules apply to the vector data:

  • Boundaries should not cross each other (i.e., boundaries which would cross must be split at their intersection to form distict boundaries). On the contrary, lines can cross each other, e.g. bridges over rivers.
  • Lines and boundaries share nodes only if their endpoints are identical. Lines or boundaries can be forced to share a common node by snapping them together. This is particulary important since nodes are not represented in the coor file, but only implicitly as endpoints of lines and boundaries.
  • 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 in 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. For example, 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(s), and a boundary which is functionally also a line should be labeled as a line by a distinct category number.

Vector map topology can be cleaned at user level by v.clean command.

Topology examples


One point (nodes: 1, lines: 1, areas: 0, isles: 0)

    + N1/L1

Node N1 (see P_Node)

node = 1, n_lines = 1, xyz = 631286.707172, 225105.223577, 0.000000
  line =   1, type = 1, angle = -9.000000

Line L1 (see P_Line)

line = 1, type = 1, offset = 18 n1 = 1, n2 = 1, left/area = 0, right = 0
N,S,E,W,T,B: 225105.223577, 225105.223577, 631286.707172, 631286.707172, 0.000000, 0.000000


One line (nodes: 2, lines: 1, areas: 0, isles: 0)

   N1         N2

Node N1 (see P_Node)

node = 1, n_lines = 1, xyz = 634624.746450, 223557.302231, 0.000000
  line =   1, type = 2, angle = -0.436257

Node N2 (see P_Node)

node = 2, n_lines = 1, xyz = 638677.484787, 221667.849899, 0.000000
  line =  -1, type = 2, angle = 2.705335

Line L1 (see P_Line)

line = 1, type = 2, offset = 18 n1 = 1, n2 = 2, left/area = 0, right = 0
N,S,E,W,T,B: 223557.302231, 221667.849899, 638677.484787, 634624.746450, 0.000000, 0.000000

Areas without holes

One line (nodes: 2, lines: 2, areas: 1, isles: 1)

         /   \
        /     \
       /       \
      /  +N2/L2 \
     /           \

Node N1 (see P_Node)

node = 1, n_lines = 2, xyz = 635720.081136, 225063.387424, 0.000000
  line =   1, type = 4, angle = -2.245537
  line =  -1, type = 4, angle = -0.842926

Node N2 (see P_Node)

node = 2, n_lines = 1, xyz = 635779.454021, 223100.127232, 0.000000
  line =   2, type = 8, angle = -9.000000

Line L1 (see P_Line)

line = 1, type = 4, offset = 18 n1 = 1, n2 = 1, left/area = 1, right = -1
N,S,E,W,T,B: 225063.387424, 222188.133874, 638184.584178, 633419.878296, 0.000000, 0.000000

Line L2 (see P_Line)

line = 2, type = 8, offset = 87 n1 = 2, n2 = 2, left/area = 1, right = 0
N,S,E,W,T,B: 223100.127232, 223100.127232, 635779.454021, 635779.454021, 0.000000, 0.000000

Area A1 (see P_Area)

area = 1, n_lines = 1, n_isles = 0 centroid = 2
N,S,E,W,T,B: 225063.387424, 222188.133874, 638184.584178, 633419.878296, 0.000000, 0.000000
  line =  -1

Isle I1 (see P_Isle)

isle = 1, n_lines = 1 area = 0
N,S,E,W,T,B: 225063.387424, 222188.133874, 638184.584178, 633419.878296, 0.000000, 0.000000
  line =   1

Areas with holes

One line (nodes: 3, lines: 3, areas: 2, isles: 2)

            / \
           /   \
          /     \
         /       \
        /  +N2/L2 \
       /           \
      /   +N3       \
     /   /\          \
    /   /  \          \
   /   /    \          \
  /    ---L3--          \
 /                       \

Node N1 (see P_Node)

node = 1, n_lines = 2, xyz = 635720.081136, 225063.387424, 0.000000
  line =   1, type = 4, angle = -2.245537
  line =  -1, type = 4, angle = -0.842926

Node N2 (see P_Node)

node = 2, n_lines = 1, xyz = 635779.454021, 223100.127232, 0.000000
  line =   2, type = 8, angle = -9.000000

Node N3 (see P_Node)

node = 3, n_lines = 2, xyz = 636788.032454, 223173.935091, 0.000000
  line =   3, type = 4, angle = -2.245537
  line =  -3, type = 4, angle = -0.866302

Line L1 (see P_Line)

line = 1, type = 4, offset = 18 n1 = 1, n2 = 1, left/area = 1, right = -1
N,S,E,W,T,B: 225063.387424, 222188.133874, 638184.584178, 633419.878296, 0.000000, 0.000000

Line L2 (see P_Line)

line = 2, type = 8, offset = 87 n1 = 2, n2 = 2, left/area = 1, right = 0
N,S,E,W,T,B: 223100.127232, 223100.127232, 635779.454021, 635779.454021, 0.000000, 0.000000

Line L3 (see P_Line)

line = 3, type = 4, offset = 197 n1 = 3, n2 = 3, left/area = 2, right = -2
N,S,E,W,T,B: 223173.935091, 222626.267748, 637253.549696, 636349.898580, 0.000000, 0.000000

Area A1 (see P_Area)

area = 1, n_lines = 1, n_isles = 1 centroid = 2
N,S,E,W,T,B: 225063.387424, 222188.133874, 638184.584178, 633419.878296, 0.000000, 0.000000
  line =  -1
  isle =   2

Area A2 (see P_Area)

area = 2, n_lines = 1, n_isles = 0 centroid = 0
N,S,E,W,T,B: 223173.935091, 222626.267748, 637253.549696, 636349.898580, 0.000000, 0.000000
  line =  -3

Isle I1 (see P_Isle)

isle = 1, n_lines = 1 area = 0
N,S,E,W,T,B: 225063.387424, 222188.133874, 638184.584178, 633419.878296, 0.000000, 0.000000
  line =   1

Isle I2 (see P_Isle)

isle = 2, n_lines = 1 area = 1
N,S,E,W,T,B: 223173.935091, 222626.267748, 637253.549696, 636349.898580, 0.000000, 0.000000
  line =   3

Topo file format




Version_Major C1file version (major)
Version_Minor C1file version (minor)
Back_MajorC1supported from GRASS version (major)

supported from GRASS version (minor)


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


header size


2D or 3D flag; zero for 2D


Bounding box coordinates (N,S,E,W,T,B)

n_nodes, n_lines, etc.I7

Number of nodes, edges, lines, areas, isles, volumes and holes

n_plines, n_llines, etc.I7

Number of points, lines, boundaries, centroids, faces and kernels

Node_offset, Edge_offset, etc.L7

Offset value for nodes, edges, lines, areas, isles, volumes and holes

coor_sizeL1File size


For each node (n_nodes):

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

For each line (n_lines):

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)

For each area (n_areas):

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)

For each isle (n_isle):

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)

Feature types:

/* 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

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.

/* 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 */

GV_BOUNDARY contains geometry and it is used to build areas. GV_LINE cannot form an area.

struct line_cats
      int *field;       /* pointer to array of fields a.k.a. layer*/
      int *cat;         /* pointer to array of categories */
      int n_cats;       /* number of vector categories attached to element */
      int alloc_cats;   /* allocated space */

Topology Example 1:

A polygon may be formed by many boundaries (more primitives but connected). One boundary is shared by adjacent areas.

|     |     |
2  A  4  B  6
|     |     |

1,2,3,4,5,6,7 = 7 boundaries (primitives)
A,B = 2 areas

Topology Example 2:

This is handled correctly in GRASS: A can be filled, B filled differently.

|    A    |
+-----+   |
|  B  |   |
+-----+   |
|         |

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.

Topology Example 3:

This is handled correctly in GRASS: Areas A1, A2, and A3 can be filled differently.

|  A1                 |
+   +------+------+   |
|   |  A2  |  A3  |   |
+   +------+------+   |
|          I1         |

In GRASS, whenever an 'inner' ring does not touch the boundary of an outside area, also not in one point, it is an 'inner' ring (Isle). The areas A2 and A3 form a single Isle I1 located within area A1. The size of Isle I1 is substracted from the size of Area A1 when calculating the size of Area A1. Any centroids falling into Isle I1 are excluded when searching for a centroid that can be attached to Area A1. A1 above can be exported from GRASS as polygon A1 with inner ring I1.

Topology Example 4: 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:

|     .     |
|     .     |
|     .     |
|  x  .     |

----  road + boundary of one parcel => type boundary
....  road => type line
x     parcel centroid (identifies whole area)

Because lines are not used to build areas, we have only one area/centroid, instead of 4 which would be necessary in TIGER.

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.

Vector library spatial index management

Spatial index (based on R-tree) is generated 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):

int main
     //writing new vector

     Vect_close();  // memory is not released

In general it is possible to free the memory with Vect_set_release_support() such as:

int main
     // writing new vector

     Vect_close();  // memory is released

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:

int main
     // select features using spatial index, e.g.  Vect_select_lines_by_box()
     Vect_close();  // memory is released

     // do some processing which needs memory

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.

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

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 */

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.

Vector TINs

TINs are simply created as 2D/3D vector polygons consisting of 3 vertices. See Vect_tin_get_z().

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):

map[@mapset] layer table [key [database [driver]]]

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:

* 1 mytable id $GISDBASE/$LOCATION_NAME/$MAPSET/vector/$MAP dbf

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".


Similar as above but all dbf files are in one directory dbf/ in mapset and names of dbf files are $MAP.dbf

water* 1 rivers id /home/grass/dbf dbf
water* 2 lakes lakeid /home/guser/mydb
trans* 1 roads key basedb odbc
trans* 5 rails

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.

water@PERMANENT 1 myrivers id /home/guser/mydbf dbf

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:

river 1 river id water odbc
river.backup* 1 NONE

could be used to say that tables should not be copied for backups of map river because table is stored in a reliable RDBMS.

DGLib (Directed Graph Library)

The Directed Graph Library or DGLib (Micarelli 2002, Directed Graph Library , 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().

Vector ASCII Format Specifications

The ASCII format is (currently) explained in the manual page of, which is defined in the file:


Vector modules and their parameters/flags

See also grass5/documents/parameter_proposal.txt

A module is a GRASS command invoked by the user.

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.

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)

List of vector library functions

The Vect_*() functions are the programmer's API for GRASS vector programming.

Vector area functions

Vector array functions

Vector bounding box functions

Vector break lines functions

Vector break polygons functions

Vector bridges functions

Vector buffer functions

Vector build functions

Vector build (native) functions

Vector build (OGR) functions

Vector categories functions

Vector category index functions

(note: vector layer is historically called "field")

Vector clean nodes functions

Vector close functions

Vector constraint functions

Vector dangles functions

Vector dbcolumns functions

Vector error functions

Vector field functions

(note: vector layer is historically called "field")

Vector find functions

Vector graph functions

Vector header functions

Vector history functions

Vector header functions

Vector intersection functions

Vector valid map name functions

Vector level functions

Vector topological (level 2) functions

Vector feature functions

Vector list functions

Vector map functions

Vector network functions

Vector open functions

Vector overlay functions

Vector polygon functions

Vector read functions

Level 1 and 2

Level 2 only

Vector remove areas functions

Vector remove duplicates functions

Vector rewind functions

Vector select functions

Vector spatial index functions

Vector snap functions

Vector TIN functions

Vector type option functions

Vector delete functions

Level 2 only

Vector write functions

Level 1 and 2

Level 2 only


  • Radim Blazek (vector architecture) <radim.blazek>
  • Roberto Micarelli (DGLib) <>


  • Markus Metz
  • Martin Landa <landa.martin>


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.

See Also

Last change:

2011-12-22 14:24:20 -0800 (Thu, 22 Dec 2011)