Introduction

QGIS' ​Processing framework is a geoprocessing environment that can be used to call native and third-party algorithms from QGIS. GRASS GIS is supported as an algorithm provider among a variety of external (to QGIS) applications. More details can be found at ​QGIS processing framework > Configuring external applications > GRASS.

How does it work?

The GRASS provider for QGIS’ Processing is a graphical interface towards GRASS. In overview:

• A GRASS GIS data base is created on-the-fly in a temporary directory

• Input layers/rasters are imported (or referenced) into this GRASS GIS data base

• Launching a GRASS algorithm from the ​Processing Toolbox is essentially a GRASS GIS command line with the requested parameters, executed in the shell or as a system call onto the temporary GRASS GIS database. This command line is recorded in a log.

• Results returned by the algorithm, are extracted from the GRASS GIS temporary database and converted into layers/rasters (and directly opened in QGIS if the respective option has been enabled).

• Finally, the temporary GRASS GIS data base is deleted

Integrating an add-on under the GRASS provider

To integrate an add-on in the GRASS provider, it is required to build a description file. A description file will suffice for simple algorithms, i.e. import input data, execute a single GRASS GIS command and extract data. However, if an algorithm consists of multiple actions (i.e. a preliminary check of the imported data, executing more than one GRASS GIS commands or transforming the output data before the extraction), then the ext mechanism has to be used. The ext mechanism is a way to add additional logic to an algorithm. More on this mechanism in the following sections.

Description file

• A description file describes the different parameters of an add-on

• The name of the description file must be identical to the add-on name

• Description files are placed under python/plugins/processing/algs/grass7/description/. Reading some of those files helps to understand the different options.

QGIS' Processing interface to GRASS

In the code of the GRASS provider for QGIS' Processing framework (python/plugins/processing/algs/grass7/Grass7Algorithm.py) there are 4 pre-defined methods to interact with GRASS GIS. These are: processCommand, processInputs, processOutputs, checkParameterValuesBeforeExecuting.

These methods reflect 4 levels of algorithmic building blocks:

1. Checking the input parameters. For example, in the case of two exclusive options, to verify that both have been enabled.

2. Processing inputs import. In the case of processing input layers after importing.

3. Processing the command by itself. For example, chaining several GRASS commands together.

4. Processing the outputs export. For example to perform special things before exporting layers or if using special export methods.

Building complex algorithms

To add some logic on one or more levels, the pre-defined methods will be overriden by custom ones defined in a Python file, named after the add-on and placed under the ext directory. In this way, the custom methods will be imported and run instead of the pre-defined ones. This enables to build an interface for complex GRASS GIS algorithms in QGIS' Processing Toolbox.

Specifically, a .py file, named after the add-on (note: substitute . with _), has to be created under python/plugins/processing/algs/grass7/ext. In this Python file, custom methods need to be defined with the following names:

• checkParameterValuesBeforeExecuting for Input parameters
• processInputs for Inputs import
• processCommand for Inputs import
• processOutputs for Outputs export