How to create custom functions in QGIS using the Function Editor

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:

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

Now, type this expression (see the image below as reference):

factor_area(10)

factor_area

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:

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s