GRASS GIS 8 Programmer's Manual
8.5.0dev(2024)-b4187339ee
|
by GRASS Development Team (https://grass.osgeo.org)
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:
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:
This information holds dig_head data structure.
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.
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.
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 |
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 |