Grass Tutorial
<<< PreviousNext >>>

C-Programming

All important aspects of C programming for GRASS are described in the GRASS 5.0 Programmer's Manual (PDF, 2.3MB). This section shall just give an overview how GRASS modules are usually structured. Generally, it will be helpful to look at some of the (over 350) existing modules as examples for learning (you can browse the source code via the CVS web interface). Only an "open source" GIS such as GRASS offers these deep insights into the "heart" of a GIS. The general structure of the modules is always similar, each module is stored in a directory of the GRASS source code.

The current source code structure is as follows:[1]

GRASS GIS library (most relevant only):

html/

modules descriptions

src/CMD/

internal scripts for compilation

src/include/

header files

src/libes/

GIS library routines

src/display/devices/

display driver

src/fonts/

character fonts

src/front.end/

internal routines for the interactive mode of modules

Modules (standard tree):

src/display/

modules for displaying maps on the GRASS monitor

src/general/

file management modules

src/imagery/

image processing modules

src/mapdev/

vector modules

src/misc/

miscellaneous modules

src/paint/

paint driver (PPM)

src/ps.map/

postscript driver

src/raster/

raster modules

src/scripts/

scripts

src/sites/

point modules

src/tcltkgrass/

Tcl/Tk GUI

Other modules:

src.contrib/

contributions of various institutions (however, many are in standard tree as well)

src.garden/

modules with linked simulation models and various interfaces

The existing GRASS modules are built upon the "GRASS programming library" which offers a multitude of GIS functions. It is structured as follows (square brackets contain the typical function name prefixes for the respective library routines):

GIS library:

database routines (GRASS file management), memory management, parser (string analysis), projections, etc. [G_]

vector library:

management of area, line, and site vectors [Vect_, V2_, dig_]

raster library:

raster data management [R_]

site data library:

site data management [G_sites_]

display library:

graphical output to the monitor [D_]

driver library:

printer driver

image data library:

image processing file management [I_]

segment library:

segmented data management [segment_]

vask library:

control of cursor keys etc. [V_]

rowio library:

for parallel row analysis of raster data [rowio_]

Some of the routines offered are quite substantial. For example they allow calculating geodesic distances out of given coordinate points, others perform queries on vector areas (e.g.: point-in-polygon tests).

Modules consist of the C program files (*.c), the header files (*.h) and a Gmakefile. GRASS has its own "make" routine: gmake5. The file Gmakefile contains instructions concerning the files to be compiled and the libraries to be used (GRASS and UNIX libraries). It has a specific pattern that must be respected. A simple example (important: indents with tab, not with space!) shall demonstrate the typical structure.[2]

The line "\$(HOME)/\$(PGM)..." and the next contain the compiler instructions, above this section the variables are set. Variables not set here are defined automatically in

grass5/src/CMD/head/head.$ARCH

where $ARCH is the name of the system architecture. Starting from GRASS 5.0 this "head" file is created automatically for the used computer platform by the "configure" script, which has to be run before the first compilation. The $(HOME) variable indicates where the binary file (i.e. the module) will be copied to: in this example it is the standard path for modules that offer command line support (no limitation to interactive only usage): grass5/etc/bin/cmd/.

The actual C program should be divided by (sub-)functionality into several files which have to be listed respectively in the list of objects in the Gmakefile. For details please refer to the "GRASS Programmer's manual" as this book cannot cover a full C programming tutorial. GRASS GIS library commands can be used directly in the source code. Interactive parameter querying is made possible by GRASS-specific parameter programming. Here is a short example of a raster module.

The calculation is done row and column wise (see "for" loop). As denoted above, it is advisable to divide the entire module into individual, thematically organized files in order to facilitate program maintenance.

Notes

[1]

This will change with new versions of GRASS in an effort to put more common routines into libraries and with the integration of a completely new vector engine (see the GRASS 5.7 programmer's manual).

[2]

The code example links in this chapter go to M. Neteler, H. Mitasova, 2002. Open Source GIS: A GRASS GIS Approach.

<<< PreviousHomeNext >>>
Scripting GRASSUpSpecial Topics