.
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.
There is not a proccesing console in QGIS, but all processing commands are available instead from the QGIS built-in Python console. That means that you can incorporate those commands into your console work and connect processing algorithms to all the other features (including methods from the QGIS API) available from there.
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 this section, we will see how to use processing algorithms from the QGIS Python console, and also how to write algorithms using 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 Layer, Vector Layer or Table. Simply use a string with the name that identifies the data object to use (the name it has in the QGIS Table of Contents) or a filename (if the corresponding layer is not opened, it will be opened but not added to the map canvas). If you have an instance of a QGIS object representing the layer, you can also pass it as parameter. If the input is optional and you do not want to use any data object, use 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 .
Unlike when an algorithm is executed from the toolbox, outputs are not added to the map canvas if you execute that same algorithm from the Python console. If you want to add an output to the map canvas, you have to do it yourself after running the algorithm. To do so, you can use QGIS API commands, or, even easier, use one of the handy methods provided for such tasks.
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().
Apart from the functions used to call algorithms, importing the processing package will also import some additional functions that make it easier to work with data, particularly vector data. They are just convenience functions that wrap some functionality from the QGIS API, usually with a less complex syntax. These functions should be used when developing new algorithms, as they make it easier to operate with input data.
Below is a list of some of these commands. More information can be found in the classes under the processing/tools package, and also in the example scripts provided with 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.
Layers and table values are strings containing the file path of the corresponding object. To turn them into a QGIS object, you can use the processing.getObjectFromUri() function. Multiple inputs also have a string value, which contains the file paths to all selected object, separated by semicolons (;).
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.
When you declare an output, the algorithm will try to add it to QGIS once it is finished. That is why, although the runalg() method does not load the layers it produces, the final TWI layer will be loaded (using the case of our previous example), since it is saved to the file entered by the user, which is the value of the corresponding output.
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.