GRASS and Python

From GRASS-Wiki
Revision as of 12:52, 10 June 2007 by Cmbarton (talk | contribs) (Writing python scripts in GRASS)

Jump to: navigation, search

(for discussions on the new GRASS GUI, see here)

Python SIGs

Python Special Interest Groups are focused collaborative efforts to develop, improve, or maintain specific Python resources. Each SIG has a charter, a coordinator, a mailing list, and a directory on the Python website. SIG membership is informal, defined by subscription to the SIG's mailing list. Anyone can join a SIG, and participate in the development discussions via the SIG's mailing list. Below is the list of currently active Python SIGs, with links to their resources.

See more at

Writing python scripts in GRASS

Python is between shell and C programs. For C part - it can handle GRASS C functions via SWIG. For shell part, it can be processed with g.parser, so automatic input check and help generation (apart from translation) can be processed.

Example of python script, which is processed by g.parser:


import sys
import os

#%  description: g.parser test script
#%  keywords: keyword1, keyword2
#%  key: f
#%  description: a flag
#% key: raster
#% type: string
#% gisprompt: old,cell,raster
#% description: raster input map
#% required : yes
#% key: vector
#% type: string
#% gisprompt: old,vector,vector
#% description: vector input map
#% required : yes
#% key: option1
#% type: string
#% description: an option
#% required : yes

def main(): 

    #add your code here
    print "" 

    if ( os.getenv("GIS_FLAG_f") != "0" ):
        print "Flag -f set"
        print "Flag -f not set"

    print "Value of GIS_OPT_option1: %s" % os.getenv("GIS_OPT_option1")
    print "Value of GIS_OPT_raster:  %s" % os.getenv("GIS_OPT_raster")
    print "Value of GIS_OPT_vect:    %s" % os.getenv("GIS_OPT_vect")

    #end of your code

if __name__ == "__main__":
    if ( len(sys.argv) <= 1 or sys.argv[1] != "@ARGS_PARSED@" ):
        os.execvp("g.parser", [sys.argv[0]] + sys.argv)



NOTE: Please improve this list!

Dear (new) GRASS Developer,

When submitting PYTHON SCRIPTS to GRASS SVN repository,
please take care of following rules:

[ see SUBMITTING for C code hints ]
[ see SUBMITTING_SCRIPTS for shell script hints ]
[ see SUBMITTING_TCLTK for TCL/TK script hints ]

1.  Indentation

    As Python determines nesting based upon indentation, it
    isn't just a stylistic issue.

    Please use 4-space indentation (GNU Emacs python-mode default).

2.  Add a header section to the script you submit and make sure you
    include the copyright. The purpose section is meant to contain a
    general over view of the code in the file to assist other programmers
    that will need to make changes to your code. For this purpose use
    Python Docstring.

    Example (fictitious header for a script called r.myscript):

MODULE: r.myscript

AUTHOR(S): Me <email AT some domain>

PURPOSE: Calculates univariate statistics from a GRASS raster map

COPYRIGHT: (C) 2007 by the GRASS Development Team

           This program is free software under the GNU General Public
           License (>=v2). Read the file COPYING that comes with GRASS
           for details.

   The copyright protects your rights according to GNU General Public
   License (

[please add further hints if required]

Python extensions for GRASS GIS

wxPython GUI development for GRASS

Python-SWIG-GRASS interface

There is a prototype GRASS-SWIG interface available (thanks to Sajith VK), find it in GRASS 6-CVS: swig/python/. Draft documentation is here. It now wraps both raster and vector data C functions plus the general GIS (G_*()) functions.

Background: SWIG (Simplified Wrapper and Interface Generator) is:

  • A compiler that turns ANSI C/C++ declarations into scripting language interfaces.
  • Completely automated (produces a fully working Python extension module).
  • Language neutral. SWIG can also target Tcl, Perl, Guile, MATLAB, etc...
  • Attempts to eliminate the tedium of writing extension modules.

Sample script for raster access (use within GRASS, Spearfish session):

import python_grass6 as g6lib

input = 'roads'
mapset = 'PERMANENT'

# initialize
infd = g6lib.G_open_cell_old(input, mapset)
cell = g6lib.G_allocate_cell_buf()

# the API still needs error checking to be added
while 1:
    myrow = g6lib.G_get_map_row_nomask(infd, cell, rown)
    print rown,myrow[0:10]
    rown = rown+1
    if rown==476:break


Sample script for vector access (use within GRASS, Spearfish session):

import python_grass6 as g6lib

input = 'soils'
mapset = 'PERMANENT'

# initialize

# define map structure
map = g6lib.Map_info()

# define open level (level 2: topology)
g6lib.Vect_set_open_level (2)

# open existing map
g6lib.Vect_open_old(map, input, mapset)

# query
print 'Vect is 3D: ', g6lib.Vect_is_3d (map)
print 'Vect DB links: ', g6lib.Vect_get_num_dblinks(map)
print 'Map Scale:  1:', g6lib.Vect_get_scale(map)

# close map

TODO: Implement modules support in a Python class using --interface-description and a Python-XML parser. This should be a generic class with module's name as parameter, returning back an object which describes the module (description, flags, parameters, status of not/required). See GRASS 6 wxPython interface for inspiration. Important is to auto-generate the GRASS-Python class at compile time with a Python script.

Python-GRASS add-ons

Stand-alone addons:

  1. Jáchym Čepický's, a GUI to typeset printable maps with (
  2. Jáchym Čepický's v.pydigit, a GUI to v.edit (
  3. Jáchym Čepický's PyWPS, GRASS-Web Processing Service (

Using Grass gui.tcl in python

Here is some example code to use the grass automatically generated guis in python code. This could (should) all be bundled up and abstracted away so that the implementation can be replaced later.

import Tkinter
import os

# Startup (once):

tk = Tkinter.Tk()
tk.eval ("wm withdraw .")
tk.eval ("source $env(GISBASE)/etc/gui.tcl")
# Here you could do various things to change what the gui does
# See gui.tcl and README.GUI

# Make a gui (per dialog)
# This sets up a window for the command.
# This can be different to integrate with tkinter:
tk.eval ('set path ".dialog$dlg"')
tk.eval ('toplevel .dialog$dlg')
# Load the code for this command:
fd = os.popen ("d.vect --tcltk")
gui =
# Run it
dlg = tk.eval('set dlg') # This is used later to get and set 

# Get the current command in the gui we just made:
currentcommand = tk.eval ("dialog_get_command " + dlg)

# Set the command in the dialog we just made:
tk.eval ("dialog_set_command " + dlg + " {d.vect map=roads}")



More Python tutorials for programmers


From FOSS4G2006: