mirror of
https://github.com/qgis/QGIS.git
synced 2025-02-25 00:58:06 -05:00
187 lines
9.7 KiB
Plaintext
187 lines
9.7 KiB
Plaintext
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 model designer, 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, 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 provider 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 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 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
|
|
|
|
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]
|
|
|
|
Example: QgsProcessingParameterFeatureSource|input|Name of input vector map|-1|None|False
|
|
|
|
To indicate the type of 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]
|
|
|
|
Example: QgsProcessingParameterMultipleLayers|input|Input rasters|3|None|False
|
|
|
|
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.
|
|
|
|
Example: QgsProcessingParameterNumber|levels|levels|QgsProcessingParameterNumber.Integer|32|False|1|256
|
|
|
|
- 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
|
|
|
|
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 value
|
|
|
|
QgsProcessingParameterBoolean|[name of GRASS parameter]|[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
|
|
|
|
- A rectangular map 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
|
|
|
|
- Outputs
|
|
|
|
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]
|
|
|
|
Example: QgsProcessingParameterRasterDestination|length_slope|Slope length and steepness (LS) factor for USLE|None|True
|
|
|
|
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
|
|
|
|
QgsProcessing.TypeVectorPoint
|
|
QgsProcessing.TypeVectorLine
|
|
QgsProcessing.TypeVectorPolygon
|
|
QgsProcessing.TypeVectorAnyGeometry
|
|
|
|
Example: QgsProcessingParameterVectorDestination|flowline|Flow line|QgsProcessing.TypeVectorLine|None|True
|
|
|
|
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
|
|
|
|
A 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
|
|
|
|
- Advanced parameters
|
|
|
|
to tag a parameter as "advanced", just add "*" before its declaration. For instance:
|
|
|
|
*ParameterBoolean|-c|-c|True
|
|
|
|
RELOADING ALGORITHM DESCRIPTIONS
|
|
---------------------------------------
|
|
You do not need to restart QGIS after editing or creating an algorithm description - simply click the wrench icon in the processing toolbox, then click OK, and QGIS will reload the descriptions.
|
|
|
|
ADVANCED PROCESSING
|
|
--------------------------
|
|
|
|
To save the console output from GRASS to file, simply create a QgsProcessingParameterFileDestination parameter named 'html'
|
|
|
|
Example: QgsProcessingParameterFileDestination|html|List of addons|Html files (*.html)|addons_list.html|False
|
|
|
|
To add additional logic to an algorithm, like a preliminary check on data, the use of more than one GRASS command,
|
|
or a transformation of output data, then you need to use the ext mechanism.
|
|
|
|
There are 4 different levels where you can add logic:
|
|
- Checking the input parameters, e.g. if you want to verify that two mutually exclusive options have not been both enabled.
|
|
- Processing inputs import: if you need to do more than importing input layers.
|
|
- Processing the command itself: if you need to chain more than one GRASS command for your algorithm.
|
|
- Processing the outputs: if you need to do special things before exporting layers or if you need special export methods.
|
|
|
|
Whenever you want to add some logic on one (or more) level(s), you have to create a .py file named according to the algorithm name in python/plugins/grassprovider/ext, replacing '.' with '_'.
|
|
Then you need to create methods using the respective names:
|
|
- Input parameters: checkParameterValuesBeforeExecuting
|
|
- Inputs import: processInputs
|
|
- Command: processCommand
|
|
- Outputs: processOutputs
|
|
|
|
If there is a Python file with the algorithm name in the ext directory, methods will be imported from the file and run instead of the common methods (there are "standard" processCommand/processInputs/processOutputs/checkParameterValuesBeforeExecuting methods in the code of the GRASS provider for QGIS Processing, in python/plugins/grassprovider/Grass7Algorithm.py).
|
|
|
|
If we take the example of v.what.rast, 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 (we do not want to have standard outputs).
|
|
Then there is also a customized 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.
|
|
|
|
If you want to do special things in the ext mechanism, you will need to read (and understand) the GRASS provider code standard methods in Grass7Algorithm.py.
|