EVOLUTION-MANAGER

Edit File: drv_grass.html

<html>
<head>
<title>GRASS Vector Format</title>
</head>

<h1>GRASS Vector Format</h1>

GRASS driver can read GRASS (version 6.0 and higher) vector maps.
Each GRASS vector map is represented as one datasource.  A GRASS
vector map may have 0, 1 or more layers.

<p>
GRASS points are represented as wkbPoint, lines and boundaries as
wkbLineString and areas as wkbPolygon. wkbMulti* and
wkbGeometryCollection are not used.  More feature types can be mixed
in one layer. If a layer contains only features of one type, it is set
appropriately and can be retrieved by OGRLayer::GetLayerDefn();

<p>
If a geometry has more categories of the same layer attached, its
represented as more features (one for each category).

<p>
Both 2D and 3D maps are supported.

<h2>Datasource name</h2>

Datasource name is full path to 'head' file in GRASS vector directory.
Using names of GRASS environment variables it can be expressed:
<pre>
   $GISDBASE/$LOCATION_NAME/$MAPSET/vector/mymap/head
</pre>
where 'mymap' is name of a vector map. For example:
<pre>
   /home/cimrman/grass_data/jizerky/jara/vector/liptakov/head
</pre>

<h2>Layer names</h2>

Usually layer numbers are used as layer names. Layer number 0 is used
for all features without any category. It is possible to optionally
give names to GRASS layers linked to database however currently this
is not supported by grass modules.  A layer name can be added in
'dbln' vector file as '/name' after layer number, for example to
original record:

<pre>
1 rivers cat $GISDBASE/$LOCATION_NAME/$MAPSET/dbf/ dbf
</pre>
it is possible to assign name 'rivers'
<pre>
1/rivers rivers cat $GISDBASE/$LOCATION_NAME/$MAPSET/dbf/ dbf
</pre>
the layer 1 will be listed is layer 'rivers'.

<h2>Attribute filter</h2>

If a layer has attributes stored in a database, the query is passed to
the underlying database driver. That means, that SQL conditions which
can be used depend on the driver and database to which the layer is
linked. For example, DBF driver has currently very limited set of SQL
expressions and PostgreSQL offers very rich set of SQL expressions.

<p>
If a layer has no attributes linked and it has only categories, OGR
internal SQL engine is used to evaluate the expression.  Category is
an integer number attached to geometry, it is sort of ID, but it is
not FID as more features in one layer can have the same category.

<p>
Evaluation is done once when the attribute filter is set.

<h2>Spatial filter</h2>

Bounding boxes of features stored in topology structure are used to
evaluate if a features matches current spatial filter.

<p>
Evaluation is done once when the spatial filter is set.

<h2>GISBASE</h2>

GISBASE is full path to the directory where GRASS is installed.  By
default, GRASS driver is using the path given to gdal configure
script.  A different directory can be forced by setting GISBASE
environment variable.  GISBASE is used to find GRASS database drivers.

<h2>Missing topology</h2>

GRASS driver can read GRASS vector files if topology is available (AKA
level 2).  If an error is reported, telling that the topology is not
available, it is necessary to build topology within GRASS using
v.build module.

<h2>Random access</h2>

If random access (GetFeature instead of GetNextFeature) is used on
layer with attributes, the reading of features can be quite slow. It
is because the driver has to query attributes by category for each
feature (to avoid using a lot of memory) and random access to database
is usually slow. This can be improved on GRASS side optimizing/writing
file based (DBF, SQLite) drivers.

<h2>Known problem</h2>

Because of bug in GRASS library, it is impossible to start/stop
database drivers in FIFO order and FILO order must be used. The GRASS
driver for OGR is written with this limit in mind and drivers are
always closed if not used and if a driver remains opened kill() is
used to terminate it.  It can happen however in rare cases, that the
driver will try to stop database driver which is not the last opened
and an application hangs.  This can happen if sequential read
(GetNextFeature) of a layer is not finished (reading is stopped before
last available feature is reached), features from another layer are
read and then the reading of the first layer is finished, because in
that case kill() is not used.

<ul>
<li> <a href="http://grass.osgeo.org">GRASS GIS home page</a><p>
</ul>

<hr>
Development of this driver was financially supported by Faunalia
(<a href="http://www.faunalia.it/">www.faunalia.it</a>).

</body>
</html>