grass.osgeo.

org

GRASS GIS 8 Programmer's Manual

12-15 minutos

GRASS GIS (Geographic Resources Analysis Support System) is an

open source, free software Geographical Information System (GIS) with
raster, topological vector, image processing, and graphics production
functionality that operates on various platforms through a graphical user
interface (GUI) or command line interface (CLI). It is released under GNU
General Public License (GPL).

This manual introduces the reader to the Geographic Resources Analysis

Support System from the programming perspective. Design theory,
system support libraries, system maintenance, and system enhancement
are all presented. This work is part of ongoing research being performed
by the GRASS Development Team, an international team of
programmers, GRASS module authors are cited within their module's
source code and the contributed manual pages.

© 2000-2024 by the GRASS Development Team

This manual is published under GNU Free Documentation License

(GFDL), and comes with ABSOLUTELY NO WARRANTY. The
development of GRASS software and this manual is kindly supported by
the Open Source Geospatial Foundation, who provides the GRASS main
infrastructure.

Main web site: https://grass.osgeo.org

Note: Missing entries below still need to be documented in Doxygen

format.
 GRASS GIS Architecture

Libraries

Core libraries

(the name refers to the directory name in lib/ in the source code)

• gis: GRASS GIS General Library (aka GIS Library)

• raster: GRASS Raster Library

• vector: GRASS Vector Library

• Temporal GIS API: See https://grass.osgeo.org/grass-devel/manuals/

libpython/temporal_framework.html

Further libraries

(the name refers to the directory name in lib/ in the source code)

Display Libraries and Drivers

• display: GRASS Display Library (general display library)

• cairodriver: GRASS Cairo Display Driver

• driver: Graphics monitor driver

• htmldriver: htmldriverlib (HTML graphics driver)

• pngdriver: GRASS GIS PNG Display Driver Library

• psdriver: GRASS Postscript Display Driver Library

Math and Statistics Libraries

• arraystats: GRASS Array Statistics Library (library of statistics for arrays of

doubles)

• cdhc: GRASS testing normality & exponentiality Library

• gmath: GRASS Numerical math interface (generic mathematical

functions and BLAS/LAPACK library wrapper)

• gpde: GRASS Partial differential equations Library (GPDE)

Raster Libraries

• raster: GRASS Raster Library (2D raster library)

• raster3d: GRASS 3D Raster Volume Library (3D raster aka voxels or

volumes)

• rowio: GRASS Row Input/Output Library (library for reading/writing raster

rows)

• rst: GRASS Library for interpolation with regularized splines with tension
(library for interpolation with regularized splines with tension)

• segment: GRASS Segment Library (segment library for segmented raster

reading)

• stats: statslib (statistics library)

Imagery Libraries (image processing)

• cluster: GRASS Cluster analysis statistics Library (library for k-means
style of cluster analysis processing)

• imagery: GRASS Imagery Library (library for image processing)

Vector Libraries

• vector: GRASS Vector Library (architecture description)

• dglib: GRASS Directed Graph Library

• vedit: GRASS Vedit Library (vector editing library)

• neta: GRASS Network Analysis Library

• rtree: rtree.h (R search tree library)

Search tree libraries

• btree: btree.h

• btree2: btree2 library

• rtree: rtree.h (R search tree library)

Database Management Libraries

• db: GRASS DataBase Management Interface

OpenGL Libraries and friends

• ogsf: GRASS GIS OGSF Library (OpenGL (R) ported gsurf library
(required for NVIZ))

• nviz: GRASS Nviz Library (used by wxGUI Nviz extension and CLI-based
Nviz module)

Python API

• python: See GRASS GIS Python library (https://grass.osgeo.org/grass-

 devel/manuals/libpython/)

Projection Libraries

• proj: GRASS and the PROJ projection library (wrapper to PROJ4

projection library)

Miscellaneous Libraries

• datetime: datetime (DateTime library)

• external: Adding External Libraries (External libraries from other projects

such as shapelib, parson and CCMATH mathematics library source code)

• fonts: fonts (GRASS fonts library)

• init: Library Initialization (GRASS initialization code + scripts)

• iostream: iostream (fast I/O library)

• lidar: lidar.h (LiDAR data related library)

• linkm: linkm (linked list memory manager)

• manage: GRASS Data Elements Manage Library

• symbol: symbol (Drawing symbols for point vector data library)

Adding External Libraries

The following files must be added or updated when including a new

external library.

• add: lib/external/newlib

