Introduzione

Questo documento è da intendersi sia come un tutorial che come una guida di riferimento. Sebbene esso non contempli tutti i possibili casi d’uso, dovrebbe comunque fornire una buona panoramica delle funzionalità principali.

A partire dalla versione 0.9, QGIS ha il supporto per lo scripting opzionale utilizzando il linguaggio Python. Abbiamo optato per il Python perché è uno dei linguaggi maggiormente preferiti per lo scripting. Le dipendenze PyQGIS fanno riferimento a SIP e PyQt4. Il motivo per cui si utilizza SIP invece del più diffuso SWIG è che l’intero codice di QGIS dipende dalle librerie Qt. Le dipendenze Python per Qt (PyQt) sono eseguite anche utilizzando SIP e ciò consente un’integrazione senza interruzioni tra PyQGIS e PyQt.

Ci sono diversi modi per utilizzare Python nel desktop QGIS che sono trattati in dettaglio nelle seguenti sezioni:

  • avviare automaticamente codice Python all’avvio di QGIS

  • esegui comandi nella console Python all’interno di QGIS

  • creare ed usare plugin in Python

  • Creare un’applicazione personalizzata basata sulle API di QGIS

Python è utilizzabile anche in QGIS Server:

  • dallla versione 2.8, i plugin Python sono utilizzabili anche su QGIS Server (see: Server Python Plugins)

  • dalla versione 2.11 la libreria QGIS Server può essere usata per collegare QGIS Server con un applicazione Python.

Esiste un riferimento di API di QGIS completa <http://qgis.org/api/> _ ref che documenta le classi provenienti dalle librerie di QGIS. Le API di QGIS per Python sono quasi identiche a quelle in C++.

Una buona risorsa quando si tratta di plugin è scaricare alcuni plugin dal plugin repository <http://plugins.qgis.org/> e esaminarne il codice. Inoltre, la cartella python/plugins/ nell’installazione QGIS contiene un plugin che puoi utilizzare per imparare a sviluppare plugin e come eseguire alcune delle attività più comuni.

avviare automaticamente codice Python all’avvio di QGIS

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

Variabile di ambiente PYQGIS_STARTUP

Si può avviare codice Python subito prima dell’inizializzazione impostando la variabile d’ambiente PYQGIS_STARTUP al percorso di un file Python esistente.

This method is something you will probably rarely need, but worth mentioning here because it is one of the several ways to run Python code within QGIS and because this code will run before QGIS initialization is complete. This method is very useful for cleaning sys.path, which may have undesireable paths, or for isolating/loading the initial environ without requiring a virt env, e.g. homebrew or MacPorts installs on Mac.

The startup.py file

Every time QGIS starts, the user’s Python home directory (usually: .qgis2/python) is searched for a file named startup.py, if that file exists, it is executed by the embedded Python interpreter.

Console Python

Per chi utilizza gli script, è possibile sfruttare la console Python integrata, accessibile dal menu Plugins ‣ Python Console. La console si apre come una finestra di dialogo non modale.

../../_images/console.png

Console python di GIS

La schermata soprastante illustra come ottenere il layer attualmente selezionato nella lista dei layer, mostrare il suo ID e, se si tratta di un vettore, mostrare il conteggio delle geometrie. Per l’interazione con l’ambiente di QGIS, esiste una variabile iface, che è un’istanza della classe QgsInterface. Tale interfaccia consente di accedere alla mappa, ai menu, ai pannelli e alle parti di QGIS.

For convenience of the user, the following statements are executed when the console is started (in future it will be possible to set further initial commands)

from qgis.core import *
import qgis.utils

Per chi utilizza spesso la console, potrebbe essere utile impostare una scorciatoia per attivarla (all’interno del menu Impostazioni ‣ Configura scorciatoie...)

Plugin Python

QGIS consente un miglioramento delle sue funzionalità utilizzando i plugin. Ciò era originariamente possibile solo con il linguaggio C++. Con l’aggiunta del supporto Python per QGIS, è altresì possibile utilizzare plugin scritti in Python. Il vantaggio principale rispetto ai plugin in C++ sono la sua semplicità di distribuzione (non è necessario la compilazione per ogni piattaforma) e un più facile sviluppo.

