1. Introductie

Dit document is zowel bedoeld om te gebruiken als handleiding en als gids met verwijzingen. Hoewel het niet alle mogelijke gevallen van gebruik weergeeft zou het een goed overzicht moeten geven van de belangrijkste functionaliteiten.

Iedereen heeft het recht om dit document te kopiëren, te verspreiden en aan te passen onder de voorwaarden van de GNU Free Documentation License, Version 1.3 of een latere versie gepubliceerd door de Free Software Foundation; De voor- en achterkant en de inhoudelijke indeling van het document dient gelijk te blijven.

Een kopie van de licentie is opgenomen in het gedeelte GNU Free Documentation License.

Deze licentie is ook van toepassing op alle codesnippers in dit document.

Ondersteuning voor Python werd voor het eerst geïntroduceerd in QGIS 0.9. Er zijn verscheidene manieren om Python te gebruiken QGIS Desktop (worden in de volgende gedeelten behandeld):

  • Opdrachten opgeven in de console voor Python in QGIS

  • Plug-ins in Python maken en gebruiken

  • Python-code automatisch uitvoeren wanneer QGIS start

  • Algoritmen voor Processing maken

  • Functies voor expressies in QGIS maken

  • Aangepaste toepassingen maken, gebaseerd op de API van QGIS

Python-bindings zijn ook beschikbaar voor QGIS Server, inclusief plug-ins voor Python (zie QGIS Server en Python) en Python-bindings die kunnen worden gebruikt om QGIS Server in te bedden in een toepassing van Python.

Er is een verwijzing complete C++ API voor QGIS dat de klassen uit de bibliotheken van QGIS documenteert. The Pythonic QGIS API (pyqgis) is nagenoeg identiek aan de API voor C++.

Een andere goede bron voor het leren hoe algemene taken uit te voeren is om bestaande plug-ins te downloaden vanaf de opslagplaats voor plug-ins en de code ervan te bestuderen.

1.1. Scripten in de console voor Python

QGIS verschaft een geïntegreerde Python console voor scripten. Deze kan geopend worden via het menu Plug-ins ► Python Console:

../../_images/console.png

Fig. 1.4 QGIS Python-console

De schermafdruk hierboven illustreert hoe de huidige geselecteerde laag in de Lagenlijst te verkrijgen, de ID ervan weer te geven en optioneel, als het een vectorlaag is, het aantal objecten weer te geven. Voor interactie met de omgeving van QGIS is er een variabele iface, wat een instance is van QgsInterface. Deze interface maakt toegang mogelijk tot het kaartvenster, menu’s, werkbalken en andere delen van de toepassing QGIS.

Voor het gemak van de gebruiker zullen de volgende argumenten worden uitgevoerd wanneer de console wordt opgestart (in de toekomst zal het mogelijk zijn meer initiële opdrachten in te stellen)

from qgis.core import *
import qgis.utils

Voor hen die de console vaak gebruiken, kan het handig zijn een sneltoets in te stellen voor het activeren van de console (in Extra ► Toetsenbord sneltoetsen…)

1.2. Plug-ins in Python

De functionaliteit van QGIS kan worden uitgebreid met plug-ins. Plug-ins mogen zijn geschreven in Python. Het belangrijkste voordeel boven plug-ins van C++ is de eenvoudige manier van verdelen (niet meer nodig om te compileren voor elk platform) en eenvoudiger ontwikkelen.

Veel plug-ins, die verschillende functionaliteiten behandelen, zijn geschreven sinds de introductie van ondersteuning voor Python. Het installatieprogramma voor plug-ins stelt gebruikers in staat om eenvoudig plug-ins voor Python op te halen, bij te werken en te verwijderen. Bekijk de pagina Python Plugins voor meer informatie over plug-ins en het ontwikkelen van plug-ins.

Plug-ins maken in Python is simpel, zie Python plug-ins ontwikkelen voor gedetailleerde instructies.

Notitie

Plug-ins voor Python zijn ook beschikbaar voor QGIS Server. Bekijk QGIS Server en Python voor meer details.

1.3. Python-code uitvoeren wanneer QGIS start

Er zijn twee afzonderlijke methoden om Python-code uit te voeren elke keer als QGIS start.

  1. Een script startup.py schrijven

  2. Instellen van de omgevingsvariabele PYQGIS_STARTUP naar een bestaand bestand voor Python

1.3.1. Het bestand startup.py

Elke keer als QGIS start, wordt in de thuismap voor Python van de gebruiker

  • Linux: .local/share/QGIS/QGIS3

  • Windows: AppData\Roaming\QGIS\QGIS3

  • macOS: Library/Application Support/QGIS/QGIS3

