.
La console permette ad utenti esperti di aumentare la propria produttività e di eseguire operazioni complesse che non possono essere eseguite utilizzando uno qualsiasi degli altri elementi dell’interfaccia grafica di Processing. I modelli che richiamano diversi algoritmi possono essere definiti utilizzando l’interfaccia della riga di comando, e le operazioni aggiuntive, come i loop e le frasi condizionali possono essere aggiunte per creare flussi di lavoro più flessibili e potenti.
Non c’è una console di Processing in QGIS, ma tutti i comandi di Processing sono disponibili al posto di quelli nativi di QGIS della console di python. Questo significa che puoi incorporare questi comandi nella tua console di lavoro e collegare gli algoritmi di Processing a tutte le altre funzionalità (inclusi i metodi della API di QGIS) disponibili.
Il codice che puoi eseguire dalla console di python, anche se non richiama un metodo specifico di Processing, può essere convertito in un nuovo algoritmo che potrai richiamare in seguito dagli Strumenti, dal Modellatore grafico o da qualunque altra parte, proprio come ogni altro algoritmo. Alcuni algoritmi che trovi in Strumenti sono in effetti degli script semplici.
In questa sezione verrà spiegato come usare gli algoritmi di Processing dalla console di python e anche come scrivere un algoritmo usando python.
La prima cosa da fare è importare le funzioni di Processing con la seguente istruzione:
>>> import processing
Fondamentalmente, c’è solo una cosa (interessante) che puoi fare dalla console: eseguire un algoritmo. Questo viene fatto usando il comando runalg(), che prende il nome dell’algoritmo da eseguire come primo parametro, e poi un numero variabile di parametri aggiuntivi che dipendono da ciò che è richiesto dall’algoritmo. Quindi la prima cosa che devi sapere è il nome dell’algoritmo da eseguire. Questo non è il nome che è riportato in Strumenti, ma un nome univoco da richiamare nella da riga di comando. Per trovare il nome corretto dell’algoritmo, puoi usare il comando algslist(). Inserisci il seguente comando nella console:
>>> processing.alglist()
Il risultato dovrebbe essere.
Accumulated Cost (Anisotropic)---------------->saga:accumulatedcost(anisotropic)
Accumulated Cost (Isotropic)------------------>saga:accumulatedcost(isotropic)
Add Coordinates to points--------------------->saga:addcoordinatestopoints
Add Grid Values to Points--------------------->saga:addgridvaluestopoints
Add Grid Values to Shapes--------------------->saga:addgridvaluestoshapes
Add Polygon Attributes to Points-------------->saga:addpolygonattributestopoints
Aggregate------------------------------------->saga:aggregate
Aggregate Point Observations------------------>saga:aggregatepointobservations
Aggregation Index----------------------------->saga:aggregationindex
Analytical Hierarchy Process------------------>saga:analyticalhierarchyprocess
Analytical Hillshading------------------------>saga:analyticalhillshading
Average With Mask 1--------------------------->saga:averagewithmask1
Average With Mask 2--------------------------->saga:averagewithmask2
Average With Thereshold 1--------------------->saga:averagewiththereshold1
Average With Thereshold 2--------------------->saga:averagewiththereshold2
Average With Thereshold 3--------------------->saga:averagewiththereshold3
B-Spline Approximation------------------------>saga:b-splineapproximation
...
Questa è l’elenco di tutti gli algoritmi disponibili in ordine alfabetico, con il corrispondente nome da utilizzare nella riga di comando.
Puoi usare una stringa come parametro per questo comando. Invece di restituire l’elenco completo degli algoritmi, verranno visualizzati solo quelli che includono tale stringa. Se, per esempio, stai cercando un algoritmo per calcolare la pendenza da un DEM, inserisci alglist ("slope") per ottenere il seguente risultato:
DTM Filter (slope-based)---------------------->saga:dtmfilter(slope-based)
Downslope Distance Gradient------------------->saga:downslopedistancegradient
Relative Heights and Slope Positions---------->saga:relativeheightsandslopepositions
Slope Length---------------------------------->saga:slopelength
Slope, Aspect, Curvature---------------------->saga:slopeaspectcurvature
Upslope Area---------------------------------->saga:upslopearea
Vegetation Index[slope based]----------------->saga:vegetationindex[slopebased]
Il risultato potrebbe cambiare a seconda degli algoritmi disponibili.
Ora è più facile ora trovare sia l’algoritmo che cercavi sia il suo nome da utilizzare nella riga di comando, in questo caso saga: slopeaspectcurvature.
Una volta che sai qual è il nome dell’algoritmo da utilizzare nella riga di comando, la prossima cosa da fare è conoscere la giusta sintassi per eseguirlo. Questo significa conoscere quali sono i parametri necessari e l’ordine in cui questi devono essere dichiarati quando si esegue il comando runalg (). Processing ha un comando per descrivere un algoritmo in dettaglio, che puoi usare per ottenere un elenco dei parametri che un algoritmo richiede e gli output che genererà. Puoi usare il comando alghelp (nome_algoritmo). Usa solo il nome dell’algoritmo nella riga di comando, non il nome descrittivo completo.
Chiamando il metodo saga:slopeaspectcurvature come parametro, otterrai la seguente descrizione:
>>> processing.alghelp("saga:slopeaspectcurvature")
ALGORITHM: Slope, Aspect, Curvature
ELEVATION <ParameterRaster>
METHOD <ParameterSelection>
SLOPE <OutputRaster>
ASPECT <OutputRaster>
CURV <OutputRaster>
HCURV <OutputRaster>
VCURV <OutputRaster>
Ora hai tutto il necessario per eseguire qualsiasi algoritmo. Come già accennato, c’è solo un unico comando per eseguire algoritmi: `` runalg () ``. La sua sintassi è la seguente:
>>> processing.runalg(name_of_the_algorithm, param1, param2, ..., paramN,
Output1, Output2, ..., OutputN)
L’elenco dei parametri e degli output da aggiungere dipende dall’algoritmo che vuoi eseguire, ed è esattamente la lista che il comando alghelp() restituisce, nello stesso ordine, come mostrato.
A seconda del tipo di parametro, i valori sono inseriti in maniera diversa. Il seguente elenco dà una rapida panoramica di come inserire valori per ogni tipo di parametro in input:
Raster, vettore o tabella. Basta usare una stringa con il nome che identifica l’oggetto da usare (il nome che ha nella legenda di QGIS ) o il nome di un file (se il layer corrispondente non è aperto, sarà aperto, ma non aggiunto alla mappa). Se hai un’istanza di un oggetto di QGIS che rappresenta il layer, puoi anche usarla come parametro. Se l’input è opzionale e non vuoi usare alcun dato, scegli None.
Selezione. Se un algoritmo ha un parametro di selezione, dovresti inserire il valore di questo parametro usando un valore intero. Per conoscere le opzioni disponibili puoi usare il comando algoptions() come mostrato nel seguenti esempio:
>>> processing.algoptions("saga:slopeaspectcurvature")
METHOD(Method)
0 - [0] Maximum Slope (Travis et al. 1975)
1 - [1] Maximum Triangle Slope (Tarboton 1997)
2 - [2] Least Squares Fitted Plane (Horn 1981, Costa-Cabral & Burgess 1996)
3 - [3] Fit 2.Degree Polynom (Bauer, Rohdenburg, Bork 1985)
4 - [4] Fit 2.Degree Polynom (Heerdegen & Beran 1982)
5 - [5] Fit 2.Degree Polynom (Zevenbergen & Thorne 1987)
6 - [6] Fit 3.Degree Polynom (Haralick 1983)
In questo caso, l’algoritmo ha uno di questi parametri con sette opzioni, ordinate partendo da zero.
Input multipli. Il valore è una stringa con descrittori in input separati da un punto e virgola (;). Come nel caso di layer singoli o tabelle, ogni descrittore in input può essere il nome dell’oggetto o il suo percorso.
Campo di una Tabella da XXX. Inserisci una stringa con il nome del campo da usare. Il parametro è sensibile alle lettere maiuscole.
Tabella fissa. Inserisci l’elenco di tutti i valori delle tabelle separati da una virgola (,) e racchiusi fra virgolette ("). I valori partono dalla riga in alto e proseguono da sinistra verso destra. Puoi usare un array 2-D per i valori che rappresentano la tabella.
SR. Inserisci il codice EPSG del SR desiderato.
Estensione. Usa un stringa con valori xmin, xmax, ymin e ymax separati da virgole (,).
Parametri booleani, di file, di stringa e numerici non hanno bisogno di ulteriori spiegazioni.
I parametri di input, come stringhe, booleani, o valori numerici hanno valori predefiniti. Per utilizzarli, specifica `` None`` nella corrispondente voce di parametro.
Per per salvare i dati in output, digita il percorso del file da utilizzare, così come viene fatto in Strumenti. Se vuoi salvare il risultato in un file temporaneo, utilizzare None. L’estensione del file determina il formato del file. Se inserisci un’estensione del file non inclusa tra quelle supportate dall’algoritmo, verrà utilizzato il formato di file predefinito per il tipo di output e sarà aggiunta al percorso del file specificato la sua estensione corrispondente .
A differenza di quando un algoritmo viene eseguito dagli Strumenti, gli output non vengono aggiunti alla mappa quando esegui lo stesso algoritmo dalla console python. Se vuoi aggiungere l’output alla mappa lo devi fare da solo dopo l’esecuzione dell’algoritmo. Per farlo, puoi usare i comandi delle API di QGIS oppure, più facilmente, usare uno dei seguenti metodi.
Il metodo runalg restituisce un dizionario con i nomi degli output (quelli visti nella descrizione dell’algoritmo) come chiavi e il percorso degli output come valori. Puoi caricare questi layer con il metodo load().
Accanto alle funzioni usate per richiamare gli algoritmi, importare il pacchetto processing significa anche importare funzioni aggiuntive che permettono di lavorare con maggiore facilità con i dati, specialmente con i vettori. Sono semplicemente funzioni che incorporano le funzionalità delle API di QGIS, ma con una sintassi più semplice. Dovresti usare queste funzioni quando sviluppi nuovi algoritmi proprio perché è più facile lavorare con i dati in input.
Di sotto trovi un elenco di alcuni di questi comandi. Ulteriori informazioni possono essere trovare sotto le classi del pacchetto processing/tools e anche negli script di esempio forniti con QGIS.
getObject(obj): restituisce un oggetto QGIS (layer o tabella) da precedenti, che può essere un nome di file o il nome dell’oggetto nella legenda QGIS.
values(layer, fields): restituisce i valori nella tabella degli attributi di un vettore dei campi interessati. Puoi eseguire i campi come nome o come indici basati su zero. Restituisce un dict di elenchi, con gli identificatori dei campi come chiavi. Considera la selezione esistente.
features(layer): ti restituisce un iteratore sulla geometria di vettore, considerando la selezione esistente.
uniqueValues(layer, field): restituisce un elenco di valori unici per un dato attributo. Gli attributi possono essere un nome di campo o di un indice con base zero. Considera la selezione esistente.
Puoi creare i tuoi algoritmi scrivendo il codice python corrispondente e aggiungendo solo poche righe extra che forniscono le informazioni sulla semantica dell’algoritmo. In Strumenti puoi trovare il menu Crea nuovo script nel gruppo Script. Se fai doppio click su questo menu di aprirà una finestra di dialogo dove potrai inserire il codice. Salvando lo script nella cartella scripts (cartella predefinita per il salvataggio degli script) con l’estensione .py verrà automaticamente creato l’algoritmo corrispondente.
Il nome dell’algoritmo (quello che vedrai in Strumenti) viene creato dal nome del file, rimuovendo l’estensione del file e sostituendo i trattini bassi con spazi vuoti.
Questo di seguito è il codice che calcola l’Indice di Umidità Topografica (Topographic Wetness Index, TWI) direttamente da un DEM.
##dem=raster
##twi=output
ret_slope = processing.runalg("saga:slopeaspectcurvature", dem, 0, None,
None, None, None, None)
ret_area = processing.runalg("saga:catchmentarea(mass-fluxmethod)", dem,
0, False, False, False, False, None, None, None, None, None)
processing.runalg("saga:topographicwetnessindex(twi), ret_slope['SLOPE'],
ret_area['AREA'], None, 1, 0, twi)
Come puoi vedere, durante il calcolo vengono usati tre algoritmi, tutti di SAGA. L’ultimo calcola il TWI, ma richiede un raster delle pendenze e uno di accumulo dei flussi. Anche se non hai questi layer, li puoi ricavare direttamente dal DEM grazie agli algoritmi di SAGA.
La parte del codice in cui avviene questo processo non è difficile da capire, una volta lette le sezioni precedenti di questo capitolo. Le prime linee, tuttavia, hanno bisogno di qualche spiegazione aggiuntiva. Queste forniscono a Processing le informazioni di cui ha bisogno per trasformare il codice in un algoritmo che potrai eseguire da uno dei suoi componenti, come gli Strumenti o il modellatore grafico.
Queste righe iniziano con un doppio commento di python (##) a hanno la seguente struttura:
[parameter_name]=[parameter_type] [optional_values]
Ecco un elenco di tutti i tipi di parametri supportati dagli script di Processing, la loro sintassi ed alcuni esempi.
raster. Un raster.
vector. Un vettore.
table. Una tabella.
number. Un valore numerico Devi fornire un valore predefinito, per esempio, depth=number 2.4.
string. una stringa. Come per i valori numerici, devi fornire un valore predefinito, per esempio, name=string Victor.
boolean. un valore booleano. Aggiungi True o False dopo per scegliere il valore predefinito. Per esempio, verbose=boolean True.
multiple raster. Un insieme di raster in input.
field. Un campo nella tabella degli attributi di un vettore. Il nome del vettore deve essere aggiunto dopo il tag field. Ad esempio, una volta chiamato il vettore in input con mylayer=vector, puoi usare myfield=field mylayer per aggiungere come parametro un campo di quel vettore.
folder. Una cartella.
file. Un nome di un file.
Il nome del parametro è il nome che ti verrà mostrato durante l’esecuzione dell’algoritmo, ed è anche il nome della variabile da usare nel codice dello script. Il valore che hai inserito per quel parametro sarà assegnato a una variabile con quel nome.
Quando viene mostrato il nome del parametro, il nome verrà modificato per migliorare l’aspetto, sostituendo i trattini con degli spazi. Quindi, per esempio, se vuoi visualizzare il parametro A numerical value, puoi inserire il nome della variabile anche cosi: A_numerical_value.
I valori dei layer e delle tabelle sono stringhe che contengono il percorso dell’oggetto corrispondente. Per trasformarlo in un oggetto QGIS puoi usare la funzione processing.getObjectFromUri(). Anche gli input multipli hanno valori di stringhe che contengono il percorso dell’oggetto selezionato, separati da punto e virgola
Gli output sono definiti in maniera simile, usando i seguenti tag:
Il valore assegnati alle variabili in output è sempre una stringa con il percorso del file. Corrisponderà a un percorso temporaneo nel caso in cui non hai inserito il nome del file.
Quando dichiari un output, l’algoritmo cercherà di aggiungerlo a QGIS una volta eseguito. Questa è la ragione per cui, anche se il comando runalg() non carica i layer finali, il layer TWI (nel caso dell’esempio precedente) verrà caricato, poiché è salvato nel file che hai scelto, ovvero il valore dell’output corrispondente.
Non usare il comando load() negli algoritmi degli script, usalo solo quando lavori con la riga di comando. Se un layer viene creato come output di un algoritmo, dovrebbe essere dichiarato come tale. Altrimenti non potrai usare l’algoritmo nel modellatore grafico dal momento che la sua sintassi (come definita dai tag spiegato sopra) non corrisponde a ciò che l’algoritmo in realtà crea.
Gli output nascosti (numeri e stringhe) non hanno un valore. Sei tu che devi assegnarli un valore. Per farlo, basta impostare il valore di una variabile con il nome utilizzato per dichiarare quell’output. Per esempio, se hai usato questa dichiarazione,
##average=output number
la linea seguente imposterà il valore dell’output a 5:
average = 5
Oltre ai tag per i parametri e gli output, è anche possibile definire il gruppo in cui verrà mostrato l’algoritmo, utilizzando il tag group.
Se l’algoritmo impiega molto tempo per essere eseguito, è una buona idea fornire questa informazione. Hai a disposizione due comandi globali denominati progress con due metodi disponibili : setText(text) e setPercentage(percent) per modificare il testo e la barra di avanzamento.
Ti abbiamo fornito diversi esempi. Controllali per vedere alcuni esempi reali di come creare algoritmi che utilizzano queste classi di Processing. Puoi fare clic con il tasto destro su un qualsiasi algoritmo e selezionare Edit script per modificare il codice o solo per vederlo.
Come nel caso dei modelli, puoi creare una documentazione aggiuntiva per gli script, per spiegare che cosa fanno e come usarli. Nella finestra di modifica dello script trovi il pulsante [Edit script help]. Cliccaci per aprire una finestra di editing dell’help. Controlla il capitolo sul modellatore grafico per sapere di più su questa finestra di dialogo e come usarla.
Gli help file vengono salvati nella stessa cartella dello stesso script, aggiungendo l’estensione .help al nome del file. Puoi modificare la guida dello script prima di salvarlo per la prima volta. Se in seguito chiudi la finestra di modifica dello script senza salvarlo (cioè lo scarti), perderai il contenuto già scritto della guida. Se hai già salvato lo script e se questo è associato ad un nome di file, il salvataggio è fatto automaticamente.
Gli script possono essere usati come agganci pre e post esecuzione di funzioni prima e dopo che un algoritmo venga eseguito. Li puoi usare per automatizzare dei compiti da espletare all’esecuzione di un algoritmo.
La sintassi è identica alla sintassi spiegato sopra, ma hai a disposizione anche una variabile globale chiamata alg che rappresenta l’algoritmo che è appena (o che sarà) stato eseguito.
Nel gruppo General del menu di configurazione di Processing trovi due voci chiamate Pre-execution script file e Post-execution script file dove puoi inserire il nome del file dello script che deve essere eseguito.