Basic rules for writing Python scripts for Processing Toolbox in QGIS

One of the most powerful QGIS tools is the possibility to create custom Python codes and then adding them to the Processing Toolbox.

This operation has several advantages, for example:

  1. the creation of user-friendly dialogs for the user inputs and output files;
  2. the integration of the custom script with other tools already loaded in the Processing Toolbox;
  3. the performing of more or less complex tasks in a programmatically way;
  4. the integration of the custom script within the QGIS Graphical Modeler for managing particular situations not covered by the default tools.

The following guidelines are essentially based on the QGIS Documentation.


Creating a new script

Quick procedure:

  1. go to  Processing  >  Toolbox ;
  2. from the Processing toolbox (just activated on the right side of the main QGIS window), go to  Create new script  menu under the  Tools  group in the  Scripts  algorithms block of the toolbox;
  3. to be recognized as a Processing script, it is necessary to specify the inputs and the outputs. We will learn how to do this later so, by now, type the following lines in the  Script editor:
    ##Custom=group
    ##my_first_script=name
    

    and then click on the  Save  button:
    Cattura

  4. name the script  my_first_script  and save it at the default location under the  .qgis  >  processing  >  scripts  folder (you will be automatically pointed to it);
  5. if you correctly performed the previous steps, you will see a new script, named  my_first_script , within the  Custom  group of the  Scripts  block in the Processing Toolbox:
    Cattura

We have just learned how easy is creating a new custom script (the last steps may be obviously skipped if you don’t want to save it permanently).


Setting the inputs

As previously said, the first lines provide the information about the inputs and the outputs and lead the creation of a user-friendly dialog.

These lines start with a double Python comment symbol (##) and have the following structure:

[parameter_name]=[parameter_type] [optional_value]

where:

  • the  parameter_name  is the name that will be shown to the user when executing the algorithm;
  • the  parameter_type  specifies the variable type (e.g. raster, vector, and so on);
  • the  optional_value  is an optional value assigned by default to the parameter (we will see an example later).

In the following code snippet, we will try to report a list of all the parameter types that are supported, their syntax and some examples, remembering that[parameter_name]  must be replaced by the preferred name for the parameter itself and preceded by ## :

# All the parameters follow the syntax:
# [parameter_name]=[parameter_type] [optional_value]

# A raster layer
[parameter_name]=raster

# A vector layer
[parameter_name]=vector
# A point vector layer
[parameter_name]=vector point
# A line vector layer
[parameter_name]=vector line
# A polygon vector layer
[parameter_name]=vector polygon

# A table
[parameter_name]=table

# A numerical value (a default value must be provided). For instance,
[parameter_name]=number 10

# A text string (a default value must be provided). For instance,
[parameter_name]=string John
# A text string shown in a larger text box (a default value must be provided)
[parameter_name]=longstring

# A boolean value (a default 'True' or 'False' value must be provided). For instance,
[parameter_name]=boolean True

# A set of input raster layers
[parameter_name]=multiple raster

# A set of input vector layers
[parameter_name]=multiple vector

# A field in the Attribute Table of a vector layer (a field must be provided). For instance, if 'my_layer' is the parameter name of a declared vector,
[parameter_name]=field my_layer

# A folder
[parameter_name]=folder

# A filename
[parameter_name]=filename

# A Coordinate Reference System
[parameter_name]=crs

Setting the outputs

The outputs are defined similarly to the inputs. The information about them starts with a double Python comment symbol (##) and has the following structure:

[parameter_name]=output [output_type]

Remembering that[parameter_name]  must be replaced by the preferred name for the parameter itself and preceded by ## , we report a list of all the output types that are supported:

# All the parameters follow the syntax:
# [parameter_name]=output [output_type]

# A raster output
[parameter_name]=output raster

# A vector output
[parameter_name]=output vector

# A table output
[parameter_name]=output table

# A html output
[parameter_name]=output html

# A file output
[parameter_name]=output file

# A number output
[parameter_name]=output number

# A string output
[parameter_name]=output string

# An extent output
[parameter_name]=output extent

An easy example

Starting from this sample code and running it (see the using of underscores, which are replaced with spaces):

##Custom=group
##my_first_script=name
##Let_us_use_a_vector=vector
##A_point_vector_here=vector point
##Keep_attributes=boolean True
##One_raster_is_not_enough=multiple raster
##Gives_nothing=output vector

Cattura

we will get this input dialog (all selectors are empty since there isn’t any layer loaded in QGIS):

Cattura

Since we have just learned how to deal with the Processing framework, we only need to add some code for performing any task (I know, this is the best part of the game! 🙂 ). Happy coding!

Advertisements

3 thoughts on “Basic rules for writing Python scripts for Processing Toolbox in QGIS

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