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 SEXTANTE. 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 SEXTANTE in QGIS, ma tutti i comandi di SEXTANTE sono disponibili invece dalla console Python interna presente in QGIS. Ciò significa che è possibile incorporare quei comandi nella console di lavoro e connettere gli algoritmi di SEXTANTE a tutte le altre funzioni (compresi i metodi derivanti dalle API di QGIS) da lì disponibili.
Il codice che è possibile eseguire dalla console Python, anche se chiama un qualsiasi modulo di SEXTANTE, può essere convertito in un nuovo algoritmo di SEXTANTE che in seguito sarà possibile chiamare dalla finestra degli strumenti, il modellatore grafico o qualsiasi altro componente di SEXTANTE, proprio come si fa con qualunque algoritmo di SEXTANTE. Infatti, alcuni algoritmi che si possono trovare nella casella degli strumenti, come tutti quelli del gruppo mmqgis, sono semplici script.
In questo capitolo si spiegherà come utilizzare SEXTANTE dalla console Python di QGIS ed anche come scrivere un algoritmo in Python.
La prima cosa da fare è importare le funzioni di SEXTANTE con la seguente istruzione:
>>> import sextante
Fondamentalmente, c’è solo una cosa (interessante) che si può fare con SEXTANTE dalla console: eseguire un algoritmo. Ciò 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 da sapere è il nome dell’algoritmo da eseguire. Questo non è il nome che è riportato nella finestra degli strumenti, ma un nome univoco da richiamare nella da riga di comando. Per trovare il nome corretto dell’algoritmo, è possibile utilizzare il comando `` algslist () ``. Digitare la seguente istruzione:
>>> sextante.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 è la lista di tutti gli algoritmi disponibili in ordine alfabetico, con il corrispondente nome da utilizzare nella riga di comando.
È possibile utilizzare 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, si sta cercando un algoritmo per calcolare la pendenza da un DEM, si digiti ``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 che sono disponibili.
È più facile ora trovare l’algoritmo che si sta cercando e il suo nome da utilizzare nella riga di comando, in questo caso `` saga: slopeaspectcurvature ``.
Una volta che si conosce il nome dell’algoritmo da utilizzare nella riga di comando, la prossima cosa da fare è conoscere la giusta sintassi per eseguirlo. Ciò significa conoscere quali sono i parametri necessari e l’ordine in cui essi devono essere dichiarati quando si esegue il comando `` runalg () `` . SEXTANTE ha un comando per descrivere un algoritmo in dettaglio, che può essere usato per ottenere un elenco dei parametri che un algoritmo richiede e gli output che genererà. È possibile utilizzare il comando `` alghelp (nome_algoritmo) ``. Utilizzare il nome dell’algoritmo nella riga di comando, non il nome descrittivo completo.
Chiamando la funzione saga:slopeaspectcurvature come parametro, si otterrà la seguente descrizione.
>>> sextante.alghelp("saga:slopeaspectcurvature")
ALGORITHM: Slope, Aspect, Curvature
ELEVATION <ParameterRaster>
METHOD <ParameterSelection>
SLOPE <OutputRaster>
ASPECT <OutputRaster>
CURV <OutputRaster>
HCURV <OutputRaster>
VCURV <OutputRaster>
Ora si ha tutto il necessario per eseguire qualsiasi algoritmo. Come già accennato, vi è solo un unico comando per eseguire algoritmi: `` runalg () ``. La sua sintassi è la seguente:
>>> sextante.runalg{name_of_the_algorithm, param1, param2, ..., paramN,
Output1, Output2, ..., OutputN)
L’elenco dei parametri e degli output da aggiungere dipende dall’algoritmo che si desidera eseguire, ed è esattamente la lista che il comando `` alghelp () `` restituisce, nello stesso ordine, come mostrato.
A seconda del tipo di parametro, i valori vengono introdotti in modo diverso. Di seguito, una rapida rassegna di come introdurre i valori per ciascun tipo di parametro di input
Layer raster, layer vettoriale o tabella. Basta usare una stringa con il nome che identifica l’oggetto da utilizzare (il nome che ha nell’area di legenda di QGIS ) o il nome di un file (se il layer corrispondente non è aperto, sarà aperto, ma non aggiunto alla mappa ). Se si dispone di un’istanza di un oggetto di QGIS che rappresenta il layer, è anche possibile utilizzarla come parametro. Se l’input è opzionale e non si desidera utilizzare alcun dato, utilizzare ``None ``.
Selezione. Se un algoritmo ha un parametro di selezione, il valore di tale parametro deve essere inserito come valore intero. Per conoscere le opzioni disponibili, è possibile utilizzare il comando ``algoptions ``, come mostrato nel seguente esempio:
>>> sextante.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 7 opzioni, ordinate a partire da zero.
Input multipli. Il valore è una stringa con i descrittori degli input separati da virgola. Come nel caso di singoli layer o tabelle, ogni descrittore di input ingresso può essere il nome dell’oggetto, o il suo percorso sul disco.
Campo di una Tabella da XXX. Inserire una stringa con il nome del campo da utilizzare. Il parametro è sensibile alle lettere maiuscole
Tabella fissa. Digitare l’elenco di tutti i valori della tabella, separati da virgole e racchiusi tra virgolette. I valori iniziano dalla riga superiore e vanno da sinistra a destra. È inoltre possibile utilizzare una matrice 2D dei valori che rappresenta la tabella.
Sistema di Riferimento per le Coordinate (Coordinate Reference System, CRS). Inserire il codice EPSG per indicare il sistema di riferimento desiderato.
Estensione. È necessario utilizzare una stringa con i valori di 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 o valori numerici o booleani hanno valori di default. Per utilizzarli, usare ``None ``nella voce del parametro corrispondente.
Per per salvare i dati di output, digitare il percorso del file da utilizzare, così come viene fatto nella finestra degli strumenti. Se si desidera salvare il risultato in un file temporaneo, utilizzare ``None ``. L’estensione del file determina il formato del file. Se si immette 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 dalla finestra degli strumenti, se si esegue lo stesso algoritmo dalla console Python, gli output non vengono aggiunti alla vista mappa. Se si desidera aggiungere un output alla vista, bisogna farlo dopo l’esecuzione dell’algoritmo. Per fare ciò, è possibile utilizzare i comandi API QGIS, o, ancora più semplicemente, utilizzare uno dei comandi forniti da SEXTANTE per tale compito.
Il comando `` runalg () `` restituisce un dizionario con i nomi di output (quelli indicati nella descrizione dell’algoritmo) come chiavi e i percorsi dei file di quegli output come valori. Per aggiungere tutti gli output generati da un algoritmo, si può utilizzare il comando `` loadFromAlg () `` che processa il dizionario. È anche possibile caricare un singolo layer passando il suo percorso del file al comando `` load() ``.
È possibile creare i propri algoritmi, scrivendo il relativo codice Python e aggiungendo qualche riga in più per fornire ulteriori informazioni necessarie a SEXTANTE. Il comando Create new script si trova sotto il gruppo strumenti nel blocco degli Script, nella finestra degli strumenti. Fare doppio clic su di esso per aprire la finestra di dialogo dell’editor di script. È lì che si deve digitare il codice. Salvando lo script nella cartella scripts (è quella di default quando si apre la finestra di dialogo Salva file), con estensione .py , automaticamente si creerà l’algoritmo corrispondente.
Il nome dell’algoritmo (quello si vedrà nella finestra degli strumenti) viene creato dal nome del file, rimuovendo la sua estensione e sostituendoi trattini bassi con spazi vuoti.
Ad esempio, quello seguente è il codice che calcola l’Indice di Umidità Topografica (Topographic Wetness Index, TWI) direttamente da un DEM
##dem=raster
##twi=output
ret_slope = sextante.runalg("saga:slopeaspectcurvature", dem, 0, None,
None, None, None, None)
ret_area = sextante.runalg("saga:catchmentarea(mass-fluxmethod)", dem,
0, False, False, False, False, None, None, None, None, None)
sextante.runalg("saga:topographicwetnessindex(twi), ret_slope['SLOPE'],
ret_area['AREA'], None, 1, 0, twi)
Come si può vedere, si tratta di tre algoritmi, tutti provenienti da SAGA. L’ultimo calcola il TWI, ma ha bisogno del layer dell’inclinazioe e del layer della flow accumulation. Non essendo disponibili direttamente ed avendo a disposizione il DEM, possono essere calcolati richiamando i corrispondenti 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. Esse forniscono a SEXTANTE le informazioni di cui ha bisogno per trasformare il codice in un algoritmo che può essere eseguito da uno dei suoi componenti, come la finestra degli strumenti o il modellatore grafico.
Queste linee iniziano con un doppio simbolo di commento Python ed hanno la seguente struttura:
[parameter_name]=[parameter_type] [optional_values]
Ecco un elenco di tutti i tipi di parametri che SEXTANTE supporta nei suoi scrpt, la loro sintassi ed alcuni esempi.
raster. Un layer raster
vector. Un layer vettoriale
table. Una tabella
number. Un valore numerico. Deve essere indicato un valore di default. Ad esempio, depth=number 2.4
string. Una stringa di testo. Come nel caso dei valori numerici, deve essere indicato un valore di default. Ad esempio, name=string Victor````number
boolean. Un valore booleano. Aggiungere True o False dopo di esso per indicare il valore di default. Ad esempio, verbose=boolean True
multiple raster. Un insieme di layer raster di input.
field. Un campo nella tabella degli attributi di un layer vettoriale. Il nome del layer deve essere aggiunto dopo il tag field. Ad esempio, una volta dichiarato il layer vettoriale di input con mylayer=vector, si può usare myfield=field mylayer per aggiungere come parametro un campo di quel layer.
folder. Una cartella
file. Un nome di un file
Il nome del parametro è il nome che verrà mostrato all’utente durante l’esecuzione dell’algoritmo, ed è anche il nome della variabile da utilizzare nel codice dello script. Il valore immesso dall’utente per quel parametro sarà assegnato a una variabile con quel nome.
Quando mostra all’utente il nome del parametro, SEXTANTE lo modifica per migliorare il suo aspetto, sostituendo i trattini bassi con spazi vuoti. Così, per esempio, se si desidera che l’utente visualizzi un parametro denominato `` Un valore numerico``, è possibile utilizzare il nome della variabile `` Un_valore_numerico ``.
I valori dei layer e delle tabelle sono stringhe contenenti il percorso del file dell’oggetto corrispondente. Per trasformarle in un oggetto di QGIS, è possibile utilizzare la funzione ``sextante.getObjectFromUri () `` funzione. Anche input multipli hanno un valore della stringa, che contiene il percorso di gli oggetti selezionati, separati da punto e virgola.
Gli output sono definiti in maniera simile, usando i seguenti tag:
Il valore assegnato alle variabili di otput è sempre una stringa con un percorso file. Esso corrisponde al percorso di un file temporaneo nel caso in cui l’utente non ha specificato alcun file di output.
Quando si dichiara un output, SEXTANTE cercherà di aggiungerlo QGIS una volta che l’algoritmo è finito. Questa è la ragione per cui, anche se il comando `` runalg () `` non carica i layer che produce, il layer finale del TWI verrà caricato, poiché è salvato nel file scelto dall’utente, che è il valore dell’output corrispondente.
Non usare il comando `` load() `` negli algoritmi di script, ma solo quando si lavora con la linea di comando. Se un layer viene creato come output di un algoritmo, esso dovrebbe essere dichiarato come tale. In caso contrario, l’algoritmo nel modellatore non potrà essere utilizzato correttamente, dal momento che la sua sintassi (come definita dai tag spiegato sopra) non corrisponde a ciò che l’algoritmo in realtà crea.
Output nascosti (numeri e stringhe) non hanno un valore. È invece l’utente che deve assegnare loro un valore. Per farlo, è sufficiente impostare il valore di una variabile con il nome utilizzato per dichiarare quell’output. Per esempio, se è stata usata questa dichiarazione,
##average=output number
la riga 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 elaborare, è una buona idea informare l’utente. Si dispone di due comandi globali denominati ``progress ``con due metodi disponibile : `` setText (testo) `` e `` setPercentage (percent) `` per modificare il testo e la barra di avanzamento.
Con SEXTANTE sono forniti diversi esempi. Si prega di controllarli per vedere alcuni esempi reali di come creare algoritmi che utilizzano questa funzione di SEXTANTE. È possibile fare clic destro su un qualsiasi algoritmo di script e selezionare select Edit script per modificare il codice o solo per vederlo.
Come nel caso dei modelli, è possibile creare una documentazione aggiuntiva per gli script, per spiegare che cosa fanno e come usarli. Nella finestra di modifica dello script si trova un pulsante [Edit script help]. Fare clic su di esso e si aprirà una finestra di editing dell’help. Controllare il capitolo sul modellatore grafico per sapere di più su questa finestra di dialogo e come usarla.
I file della guida vengono salvati nella stessa cartella dello stesso script, aggiungendo l’estensione .help al nome del file. Si noti che è possibile modificare la guida dello script prima di salvarlo per la prima volta. Se in seguito si chiude la finestra di modifica dello script senza salvare lo script (cioè la si scarta), il contenuto già scritto della guida verrà perso. Se lo script è già stato salvato ed è associato ad un nome di file, il salvataggio è fatto automaticamente.