After having tried to explain in a simple way some Basic rules for writing Python scripts for Processing Toolbox in QGIS, this time we will discover the basic rules for writing custom functions in QGIS using the Function Editor.
QGIS allows the definition of user-defined expression functions (in Python or C++) from the Function Editor tab in the Field Calculator. They can be eventually used in combination with the other built-in expressions or even for rule-based rendering, for the creation of geometry generators for styling, for generating labels, and so on.
Learning the syntax
We still don’t know how to use it, but this is a short example of a custom function:
@qgsfunction(args="auto", group='Custom') def myfunc(value1, value2, feature, parent): """ Add some text here for documenting the function """ pass
We have just created a new custom function ‘myfunc’ with two input parameters. Let’s analyze it in detail:
- ‘myfunc’ is the name of the custom function;
- ‘value1’, ‘value2’ (and so on) are the input parameters (at least one value must be taken as argument);
- ‘feature’ is the current
QgsFeature(it must always be taken as argument);
- ‘parent’ is the expression engine node (it must always be taken as argument);
- ‘args’ is the number of arguments defined. For example, when setting args=2, we are defining two input parameters (i.e. ‘value1’ and ‘value2′).
When using the args=’auto’ function argument, the number of function parameters required will be calculated by the number of arguments the function has been defined within Python (minus 2 – feature, and parent). Using args=’auto’ is the most common choice for general applications (no problems because everything is automatic!).
When using the args=-1 function argument, instead, the input parameters will be a list (see this question on GIS Stack Exchange for a better understanding);
- ‘group’ is the name of the group in the expression builder UI where the function will be listed.
That’s all. As always, the best way for learning is doing, so let’s not waste time.
Learning by doing
We will try to create a custom function that returns the area of the current geometry multiplied by a user-defined factor.
First of all, go to the Function Editor tab from the Field Calculator (or wherever you are working on and you find a Function Editor tab 😀 ).
Then, click on ‘New file’ and type ‘factor_area’ as the name of the new function:
You will see that a new function has been created and it is listed on the left side of the dialog. Now, click on the name of the function and replace the default
@qgsfunction with the following code (don’t delete the libraries imported by default):
@qgsfunction(args='auto', group='Custom') def factor_area(factor, feature, parent): """ This function returns the area of the current geometry multiplied by a user-defined factor. """ geom_area = feature.geometry().area() new_area = factor * geom_area return new_area
Once you have done this, click on the
Load button and you will be able to see the function from the
Custom Menu of the
Now, type this expression (see the image below as reference):
The output will be the value of the area for the current feature, multiplied by a factor of 10.
This was a really simple example. For appreciating more the power of custom functions, you may have a look at the following answers that I wrote on GIS Stack Exchange:
- Rendering point symbols on top of diagrams?
- If two symbols in same QGIS layer are too close, show only one?
- Shifting display of overlapping lines in QGIS?