Skip to content

Commit

Permalink
Update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
nyalldawson committed Dec 5, 2023
1 parent c84ae3f commit 3f82f73
Showing 1 changed file with 12 additions and 9 deletions.
21 changes: 12 additions & 9 deletions python/plugins/grassprovider/grass7.txt
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,16 @@ a grass command is usually done because the processing provider does not support
parameters, so it will call GRASS using all parameters defined in the description
file.

** After updating the .txt description files the `description_to_json.py` script
MUST be run to update the aggregated algorithms.json 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
- 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
Expand Down Expand Up @@ -152,7 +155,7 @@ to tag a parameter as "advanced", just add "*" before its declaration. For insta

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.
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
--------------------------
Expand All @@ -162,13 +165,13 @@ To save the console output from GRASS to file, simply create a QgsProcessingPara
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.
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.
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:
Expand All @@ -181,6 +184,6 @@ If there is a Python file with the algorithm name in the ext directory, methods

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.
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.

0 comments on commit 3f82f73

Please sign in to comment.