Using Eclipse to develop GRASS Python programs

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 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 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 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:

 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