Directory structure

Vector map is stored in a number of data files. Vector map directory structure and file names were changed in GRASS 6 with respect to previous GRASS versions. All vector files for one vector map are stored in one directory:

$MAPSET/vector/vector_name/

This directory contains these files:

coor - binary file, coordinates see former dig/ file
topo - binary file, topology see former dig_plus/ file
sidx - binary file, spatial index (see Sidx file format specification)
cidx - binary file, category index (see Cidx file format specification)
head - text file, header information see former part of dig/ file
dbln - text file, link(s) to attribute table(s) (see DB link file format specification)
hist - text file, vector map change history
frmt - text file, format description (external formats only)
fidx - binary file, feature index (OGR format only)

Header file format specification

The header contains meta information, a description of the vector map and many other information. The file is an unordered list of key/value entries. The key is a string separated from value by a colon and optional whitespace.

Keywords are:

ORGANIZATION - organization that digitized the data
DIGIT DATE - date the data was digitized
DIGIT NAME - person who digitized the data
MAP NAME - title of the original source map
MAP DATE - date of the original source map
MAP SCALE - scale of the original source map
OTHER INFO - other comments about the map
ZONE - zone of the map (e.g., UTM zone)
MAP THRESH - digitizing threshold

This information holds dig_head data structure.

DB link file format specification

Each vector maps has its own DBMI settings stored in the '$MAPSET/vector/vector_name/dbln' text file. For each pair vector map + layer, all of table, key column, database, driver must be defined in a new row. This definition must be written to '$MAPSET/vector/vector_name/dbln' text file. Each row in the 'dbln' file contains names separated by spaces in following order ([ ] - optional):

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, and $MAP may be used in table, key, database and driver names (function Vect_subst_var()). Note that $MAPSET is not the current mapset but mapset of the map the rule is defined for.

Note that vector features in GRASS vector maps may have attributes in different tables or may be without attributes. Boundaries form areas but it may happen that some boundaries are not closed (such boundaries would not appear in polygon layer). Boundaries may have attributes. All types may be mixed in one vector map.

The link to the table is permanent and it is stored in 'dbln' file in vector directory. Tables are considered to be a part of the vector and the command g.remove, for example, deletes linked tables of the vector. Attributes must be joined with geometry.

Information about database links holds dblinks data structure.

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

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

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 vector map i.e. in one vector map may be more features linked to more attribute tables. Definitions on first 2 rows are applied for example on maps water1, water2, ... so that more maps may share one table.

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 vector map from one database and write to some other and even with some other driver (should not be a problem).

There are open questions, however. For one, how does one distinguish when new tables should be written and when not? For example, definitions:

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.

Coor file format specification

In the coor file the following is stored: 'line' (element) type, number of attributes and layer number for each category. Coordinates in binary file are stored as double (8 bytes). See Coor_info data structure.

Header

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	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, GV_FACE, GV_KERNEL 4.-7. bit: reserved, not used
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