gezocht naar een bestand genaamd startup.py. Als dat bestand bestaat wordt het door de ingebedde interpreter van Python uitgevoerd.

Notitie

Het standaard pad is afhankelijk van het besturingssysteem. Open, om het pad te zoeken dat voor u zal werken, de console voor Python en voer QStandardPaths.standardLocations(QStandardPaths.AppDataLocation) uit om de lijst met de standaard mappen te zien.

1.3.2. De omgevingsvariabele PYQGIS_STARTUP

U kunt Python-code uitvoeren kort voor de initialisatie van QGIS wordt voltooid door de omgevingsvariabele PYQGIS_STARTUP in te stellen op het pad van een bestaand bestand van Python.

Deze code zal worden uitgevoerd vóórdat de initialisatie van QGIS is voltooid. Deze methode is zeer handig voor het opschonen van sys.path, wat ongewenste paden zou kunnen bevatten, of voor het isoleren/laden van de initiële omgeving zonder een virtuele omgeving te vereisen, bijv. homebrew of installaties van MacPorts op Mac.

1.4. Toepassingen in Python

Het is vaak handig om enkele scripts te maken voor het automatiseren van processen. Met PyQGIS is dit perfect mogelijk — importeer de module https://qgis.org/pyqgis/3.16/qgis.core <core>QGIS, initialiseer die en u bent klaar om te verwerken.

Of u wilt misschien een interactieve toepassing maken die functionaliteit van GIS gebruikt — metingen uitvoeren, exporteren van een kaart als PDF, …. De module qgis.gui geeft verscheidene componenten voor een GUI, waarvan de meest belangrijke de widget voor het kaartvenster is die kan worden opgenomen in de toepassing met ondersteuning voor zoomen, pannen en/of elke andere aangepaste gereedschappen voor de kaart.

Aangepaste toepassingen of zelfstandige scripts voor PyQGIS moeten worden geconfigureerd om de bronnen van QGIS te kunnen vinden, zoals informatie over de projectie en providers voor het lezen van vector- en rasterlagen. Bronnen voor QGIS worden geïnitialiseerd door een aantal regels toe te voegen aan het begin van uw toepassing of script. De code om QGIS voor aangepaste toepassingen en zelfstandige scripts te initialiseren is soortgelijk. Voorbeelden voor elk daarvan worden hieronder vermeld.

Notitie

Gebruik niet qgis.py als naam voor uw script. Python zal niet in staat zijn de bindingen te importeren omdat de naam van het script die zal overschaduwen.

1.4.1. PyQGIS gebruiken in zelfstandige scripts

Initialiseer, om een zelfstandig script te starten, de bronnen voor QGIS aan het begin van het script:

 1from qgis.core import *
 2
 3# Supply path to qgis install location
 4QgsApplication.setPrefixPath("/path/to/qgis/installation", True)
 5
 6# Create a reference to the QgsApplication.  Setting the
 7# second argument to False disables the GUI.
 8qgs = QgsApplication([], False)
 9
10# Load providers
11qgs.initQgis()
12
13# Write your code here to load some layers, use processing
14# algorithms, etc.
15
16# Finally, exitQgis() is called to remove the
17# provider and layer registries from memory
18qgs.exitQgis()

Eerst importeren we de module qgis.core en configureren dan het pad voor het voorvoegsel. Het pad voor het voorvoegsel is de locatie waar QGIS is geïnstalleerd op uw systeem. Het wordt in het script geconfigureerd door de methode setPrefixPath() aan te roepen. Het tweede argument van setPrefixPath() wordt ingesteld op True en specificeert dat de standaardpaden worden gebruikt.

Het pad voor de installatie van QGIS varieert per platform; de eenvoudigste manier om het voor uw systeem te vinden is door de Scripten in de console voor Python te gebruiken vanuit QGIS en te kijken naar de uitvoer bij het uitvoeren van:

QgsApplication.prefixPath()

Nadat het pad voor het voorvoegsel is geconfigureerd slaan we een verwijzing naar QgsApplication op in de variabele qgs. Het tweede argument wordt ingesteld op False, wat specificeert dat we niet van plan zijn om de GUI te gebruiken omdat we een zelfstandig script schrijven. Met QgsApplication geconfigureerd laden we de gegevensproviders en registratie van lagen voor QGIS door de methode initQgis() aan te roepen.

qgs.initQgis()

Met QGIS geïnitialiseerd zijn we klaar om de rest van het script te schrijven. Tenslotte sluiten we af door de methode exitQgis() aan te roepen om de gegevensproviders en registratie van lagen uit het geheugen te verwijderen.

qgs.exitQgis()

