GRASS-SEXTANTE

Configuring and using GRASS from SEXTANTE.

This documents describes how to configure SEXTANTE so it can call GRASS algorithms and incorporate them into its own set of geoalgorithms. It also gives some additional information on the mechanism used by SEXTANTE to integrate GRASS functions, which should be useful for all users, but specially for those familiar with the GRASS command-line interface.

Configuring SEXTANTE to use GRASS takes just a few easy steps. Once you have configured the system, you will be able to execute GRASS algorithms from any SEXTANTE component like the toolbox or the graphical modeller, just like you do with any other SEXTANTE geoalgorithm.

Open the settings dialog and select the GRASS menu. You will see something like this:

Only two parameters must be set, namely:

The path to the grass installation folder. Needed by SEXTANTE to execute GRASS commands. Under Linux, this is usually usr/lib/grassXX
The path to a GRASS mapset. The mapset doesn't have to contain any data at all, since data will be imported automatically each time you execute an algorithm. The only important part of the mapset is the location information, particularly the Coordinate Reference System. You must set the same CRS that is used by the layers that you want to process using GRASS algorithms. If, for instance, you have layers with data in the EPSG 23030 reference system, you must set the mapset to that same reference system. When data is imported into the mapset, no reprojection is performed, and layers are assumed to be in the same projection as the mapset itself.

Once you have set the previous paths, click on OK to close the settings dialog. SEXTANTE will now try to execute GRASS and create the definition files that are used to generate the graphical interfaces of all the suitable GRASS algorithms, along with the corresponding help files. This process might take a few seconds. If you are running Windows, you will see a new window (by default it is minimized). Just wait until it closes. After that, GRASS algorithms will be shown in the toolbox and identified with a GRASS icon. They will appear in a new branch named "GRASS" in the algorithms tree -which contains two groups: raster (r.*) and vector (v.*)-, and also in the usual groups used for built-in SEXTANTE algorithms. This way, it is easier to find the right algorithm, both for SEXTANTE users with no previous GRASS experience and former GRASS users.

Not all GRASS algorithms are available from SEXTANTE. Some of them are not compatible with the architecture of SEXTANTE and its algorithm-definition semantics, while others do not make much sense in the context of SEXTANTE (like, for instance, those used to digitize and create new vector layer). Unsuitable algorithms are automatically removed and will not appear in any SEXTANTE component.

How the SEXTANTE-GRASS integration works. Limitations and other issues.

If you are a GRASS user, it might be useful for you to know how SEXTANTE calls GRASS algorithms and comunicates with the GRASS interface. This can be summarized in the following steps:

Importing data. The layers that have been selected as input are imported into the GRASS mapset. Not every layer that you can open in your GIS can be used to execute a GRASS algorithm. It must be a file-based layer and it must have a format compatible with the capabilities of the GRASS modules that import external data. Refer to the GRASS help files for further information.
Processing. The selected GRASS algorithm is executed.
Exporting results. Resulting data are exported to the filenames selected by the user in the input parameters dialog. Only layers (whether raster or vector) are exported. Any other results that might have been created by the algorithm (such as, for instance, text results shown in the console window) are not handled, and therefore, they will not be presented as results by the wrapping SEXTANTE algorithm. Also, take into account that exporting data also has its limitations, and not all the information generated might be available. For instance, topological information will be lost, since data are exported to shapefile format, which cannot store it. for further details, check the help file associated with GRASS export modules.

All this steps are stored in a batch file that is executed using the GRASS_BATCH_JOB variable. When SEXTANTE invokes GRASS, the commands in the batch file are executed and GRASS closes up automatically after that.