Introductie

Dit document is 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.

Beginnend met de uitgave 0.9, heeft QGIS optionele ondersteuning voor scripten met behulp van de taal Python. We hebben gekozen voor Python omdat het één van de meest favoriete talen voor scripten is. Bindingen voor PyQGIS zijn afhankelijk van SIP en PyQt4. De reden voor het gebruiken van SIP in plaats van het meer wijd gebruikte SWIG is dat de gehele code voor QGIS afhankelijk is van bibliotheken van Qt. Bindingen voor Python voor Qt (PyQt) worden ook gedaan met behulp van SIP en dat maakt een naadloze integratie van PyQGIS met PyQt mogelijk.

TODO:

PyQGIS laten werken (handmatig compileren, probleemoplossing)

Er bestaan verscheidene manieren om bindingen van Python voor QGIS te gebruiken, zij worden in detail behandeld in de volgende gedeelten:

  • Python-code automatisch uitvoeren wanneer QGIS start

  • opdrachten opgeven in de console voor Python in QGIS

  • plug-ins in Python maken en gebruiken

  • aangepaste toepassingen maken, gebaseerd op de API van QGIS

Er is een verwijzing complete API voor QGIS dat de klassen uit de bibliotheken van QGIS documenteert. Pythonische API voor QGIS is nagenoeg identiek aan de API in C++.

Er bestaan enkele bronnen over het programmeren met PyQGIS op het QGIS blog. Bekijk QGIS tutorial ported to Python voor enkele voorbeelden van eenvoudige toepassingen van 3e partijen. Een goede bron voor het werken met plug-ins is om enkele plug-ins te downloaden vanaf plugin repository en hun code te bestuderen. Ook bevat de map python/plugins/ in uw installatie van QGIS enkele plug-ins die u kunt gebruiken om te leren hoe een dergelijk plug-in wordt ontwikkeld en hoe enkele van de meest voorkomende taken uit te voeren

Python-code uitvoeren wanneer QGIS start

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

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 methode is iets wat u vermoedelijk zelden nodig heeft, maar is het waard vermeld te worden omdat het één van de manieren is om Python-code uit te voeren binnen QGIS en omdat 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.

Het bestand startup.py

Elke keer als QGIS start, wordt in de eigen map van de gebruiker voor Python (gewoonlijk: .qgis2/python) naar een bestand genaamd startup.py gezocht. Als dat bestand bestaat wordt het uitgevoerd door de ingebedde interpreter voor Python.

Python-console

Voor scripten is het mogelijk om voordeel te halen uit de geïntegreerde console voor Python. Deze kan geopend worden via het menu: Plug-ins ‣ Python Console. De console opent als een non-modaal gebruiksvenster.

../../_images/console.png

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 anatal objecten weer te geven. Voor interactie et de omgeving van QGIS is er de 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 menu Extra ‣ Snelkoppelingen configureren...)

Plug-ins in Python

QGIS maakt het mogelijk zijn functionaliteit te verbeteren met behulp van plug-ins. Dit was oorspronkelijk alleen mogelijk met de taal C++. Met de toevoeging van ondersteuning voor Python aan QGIS, is het ook mogelijk plug-ins te gebruiken die 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 Plugin Repositories voor verscheidene bronnen voor plug-ins.

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

Toepassingen in Python

Bij het verwerken van gegevens van GIS is het vaak handig om enkele scripts te maken voor het automatiseren van het proces in plaats van dezelfde taak steeds opnieuw te herhalen. Met PyQGIS is dit perfect mogelijk — importeer de module qgis.core, initialiseer die en u bent klaar om te verwerken.

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

PyQGIS gebruiken in aangepaste toepassing

Opmerking: gebruik niet qgis.py als een naam voor uw testscript — Python zal niet in staat zijn de bindingen te importeren omdat de naam van het script die zal overschaduwen.

Als eerste dient u de module qgis te importeren, het pad voor QGIS in te stellen waar gezocht moet worden naar bronnen — database van projecties, providers etc. Wanneer u het prefix-pad instelt met als tweede argument ingesteld True, zal QGIS alle paden met standaard dir onder de map van de prefix initialiseren. Aanroepen van de functie initQgis() is belangrijk om QGIS te laten zoeken naar de beschikbare providers.

from qgis.core import *

# supply path to where is your qgis installed
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# load providers
QgsApplication.initQgis()

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 :-)

Wanneer u klaar bent met het gebruiken van de bibliotheek van QGIS, roep exitQgis() aan om er voor te zorgen dat alles wordt opgeruimd (bijv. het register van kaartlagen legen en lagen verwijderen):

QgsApplication.exitQgis()

Aangepaste toepassingen uitvoeren

U zult uw systeem moeten vertellen waar te zoeken naar de bibliotheken van QGIS en de toepasselijke modules voor Python als zij nog niet op ene bekende locatie staan — anders zal Python gana 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 wordne 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

Het pad naar de modules van PyQGIS is nu bekend, zij zijn echter afhankelijk van de bibliotheken qgis_core en qgis_gui (de modules van Python dienen slechts als verpakkingen). Het pad naar deze bibliotheken is meestal onbekend voor het besturingssysteem, dus krijgt u opnieuw een fout bij het importeren (het bericht kan variëren, afhankelijk van het systeem):

>>> import qgis.core
ImportError: libqgis_core.so.1.5.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;%PATH%

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 op zijn platform installeert, voorafgaand aan het installeren van uw toepassing. Het installatieprogramma van de 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 - rol een zelfstandige toepassing uit op Windows en Mac OS X, laat voor Linux de installatie van QGIS over aan de gebruiker en diens pakketbeheer.