• add: lib/external/newlib/*.c

• add: lib/external/newlib/*.h

• add: lib/external/newlib/LICENSE

• add: lib/external/newlib/Makefile
• update: lib/external/Makefile

• update: lib/external/README.license

• update: lib/README.md

• update: include/Make/Install.make

• update: include/Make/Grass.make

• update: Makefile

File structure of GRASS Location

A GRASS raster map consists of several files in several subdirectories in

a mapset, organized as follows:

cellhd/
map header including projection code, coordinates representing the
spatial extent of the raster map, number of rows and columns,
resolution, and information about map compression;
cell/, fcell/ or grid3/
generic matrix of values in a compressed, portable format which
depends on the raster data type (integer, floating point or 3D grid);
hist/
history file which contains metadata such as the data source, the
command that was used to generate the raster map, or other
information provided by the user;
cats/
optional category file which contains text or numeric labels assigned
to the raster map categories;
colr/
optional color table;
cell_misc/
optional timestamp, range of values, quantization rules (for floating
point maps) and null (no-data) files;
A GRASS vector maps are stored in several separate files in a single
directory (see GRASS Vector Library). While the attributes are stored in
either a DBF file, a SQLite file or in an external DBMS (PostgreSQL,
MySQL, ODBC), the geometric data are saved as follows:

head
vector map ASCII header with information about the map creation
(date and name), its scale and threshold;
coor
binary geometry file which includes the coordinates of graphic
elements (primitives) that define the vector feature;
topo
binary topology file describes the spatial relationships between the
map's graphic elements;
hist
history ASCII file with complete commands that were used to create
the vector map, as well as the name and date/time of the map
creation;
cidx
binary category index file which is used to link the vector object IDs to
the attribute table rows;
dbln
ASCII file which contains definition(s) of link to attribute storage in
database (DBMS).
Diagram of GRASS file structure

Compiling and Installing GRASS Modules

GRASS modules are compiled and installed using the UNIX make
command, which reads a file named Makefile (see Multiple-
Architecture Conventions for more information) and then runs the
compiler. The GRASS compilation process allows for multiple-
architecture compilation from a single copy of the source code (for
instance, if the source code is NFS mounted to various machines with
differing architectures). This chapter assumes that the programmer is
familiar with make and its accompanying Makefile.

To compile enter following:

./configure
make
make install

Then the code will be compiled into "/usr/local/grass-7.x.y" directory. The

start script "grass7x" will be placed into "/usr/local/bin/".

Optionally other target directories can be specified while "configuring":

./configure --prefix=/opt/grass-7.x.y --with-bindir=/usr/bin

make
make install

This will store the GRASS binaries into the directory "/opt/grass-7.x.y" and
the script mentioned above into "/usr/bin".

The script "make" is required to compile single modules. The compilation

process and requirements are discussed in more detail now.
 Makefile Variables

Todo:
Update the list.

GRASS Libraries. The following variables name the various GRASS

libraries:

• GISLIB - This names the GIS Library, which is the principal GRASS
library. See GRASS GIS General Library (aka GIS Library) for details
about this library, and Loading the GIS Library for a sample Makefile
which loads this library.

• SEGMENTLIB - This names the Segment Library, which manages large

matrix data. See GRASS Segment Library for details about this library,
and Loading the Segment Library for a sample Makefile which loads this
library.

• RASTERLIB - This names the Raster Library, which is the principal

GRASS library for raster data access. See GRASS Raster Library for
details about this library, and Loading the Raster Library for a sample
Makefile which loads this library.

• VECTORLIB - This names the Vector Library, which is the principal

GRASS library for vector data access. See GRASS Vector Library for
details about this library, and Loading_the_Vector_Library for a sample
Makefile which loads this library.

• DISPLAYLIB - This names the Display Library, which communicates

with GRASS graphics drivers. See GRASS Display Library for details
about this library, and Loading_the_Display_Library for a sample Makefile
which loads this library.

UNIX Libraries: The following variables name some useful UNIX system
libraries:

• MATHLIB - This names the math library. It should be used instead of the -
 lm loader option.

Compiler and loader variables. The following variables are related to

compiling and loading C programs:

• EXTRA_CFLAGS - This variable can be used to add additional options to

$CFLAGS. It has no predefined values. It is usually used to specify
additional -I include directories, or -D preprocessor defines.

Constructing a Makefile

The complete syntax for a Makefile is discussed in the UNIX

documentation for make and will not be repeated here. The essential idea
is that a target (e.g. a GRASS module) is to be built from a list of
dependencies (e.g. object files, libraries, etc.). The relationship between
the target, its dependencies, and the rules for constructing the target is
expressed according to the following syntax:

target: dependencies

actions

more actions

If the target does not exist, or if any of the dependencies have a newer
date than the target (i.e., have changed), the actions will be executed to
build the target. The actions must be indented using a TAB. make is picky
about this. It does not like spaces in place of the TAB.

Multiple-Architecture Conventions

The following conventions allow for multiple architecture compilation on a

machine that uses a common or networked GRASS source code
directory tree.

Object files and library archives are compiled into subdirectories that
represent the architecture that they were compiled on. These
subdirectories are created in the $SRC directory as OBJ.arch and
 LIB.arch, where arch represents the architecture of the compiling
machine. Thus, for example, $SRC/OBJ.sun4 would contain the object
files for Sun/4 and SPARC architectures, and $SRC/LIB.686-pc-
linux-gnu would contain library archives for Linux architectures.
Likewise, $SRC/OBJ.686-pc-linux-gnu would contain the object
files for Linux architectures, and $SRC/LIB.686-pc-linux-gnu would
contain library archives for Linux architectures.

Note that 'arch' is defined for a specific architecture during setup and
compilation of GRASS, it is not limited to sun4 or any specific string.

Vector modules and their parameters/flags

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 GRASS GIS 5.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

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)

Parameters:

• 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 or name

• where condition of SQL statement for selection of records

• column column name (in external table)