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.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

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 and 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 and Python .

1.3. Esegui il codice Python all’avvio di QGIS

Esistono du metodi distinti per avviare codice Python all’avvio di QGIS.

  1. Crea uno script startup.py

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

1.3.1. Il file startup.py

Ad ogni avvio di QGIS, la cartella principale di Python

  • Linux: .local/share/QGIS/QGIS3

  • Windows: AppData\Roaming\QGIS\QGIS3

  • macOS: Library/Application Support/QGIS/QGIS3

viene cercato un file denominato startup.py. Se quel file esiste, viene eseguito dall’interprete Python installato.

Nota

Il percorso predefinito dipende dal sistema operativo. Per trovare il percorso adatto a te, apri il terminale Python ed esegui QStandardPaths.standardLocations(QStandardPaths.AppDataLocation) pre vedere la list delle cartelle predefinite.

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.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.