1.4.2. PyQGIS gebruiken in aangepaste toepassing

Het enige verschil tussen PyQGIS gebruiken in zelfstandige scripts en een aangepaste toepassing van PyQGIS is het tweede argument bij het instantiëren van QgsApplication. Geef True op in plaats van False om aan te geven dat we van plan zijn om een GUI te gaan gebruiken.

 1from qgis.core import *
 2
 3# Supply the path to the qgis install location
 4QgsApplication.setPrefixPath("/path/to/qgis/installation", True)
 5
 6# Create a reference to the QgsApplication.
 7# Setting the second argument to True enables the GUI.  We need
 8# this since this is a custom application.
 9
10qgs = QgsApplication([], True)
11
12# load providers
13qgs.initQgis()
14
15# Write your code here to load some layers, use processing
16# algorithms, etc.
17
18# Finally, exitQgis() is called to remove the
19# provider and layer registries from memory
20qgs.exitQgis()

Nu kunt u werken met de API van QGIS - lagen laden en enige verwerking doen of een GUI met een kaartvenster opstarten. De mogelijkheden zijn eindeloos :-)

1.4.3. Aangepaste toepassingen uitvoeren

U moet uw systeem vertellen waar te zoeken naar de bibliotheken van QGIS en de toepasselijke modules voor Python als zij nog niet op een bekende locatie staan - anders zal Python gaan klagen:

>>> import qgis.core
ImportError: No module named qgis.core

Dit kan worden opgelost door de omgevingsvariabele PYTHONPATH in te stellen. In de volgende opdrachten zou <qgispath> moeten worden vervangen door uw actuele pad voor de installatie van QGIS:

  • op Linux: export PYTHONPATH=/<qgispath>/share/qgis/python

  • op Windows: set PYTHONPATH=c:\<qgispath>\python

  • op macOS: export PYTHONPATH=/<qgispath>/Contents/Resources/python

Nu is het pad naar de modules van PyQGIS bekend, maar zij zijn afhankelijk van de bibliotheken qgis_core en qgis_gui (de modules van Python dienen slechts als verpakkingen). Het pad naar deze bibliotheken zou onbekend kunnen zijn voor het besturingssysteem, en dan zult u opnieuw een fout bij het importeren krijgen (het bericht kan variëren, afhankelijk van het systeem):

>>> import qgis.core
ImportError: libqgis_core.so.3.2.0: cannot open shared object file:
  No such file or directory

Los dit op door de mappen waar de bibliotheken van QGIS zijn opgeslagen toe te voegen aan het zoekpad van de dynamische linker:

  • op Linux: export LD_LIBRARY_PATH=/<qgispath>/lib

  • op Windows: set PATH=C:\<qgispath>\bin;C:\<qgispath>\apps\<qgisrelease>\bin;%PATH% waar <qgisrelease> zou moeten worden vervangen door het type uitgave dat uw doel is (bijv, qgis-ltr, qgis, qgis-dev)

Deze opdrachten kunnen worden geplaatst in een bootstrap-script dat het opstarten voor zijn rekening zal nemen. Bij het uitrollen van toepaste toepassingen met behulp van PyQGIS, zijn er gewoonlijk twee mogelijkheden:

  • eis dat de gebruiker QGIS installeert, voorafgaand aan het installeren van uw toepassing. Het installatieprogramma van de toepassing zou moeten zoeken naar standaardlocaties voor de bibliotheken van QGIS en de gebruiker moeten toestaan het pad in te vullen als dat niet werd gevonden. Deze benadering heeft het voordeel dat het eenvoudiger is, het vereist echter dat de gebruiker meer stappen uitvoert.

  • verpak QGIS tezamen met uw toepassing. Uitgeven van de toepassing ka uitdagender zijn en het pakket zal groter zijn, maar de gebruiker zal verlost zijn van de last van het downloaden en installeren van aanvullende stukken software.

De twee modellen van uitrollen kunnen worden gemixt. U kunt zelfstandige toepassingen uitrollen op Windows en macOS, maar voor Linux de installatie van GIS overlaten aan de gebruiker en diens pakketbeheer.

1.5. Technische opmerkingen over PyQt en SIP

We hebben gekozen voor Python omdat het één van de meest favoriete talen voor scripten is. Bindingen voor PyQGIS in QGIS 3 zijn afhankelijk van SIP en PyQt5. De reden voor het gebruiken van SIP in plaats van het meer breder gebruikte SWIG is dat de gehele code voor QGIS afhankelijk is van bibliotheken van Qt. Bindingen voor Python voor Qt (PyQt) worden gedaan met SIP en dat maakt een naadloze integratie van PyQGIS met PyQt mogelijk.