GRASS-Wiki - User contributions [en]

GRASS and Python

2010-03-05T16:49:09Z

⚠️Sonja:

''(for discussions on the new GRASS GUI, see [[GRASS GUI|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 http://www.python.org/community/sigs/

==Writing Python scripts in GRASS==

Python is a programming language which is more powerful than shell scripting but easier and more forgiving than C.
The Python script can contain simple module description definitions which will be processed with {{cmd|g.parser}}, as shown in the example below. In this way with no extra coding a GUI can be built, inputs checked, and a skeleton help page can be generated automatically. In addition it adds links to the GRASS message translation system.
For code which needs access to the power of C, you can access the GRASS C library functions via the SWIG interface.

* GRASS Python interface to library functions: http://download.osgeo.org/grass/grass6_progman/swig/
* GRASS Python scripting library: http://download.osgeo.org/grass/grass6_progman/pythonlib.html

Code style: Have a look at [http://trac.osgeo.org/grass/browser/grass/trunk/SUBMITTING_PYTHON SUBMITTING_PYTHON].

=== Creating Python scripts that run in GRASS under MS-Windows ===

The environment variables have to be set as follows:
GISBASE= C:\GRASS-64
GISRC= C:\Documents and Settings\user\.grassrc6
LD_LIBRARY_PATH= C:\GRASS-64\lib
PATH= C:\GRASS-64\etc;C:\GRASS-64\etc\python;C:\GRASS-64\lib;C:\GRASS-64\bin;C:\GRASS-64\extralib;C:\GRASS-64\msys\bin;C:\Python26;
PYTHONLIB= C:\Python26
PYTHONPATH= C:\GRASS-64\etc\python
GRASS_SH= C:\GRASS-64\msys\bin\sh.exe

Some hints:

# The Python interpreter (python.exe) needs to be in the PATH
# Python needs to be associated with the .py extension
# PATHEXT needs to include .py if you want to be able to omit the extension
# PYTHONPATH needs to be set to %WINGISBASE%\etc\python

1-3 should be taken care of by the Python installer. 4 needs to be done by the startup (currently, this doesn't appear to be the case on MS-Windows).

=== Running external commands from Python ===
For information on running external commands from Python, see:
http://docs.python.org/lib/module-subprocess.html

Avoid using the older os.* functions. Section 17.1.3 lists equivalents
using the Popen() interface, which is more robust (particularly on
Windows).

=== Examples ===

==== Display example ====
Example of Python script, which is processed by g.parser:

<source lang="python">
#!/usr/bin/env python
#
############################################################################
#
# MODULE: d.shadedmap
# AUTHOR(S): Unknown; updated to GRASS 5.7 by Michael Barton
# Converted to Python by Glynn Clements
# PURPOSE: Uses d.his to drape a color raster over a shaded relief map
# COPYRIGHT: (C) 2004,2008,2009 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.
#
#############################################################################

#%Module
#% description: Drapes a color raster over a shaded relief map using d.his
#%End
#%option
#% key: reliefmap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of shaded relief or aspect map
#% required : yes
#%end
#%option
#% key: drapemap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of raster to drape over relief map
#% required : yes
#%end
#%option
#% key: brighten
#% type: integer
#% description: Percent to brighten
#% options: -99-99
#% answer: 0
#%end

import sys
from grass.script import core as grass

def main():
drape_map = options['drapemap']
relief_map = options['reliefmap']
brighten = options['brighten']
ret = grass.run_command("d.his", h_map = drape_map, i_map = relief_map, brighten = brighten)
sys.exit(ret)

if __name__ == "__main__":
options, flags = grass.parser()
main()
</source>

==== Example for embedding r.mapcalc (map algebra) ====

grass.mapcalc() accepts a template string followed by keyword
arguments for the substitutions, e.g. (code snippets):

<source lang="python">
grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = options['output'],
rast1 = options['raster1'],
rast2 = options['raster2'])
</source>

''Best practice'': first copy all of the options[] into separate variables at the beginning of main(), i.e.:

<source lang="python">
def main():
output = options['output']
raster1 = options['raster1']
raster2 = options['raster2']

...

grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = output,
rast1 = raster1,
rast2 = raster2)
</source>

==Python extensions for GRASS GIS==
=== wxPython GUI development for GRASS ===

* See the [[GRASS GUI]] wiki page

=== GRASS Python library ===

See [http://download.osgeo.org/grass/grass6_progman/pythonlib.html GRASS Python library]

==== Interfacing with NumPy ====

''Glynn writes:''

The grass.script.array module defines a class "array" which is a
subclass of numpy.memmap with .read() and .write() methods to
read/write the underlying file via r.out.bin/r.in.bin.

Example:

<source lang="python">
import grass.script.array as garray
a = garray.array()
a.read("elevation.dem")
b = garray.array()
b[...] = (a / 50).astype(int) * 50 # or whatever
b.write("elev.50m")
</source>

The size of the array is taken from the current region.

The main drawback of using numpy is that you're limited by available
memory. Using a subclass of numpy.memmap lets you use files which may
be much larger, but processing the entire array in one go is likely to
produce in-memory results of a similar size.

One may also use the scipy matlab interface:

### SH: in GRASS ###
r.out.mat input=elevation output=elev.mat

<source lang="python">
### PY ###
import scipy.io as sio
# load data
elev = sio.loadmat('elev.mat')
# retrive the actual array. the data set contains also the spatial reference
elev.get('map_data')
data = elev.get('map_data')
# a first simple plot
import pylab
pylab.plot(data)
pylab.show()
# the contour plot
pylab.contour(data)
# obviously data needs to ne reversed
import numpy as np
data_rev = data[::-1]
pylab.contour(data_rev)
# => this is a quick plot. basemap mapping may provide a nicer map!
#######
</source>

=== 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 [http://download.osgeo.org/grass/grass6_progman/swig/ here]. It now wraps both raster and vector data C functions plus the general GIS (G_*()) functions.

Background: [http://www.swig.org 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 (try PyLab+Matplotlib from python), etc...
* Attempts to eliminate the tedium of writing extension modules.

==== Python-SWIG examples ====

* Latest and greatest: [[http://trac.osgeo.org/grass/browser/grass/trunk/scripts GRASS 7 Python scripts]]

* [[PythonSwigExamples|More complicated examples]]

Sample script for GRASS 6 raster access (use within GRASS, Spearfish session):
<source lang="python">
#!/usr/bin/env python

import os, sys
from grass.lib import grass

if "GISBASE" not in os.environ:
print "You must be in GRASS GIS to run this program."
sys.exit(1)

if len(sys.argv)==2:
input = sys.argv[1]
else:
input = raw_input("Raster Map Name? ")

# initialize
grass.G_gisinit('')

# find map in search path
mapset = grass.G_find_cell2(input, '')

# determine the inputmap type (CELL/FCELL/DCELL) */
data_type = grass.G_raster_map_type(input, mapset)

infd = grass.G_open_cell_old(input, mapset)
inrast = grass.G_allocate_raster_buf(data_type)

rown = 0
while True:
myrow = grass.G_get_raster_row(infd, inrast, rown, data_type)
print rown, myrow[0:10]
rown += 1
if rown == 476:
break

grass.G_close_cell(inrast)
grass.G_free(cell)
</source>

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

<source lang="python">
#!/usr/bin/python

# run within GRASS Spearfish session
# run this before starting python to append module search path:
# export PYTHONPATH=/usr/src/grass70/swig/python
# check with "import sys; sys.path"
# or:
# sys.path.append("/usr/src/grass70/swig/python")
# FIXME: install the grass bindings in $GISBASE/lib/ ?

import os, sys
from grass.lib import grass
from grass.lib import vector as grassvect

if "GISBASE" not in os.environ:
print "You must be in GRASS GIS to run this program."
sys.exit(1)

if len(sys.argv)==2:
input = sys.argv[1]
else:
input = raw_input("Vector Map Name? ")

# initialize
grass.G_gisinit('')

# find map in search path
mapset = grass.G_find_vector2(input,'')

# define map structure
map = grassvect.Map_info()

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

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

# query
print 'Vect map: ', input
print 'Vect is 3D: ', grassvect.Vect_is_3d (map)
print 'Vect DB links: ', grassvect.Vect_get_num_dblinks(map)
print 'Map Scale: 1:', grassvect.Vect_get_scale(map)
print 'Number of areas:', grassvect.Vect_get_num_areas(map)

# close map
grassvect.Vect_close(map)
</source>

==== 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 [http://trac.osgeo.org/grass/browser/grass/trunk/gui/wxpython/ 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:

# Jáchym Čepický's G-ps.map, a GUI to typeset printable maps with ps.map (http://193.84.38.2/~jachym/index.py?cat=gpsmap)
# Jáchym Čepický's v.pydigit, a GUI to v.edit (http://les-ejk.cz/?cat=vpydigit)
# Jáchym Čepický's PyWPS, GRASS-Web Processing Service (http://pywps.wald.intevation.org)

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

<source lang="python">
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 = fd.read()
# Run it
tk.eval(gui)
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}")
</source>

== Links ==

=== General guides ===

* [http://en.wikibooks.org/wiki/Python_Programming/ Wikibook Python Programming]
* [http://www.poromenos.org/tutorials/python Quick Python tutorial] for programmers of other languages
: [http://wiki.python.org/moin/BeginnersGuide/Programmers More Python tutorials] for programmers
* [http://www.python.org/dev/peps/pep-0008/ Python programming style guide]

=== Programming ===

* Python and GRASS:
** GRASS Python interface to library functions: http://download.osgeo.org/grass/grass6_progman/swig/ based on SWIG http://www.swig.org/
** GRASS Python scripting library: http://download.osgeo.org/grass/grass6_progman/pythonlib.html
** PyWPS, GRASS-Web Processing Service http://pywps.wald.intevation.org

* Python and OSGeo:
** [http://wiki.osgeo.org/wiki/OSGeo_Python_Library OSGeo Python Library]

* Python and GDAL/OGR:
** [http://mapserver.gis.umn.edu/community/conferences/MUM3/workshop/python Open Source Python GIS Hacks Mum'03]
** http://hobu.biz/software/OSGIS_Hacks - Python OSGIS Hacks '05
** http://zcologia.com/news/categorylist_html?cat_id=8
** http://www.perrygeo.net/wordpress/?p=4

* Python bindings to PROJ:
** http://www.cdc.noaa.gov/people/jeffrey.s.whitaker/python/pyproj.html

* Python and GIS:
** [http://gispython.org/ Open Source GIS-Python Laboratory]

* Python and Statistics:
** [http://rpy.sourceforge.net/ RPy] - Python interface to the R-statistics programming language

* Bindings:
** SIP (C/C++ bindings generator) http://directory.fsf.org/all/Python-SIP.html
** [http://www.cython.org/ Cython] - C-Extensions for Python (compile where speed is needed)

* Other external projects
** [http://www.scipy.org Scientific Python]
** [http://wiki.python.org/moin/NumericAndScientific Numeric and Scientific]
** [http://w3.pppl.gov/~hammett/comp/python/python.html Info on Python for Scientific Applications]

=== Presentations ===

From FOSS4G2006:
* [http://www.foss4g2006.org/materialDisplay.py?contribId=136&sessionId=48&materialId=slides&confId=1 A Python sweeps in the GRASS] - A. Frigeri 2006
* [http://www.foss4g2006.org/materialDisplay.py?contribId=67&sessionId=48&materialId=slides&confId=1 GRASS goes web: PyWPS] - J. Cepicky 2006

[[Category:Development]]
[[Category:Linking to other languages]]
[[Category:Python]]

GRASS and Python

2010-03-05T16:47:42Z

⚠️Sonja:

''(for discussions on the new GRASS GUI, see [[GRASS GUI|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 http://www.python.org/community/sigs/

==Writing Python scripts in GRASS==

Python is a programming language which is more powerful than shell scripting but easier and more forgiving than C.
The Python script can contain simple module description definitions which will be processed with {{cmd|g.parser}}, as shown in the example below. In this way with no extra coding a GUI can be built, inputs checked, and a skeleton help page can be generated automatically. In addition it adds links to the GRASS message translation system.
For code which needs access to the power of C, you can access the GRASS C library functions via the SWIG interface.

* GRASS Python interface to library functions: http://download.osgeo.org/grass/grass6_progman/swig/
* GRASS Python scripting library: http://download.osgeo.org/grass/grass6_progman/pythonlib.html

Code style: Have a look at [http://trac.osgeo.org/grass/browser/grass/trunk/SUBMITTING_PYTHON SUBMITTING_PYTHON].

=== Creating Python scripts that run in GRASS under MS-Windows ===

The environment variables have to be set as follows:
GISBASE= C:\GRASS-64
GISRC= C:\Documents and Settings\user\.grassrc6
LD_LIBRARY_PATH= C:\GRASS-64\lib
PATH= C:\GRASS-64\etc;C:\GRASS-64\etc\python;C:\GRASS-64\lib;C:\GRASS-64\bin;C:\GRASS-64\extralib;C:\GRASS-4-SVN\msys\bin;C:\Python26;
PYTHONLIB= C:\Python26
PYTHONPATH= C:\GRASS-64\etc\python
GRASS_SH= C:\GRASS-4-SVN\msys\bin\sh.exe

Some hints:

# The Python interpreter (python.exe) needs to be in the PATH
# Python needs to be associated with the .py extension
# PATHEXT needs to include .py if you want to be able to omit the extension
# PYTHONPATH needs to be set to %WINGISBASE%\etc\python

1-3 should be taken care of by the Python installer. 4 needs to be done by the startup (currently, this doesn't appear to be the case on MS-Windows).

=== Running external commands from Python ===
For information on running external commands from Python, see:
http://docs.python.org/lib/module-subprocess.html

Avoid using the older os.* functions. Section 17.1.3 lists equivalents
using the Popen() interface, which is more robust (particularly on
Windows).

=== Examples ===

==== Display example ====
Example of Python script, which is processed by g.parser:

<source lang="python">
#!/usr/bin/env python
#
############################################################################
#
# MODULE: d.shadedmap
# AUTHOR(S): Unknown; updated to GRASS 5.7 by Michael Barton
# Converted to Python by Glynn Clements
# PURPOSE: Uses d.his to drape a color raster over a shaded relief map
# COPYRIGHT: (C) 2004,2008,2009 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.
#
#############################################################################

#%Module
#% description: Drapes a color raster over a shaded relief map using d.his
#%End
#%option
#% key: reliefmap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of shaded relief or aspect map
#% required : yes
#%end
#%option
#% key: drapemap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of raster to drape over relief map
#% required : yes
#%end
#%option
#% key: brighten
#% type: integer
#% description: Percent to brighten
#% options: -99-99
#% answer: 0
#%end

import sys
from grass.script import core as grass

def main():
drape_map = options['drapemap']
relief_map = options['reliefmap']
brighten = options['brighten']
ret = grass.run_command("d.his", h_map = drape_map, i_map = relief_map, brighten = brighten)
sys.exit(ret)

if __name__ == "__main__":
options, flags = grass.parser()
main()
</source>

==== Example for embedding r.mapcalc (map algebra) ====

grass.mapcalc() accepts a template string followed by keyword
arguments for the substitutions, e.g. (code snippets):

<source lang="python">
grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = options['output'],
rast1 = options['raster1'],
rast2 = options['raster2'])
</source>

''Best practice'': first copy all of the options[] into separate variables at the beginning of main(), i.e.:

<source lang="python">
def main():
output = options['output']
raster1 = options['raster1']
raster2 = options['raster2']

...

grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = output,
rast1 = raster1,
rast2 = raster2)
</source>

==Python extensions for GRASS GIS==
=== wxPython GUI development for GRASS ===

* See the [[GRASS GUI]] wiki page

=== GRASS Python library ===

See [http://download.osgeo.org/grass/grass6_progman/pythonlib.html GRASS Python library]

==== Interfacing with NumPy ====

''Glynn writes:''

The grass.script.array module defines a class "array" which is a
subclass of numpy.memmap with .read() and .write() methods to
read/write the underlying file via r.out.bin/r.in.bin.

Example:

<source lang="python">
import grass.script.array as garray
a = garray.array()
a.read("elevation.dem")
b = garray.array()
b[...] = (a / 50).astype(int) * 50 # or whatever
b.write("elev.50m")
</source>

The size of the array is taken from the current region.

The main drawback of using numpy is that you're limited by available
memory. Using a subclass of numpy.memmap lets you use files which may
be much larger, but processing the entire array in one go is likely to
produce in-memory results of a similar size.

One may also use the scipy matlab interface:

### SH: in GRASS ###
r.out.mat input=elevation output=elev.mat

<source lang="python">
### PY ###
import scipy.io as sio
# load data
elev = sio.loadmat('elev.mat')
# retrive the actual array. the data set contains also the spatial reference
elev.get('map_data')
data = elev.get('map_data')
# a first simple plot
import pylab
pylab.plot(data)
pylab.show()
# the contour plot
pylab.contour(data)
# obviously data needs to ne reversed
import numpy as np
data_rev = data[::-1]
pylab.contour(data_rev)
# => this is a quick plot. basemap mapping may provide a nicer map!
#######
</source>

=== 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 [http://download.osgeo.org/grass/grass6_progman/swig/ here]. It now wraps both raster and vector data C functions plus the general GIS (G_*()) functions.

Background: [http://www.swig.org 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 (try PyLab+Matplotlib from python), etc...
* Attempts to eliminate the tedium of writing extension modules.

==== Python-SWIG examples ====

* Latest and greatest: [[http://trac.osgeo.org/grass/browser/grass/trunk/scripts GRASS 7 Python scripts]]

* [[PythonSwigExamples|More complicated examples]]

Sample script for GRASS 6 raster access (use within GRASS, Spearfish session):
<source lang="python">
#!/usr/bin/env python

import os, sys
from grass.lib import grass

if "GISBASE" not in os.environ:
print "You must be in GRASS GIS to run this program."
sys.exit(1)

if len(sys.argv)==2:
input = sys.argv[1]
else:
input = raw_input("Raster Map Name? ")

# initialize
grass.G_gisinit('')

# find map in search path
mapset = grass.G_find_cell2(input, '')

# determine the inputmap type (CELL/FCELL/DCELL) */
data_type = grass.G_raster_map_type(input, mapset)

infd = grass.G_open_cell_old(input, mapset)
inrast = grass.G_allocate_raster_buf(data_type)

rown = 0
while True:
myrow = grass.G_get_raster_row(infd, inrast, rown, data_type)
print rown, myrow[0:10]
rown += 1
if rown == 476:
break

grass.G_close_cell(inrast)
grass.G_free(cell)
</source>

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

<source lang="python">
#!/usr/bin/python

# run within GRASS Spearfish session
# run this before starting python to append module search path:
# export PYTHONPATH=/usr/src/grass70/swig/python
# check with "import sys; sys.path"
# or:
# sys.path.append("/usr/src/grass70/swig/python")
# FIXME: install the grass bindings in $GISBASE/lib/ ?

import os, sys
from grass.lib import grass
from grass.lib import vector as grassvect

if "GISBASE" not in os.environ:
print "You must be in GRASS GIS to run this program."
sys.exit(1)

if len(sys.argv)==2:
input = sys.argv[1]
else:
input = raw_input("Vector Map Name? ")

# initialize
grass.G_gisinit('')

# find map in search path
mapset = grass.G_find_vector2(input,'')

# define map structure
map = grassvect.Map_info()

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

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

# query
print 'Vect map: ', input
print 'Vect is 3D: ', grassvect.Vect_is_3d (map)
print 'Vect DB links: ', grassvect.Vect_get_num_dblinks(map)
print 'Map Scale: 1:', grassvect.Vect_get_scale(map)
print 'Number of areas:', grassvect.Vect_get_num_areas(map)

# close map
grassvect.Vect_close(map)
</source>

==== 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 [http://trac.osgeo.org/grass/browser/grass/trunk/gui/wxpython/ 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:

# Jáchym Čepický's G-ps.map, a GUI to typeset printable maps with ps.map (http://193.84.38.2/~jachym/index.py?cat=gpsmap)
# Jáchym Čepický's v.pydigit, a GUI to v.edit (http://les-ejk.cz/?cat=vpydigit)
# Jáchym Čepický's PyWPS, GRASS-Web Processing Service (http://pywps.wald.intevation.org)

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

<source lang="python">
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 = fd.read()
# Run it
tk.eval(gui)
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}")
</source>

== Links ==

=== General guides ===

* [http://en.wikibooks.org/wiki/Python_Programming/ Wikibook Python Programming]
* [http://www.poromenos.org/tutorials/python Quick Python tutorial] for programmers of other languages
: [http://wiki.python.org/moin/BeginnersGuide/Programmers More Python tutorials] for programmers
* [http://www.python.org/dev/peps/pep-0008/ Python programming style guide]

=== Programming ===

* Python and GRASS:
** GRASS Python interface to library functions: http://download.osgeo.org/grass/grass6_progman/swig/ based on SWIG http://www.swig.org/
** GRASS Python scripting library: http://download.osgeo.org/grass/grass6_progman/pythonlib.html
** PyWPS, GRASS-Web Processing Service http://pywps.wald.intevation.org

* Python and OSGeo:
** [http://wiki.osgeo.org/wiki/OSGeo_Python_Library OSGeo Python Library]

* Python and GDAL/OGR:
** [http://mapserver.gis.umn.edu/community/conferences/MUM3/workshop/python Open Source Python GIS Hacks Mum'03]
** http://hobu.biz/software/OSGIS_Hacks - Python OSGIS Hacks '05
** http://zcologia.com/news/categorylist_html?cat_id=8
** http://www.perrygeo.net/wordpress/?p=4

* Python bindings to PROJ:
** http://www.cdc.noaa.gov/people/jeffrey.s.whitaker/python/pyproj.html

* Python and GIS:
** [http://gispython.org/ Open Source GIS-Python Laboratory]

* Python and Statistics:
** [http://rpy.sourceforge.net/ RPy] - Python interface to the R-statistics programming language

* Bindings:
** SIP (C/C++ bindings generator) http://directory.fsf.org/all/Python-SIP.html
** [http://www.cython.org/ Cython] - C-Extensions for Python (compile where speed is needed)

* Other external projects
** [http://www.scipy.org Scientific Python]
** [http://wiki.python.org/moin/NumericAndScientific Numeric and Scientific]
** [http://w3.pppl.gov/~hammett/comp/python/python.html Info on Python for Scientific Applications]

=== Presentations ===

From FOSS4G2006:
* [http://www.foss4g2006.org/materialDisplay.py?contribId=136&sessionId=48&materialId=slides&confId=1 A Python sweeps in the GRASS] - A. Frigeri 2006
* [http://www.foss4g2006.org/materialDisplay.py?contribId=67&sessionId=48&materialId=slides&confId=1 GRASS goes web: PyWPS] - J. Cepicky 2006

[[Category:Development]]
[[Category:Linking to other languages]]
[[Category:Python]]

Using Eclipse to develop GRASS Python programs

2010-03-05T15:56:25Z

⚠️Sonja:

= How to use Eclipse to develop Python scripts that access GRASS object =

Recent releases of GRASS have emphasized the use of Python as the language of choice for developing scripts which access GRASS objects and can be used to automate operations without GRASS running.

This short tutorial shows how to set up a complete development environment using the Eclipse IDE to develop, debug and run Python programs that access GRASS objects. These instructions apply to MS-Windows and Linux, and probably Mac as well, since all the packages required are open source software which runs on all three platforms.

Please note that this is not an Eclipse, nor a Python, nor a GRASS tutorial. It is just a description on how to get all the above to work together. It assumes some (but not much, because I don't have much!) knowledge of all the above.

=== Prerequisites (Release versions are as at the time of writing) ===

* GRASS 6.4 and Python 2.6.x
* Eclipse 3.4.x
* Pydev 1.4.5 Eclipse plug-in for Python
* Optionally, other plugins for Eclipse

==== GRASS 6.4.0RC5 and Python 2.6.x ====

Many Linux distributions already include GRASS in their packaging but you must ensure you download the latest GRASS 6.4.0 release for Linux, MS-Windows, and Mac, available in binary (executable) from the GRASS {{website|download|download site}}, and install it as instructed for your platform. On Windows install the stand-alone WinGRASS and not the OSGeo4W GRASS version. You will also need to download Python 2.6 for your platform from the [http://www.python.org Python.org site] and install it as required for your platform making a note of where the python executable (python.exe in MS-Windows) is installed. Most recent Linux already come with Python 2.6.2 installed.

==== Eclipse ====

Eclipse 3.4.2 is the minimum version recommended, but other releases could work as well. Download it from [http://www.eclipse.org the Eclipse download page]. The Ganymede 3.4.2 release for Java developers is fine (85MB). Installing Eclipse is very easy because installations consists simply of unpacking the download package in a directory of your choice.
To avoid permission problems in Linux, install Eclipse in your Home directory or a subdirectory.

==== Pydev ====
Pydev is an Eclipse plugin that adapts the Eclipse platform to the specific needs of Python program development, debugging and testing. It is not the only Python plugin available, but the one largely recommended.
The current release is 1.4.5 and to install it you should use the Eclipse Update Manager mechanism, as detailed below.

Open the Eclipse platform and click on the Help → Software Updates menu entry, click on the Available Software tab and click on the Add Site button. This will open a dialog box where you insert the following URL: http://pydev.org/updates/ . Then press OK and follow the instructions. This will result in the Pydev plug-in being automatically downloaded. Click on the install button to install it among your other Eclipse plug-ins. Furthermore it will automatically inform you in future when new updates are available. The Home page for Pydev is: http://pydev.org/ .
At this point you have all the software pre-requisites installed, ready for the next step.

==== Creating a new project ====

When you first open the Eclipse platform after a new installation you will be asked to set-up a workspace, which will normally be in your home directory by default, then you will see a Welcome screen with various buttons. Click on the one that opens the Eclipse workspace, which will be empty and probably be Java oriented.
To change it to be Python oriented you must open what in Eclipse is called a "perspective", which is a combination of views and windows which suits the plug-in you are actually using at any one time. So, go to the Window → Open Perspective sub-menu and select Pydev. This will open the Pydev perspective where most of your development work will be done, and since new development starts with a new Project, now go to the File → New menu and select Pydev Project, and follow the prompts to create a new empty Python project which we will name Myproject.

==== Configuring Eclipse and Pydev ====

Eclipse is highly configurable, but for our purpose we will only look at the configuration required for Python use.
There are three preferences menus you should know, the Window (or Eclipse) Preferences menu, the Project Properties menu, and the Run or Debug Configuration menu, but for our needs we will just look at Window and Run Configuration.

Open the Window → Preferences menu, expand the Pydev entry and select Interpreter - Python. Sometime Eclipse can automatically detect the location of your Python interpreter, in which case it will appear in the top right box: but if it didn't simply add it via the New button (remember you made a note of its location earlier on!).
In the bottom box add the following New Folders to the ones automatically added by Eclipse, and which point to the GRASS libraries (in Mac(?) they will be located within the GRASS installation directory tree):

Linux:
/usr/lib/grass64/etc
/usr/lib/grass64/etc/python
/usr/lib/grass64/bin
/usr/lib/grass64/scripts

Windows:
C:\GRASS-64\etc
C:\GRASS-64\etc\python
C:\GRASS-64\bin

then press Apply and OK. Finally go to the Run Configurations menu and create a new entry for test.py as follows:

* Click on Python Run, then click on the New configuration icon, the first at the top. Provide a Name, Project and Module names either manually or by browsing and press Apply to create the new configuration.

* Click on the Environment tab and enter the following variables and values, keeping in mind that as shown they reflect my configuration.When you start GRASS it sets most of these variables but since you now want to run programs without GRASS itself running, you will have to set them yourself and find the equivalent locations for your specific configuration. If you have trouble do the following: in Windows or Linux (and Mac?) start GRASS and in the GRASS command shell type 'export' without quotes or parameters. This will list all the variables and their values as they apply to your GRASS environment, but don't be scared by their number, just look up the few I have listed then adjust their values accordingly:

Linux:
GISBASE=/usr/lib/grass64
GISRC=/home/george/.grassrc6
LD_LIBRARY_PATH=/usr/lib/grass64/lib
PATH=/home/george/local/jdk1.6.0_13/lib:/home/george/local/jdk1.6.0_13/jre:/home/george/local/jdk1.6.0_13/jre/bin/java/home/george/local/jdk1.6.0_13/jre/bin:/usr/lib/grass64:/usr/lib/grass64/bin:/usr/lib/python2.6:/usr/lib/grass64/lib:usr/lib/grass64/scripts:/usr/lib/grass64/etc:/usr/lib/grass64/etc/python:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games
PYTHONPATH=/usr/lib/grass64/etc:/usr/lib/grass64/etc/python:/usr/lib/grass64/lib:/usr/lib/grass64/bin:/usr/lib/grass64/scripts:/usr/lib/python2.6
PYTHONLIB=/usr/lib/python2.6

Windows:
GISBASE= C:\GRASS-64
GISRC= C:\Documents and Settings\user\.grassrc6
LD_LIBRARY_PATH= C:\GRASS-64\lib
PATH= C:\GRASS-64\etc;C:\GRASS-64\etc\python;C:\GRASS-64\lib;C:\GRASS-64\bin;C:\GRASS-64\extralib;C:\GRASS-4-SVN\msys\bin;C:\Python26;
PYTHONLIB= C:\Python26
PYTHONPATH= C:\GRASS-64\etc\python
GRASS_SH= C:\GRASS-4-SVN\msys\bin\sh.exe

and Apply all of them.
* Now click on the Interpreter tab to verify that the interpreter has been correctly located and Pythonpath correctly set. Press OK to exit and now you are ready to run or debug your first Python program from Eclipse!

==== Running a test program ====

Finally create the following new Python source program by right-clicking the Myproject source tree and selecting New → File from the menu. Name the file test.py (including the extension) and when the empty file opens on your workspace paste the following lines:

<source lang="python">
import os
import grass.script as grass
env = grass.gisenv()
print env
#List all environment variables
for key, value in os.environ.items(): print key, value
#Print region extent
r = grass.read_command("g.region", flags='p' )
print r
</source>

Save the file and press the Run button in the Run Configuration dialog, or from the Run menu select 'Run'.

== See also ==

* [[Eclipse]] in general

[[Category:Development]]
[[Category:FAQ]]
[[Category:Linking to other languages]]
[[Category:Python]]

Using Eclipse to develop GRASS Python programs

2010-01-18T12:46:58Z

⚠️Sonja:

= How to use Eclipse to develop Python scripts that access GRASS object =

Recent releases of GRASS have emphasised the use of Python as the language of choice for developing scripts which access GRASS objects and can be used to automate operations without GRASS running.

This short tutorial shows how to set up a complete development environment using the Eclipse IDE to develop, debug and run Python programs that access GRASS objects. These instructions apply to MS-Windows and Linux, and probably Mac as well, since all the packages required are open source software which runs on all three platforms.

Please note that this is not an Eclipse, nor a Python, nor a GRASS tutorial. It is just a description on how to get all the above to work together. It assumes some (but not much, because I don't have much!) knowledge of all the above.

=== Prerequisites (Release versions are as at the time of writing) ===

* GRASS 6.4 and Python 2.6.x
* Eclipse 3.4.x
* Pydev 1.4.5 Eclipse plug-in for Python
* Optionally, other plugins for Eclipse

==== GRASS 6.4.0RC4 and Python 2.6.x ====

Many Linux distributions already include GRASS in their packaging but you must ensure you download the latest (GRASS 6.4.0RC4) release for Linux, MS-Windows, and Mac, available in binary (executable) from the GRASS {{website|download|download site}}, and install it as instructed for your platform. On Windows install the stand-alone WinGRASS and not the OSGeo4W GRASS version. You will also need to download Python 2.6 for your platform from the [http://www.python.org Python.org site] and install it as required for your platform making a note of where the python executable (python.exe in MS-Windows) is installed. Most recent Linux already come with Python 2.6.2 installed.

==== Eclipse ====

Eclipse 3.4.2 is the minimum version recommended, but other releases could work as well. Download it from [http://www.eclipse.org the Eclipse download page]. The Ganymede 3.4.2 release for Java developers is fine (85MB). Installing Eclipse is very easy because installations consists simply of unpacking the download package in a directory of your choice.
To avoid permission problems in Linux, install Eclipse in your Home directory or a subdirectory.

==== Pydev ====
Pydev is an Eclipse plugin that adapts the Eclipse platform to the specific needs of Python program development, debugging and testing. It is not the only Python plugin available, but the one largely recommended.
The current release is 1.4.5 and to install it you should use the Eclipse Update Manager mechanism, as detailed below.

Open the Eclipse platform and click on the Help → Software Updates menu entry, click on the Available Software tab and click on the Add Site button. This will open a dialog box where you insert the following URL: http://pydev.org/updates/ . Then press OK and follow the instructions. This will result in the Pydev plug-in being automatically downloaded. Click on the install button to install it among your other Eclipse plug-ins. Furthermore it will automatically inform you in future when new updates are available. The Home page for Pydev is: http://pydev.org/ .
At this point you have all the software pre-requisites installed, ready for the next step.

==== Creating a new project ====

When you first open the Eclipse platform after a new installation you will be asked to set-up a workspace, which will normally be in your home directory by default, then you will see a Welcome screen with various buttons. Click on the one that opens the Eclipse workspace, which will be empty and probably be Java oriented.
To change it to be Python oriented you must open what in Eclipse is called a "perspective", which is a combination of views and windows which suits the plug-in you are actually using at any one time. So, go to the Window → Open Perspective sub-menu and select Pydev. This will open the Pydev perspective where most of your development work will be done, and since new development starts with a new Project, now go to the File → New menu and select Pydev Project, and follow the prompts to create a new empty Python project which we will name Myproject.

==== Configuring Eclipse and Pydev ====

Eclipse is highly configurable, but for our purpose we will only look at the configuration required for Python use.
There are three preferences menus you should know, the Window (or Eclipse) Preferences menu, the Project Properties menu, and the Run or Debug Configuration menu, but for our needs we will just look at Window and Run Configuration.

Open the Window → Preferences menu, expand the Pydev entry and select Interpreter - Python. Sometime Eclipse can automatically detect the location of your Python interpreter, in which case it will appear in the top right box: but if it didn't simply add it via the New button (remember you made a note of its location earlier on!).
In the bottom box add the following New Folders to the ones automatically added by Eclipse, and which point to the GRASS libraries (in Mac(?) they will be located within the GRASS installation directory tree):

Linux:
/usr/lib/grass64/etc
/usr/lib/grass64/etc/python
/usr/lib/grass64/scripts
/usr/lib/grass64/bin

Windows:
C:\GRASS-4-SVN\etc
C:\GRASS-4-SVN\etc\python
C:\GRASS-4-SVN\scripts
C:\GRASS-4-SVN\bin

then press Apply and OK. Finally go to the Run Configurations menu and create a new entry for test.py as follows:

* Click on Python Run, then click on the New configuration icon, the first at the top. Provide a Name, Project and Module names either manually or by browsing and press Apply to create the new configuration.

* Click on the Environment tab and enter the following variables and values, keeping in mind that as shown they reflect my configuration.When you start GRASS it sets most of these variables but since you now want to run programs without GRASS itself running, you will have to set them yourself and find the equivalent locations for your specific configuration. If you have trouble do the following: in Windows or Linux (and Mac?) start GRASS and in the GRASS command shell type 'export' without quotes or parameters. This will list all the variables and their values as they apply to your GRASS environment, but don't be scared by their number, just look up the few I have listed then adjust their values accordingly:

Linux:
GISBASE=/usr/lib/grass64
GISRC=/home/george/.grassrc6
LD_LIBRARY_PATH=/usr/lib/grass64/lib
PATH=/home/george/local/jdk1.6.0_13/lib:/home/george/local/jdk1.6.0_13/jre:/home/george/local/jdk1.6.0_13/jre/bin/java/home/george/local/jdk1.6.0_13/jre/bin:/usr/lib/grass64:/usr/lib/grass64/bin:/usr/lib/python2.6:/usr/lib/grass64/lib:usr/lib/grass64/scripts:/usr/lib/grass64/etc:/usr/lib/grass64/etc/python:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games
PYTHONPATH=/usr/lib/grass64/etc:/usr/lib/grass64/etc/python:/usr/lib/grass64/lib:/usr/lib/grass64/bin:/usr/lib/grass64/scripts:/usr/lib/python2.6
PYTHONLIB=/usr/lib/python2.6

Windows:
GISBASE= C:\GRASS-4-SVN
GISRC= C:\Documents and Settings\user\.grassrc6
LD_LIBRARY_PATH= C:\GRASS-4-SVN\lib
PATH= C:\GRASS-4-SVN\etc;C:\GRASS-4-SVN\etc\python;C:\GRASS-4-SVN\lib;C:\GRASS-4-SVN\bin;C:\GRASS-4-SVN\extralib;C:\GRASS-4-SVN\scripts;C:\Python26;
PYTHONLIB= C:\Python26
PYTHONPATH= C:\GRASS-4-SVN\etc;C:\GRASS-4-SVN\etc\python;C:\GRASS-4-SVN\lib;C:\GRASS-4-SVN\bin;C:\GRASS-4-SVN\extralib;C:\GRASS-4-SVN\scripts;C:\Python26;

and Apply all of them.
* Now click on the Interpreter tab to verify that the interpreter has been correctly located and Pythonpath correctly set. Press OK to exit and now you are ready to run or debug your first Python program from Eclipse!

==== Running a test program ====

Finally create the following new Python source program by right-clicking the Myproject source tree and selecting New → File from the menu. Name the file test.py (including the extension) and when the empty file opens on your workspace paste the following lines:

import os
import grass.script as grass
env = grass.gisenv()
print env
#List all environment variables
for key, value in os.environ.items(): print key, value
#Print region extent
r = grass.read_command("g.region", flags='p' )
print r

Save the file and press the Run button in the Run Configuration dialog, or from the Run menu select 'Run'.

== See also ==

* [[Eclipse]] in general

[[Category:Development]]
[[Category:FAQ]]