QGIS's versatility is due mainly to two reasons. The first is the ability to customize it by adding functions, thanks to its plugin structure. The second is the power of the Processing Toolbox, which can connect different backend algorithms such as R, GRASS GIS, SAGA, GDAL/OGR, Orfeo Toolbox, OSM Overpass, and many more, with dedicated providers.
In this way, for example, we can access all GRASS processing algorithms by using QGIS as the project and presentation manager. Another important ability of the Processing Toolbox is that it can be used to join together all the backend algorithms, allowing you to connect the best algorithms. For example, we can connect GRASS as a producer for another algorithm that is better developed in another backend such as SAGA. Here, QGIS processing becomes the place where you can add your specific algorithm in a more complex and integrated workflow.
This section is focused on how to code the execution of algorithms that are already available in the Processing Toolbox. The main points to learn are as follows:
- Looking for a Processing Toolbox algorithm
- Discovering parameters accepted by the algorithm
- Running the algorithm
In the following sections, we will be using the processing commands after we have imported the processing module with the following code:
import processing
If the processing module is not imported, every processing command will generate an error such as the following one:
Traceback (most recent call last): File "<input>", line 1, in <module> NameError: name 'processing' is not defined
The Processing Toolbox contains a huge list of algorithms that can be searched for using keywords. Similar to how we can look for an algorithm in the Processing Toolbox GUI, it's possible to search for an algorithm using the PyQGIS commands.
For example, to look for commands to convert something, we can execute the following command in the Python console:
import processing
processing.alglist("convert")This will generate some output lines, and among them, we will find the command that we are looking for:
Convert format--------------------------------------->gdalogr:convertformat
If it's not the previous command, it can be this (depending on the Processing Toolbox version):
Convert format--------------------------------------->gdalogr:ogr2ogr
This string is composed of two parts; Convert format is the command as shown in the Processing Toolbox GUI, and gdalogr:convertformat is the command recognized by the processing commander. This means that in our PyQGIS script, we can refer to the algorithm with the name gdalogr:convertformat. In this case, the ogr2ogr algorithm belongs to the gdalogr backend. The alglist method looks for only the left part. Notice that the alglist method will also show custom scripts. This means that a custom script or model will be accessible in the PyQGIS interface of the Processing Toolbox.
Every processing algorithm has its own GUI, with input and output parameters. You may wonder about the parameters, their names, and the values that may be used in the same algorithm using PyQGIS scripts. To discover these elements, we will use the alghelp processing command.
This command accepts the command name that is used internally by processing as a parameter; for example, the gdalogr:ogr2ogr string that we saw in the previous paragraph. We can get help for this command by using the following code:
import processing
processing.alghelp("gdalogr:convertformat")The preceding code snippet will produce the following output, which would depend on the installed version of GDAL/OGR:
processing.alghelp("gdalogr:convertformat") ALGORITHM: Convert format INPUT_LAYER <ParameterVector> FORMAT <ParameterSelection> OPTIONS <ParameterString> OUTPUT_LAYER <OutputVector> FORMAT(Destination Format) 0 - ESRI Shapefile 1 - GeoJSON 2 - GeoRSS 3 - SQLite ...[cut]... 20 - XLSX 21 - PDF
As you can see, these are the same parameters that were accepted in the algorithm GUI. There is also the list of format-accepted values.
Running a processing algorithm can be done by using the runalg method or the runandload method. The first one generates the output without visualizing it and is useful when you want to generate temporary data. The second method loads and visualizes the output layer in QGIS.
The parameters accepted in this method are the processing command name strings followed by all the parameters, depending on the command used.
We will perform an exercise and convert the alaska.shp shapefile, which is available in qgis_sample_data/shapefiles, into the SpatiaLite format. This format is a very powerful SQLite spatial database that creates a self-contained spatial database in a single file. The SQLite format is referred to with the value 3, as specified in the algorithm help shown earlier.
To export algorithms into this format, we'll follow these steps:
- Load the Alaska shapefile in QGIS
- Get the
QgsVectorLayerof the loaded vector - Run the convert algorithms
- Load the result in QGIS
Assuming that the alaska.shp shapefile has been loaded in QGIS, we will run the algorithm based on the parameters shown in the previous section; this is done using the following snippet:
myVector = iface.activeLayer()
processing.runalg("gdalogr:convertformat", myVector, 3, None, "F:/temp/alaska")In the preceding code, it should be noted that the fourth parameter is None instead of an empty string, but for the Processing Toolbox, they are equivalent. The fifth parameter is the output filename, but it could be set to None. In this case, the output will be generated in a temporary file.
The return value of runalg is a dictionary with a key and the output name as specified in the alghelp, and the value of the key is the reference of the filename generated by the algorithm. In the preceding example, the output dictionary is something like the {'OUTPUT_LAYER': 'F:/temp/alaska.sqlite'} dictionary.
The last step is displaying the layer. This can be done in two ways: by loading a vector layer as usual, or by running the algorithm with the runandload method, as specified earlier. In this case, the following code will generate and load a new layer displaying it:
processing.runandload("gdalogr:convertformat", myVector, 3, None, "F:/temp/alaska")
Running a custom processing script is not much different from running a generic processing command. We only need to find out how the custom script is addressed by the toolbox.
To discover all this information, we will create and run a simple processing script.
We will start by opening the Processing Toolbox by navigating to Processing | Toolbox. Next, navigate to Scripts | Tools | Create new script in the toolbox. These actions will open a new interface, where we can paste the following code snippet:
import time
for index in range(100):
progress.setPercentage(index)
print index
time.sleep(0.1)We will save it with the name emptyloop. The code is shown in the following screenshot:
The default directory where processing will look for user scripts is <your home dir>/.qgis2/processing/scripts/.
So, our file script will be available with the name <your home dir>/.qgis2/processing/scripts/emptyloop.py.
The preceding script will count from 0 to 99. In addition, the algorithm will set the progress bar and write the step number in the Python console. The last instruction will wait for 0.1 seconds before running a loop again.
Now, run the following processing command:
processing.alglist("empty")This will generate the following output:
emptyloop-------------------------------------------->script:emptyloop
This shows that the Processing Toolbox knows our custom script with the name script:emptyloop.
We can run the custom script as usual in the Python console with the following command:
processing.runalg("script:emptyloop")
This will increment the progress bar and print the progress in the console, as shown in the following screenshot:
In this case, the progress bar will be opened in QgsMessageBar in the QGIS canvas because the algorithm is executed from the Python console.