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.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

A copy of the license is included in the section GNU General Public License.

This license also applies to all code snippets in this document.

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.

There is a complete QGIS C++ API reference that documents the classes from the QGIS libraries. The Pythonic QGIS API (pyqgis) is nearly identical to the C++ API.

Another good resource for learning how to perform common tasks is to download existing plugins from the plugin repository and examine their code.

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

It is often handy to create scripts for automating processes. With PyQGIS, this is perfectly possible — import the qgis.core module, initialize it and you are ready for the processing.

Or you may want to create an interactive application that uses GIS functionality — perform measurements, export a map as PDF, … The qgis.gui module provides various GUI components, most notably the map canvas widget that can be incorporated into the application with support for zooming, panning and/or any further custom map tools.

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
from qgis.core import *

# Supply path to qgis install location
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# Create a reference to the QgsApplication.  Setting the
# second argument to False disables the GUI.
qgs = QgsApplication([], False)

# Load providers
qgs.initQgis()

# Write your code here to load some layers, use processing
# algorithms, etc.

# Finally, exitQgis() is called to remove the
# provider and layer registries from memory
qgs.exitQgis()

First we import the qgis.core module and configure the prefix path. The prefix path is the location where QGIS is installed on your system. It is configured in the script by calling the setPrefixPath() method. The second argument of setPrefixPath() is set to True, specifying that default paths are to be used.

The QGIS install path varies by platform; the easiest way to find it for your system is to use the Scripting nel terminale python from within QGIS and look at the output from running:

QgsApplication.prefixPath()

After the prefix path is configured, we save a reference to QgsApplication in the variable qgs. The second argument is set to False, specifying that we do not plan to use the GUI since we are writing a standalone script. With QgsApplication configured, we load the QGIS data providers and layer registry by calling the initQgis() method.

qgs.initQgis()

With QGIS initialized, we are ready to write the rest of the script. Finally, we wrap up by calling exitQgis() to remove the data providers and layer registry from memory.

qgs.exitQgis()

1.4.2. Usare PyQGIS in applicazioni personalizzate

The only difference between Usare PyQGIS in script and a custom PyQGIS application is the second argument when instantiating the QgsApplication. Pass True instead of False to indicate that we plan to use a GUI.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
from qgis.core import *

# Supply the path to the qgis install location
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# Create a reference to the QgsApplication.
# Setting the second argument to True enables the GUI.  We need
# this since this is a custom application.

qgs = QgsApplication([], True)

# load providers
qgs.initQgis()

# Write your code here to load some layers, use processing
# algorithms, etc.

# Finally, exitQgis() is called to remove the
# provider and layer registries from memory
qgs.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.