Skip to content

Commit 830ad0b

Browse files
committedMay 11, 2018
Rough beginnings to processing algorithm porting guide
1 parent 3e62627 commit 830ad0b

File tree

1 file changed

+72
-0
lines changed

1 file changed

+72
-0
lines changed
 

‎doc/porting_processing.dox

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
- Derive your algorithms from the new base class QgsProcessingAlgorithm (or a subclass of QgsProcessingAlgorithm), not GeoAlgorithm
2+
3+
- Ensure that your algorithm (or algorithm's parent class) implements the new pure virtual createInstance(self, config) call to return a new instance of the algorithm class. Note that this should not return a copy of the algorithm, but instead a newly constructed instance of the class. If you use a base class in your plugin for all algorithms, you can usually shortcut the createInstance implementation by placing:
4+
5+
def createInstance(self, config={}):
6+
return type(self)()
7+
8+
inside your algorithm base class.
9+
10+
- Input parameters and available outputs must be declared in an implementation of the new pure virtual method initAlgorithm(self, config={})
11+
12+
- The input parameters and outputs classes have been replaced with new c++ versions, which must be used when calling addParameter and addOuput.
13+
Map parameters from old classes to new classes
14+
- ParameterNumber -> QgsProcessingParameterNumber
15+
- constructor arguments in different order
16+
- type specified explicitly, not via min/max/default type
17+
- ParameterBoolean -> QgsProcessingParameterBoolean
18+
- ParameterCrs -> QgsProcessingParameterCrs
19+
20+
- Use featuresources and sinks wherever possible
21+
22+
Update outputs
23+
24+
- OutputVector ->
25+
26+
- processAlgorithm has a new signature....
27+
28+
Update retrieval of parameters
29+
30+
- Extent parameters now returned as QgsRectangle. In 2.x extent parameters were returned as a delimited string, leaving the algorithm
31+
responsible for parsing the string and validating it. In 3.0 this is automatically handled and a QgsRectangle returned, ready for use.
32+
33+
- Crs parameters now returned as QgsCoordinateReferenceSystem objects. In 2.x crs parameters were returned as a string, leaving the algorithm
34+
responsible for interpreting this string and working out how to convert it to a suitable CRS object. In 3.0 this is automatically handled
35+
and a QgsCoordinateReferenceSystem object is returned, ready for use. If you require a string version of the CRS, use the
36+
QgsCoordinateReferenceSystem methods like authid() to obtain a string representation of the CRS in the desired format.
37+
38+
39+
Use parameterAsSink instead of getOutputFromName
40+
41+
- Since processing algorithms can now be run in the background, it's important to implement support for cancelation in your
42+
algorithms. Whenever looping (or before/after calling lengthy operations) listen out for user cancelation via the provided
43+
feedback object. E.g.
44+
45+
if feedback.isCanceled():
46+
break
47+
48+
- Give feedback via the feedback object, not directly to QgsMessageLog. E.g.
49+
50+
feedback.pushInfo('Feature {} was missing geometry, skipping'.format(f.id())
51+
feedback.reportError('Input layer CRS is not valid, cannot reproject')
52+
53+
- Use geoprocessingexception only for FATAL errors which force a model to terminate. Algorithms should handle common cases
54+
such as having no features in an input layer without throwing exceptions (instead, an empty layer should be output). This
55+
allows more flexibility for users creating models. They may have created models which "route" features to different algorithms
56+
based on some criteria, and it can be a valid case that no features satisfy this criteria. If your algorithm throws an
57+
exception upon encountering an empty layer, it prevents it being used in these flexible models. Instead, use the feedback
58+
object to pushInfo or reportError so that the lack of features is brought to user's attention (and logged) without breaking
59+
the model execution.
60+
61+
- Outputs are good! Declare as many outputs as useful from your algorithm. E.g. most algorithms should have at least a
62+
FEATURE_COUNT number output which records the number of features processed by the algorithm. Other algorithms might want
63+
to create numeric outputs for values like INTERSECTING_FEATURE_COUNT, NON_INTERSECTING_FEATURE_COUNT, etc. The more
64+
outputs like this available from an algorithm aids in user debugging (they are recorded in the log, so users can get
65+
a clear picture of what's happening at each step in their models), and also adds more power to models (as these outputs
66+
can be used in expressions or custom python code in later steps in a model.
67+
68+
Return a dict with output values
69+
70+
Dont’ use tablewriter - use a sink instead
71+
72+

0 commit comments

Comments
 (0)
Please sign in to comment.