1. Introduzione

Questo documento vuole essere sia un’esercitazione che un manuale. Anche se non elenca tutti i possibili casi, dovrebbe comunque fornire una buona panoramica delle funzioni principali.

È consentita la copia, la distribuzione e/o la modifica di questo documento secondo i termini della GNU Free Documentation License, versione 1.3 o qualsiasi versione successiva pubblicata dalla Free Software Foundation; senza sezioni non modificabili, senza testi di copertina e senza testi di quarta di copertina.

Una copia della licenza è inclusa nella sezione GNU General Public License.

Questa licenza si applica anche a tutti gli esempi di codice in questo documento.

Il supporto Python è stato introdotto per la prima volta in QGIS 0.9. Ci sono diversi modi per utilizzare Python in QGIS Desktop (trattato nelle seguenti sezioni):

  • Tramite i comandi nella console Python in QGIS

  • Crea e usa plugin

  • Esegui automaticamente il codice Python all’avvio di QGIS

  • Crea algoritmi di elaborazione

  • Crea funzioni per espressioni in QGIS

  • Create custom applications based on the QGIS API

Python è disponibile anche per QGIS Server, inclusi i plugin Python (vedi QGIS Server e Python) e i collegamenti Python che possono essere utilizzati per incorporare il server QGIS in un’applicazione Python.

C’è un riferimento complete QGIS C++ API che documenta le classi delle librerie QGIS. The Pythonic QGIS API (pyqgis) è quasi identico all’API C++.

Un’altra buona risorsa per imparare come svolgere operazioni comuni è scaricare i plugin esistenti dal repository dei plugin <https://plugins.qgis.org/>`_ ed esaminare il loro codice.

1.1. Scripting nel terminale python

QGIS fornisce un terminale python. Puoi aprirlo dal menu Plugins ► Python Console :

../../_images/console.png

Fig. 1.4 Console python di GIS

La schermata sopra ti mostra come puoi prendere il layer attualmente selezionato nell’elenco dei layer, mostrare il suo ID e, facoltativamente, se è un vettore, ti può mostrare il conteggio degli elementi. Per l’interazione con l’ambiente QGIS, esiste una variabile iface, che è un’istanza della :classe:`QgisInterface <qgis.gui.QgisInterface>`. Questa interfaccia ti consente l’accesso all’area della mappa, ai menu, alle barre degli strumenti e ad altre parti di QGIS.

Per comodità, esegui le seguenti istruzioni all’avvio del terminale (in futuro sarà possibile impostare ulteriori comandi iniziali)

from qgis.core import *
import qgis.utils

Se fai spesso uso del terminale, può essere utile impostare una scorciatoia per attivarlo (con Impostazioni ► Scorciatoie da tastiera…)

1.2. Plugin Python

Puoi estendere i comandi di QGIS tramite plugin, che possono essere scritti in python. Il vantaggio principale rispetto ai plugin C ++ è la semplicità della distribuzione (nessuna compilazione per ogni piattaforma) e uno sviluppo più semplice.

Molti plugin che coprono varie funzionalità sono stati scritti dal supporto Python. Il programma di installazione del plugin ti consente di recuperare, aggiornare e rimuovere facilmente i plugin python. Vedi la pagina Python Plugins <https://plugins.qgis.org/> per maggiori informazioni sui plugin e sullo sviluppo dei plugin.

Creare un plugin in python è semplice, vedi Sviluppo di plugin Python per avere istruzioni dettagliate.

Nota

I plugin python sono disponibili anche per il server QGIS. Per ulteriori dettagli, vedi QGIS Server e Python .

1.2.1. Plugin Processing

I Plugin Processing possono essere utilizzati per elaborare i dati. Sono più facili da sviluppare, più specifici e più leggeri dei plugin Python. Scrivere un plugin di Processing spiega quando l’uso degli algoritmi di Processing è appropriato e come svilupparli.

1.3. Esegui il codice Python all’avvio di QGIS

Esistono diversi metodi per eseguire il codice Python a ogni avvio di QGIS.

  1. Crea uno script startup.py

  2. Configura la variabile ambientale PYQGIS_STARTUP per un file python esistente

  3. Specificando uno script di avvio usando il parametro --code init_qgis.py.

