- Generated on Fri Nov 22 2024 07:03:33 for GRASS GIS 8 Programmer's Manual by
1.9.1
|
GRASS GIS 8 Programmer's Manual
8.5.0dev(2024)-f63024f571
|
by GRASS Development Team (https://grass.osgeo.org)
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, kernels, and volumes), their spatial relations are also stored. In general, topological GIS requires a data structure where the common boundary between two adjacent areas is stored as a single boundary, simplifying vector data maintenance.
The GRASS 6/7 vector format is very similar to the previous GRASS 4.x (5.0/5.3) vector format.
This description covers the new GRASS 6/7 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 the external relational databases, and by new 3D capabilities. Besides internal file based storage the geometry may alternatively be stored in a PostGIS database (accessible via OGR interface). 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. All vector data accessed through the OGR interface have only pseudo-topology and only a limited subset of vector operations can be performed.
The current implementation includes:
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. Two consecutive x,y,z pairs define an arc segment. Nodes are created automatically for the two endpoints of an arc. The user specifies the type of input to GRASS; GRASS doesn't decide. GRASS supports feature type definition which allows for multiple types to co-exist in the same map. An area is defined by one or more boundaries that form a closed ring. A centroid is assigned to the area it is within/inside (geometrically). The category to which an area belongs is stored with the centroid. Such centroids are stored in the same binary 'coor' file with other primitives. Areas without centroids are from a user's perspective holes within another area, therefore not presented to a user as a real area, the equivalent of a polygon in Simple Feature Access. Each vector object may have none, one or more categories (cats). More categories can be distinguished by field number (field, called "layer" at user level). A vector object can also have multiple categories in the same layer, an example would be buffers where a single area might belong to multiple buffers of multiple buffered features. Single and multi-category support on module level is implemented. The z coordinate is optional and both 2D and 3D files may be written.
The following vector feature types (primitives) are defined by the vector library (and holds by the coor file; see also Feature types):
From vector feature types mentioned above are derived:
Note that all lines and boundaries can consist of multiple segments.
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 library to maintain correct topology of areas.
There are two levels of read access to the vector data:
The level of access is returned by Vect_open_old().
Example for sequential read access without topology:
Example for random read access with topology:
Example for working with areas (requires topology):
Note: Higher level of access are planned, so when checking success return codes for a particular level of access (when calling Vect_open_old() for example), the programmer should use >= instead of == for compatibility with future releases.
An existing vector map can be opened for reading by Vect_open_old(). A new vector map can be created (or open for writing) by Vect_open_new(). Vect_open_old() attempts to open a vector map at the highest possible level of access. It will return the number of the level at which the map was opened. Vect_open_new() always opens at level 1 only. If you require that a vector map be opened at a lower level (e.g. one), you can call the routine Vect_set_open_level(1); Vect_open_old() will then either open at level one or fail. If you instead require the highest level access possible, you should not use Vect_set_open_level(), but instead check the return value of Vect_open_old() to make sure it is greater than or equal to the lowest level at which you need access. This allows for future levels to work without need for module change.
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 (category '0' is allowed for OGR layers). Categories do not have to be continuous.
Information about categories holds line_cats data structure.
For a user-centric view about attribute management, see the explanations in the GRASS GIS Wiki.
The attribute data are stored in external database. Connection with the database is done through drivers based on GRASS DataBase Management Interface. 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).
Note: vector boundaries are (typically) handled without category since adjacent parcels might have two different categories which prevents from a unique assignment.
Feature types are defined in include/vect_dig_defines.h, see the list below:
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.
Updates for GRASS 7:
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. http://www.ing.unitn.it/~grass/conferences/GRASS2002/proceedings/proceedings/pdfs/Blazek_Radim.pdf
1.9.1