Introduction to PyQGIS

Site: OpenCourseWare for GIS
Course: Programming for Geospatial Hydrological Applications
Book: Introduction to PyQGIS
Printed by: Guest user
Date: Tuesday, 28 May 2024, 1:23 AM

1. Introduction

In this tutorial you'll be introduced to PyQGIS, the Python library of QGIS.

We'll work on an example script where we create a Stage Volume Curve using PyQGIS within and outside of QGIS.

A Stage Volume Curve or Stage Storage Curve can be used to read which volume of a lake or a pit belongs to a certain water level. It's much easier to measure the water level than the volume, so once the curve is created the volume can be determined in an easy way.

In this tutorial we'll create a Stage Volume Curve for an open pit Lignite mine, but the method is the same for lakes.

After this tutorial you'll be able to

  • calculate the volume below a specific elevation in a DTM
  • use QGIS Processing Tools with PyQGIS in QGIS
  • use PyQGIS in Python without the QGIS user interface
  • create a Stage Volume Curve using PyQGIS and Pandas
The data included in this tutorial comes from the Shuttle Radar Topography Mission: SRTM 1-Arc Second. If you want to apply the tutorial to other areas you can download the data from USGS Earth Explorer.

2. Calculate the volume below a specific elevation

Before we're going to use a QGIS Processing Tool with PyQGIS, we're going to use the tool first through the interface to get familiar with it. In this tutorial we'll use the Raster surface volume tool tool to calculate the volume below a specific elevation in a DTM.

1. Start the Miniforge prompt, activate the Tutorials environment

mamba activate tutorials

2. Run QGIS from the command line, by typing


3. In the main menu go to Project | Open From | GeoPackage.

4. In the Load project from GeoPackage dialogue browse to the provided data_stagevolume.gpkg GeoPackage and open the StageVolume project.

This project has an SRTM 1-Arc Second DEM reprojected to UTM Zone 32N and clipped to the area around the open pit mine. The DEM has been styled with a colour ramp and is blended with a rendered hillshade.

5. Go to Processing | Toolbox to open the Processing Toolbox panel.

6. In the Processing Toolbox choose Raster analysis | Raster surface volume.

7. In the Raster Surface Volume dialogue choose DTM as Input layer, keep Band number as it is and here we keep Base level 0 m, because we want to calculate the volume that is below 0 m. We do that by changing the Method to Count Only Below Base Level. The Surface volume report is an html file. Give it the name volumebelowzero.html. The Surface volume table is a dbf file. We can't choose a dbf file so we save it as volumebelowzero.shp.

8. Click Run.

The Log tab gives the result: 'VOLUME' : -1155480399.7627096

It also gives an error in red. This is because it doesn't create a shapefile but a dbf file. So you can ignore this error.

9. Click Close to close the dialogue.

At the bottom of the Processing Toolbox you can find the Results Viewer.

10. Double click on the Surface volume report or the html link (it links to the same). It will open in your browser. Check the results.

11. Drag the volumebelowzero.dbf file from the Browser panel to the map canvas.

12. Click right on the volumebelowzero table in the Layers panel and choose Open Attribute Table to check the result.

13. Repeat from step 5 for some other elevations.

In the next section we're going to calculate the volumes for many elevations and store the values in one table.

Watch here the result until this step:

3. Create a Stage Volume Table with PyQGIS in QGIS

In the previous section we've calculated the volume corresponding to a specific elevation one by one.

In this section we're going to iteratively calculate the volume for a range of elevations and store the results in one table. For that purpose we need to write a PyQGIS script around the Raster Surface Volume tool.

All processing tools that you've run are stored in the history of the Processing Toolbox. Let's have a look and see how we can use that for our script.

1. In the Processing Toolbox click to open the history.

Algorithm history

There you find what we did in the previous section. Try to read what's written after

It contains the name of the tool: native: rastersurfacevolume. It contains a dictionary with all the inputs from the dialogue. That means that we can copy this and replace parts of the dictionary in a PyQGIS script with a variable. Here we should iterate for different LEVEL values from the minimum to the maximum elevation in the DTM.

2. Click Close to close the History dialogue.

3. In the main menu choose Plugins | Python Console to open the Python Console.

4. In the Python Console click to open the editor.

5. Go to this GitHub page:

6. Copy the Python code to the editor and save the script as

Read the comments to understand what happens in the code. Later we'll look in more detail at the script when we'll work with it outside of the QGIS GUI.

7. The only thing to change is to replace the projectPath and inputRasterDEM with your own names.

8. Save the script and click to run the script.

This is the result printed in the Python Console:

The script has also added a DEM layer and the StageVolume table to the Layers panel.

9. Click right on StageVolume and choose Open Attribute Table and inspect it.

Stage Volume Table

We have created the Stage Volume Table with the Level field in meters and the VolAbsKm3 field containing the volumes in km3.

In the next section we'll create the Stage Volume Curve using the Data Plotly plugin.

Note that you can also add the StageVolumeTool from GitHub to the Processing Toolbox. The tool then has a dialogue. You can download the tool from here:

4. Create a Stage Volume Curve with the Data Plotly plugin

Now we have created the Stage Volume Table we can easily create the Stage Volume Curve with the Data Plotly plugin.

1. Install the Data Plotly plugin from the plugins repository.

2. Click to open the Data Plotly panel.

3. Make sure to choose the Scatter Plot as Plot type and StageVolume as the Layer. The X field is VolAbsKm3 and the Y field is Level.

4. Click

5. Uncheck Show legend. Set the Plot title to Stage Volume, keep the Legend title blank. Change the X label to Volume (km3) and Y label to Level (m).

6. Click

You can save the result as a picture using the button.

From the Stage Volume Curve we can see a sharp change at 86.4 m. That's approximately the elevation of the boundary of the pit.

In the next section we're going to implement the entire procedure in Python using PyQGIS without the QGIS GUI.

Watch this video for the result so far:

5. Create a Stage Volume Curve using PyQGIS without QGIS GUI

For many purposes of automisation it would also be very useful to be able to use PyQGIS in scripts without starting the QGIS graphical user interface.

We're going to explore this and dive deeper in the code that was used before using a Jupyter Notebook.

  1. Open a new Miniforge prompt and activate the tutorials environment.
    mamba activate tutorials
  2. We need to install the Pandas library for this tutorial. Run the following command:
    mamba install pandas
  3. Go to the folder where you want to download the subdirectory with the tutorial.
  4. In the webbrowser go to
  5. Go to Code and copy the https url.
  6. Download the tutorial and data with git:
    git clone
  7. Go to the subdirectory \PyQGISTutorials and run:
    jupyter lab
  8. In the browser go to the subdirectory StageVolumeCurve and double click on PyQGISStageVolume.ipynb to follow the tutorial.

6. Conclusions

In this tutorial you've learned to:

  • calculate the volume below a specific elevation in a DTM
  • use QGIS Processing Tools with PyQGIS in QGIS
  • use PyQGIS in Python without the QGIS user interface
  • create a Stage Volume Curve using PyQGIS and Pandas
There's much more that you can do with PyQGIS besides this example to introduce you to PyQGIS.
Also the tutorials by Ujaval Gandhi are a very useful resource.