In order for a GRASS command to be executed within QGIS, a plain text description file is required to define the command's inputs, outputs, and parameters. Each GRASS command is described in a separate text file. However, some commands can be split into several algorithms using more than one description file, resulting in multiple entries in the algorithms list.

This splitting was originally done because the Processing provider did not support optional parameters; however, it can simplify the use of GRASS commands with many options.

Description files

Each description file starts with three lines containing:

The name of the GRASS command to call to execute the algorithm (e.g. v.buffer)
The description of the algorithm that will be displayed in the algorithm dialog. For split commands you must include the algorithm id first, e.g.:

r.sun.insoltime - Solar irradiance and irradiation model (daily sums)

and

r.sun.incidout - Solar irradiance and irradiation model (for the set local time)

The name of the group where you want the command to appear

After these three lines, the algorithm's inputs and outputs are defined, one per line.

Defining inputs and outputs

Each algorithm parameter is defined on a separate line, with elements separated by the pipe symbol |.

The following parameters are supported:

A raster layer

QgsProcessingParameterRasterLayer|[name of GRASS parameter]|[description of parameter to show]|[Default value, or None]|[True/False, indicating if the parameter is optional or not]

Example: QgsProcessingParameterRasterLayer|base|Name of input raster map|None|False

A vector layer

QgsProcessingParameterFeatureSource|[name of GRASS parameter]|[description of parameter to show]|[A number indicating the type of geometry]|[Default value, or None]|[True/False, indicating if the parameter is optional or not]

To indicate the type of the geometry, use the following values:

-1: any geometry
0: points
1: lines
2: polygons

Multiple layers

QgsProcessingParameterMultipleLayers|[name of GRASS parameter]|[description of parameter to show]|[A number indicating the type of geometry]|[Default value, or None]|[True/False, indicating if the parameter is optional or not]

To indicate the type of geometry, use the following values:

-1: any vector geometry
0: points
1: lines
2: polygons
3: raster

A file

