Using Qgis Processing Algorithms In Standalone Pyqgis Scripts
QGIS offers a robust set of geoprocessing algorithms and spatial analysis tools through its Processing framework. These powerful algorithms can be accessed directly within standalone Python scripts, allowing automation of complex geospatial workflows without the need to create full QGIS plugins.
This guide provides practical techniques for calling Processing algorithms from PyQGIS scripts. It covers accessing and executing algorithms, processing vector and raster data, optimizing script performance, integrating example scripts, common issues and solutions, and next steps for production deployment.
Accessing Processing Algorithms
The first step is importing the QGIS Processing module and gaining handle to algorithm providers.
Importing Processing Module
The Processing module contains tools for running algorithms and manipulating geospatial data sets. Import this module to enable algorithm execution:
import processing
Accessing Algorithms by Name
With Processing imported, retrieve an algorithm by passing its name to the processing.run() method. Algorithm names generally follow the convention provider_name:algorithm_label.
buffer_alg = processing.run("native:buffer")
This returns a handle to the buffer algorithm from the native QGIS provider, allowing parameters to be set and executed.
Running Algorithms
With an algorithm instance obtained, the next step is configuring parameters and executing to perform the desired geospatial analysis.
Defining Parameters
Algorithms expose a set of parameters controlling their behavior. These can be set by passing a dictionary to the algorithm’s setParameters() method:
params = {
'INPUT': vector_layer,
'DISTANCE': 10,
'SEGMENTS': 5,
'DISSOLVE': True,
'END_CAP_STYLE': 0
}
buffer_alg.setParameters(params)
Parameters correspond directly to those defined for the algorithm within QGIS. Review documentation to understand their meanings before configuring.
Executing Algorithms
After setting parameters, call the algorithm’s processAlgorithm() method to perform the geospatial operation:
buffer_alg.processAlgorithm()
This applies the buffer to the input vector layer based on configured distance/segmentation rules.
Handling Outputs
Algorithms return outputs via the destination parameters passed. Access these to obtain analysis results:
buffered_layer = buffer_alg.outputs['OUTPUT']
For buffer, this contains the polygon layer representing the buffer region around inputs.
Processing Vector Data
Many key QGIS algorithms involve manipulating vector data layers. This section demonstrates applying buffer, clip, and dissolve algorithms to vector inputs.
Buffer Example
Buffer creates polygon layers surrounding point, line or polygon features to specified distances. Call buffer algorithm and configure distance/segmentation parameters:
buffer_alg = processing.run("native:buffer")
params = {
'INPUT': airports_layer,
'DISTANCE': 5000,
'SEGMENTS': 8,
'DISSOLVE': True
}
buffer_alg.setParameters(params)
buffer_alg.processAlgorithm()
buffered_airports = buffer_alg.outputs['OUTPUT']
The above buffers airport points by 5km, outputting a dissolved polygon layer of surrounding areas.
Clip Example
Clip algorithm intersects input layers with certain clipping geometries, returning just overlapping regions:
clip_alg = processing.run("native:clip")
params = {
'INPUT': roads_layer,
'OVERLAY': study_area_layer,
'OUTPUT': 'memory:'
}
clip_alg.setParameters(params)
clip_alg.processAlgorithm()
clipped_roads = clip_alg.outputs['OUTPUT']
Here the roads layer is clipped by the polygon study area layer, creating a temporary memory layer with just intersecting features.
Dissolve Example
Dissolve aggregates geometries from multiple features based on defined attributes:
dissolve_alg = processing.run("native:dissolve")
params = {
'INPUT': regions_layer,
'FIELD': ['district'],
'OUTPUT': 'memory:'
}
dissolve_alg.setParameters(params)
dissolve_alg.processAlgorithm()
dissolved_regions = dissolve_alg.outputs['OUTPUT']
This dissolves the region layer’s geometries by the district field, condensing features sharing same districts.
Processing Raster Data
Key raster processing algorithms in QGIS include generating hillshades, calculating slope, extracting aspects and more. This section provides examples.
Hillshade Example
The hillshade algorithm calculates illumination from defined light sources:
hillshade_alg = processing.run("gdal:hillshade")
params = {
'INPUT': dem_raster,
'Z_FACTOR': 1,
'SCALE': 1,
'AZIMUTH': 315,
'ALTITUDE': 45,
'OUTPUT': 'memory:'
}
hillshade_alg.setParameters(params)
hillshade_alg.processAlgorithm()
hillshade_raster = hillshade_alg.outputs['OUTPUT']
This generates a hillshade raster from the DEM based on 315° azimuth and 45° sun altitude.
Aspect Example
The aspect algorithm calculates azimuth directions that slopes face:
aspect_alg = processing.run("gdal:aspect")
params = {
'INPUT': dem_raster,
'BAND': 1,
'TRIG_ANGLE': False,
'ZERO_FLAT': False,
'OUTPUT': 'memory:'
}
aspect_alg.setParameters(params)
aspect_alg.processAlgorithm()
aspect_raster = aspect_alg.outputs['OUTPUT']
This computes an aspect raster from the DEM input, assigning slope aspects.
Slope Example
Slope calculates maximum rate of elevation change from DEM:
slope_alg = processing.run("gdal:slope")
params = {
'INPUT': dem_raster,
'BAND': 1,
'OUTPUT': 'memory:',
'SCALE': 1
}
slope_alg.setParameters(params)
slope_alg.processAlgorithm()
slope_raster = slope_alg.outputs['OUTPUT']
This generates a slope raster from the input DEM, scaled by a factor of 1.
Optimizing Script Performance
Certain techniques can optimize PyQGIS script performance when processing geoalgorithms.
Avoiding Unnecessary Outputs
Skip writing algorithm outputs unneeded in later analysis using in-memory layers:
params = {
'INPUT': vector_layer,
'OUTPUT': 'memory:'
}
This avoids slower disk writes, improving overall workflow speed.
Leveraging Threading
Set the QGIS_PROCESSOR_MAX_THREADS environment variable to perform geospatial analysis concurrently:
import os
os.environ['QGIS_PROCESSOR_MAX_THREADS'] = '4'
This enables four threads for potential algorithm parallelization.
Caching Reusable Data
Save algorithm results to speed up repeated use as inputs to subsequent operations:
clipped_layer = processing.run(...')['OUTPUT']
processing.run({ 'INPUT': clipped_layer })
Avoiding duplicate geoanalysis improves overall execution efficiency.
Example Scripts
This section demonstrates full PyQGIS scripts leveraging processing algorithms.
Vector Analysis Script
Performs buffer, intersection, and clipping on study regions vector layer:
import processing
study_regions = 'regions.geojson'
protected_areas = 'protected.gpkg'
# Generate 10km buffer regions
buffer_alg = processing.run("native:buffer")
buffer_alg.setParameters({
'INPUT': study_regions,
'DISTANCE': 10000,
'OUTPUT': 'memory:'
})
buffer_alg.processAlgorithm()
buffered_regions = buffer_alg.outputs['OUTPUT']
# Intersect with protected areas
intersect_alg = processing.run("native:intersection")
intersect_alg.setParameters({
'INPUT': buffered_regions,
'OVERLAY': protected_areas,
'INPUT_FIELDS': [''],
'OVERLAY_FIELDS': [''],
'OUTPUT': 'memory:'
})
intersect_alg.processAlgorithm()
intersected = intersect_alg.outputs['OUTPUT']
# Clip original study regions layer
clip_alg = processing.run("native:clip")
clip_alg.setParameters({
'INPUT': study_regions,
'OVERLAY': intersected,
'OUTPUT': 'memory:'
})
clip_alg.processAlgorithm()
clipped_regions = clip_alg.outputs['OUTPUT']
print(f'Processed {clipped_regions.featureCount()} final regions')
Performs vector buffer, intersection and clip via in-memory processing.
Raster Processing Script
Chains hillshade, slope and aspect generation from input DEM:
import processing
dem_raster = 'elevation.tif'
# Hillshade
hillshade_alg = processing.run("gdal:hillshade")
hillshade_alg.setParameters({
'INPUT': dem_raster,
'Z_FACTOR': 1,
'SCALE': 1,
'AZIMUTH': 315,
'ALTITUDE': 45,
'OUTPUT': 'memory:'
})
hillshade_alg.processAlgorithm()
hillshade_raster = hillshade_alg.outputs['OUTPUT']
# Slope
slope_alg = processing.run("gdal:slope")
slope_alg.setParameters({
'INPUT': dem_raster,
'BAND': 1,
'OUTPUT': 'memory:',
'SCALE': 1
})
slope_alg.processAlgorithm()
slope_raster = slope_alg.outputs['OUTPUT']
# Aspect
aspect_alg = processing.run("gdal:aspect")
aspect_alg.setParameters({
'INPUT': dem_raster,
'BAND': 1,
'TRIG_ANGLE': False,
'ZERO_FLAT': False,
'OUTPUT': 'memory:'
})
aspect_alg.processAlgorithm()
aspect_raster = aspect_alg.outputs['OUTPUT']
print('Generated raster outputs from DEM')
Chains hillshade, slope and aspect algorithm execution on input DEM.
Geocoding Script
Geocodes a table of addresses then spatially joins to regions layer:
import processing
addresses = 'addresses.csv'
regions = 'regions.shp'
# Geocode addresses
geocode_alg = processing.run("native:geocode""")
geocode_alg.setParameters({
'INPUT': addresses,
'FIELD': 'address',
'OUTPUT': 'memory:'
})
geocode_alg.processAlgorithm()
geocoded = geocode_alg.outputs['OUTPUT']
# Spatial join to regions
join_alg = processing.run("native:joinattributesbylocation")
join_alg.setParameters({
'TARGET': regions,
'JOIN': geocoded,
'PREDICATE': [0],
'JOIN_FIELDS': ['data'],
'METHOD': 0,
'OUTPUT': 'memory:'
})
join_alg.processAlgorithm()
joined = join_alg.outputs['OUTPUT']
print(f'Geocoded {geocoded.featureCount()} addresses')
print(f'Joined data to {joined.featureCount()} regions')
Geocodes addresses then spatially joins additional data to regions layer.
Common Issues and Solutions
Several common pitfalls arise when scripting processing algorithms.
Algorithm Not Found
InvalidAlgorithmError raised when accessing unnamed algorithm. Verify algorithm names passed to processing.run().
Invalid Parameter Errors
Review algorithm documentation to ensure parameters set correctly before executing.
Output Format Errors
If outputs fail ensure destination formats compatible with algorithm. Specify output types like memory: to avoid constraints.
Next Steps
By themselves, PyQGIS scripts enable batch analysis automation. Several paths exist for further leveraging their potential.
Integrating PyQGIS Scripts into Plugins
Reuse scripts by importing within custom QGIS plugin logic. This provides user interfaces, integrated debugging, and deployment.
Deploying Scripts into Production
Containerize scripts via Docker and Kubernetes for scalable distributed geospatial processing in cloud environments.
Creating Custom Algorithms
Develop reusable custom geoalgorithms in Python by subclassing the GeoAlgorithm class. These integrate seamlessly as native operations.