A partire dall’introduzione del supporto Python sono stati scritti molti plugin che includono diverse funzionalità. L’installatore di plugin consente agli utenti di scaricare facilmente, aggiornare e rimuovere i plugin Python. Vedi la pagina Repository dei Plugin Python per vari esempi di plugin.

Creare un plugin in python è semplice, vedi Sviluppare Plugin Python per avere istruzioni dettagliate.

Nota

Python plugins are also available in QGIS server (QGIS as OGC Data Server), see QGIS Server Python Plugins for further details.

Applicazioni Python

Spesso, quando si processano alcuni dati GIS, è comodo creare degli script per automatizzare il processo invece di ripetere la stessa procedura diverse volte. Con PyQGIS, ciò è perfettamente possibile — importa il modulo qgis.core, inizializzalo e sei pronto per il processamento.

Oppure potresti voler creare un’applicazione interattiva che usa alcune funzionalità di QGIS — misurare alcune dati, esportare una mappa in PDF o una qualunque altra operazione. Il modulo qgis.gui porta con sé alcune componenti della GUI, in particolare il widget di mappa che può essere incorporato molto facilmente all’interno dell’applicazione con il supporto per zoomare, spostare e/o qualsiasi altro strumento di mappa.

PyQGIS custom applications or standalone scripts must be configured to locate the QGIS resources such as projection information, providers for reading vector and raster layers, etc. QGIS Resources are initialized by adding a few lines to the beginning of your application or script. The code to initialize QGIS for custom applications and standalone scripts is similar, but examples of each are provided below.

Nota: non usare qgis.py come nome per il tuo script di prova — Python non sarà in grado di importare le dipendenze poiché il nome dello script le metterà in ombra.

Using PyQGIS in standalone scripts

To start a standalone script, initialize the QGIS resources at the beginning of the script similar to the following code:

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.

# When your script is complete, call exitQgis() to remove the provider and
# layer registries from memory
qgs.exitQgis()

We begin by importing the qgis.core module and then configuring 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, which controls whether the default paths are used.

The QGIS install path varies by platform; the easiest way to find it for your your system is to use the Console 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, which indicates that we do not plan to use the GUI since we are writing a standalone script. With the QgsApplication configured, we load the QGIS data providers and layer registry by calling the qgs.initQgis() method. With QGIS initialized, we are ready to write the rest of the script. Finally, we wrap up by calling qgs.exitQgis() to remove the data providers and layer registry from memory.

Using PyQGIS in custom applications

The only difference between Using PyQGIS in standalone scripts 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.

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 True enables the GUI, which we need to do
# 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.

# When your script is complete, call exitQgis() to remove the provider and
# layer registries from memory
qgs.exitQgis()

Adesso puoi lavorare con l’API di QGIS — carica i layer ed esegui un po’ di processamento oppure avvia la GUI con una mappa. Le possibilità sono infinite :-)

Avviare applicazioni personalizzate

Avrai bisogno di dire al tuo sistema dove cercare per le librerie di QGIS e i moduli Python appropriati nel caso in cui non si trovino in una posizione conosciuta — altrimenti Python lo chiederà:

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

Ciò può essere fissato impostando la variabile di ambiente PYTHONPATH. Nei comandi seguenti, qgispath dovrebbe essere sostituito con il tuo attuale percorso di installazione di QGIS.

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

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

Il percorso per i moduli PyQGIS è adesso noto, comunque essi dipendono dalle librerie qgis_core e qgis_gui libraries (i moduli Python servono solo come contenitori). Il percorso per tali librerie è tipicamente sconosciuto al sistema operativo, così ottieni di nuovo un errore di importazione (il messaggio potrebbe variare in funzione del sistema):

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

Correggi ciò aggiungendo le cartelle in cui si trovano le librerie di QGIS per cercare il percorso del collegamento dinamico:

  • su Linux: export LD_LIBRARY_PATH=/qgispath/lib

  • su Windows: set PATH=C:\qgispath;%PATH%

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

  • richiedi all’utente di installare QGIS sulla sua piattaforma prima di installare la tua applicazione. L’installatore dell’applicazione dovrebbe guardare le posizioni predefinite delle librerie di QGIS e consentire all’utente di impostarne il percorso se non trovato. Questo approccio ha il vantaggio di essere più semplice, ma richiede all’utente di eseguier 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.

The two deployment models can be mixed - deploy standalone application on Windows and Mac OS X, for Linux leave the installation of QGIS up to user and his package manager.