GRASS GIS APIs

Introduction to this document

GRASS GIS is in continues development and this development is what keeps GRASS GIS alive and at the forefront of GIS evolution. From users stringing together a series of modules to build a novel processing chain to developers implementing new cutting-edge algorithms in the core of the GRASS GIS C source code there are many different ways to develop with and for GRASS GIS. This document aims at clarifying the role of the different application programming interfaces (APIs) available. For each of the different APIs, it presents typical use cases and introduces the basic logic of the API. For more detailed information, please look at more detailed introduction on GRASS GIS and Development and GRASS GIS and Python as well as the programming manuals for the C and Python APIs.

GRASS GIS Modules as "functions"

WORK IN PROGRESS

GRASS in itself is not a monolithic application, but rather a collection of over 300 applications, called modules, following the Unix philosophy with the idea that each module does one thing and does it well, even if that thing is trivial, and that real power comes from combining these tools.

A consequence of this principle is that each module is autonomous in its functioning, including its memory management and error handling. In other words, as GRASS GIS is not a monolithic application, GRASS as such cannot crash, only individual modules can.

Module output in the form of new maps is automatically stored in the GRASS GIS Database and can thus be reused by follow-up modules. Other types of outputs can either be stored in temporary files to be read later by other modules or data can be communicated between modules via the standard streams, i.e. the standard output and input.

With this structure in mind, one can argue that GRASS GIS in itself is an application programming interface with each module playing the role of a "function". Chaining these functions thus allows any user to create an application of any level of desired complexity. The description of this API can be found in the module man pages or on the command line via the --help parameter.

Here is a simple example of such an application that extracts estimated stream locations from a digital elevation model, transforms them to vector format and the creates a 500m buffer around them:

g.region rast=elevation
r.watershed elevation=elevation threshold=10000 stream=raster_streams --o
r.to.vect intput=raster_streams output=vector_streams type=line --o
v.buffer input=vector_streams output=stream_buffers distance=500 --o

Just putting the above lines into one file that the operating system can read at the command line can already be considered "programming an application" and by just changing the name of the raster used as input the same program can be launched on different data. There are many advantages of creating such application instead of clicking through the different commands in a graphical user interface:

• archiving your work flow
• making your work flow easily reproducible
• being able to send your work flow to others

However, in this form one is limited to just chaining modules without any control flow such as conditional execution of repeated execution of certain parts of the code. It can, thus be interesting to embed the calls to GRASS GIS modules in a program written in a programming language. Many programming language allow system calls which enable the programmer to call the GRASS GIS modules while having at the same time all the functions of the language at hand.

Here are some examples of such system calls (using the first line of the above example) in different programming languages:

• Python

import os
os.system('g.region rast=elevation')

• C

void main()
 {
   system("g.region rast=elevation");
 }

• Perl

system "g.region rast=elevation";

These system calls are easy to handle when no output is expected from the GRASS module. When output needs to be collected then the programming task already becomes a little harder unless you know what you are doing. It is for this reason that the Python GRASS libraries where developed that are explained in the next section.

• "Graphical programming" through the model builder

The Python scripting library

• Some specific python functions to facilitate calling grass modules and capturing their output

Easy GUI creation in scripts

• Automatic GUI creation based on basic configuration of options

The PyGRASS API using ctypes

• Direct access to low-level C-functions (via ctypes).
• Direct access to data
• Allows writing of more complex Python programs than the scripting library

The C-API

• Core library is being developed for more than 30 years
• Different additional libraries added through time