QGIS/python/plugins/processing/algs/grass7/grass7.txt

A short guide for creating and editing GRASS GIS 7 algorithms:
-----------------------------------------------------------------------

Each GRASS command, to be executed from a processing framework element such as the toolbox
or the graphical modeler, needs to be described to let it know the inputs
required by the commands, the output it generates and the parameters that are
used to configure it. Each command is described in a separate text file, although
some commands might be split in several algorithms, needing thus several files
and adding more than one new entry to the algorithms list. Splitting
a grass command is usually done because the processing framework does not support optional
parameters, so it will call GRASS using all parameters defined in the description
file.

Here is an explanation of the content of these descriptions files, so you can
create you own ones or edit current ones to improve them.

Each file starts with three lines containing:

 - The name of the grass command to call to execute the algorithm (e.g. v.buffer)
 - The name of the algorithm to show to the user. This is usually the same as the
   GRASS command, but it can be different
 - The name of the group where you want the command to appear

After this three lines, a variable number of lines appear, describing all inputs
and outputs. Here is a brief explanation of the format of these lines, depending
on the type of parameter or output to be described. All declarations are contained
in a single line, with elements separated by the symbol "|"

- A raster layer
ParameterRaster|base|base|False

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

Example: ParameterRaster|base|base|False

- A vector layer

ParameterVector|[name of GRASS parameter]|[description of parameter to shown]|[A number indicating the type of geometry]|True/False, indicating if the parameter is optional or not

ParameterVector|input|Name of input vector map|-1|False

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

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

- A numerical value

ParameterNumericalValue|[name of GRASS parameter]|[description of parameter to show]|[min value]|[max value]|[default value]

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

If the default value is written as a real number (i.e. it contains a decimal
point, even if it is an integer value like 4.0), the parameter can take any value,
including decimal ones. If it is written as an integer (i.e. 4), the parameter is
assumed to accept only integer values

Example: ParameterNumber|levels|levels|1|256|32

- A string

ParameterString|[name of GRASS parameter]|[description of parameter to show]|[default value]

- A value to select from a list

ParameterSelection|[name of GRASS parameter]|[description of parameter to show]|[list of possible values, separated by semicolons]|[zero-based index of default value]

- A boolean value

Example: ParameterBoolean|-c|-c|True

- Outputs

All outputs are added with the following syntax:

[type of output]|[name of GRASS output]|[description of output to show]

The following types are available

  -OutputRaster
  -OutputVector
  -OutputTable
  -OutputFile (for any file that is not a layer or table of a format supported by QGIS)


- Advanced parameters

to tag a parameter as "advanced", just add "*" before its declaration. For instance:

*ParameterBoolean|-c|-c|True


ADVANCED OUTPUT PROCESSING
--------------------------

In some cases, it might be interesting to take the console output from GRASS and
extract a part of it for saving or formatting.

Two things can be done about this:

 - Creating an HTML file with output. Just add an output of type OutputHTML.
   It's value will not be passed to GRASS, but you can use it later to create the
   HTML file from the console output. You should create a python file in the
   grass/ext package, with the same name as the grass module, with dots replaced
   by low hyphens (for instance r_quantile.py for the r.quantile command), and
   add a postProcessResults(alg) method. It will be called when the execution of
   the GRASS command is finished.
 - Creating a text file. Do as above, but adding an output of type OutputFile.
   Since some GRASS commands might use this type of output, and to make sure that
   the value of this output is not passed to the GRASS command when calling it,
   the output has to be named 'outputtext'