QgsProcessingParameterFile|[name of GRASS parameter]|[description of parameter to show]|QgsProcessingParameterFile.File|[file extension|[Default value, or None]|[True/False, indicating if the parameter is optional or not]

A numerical value

QgsProcessingParameterNumber|[name of GRASS parameter]|[description of parameter to show]|QgsProcessingParameterNumber.Integer or QgsProcessingParameterNumber.Double|[default value]|[True/False, indicating if the parameter is optional or not]|[min value]|[max value]

None can be used for both min and max values to indicate that there is no lower or upper limit.

A numerical range

QgsProcessingParameterRange|[name of GRASS parameter]|[description of parameter to show]|QgsProcessingParameterNumber.Integer or QgsProcessingParameterNumber.Double|[default minimum and maximum values, separated by comma]|[True/False, indicating if the parameter is optional or not]

If minimum and maximum values are omitted the range will not have lower and upper limit.

A string

QgsProcessingParameterString|[name of GRASS parameter]|[description of parameter to show]|[default value]|[True/False, indicating if the parameter is optional or not]

A value to select from a list

QgsProcessingParameterEnum|[name of GRASS parameter]|[description of parameter to show]|[list of possible values, separated by semicolons]|[True/False, indicating whether more than one value can be selected (allowMultiple)]|[zero-based index of default value]|[True/False, indicating if the parameter is optional or not]

A boolean

QgsProcessingParameterBoolean|[GRASS flag]|[description of parameter to show]|[default value]|[True/False, indicating if the parameter is optional or not]

Example: QgsProcessingParameterBoolean|-p|Output values as percentages|False|True

A pair of coordinates

QgsProcessingParameterPoint|[name of GRASS parameter]|[description of parameter to show]|[default value]|[True/False, indicating if the parameter is optional or not]

Example: QgsProcessingParameterPoint|coordinates|The coordinate of the center (east,north)|0,0|False

An extent

QgsProcessingParameterExtent|[name of GRASS parameter]|[description of parameter to show]|[default value]|[True/False, indicating if the parameter is optional or not]

Example: QgsProcessingParameterExtent|bbox|Bounding box for selecting features|None|True

A crs

QgsProcessingParameterCrs|[name of GRASS parameter]|[description of parameter to show]|[default value]|[True/False, indicating if the parameter is optional or not]

Example: QgsProcessingParameterCrs|crs|New coordinate reference system|None|False

After defining the inputs, it is necessary to define the algorithm's outputs. The outputs are also described on a separate line and use the same formatting conventions as the inputs. The following outputs are supported.

A raster layer

QgsProcessingParameterRasterDestination|[name of GRASS parameter]|[description of output to show]|[Default value, or None]|[True/False, indicating if the parameter is optional or not]

Example: QgsProcessingParameterRasterDestination|length_slope|Slope length and steepness (LS) factor for USLE|None|True

A vector layer
```
QgsProcessingParameterVectorDestination|[name of GRASS parameter]|[description of output to show]|vector type|[Default value, or None]|[True/False, indicating if the parameter is optional or not]
```
The following vector types are available
- QgsProcessing.TypeVectorPoint: points
- QgsProcessing.TypeVectorLine: lines
- QgsProcessing.TypeVectorPolygon: polygons
- QgsProcessing.TypeVectorAnyGeometry: any vector geometry
Example: QgsProcessingParameterVectorDestination|flowline|Flow line|QgsProcessing.TypeVectorLine|None|True
A file (this output type is used for data formats that are not supported by QGIS, e.g. HTML or plain text)
```
QgsProcessingParameterFileDestination|[name of GRASS parameter]|[description of output to show]|[file type]|[Default value, or None]|[True/False, indicating if the parameter is optional or not]
```
Example: QgsProcessingParameterFileDestination|reportfile|Final Report File|Txt files (*.txt)|None|True

An output folder

QgsProcessingParameterFolderDestination|[name of GRASS parameter]|[description of parameter to show]|[default value]|[True/False, indicating if the parameter is optional or not]

Example: QgsProcessingParameterFolderDestination|output_dir|Output Directory|None|False

Hardcoded parameters

Sometimes it is necessary to always add specific parameter to the GRASS command. In that case there is no need to expose it in the algorithm dialog. Instead these parameters should be defined as "hardcoded" in the description file using the following format

Hardcoded|[parameter or argument to be passed to GRASS]

Here are examples

Hardcoded|operation=report
Hardcoded|-o

These two lines mean that the parameters operation=report and -o will be added to the GRASS command generated by the algorithm.

Advanced parameters

Some algorithm parameters may not be widely used by most users. In that case, you can mark them as "advanced" so they are added to the "Advanced parameters" group of the algorithm dialog, which is collapsed by default. To mark an input parameter as "Advanced," add an asterisk (*) before its declaration.

*QgsProcessingParameterBoolean|-i|Output raster map as integer|False

Reloading algorithm descriptions

There is no need to restart QGIS after editing existing or creating a new algorithm description — simply click the wrench icon in the Processing toolbox or open Settings → Options → Processing, then click OK, and QGIS will reload the descriptions.

Advanced topics

Saving console output

To save the console output from GRASS to file, simply create a QgsProcessingParameterFileDestination parameter named html

Adding custom logic to algorithm

If you want to add custom logic to an algorithm, such as a preliminary data check or the use of more than one GRASS command, or transforming output data, you need to use the ext mechanism. This involves creating a Python file that performs the necessary actions at the predetermined level(s).

There are five different levels at which you can add logic:

Checking the input parameters. For example, if you want to verify that two mutually exclusive options have not been enabled.
Processing input import: If you need to do more than import input layers.
Processing the command itself is necessary if you need to chain more than one GRASS command for your algorithm.
Processing the outputs is necessary if you need to perform special actions before exporting layers or if you require specific export methods.
Customizing HTML outputs is useful if you need to perform special processing on an HTML output or save the raw output to an output variable.

The Python file should be placed in python/plugins/grassprovider/ext and its name should match the name of the algorithm description file with . replaced with _. For example, if GRASS algorithm description file is called v.net.path.txt, corresponging Python ext file will be called v_net_path.py.

The Python file should implement at least one of the functions:

checkParameterValuesBeforeExecuting() to validate/check inputs
processInputs() to implement custom logic for importing inputs into GRASS mapset
processCommand() to add more GRASS commands to the algorithm
processOutputs() to apply custom logic for exporting GRASS layers into QGIS
convertToHtml() to apply custom processing to HTML data

If there is a Python file with the algorithm name in the ext directory, these functions will be imported from the file. In the case of processCommand(), processInputs(), processOutputs() and convertToHtml() these will override thec "standard" versions of these methods in the code of the GRASS provider. You will need to read (and understand) the code for the "standard" methods in python/plugins/grassprovider/grass_algorithm.py. The checkParameterValuesBeforeExecuting method from ext file will override the standard checkParameterValues() method from QgsProcessingAlgorithm class.

If we take the example of v.what.rast.txt, there is an ext file: ext/v_what_rast.py. In this file there is a processCommand() method. It just launches the standard processCommand() but with the delOutputs option set to True as we do not want to have standard outputs. Then there is also a overloaded processOutputs which exports the input vector as an output for QGIS. We need to do this because v.what.rast modifies values directly in the input vector layer instead of generating a new output, so we have to build this output ourself.