From GRASS-Wiki
Revision as of 15:36, 27 January 2015 by Mlennert (talk | contribs) (beginning of section about GRASS modules as API)
Jump to navigation Jump to search

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"


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.

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 intput=raster_streams output=vector_streams type=line
v.buffer input=vector_streams output=stream_buffers distance=500

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". 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.

  • Easy to integrate into any language that allows system calls
    • Examples in Python, C, etc
  • "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


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