Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Update guide for GRASS algorithms
  • Loading branch information
AlisterH authored and nyalldawson committed May 25, 2023
1 parent b45da52 commit b223dcc
Showing 1 changed file with 39 additions and 25 deletions.
64 changes: 39 additions & 25 deletions python/plugins/grassprovider/grass7.txt
Expand Up @@ -5,9 +5,9 @@ Each GRASS command, to be executed from a processing framework element such as t
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
some commands might be split in several algorithms, thus needing 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
a grass command is usually done because the processing provider does not support optional
parameters, so it will call GRASS using all parameters defined in the description
file.

Expand All @@ -17,27 +17,29 @@ 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 description of the algorithm to show to the user. 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 this three lines, a variable number of lines appear, describing all inputs
After these 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
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: ParameterRaster|base|base|False
Example: QgsProcessingParameterRasterLayer|base|base|None|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
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]

ParameterVector|input|Name of input vector map|-1|False
Example: QgsProcessingParameterFeatureSource|input|Name of input vector map|-1|None|False

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

Expand All @@ -46,45 +48,57 @@ To indicate the type of geometry, use the following values:
1: lines
2: polygons

- 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

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

"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: QgsProcessingParameterNumber|levels|levels|QgsProcessingParameterNumber.Integer|1|256|32|False

Example: ParameterNumber|levels|levels|1|256|32
- 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]

- A string

ParameterString|[name of GRASS parameter]|[description of parameter to show]|[default value]
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

ParameterSelection|[name of GRASS parameter]|[description of parameter to show]|[list of possible values, separated by semicolons]|[zero-based index of default value]
QgsProcessingParameterEnum|[name of GRASS parameter]|[description of parameter to show]|[list of possible values, separated by semicolons]|[True/False, AJH: what does this indicate?]|[zero-based index of default value]|[True/False, indicating if the parameter is optional or not]

- A boolean value

Example: ParameterBoolean|-c|-c|True
Example: QgsProcessingParameterBoolean|-c|-c|False

- Outputs

All outputs are added with the following syntax:
Raster outputs are added with the following syntax:

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

[type of output]|[name of GRASS output]|[description of output to show]
Vector outputs are added with the following syntax:

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

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)
QgsProcessing.TypeVectorLine
QgsProcessing.VectorLine
QgsProcessing.VectorPolygon
QgsProcessing.TypeVectorAnyGeometry

File outputs which are not layers or tables of a format supported by QGIS are added with the following syntax:

QgsProcessingParameterFileDestination|[name of GRASS output]|[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

- Advanced parameters

Expand Down

0 comments on commit b223dcc

Please sign in to comment.