1.3.1. Il file startup.py

Ad ogni avvio di QGIS, la cartella home di Python dell’utente e un elenco di percorsi di sistema vengono cercati per trovare un file chiamato startup.py. Se questo file esiste, viene eseguito dall’interprete Python incorporato.

Il percorso nella cartella home dell’utente si trova solitamente sotto:

  • Linux: .local/share/QGIS/QGIS3

  • Windows: AppData\Roaming\QGIS\QGIS3

  • macOS: Library/Application Support/QGIS/QGIS3

I percorsi di sistema predefiniti dipendono dal sistema operativo. Per trovare i percorsi che fanno al tuo caso, apri la console di Python ed esegui QStandardPaths.standardLocations(QStandardPaths.AppDataLocation) per vedere l’elenco delle cartelle predefinite.

Lo script startup.py viene eseguito immediatamente dopo l’inizializzazione di python in QGIS, nella fase di avvio dell’applicazione.

1.3.2. La variabile ambientale `PYQGIS_STARTUP

Puoi eseguire il codice Python appena prima del completamento dell’inizializzazione di QGIS impostando la variabile ambiente PYQGIS_STARTUP sul percorso di un file Python esistente.

Questo codice verrà eseguito prima del completamento dell’inizializzazione di QGIS. Questo metodo è molto utile per pulire sys.path, che può avere percorsi indesiderati, o per isolare/caricare l’ambiente iniziale senza richiedere un ambiente virtuale, ad es. homebrew o MacPorts si installa su Mac.

1.3.3. Il parametro --code

Puoi fornire codice personalizzato da eseguire come parametro di avvio di QGIS. A tale scopo, crea un file python, ad esempio qgis_init.py, per eseguire e avviare QGIS dalla linea di comando usando qgis --code qgis_init.py.

Il codice fornito tramite ``–code”” viene eseguito in una fase successiva alla fase di inizializzazione di QGIS, dopo che i componenti dell’applicazione sono stati caricati.

1.3.4. Argomenti aggiuntivi per Python

Per fornire argomenti aggiuntivi allo script --code'' o ad altro codice python che viene eseguito, si può usare l'argomento ``--py-args''. Qualsiasi argomento che viene dopo ``--py-args e prima di un argomento -- (se presente) verrà passato a Python ma ignorato dall’applicazione QGIS stessa.

Nell’esempio seguente, myfile.tif sarà disponibile tramite sys.argv in Python ma non sarà caricato da QGIS. Mentre otherfile.tif sarà caricato da QGIS ma non è presente in sys.argv.

qgis --code qgis_init.py --py-args myfile.tif -- otherfile.tif

Se vuoi accedere a ogni parametro della linea di comando da Python, puoi usare QCoreApplication.arguments().

QgsApplication.instance().arguments()

1.4. Applicazioni Python

È spesso comodo creare degli script per automatizzare i processi. Con PyQGIS, questo è perfettamente possibile — importa il modulo qgis.core, inizializzalo e sei pronto per l’elaborazione.

Oppure potresti voler creare un’applicazione interattiva che usi le funzionalità GIS — eseguire misurazioni, esportare una mappa in PDF, … Il modulo qgis.gui fornisce vari componenti dell’interfaccia grafica, in particolare il widget dell’area grafica della mappa che può essere incorporato nell’applicazione con il supporto per lo zoom, la panoramica e/o qualsiasi altro strumento personalizzato della mappa.

Le applicazioni personalizzate PyQGIS o i singoli script autonomi devono essere configurati per individuare le risorse QGIS, come le informazioni di proiezione e gli operatori per la lettura dei vettori e dei raster. Le risorse di QGIS vengono inizializzate aggiungendo alcune righe all’inizio dell’applicazione o dello script. Il codice per inizializzare QGIS per applicazioni personalizzate e singoli script è simile. Di seguito sono riportati esempi di ciascuno.

Nota

Non usare qgis.py come nome per il tuo script. Python non sarà in grado di importare i collegamenti poiché il nome dello script li confonderà.

1.4.1. Usare PyQGIS in script

Per avviare un singolo script, attiva le risorse QGIS all’inizio dello 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()

Prima importiamo il modulo qgis.core e configuriamo il prefisso del percorso. Il prefisso del percorso è la posizione in cui QGIS è installato sul tuo sistema. Viene configurato nello script chiamando il metodo setPrefixPath(). Il secondo parametro di setPrefixPath() è impostato a True, specificando che i percorsi predefiniti devono essere usati.

Il percorso di installazione di QGIS varia a seconda della piattaforma; il modo più semplice per trovarlo per il tuo sistema è usare il Scripting nel terminale python dall’interno di QGIS e controllare il risultato della sua esecuzione:

QgsApplication.prefixPath()

Dopo aver configurato il prefisso del percorso, salviamo un riferimento a QgsApplication nella variabile qgs. Il secondo parametro è impostato a False, specificando che non abbiamo intenzione di usare la GUI poiché stiamo scrivendo uno script standalone. Con QgsApplication configurato, carichiamo i fornitori di dati QGIS e il registro dei layer chiamando il metodo initQgis().

qgs.initQgis()

Con QGIS inizializzato, siamo pronti a scrivere il resto dello script. Infine, concludiamo chiamando exitQgis() per rimuovere i data provider e il registro dei layer dalla memoria.

qgs.exitQgis()

1.4.2. Usare PyQGIS in applicazioni personalizzate

L’unica differenza tra Usare PyQGIS in script e un’applicazione PyQGIS personalizzata è il secondo parametro quando si istanzia la QgsApplication. Imposta True invece di False per indicare che abbiamo intenzione di usare una GUI.

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

Ora puoi lavorare con l’API QGIS: caricare i livelli ed eseguire alcune elaborazioni o avviare una GUI con un’area della mappa. Le possibilità sono infinite :-)

1.4.3. Avviare applicazioni personalizzate

Devi dire al tuo sistema dove cercare le librerie QGIS e i moduli Python se non si trovano in una posizione già nota, altrimenti Python lo segnalerà:

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

Puoi risolvere impostando la variabile ambiente PYTHONPATH. Nei seguenti comandi, <qgispath> deve essere sostituito con il percorso di installazione di QGIS:

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

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

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

Ora, il percorso dei moduli PyQGIS è noto, ma questi dipendono dalle librerie qgis_core e qgis_gui (i moduli Python servono solo come contenitori). Il percorso di queste librerie potrebbe essere sconosciuto al sistema operativo, quindi verrà visualizzato nuovamente un errore di importazione (il messaggio potrebbe variare in base al sistema):

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

Risolvi questo aggiungendo le cartelle delle librerie QGIS nel percorso di ricerca del collegamento dinamico:

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

  • su Windows: set PATH=C:\<qgispath>\bin;C:\<qgispath>\apps\<qgisrelease>\bin;%PATH% dove <qgisrelease> dovrebbe essere sostituito con il tuo tipo di versione (es. qgis-ltr, qgis, qgis-dev)

Questi comandi possono essere inseriti in uno script che se ne occuperà all’avvio del programma. Quando si fa uso di applicazioni personalizzate utilizzando PyQGIS, esistono di solito due possibilità:

  • richiede all’utente di installare QGIS prima di installare l’applicazione. Il programma di installazione dell’applicazione dovrebbe cercare percorsi predefiniti delle librerie QGIS e consentire all’utente di impostare il percorso se non trovato. Questo approccio ha il vantaggio di essere più semplice, tuttavia richiede all’utente di fare più passaggi.

  • impacchetta QGIS insieme alla tua applicazione. Rilasciare l’applicazione può essere più impegnativo e il pacchetto sarà più grande, ma l’utente sarà risparmiato dall’onere di scaricare e installare parti addizionali del programma.

I due modelli di distribuzione possono essere combinati. È possibile fornire applicazioni indipendenti su Windows e macOS, ma per Linux lasciare l’installazione di GIS all’utente e al suo gestore dei pacchetti.

1.5. Note tecniche su PyQt e SIP

Python è una dei linguaggi preferiti per lo scripting. I collegamenti PyQGIS in QGIS 3 dipendono da SIP e PyQt5. La ragione per usare SIP invece del SWIG più usato è che il codice QGIS dipende dalle librerie Qt. I collegamenti Python per Qt (PyQt) vengono eseguiti utilizzando SIP e ciò consente una perfetta integrazione di PyQGIS con PyQt.