13.1. Espressioni

Basate sui dati dei layer e sulle funzioni predefinite o definite dall’utente, le Espressioni offrono un modo potente per manipolare il valore degli attributi, la geometria e le variabili al fine di cambiare dinamicamente lo stile della geometria, il contenuto o la posizione dell’etichetta, il valore del diagramma, la quota di un oggetto del layout, selezionare alcuni elementi, creare un campo virtuale, …

Nota

Una lista delle funzioni e delle variabili predefinite per scrivere espressioni può essere trovata in Lista delle funzioni, con informazioni dettagliate ed esempi.

13.1.1. Il Calcolatore di campi

La finestra di dialogo principale per la creazione di espressioni Calcolatore di campi è disponibile da molte parti in QGIS e, in particolare, puoi accederci:

Le finestre di dialogo del Costruttore di Espressioni offrono l’accesso a:

  • Expression tab che, grazie ad un elenco di funzioni predefinite, aiuta a scrivere e controllare l’espressione da utilizzare;

  • Function Editor tab delle funzioni che consente di ampliare l’elenco delle funzioni creando quelle personalizzate.

13.1.1.1. L’Interfaccia

La scheda Espressione fornisce l’interfaccia principale per scrivere espressioni utilizzando funzioni, campi del layer e valori. Contiene i seguenti widget:

../../../_images/function_list.png

Fig. 13.1 La scheda Espressioni

  • Un’area di editing di espressioni per digitare o copiare le espressioni. L’autocompletamento è disponibile per velocizzare la scrittura delle espressioni:

    • Le variabili, i nomi delle funzioni e dei campi corrispondenti al testo di input sono mostrati di seguito: usare le frecce Up e Down per sfogliare gli elementi e premere Tab per inserireli nell’espressione o semplicemente cliccare sull’elemento desiderato.

    • I parametri delle funzione vengono visualizzati durante la digitazione.

    QGIS controlla anche la correttezza dell’espressione ed evidenzia tutti gli errori utilizzando:

    • Sottolineatura: per funzioni sconosciute, argomenti errati o non corretti;

    • Simbolo: per ogni altro errore (es. parentesi mancante, carattere imprevisto) in una singola posizione.

    Suggerimento

    Documentare le tue espressioni con i commenti

    Quando si usa un’espressione complessa, è buona pratica aggiungere testo sia come commento multilinea che come commento in linea per aiutarti a ricordare.

    /*
Labels each region with its highest (in altitude) airport(s)
and altitude, eg 'AMBLER : 264m' for the 'Northwest Artic' region
*/
with_variable(
  'airport_alti', -- stores the highest altitude of the region
  aggregate(
    'airports',
    'max',
    "ELEV", -- the field containing the altitude
    -- and limit the airports to the region they are within
    filter := within( $geometry, geometry( @parent ) )
  ),
    aggregate( -- finds airports at the same altitude in the region
      'airports',
      'concatenate',
      "NAME",
      filter := within( $geometry, geometry( @parent ) )
        and "ELEV" = @airport_alti
    )
    || ' : ' || @airport_alti || 'm'
    -- using || allows regions without airports to be skipped
)

  • Sopra l’editor di espressioni, una serie di strumenti ti aiutano:

  • Sotto l’editor di espressioni, trovi:

    • Un insieme di operatori di base per aiutarti a costruire l’espressione

    • Un’indicazione del formato in uscita previsto quando definisci le proprietà degli elementi.

    • Una Anteprima in tempo reale dell’espressione (fino a 60 caratteri), valutata per impostazione predefinita sul primo elemento del layer. Per visualizzare il testo dell’anteprima in uscita oltre i 60 caratteri, puoi passare il cursore sul testo per visualizzare un pop-up contenente l’intera anteprima in uscita. Per copiare il testo dell’anteprima in uscita negli appunti, fai clic con il pulsante destro del mouse sul testo dell’anteprima in uscita e seleziona editCopy Copia il Valore dell’Espressione.

      Puoi sfogliare e valutare altri elementi del layer usando la casella combinata Elemento (i valori sono presi dalla proprietà display name del layer).

      In caso di errore, lo indica e si può accedere ai dettagli con il link ipertestuale fornito.

  • Un selettore di funzioni visualizza l’elenco di funzioni, variabili, campi…. organizzati in gruppi. Una casella di ricerca è disponibile per filtrare l’elenco e trovare rapidamente una particolare funzione o campo. Facendo doppio clic su un elemento lo aggiunge all’editor di espressioni.

  • Un pannello di aiuto visualizza la guida per ogni voce selezionata nel selettore di funzione.

    Suggerimento

    Premi Ctrl+Click quando passi con il mouse sul nome di una funzione in un’espressione per visualizzare automaticamente il suo aiuto nella finestra di dialogo.

    Il widget dei valori di un campo mostrato quando un campo è selezionato nel selettore di funzioni aiuta a cercare gli attributi degli elementi:

    • Cercare un particolare valore di campo

    • Visualizza l’elenco di Tutti i Valori Univoci o di 10 Campioni. Disponibile anche con il tasto destro del mouse.

      Quando il campo è mappato con un altro layer o un insieme di valori, ad esempio se il field widget è di tipo RelationReference, ValueRelation o ValueMap, è possibile elencare tutti i valori del campo mappato (dal layer, tabella o lista di riferimento). Inoltre, puoi filtrare questa lista con checkbox Mostra solo i valori in uso nel campo corrente.

    Il doppio clic sul valore di un campo nel widget lo aggiunge all’editor di espressioni.

    Suggerimento

    Il pannello di destra, che mostra le funzioni di aiuto o i valori del campo, può essere chiuso (invisibile) nella finestra di dialogo. Premi il pulsante Mostra Valori o Mostra Guida per recuperarlo.

13.1.1.2. Scrivere una espressione

Le espressioni di QGIS sono usate per selezionare elementi o impostare valori. Scrivere un’espressione in QGIS segue alcune regole:

  1. La finestra di dialogo definisce il contesto: se siete abituati a SQL, probabilmente conoscete query del tipo select features from layer where condition o update layer set field = new_value where condition. Anche un’espressione QGIS ha bisogno di tutte queste informazioni, ma lo strumento che usi per aprire la finestra di dialogo del costruttore di espressioni ne fornisce alcune parti. Per esempio, avendo un layer (buildings) con un campo (height):

    • Usando lo strumento expressionSelectSeleziona per espressione significa che vuoi «selezionare gli elementi da buildings». La condizione è l’unica informazione che devi fornire nel widget di testo dell’espressione, ad esempio scrivi "height" > 20 per selezionare gli edifici che sono più alti di 20.

    • con questa selezione fatta, premendo il pulsante calculateField Calcolatore di campi e scegliendo «altezza» come Aggiornamento campo esistente, si fornisce già il comando «aggiorna edifici set altezza = ??? dove altezza > 20». L’unico elemento rimanente che devi fornire in questo caso è il nuovo valore, ad esempio inserisci semplicemente 50 nella casella di testo dell’editor di espressioni per impostare l’altezza degli edifici precedentemente selezionati.

  2. Fai attenzione alle virgolette: le virgolette singole restituiscono una stringa carattere, quindi un testo posto tra virgolette singole ('145') viene interpretato come una stringa. I doppi apici ti daranno il valore di quel testo, quindi usali per i campi ("myfield"). I campi possono anche essere usati senza virgolette (myfield). Niente virgolette per i numeri (3.16).

    Nota

    Le funzioni normalmente richiedono come parametro una stringa per il nome del campo. Fai:

    attribute( @atlas_feature, 'height' ) -- returns the value stored in the "height" attribute of the current atlas feature

    e non:

    attribute( @atlas_feature, "height" ) -- fetches the value of the attribute named "height" (e.g. 100), and use that value as a field
                                      -- from which to return the atlas feature value. Probably wrong as a field named "100" may not exist.

Suggerimento

Usare i parametri in modo esplicito per facilitare la lettura delle espressioni

Alcune funzioni richiedono l’impostazione di molti parametri. Il motore delle espressioni supporta l’uso di parametri con nomi espliciti. Questo significa che invece di scrivere la criptica espressione clamp( 1, 2, 9), puoi usare clamp( min:=1, value:=2, max:=9). Questo permette anche di cambiare ordine agli argomenti, ad esempio clamp( value:=2, max:=9, min:=1). L’uso di parametri con nome aiuta a chiarire a cosa si riferiscono gli argomenti di una funzione di espressione, il che è utile quando si cerca di interpretare un’espressione in seguito!

13.1.1.3. Alcuni casi di uso di espressioni

  • Dal calcolatore di campi, calcola un campo «pop_density» usando i campi esistenti «total_pop» e «area_km2»:

    "total_pop" / "area_km2"

  • Etichetta o categorizza gli elementi in base alla loro area:

    CASE WHEN $area > 10 000 THEN 'Larger' ELSE 'Smaller' END

  • Aggiornare il campo «density_level» con le categorie in base ai valori «pop_density»:

    CASE WHEN "pop_density" < 50 THEN 'Low population density'
     WHEN "pop_density" >= 50 and "pop_density" < 150 THEN 'Medium population density'
     WHEN "pop_density" >= 150 THEN 'High population density'
END

  • Applicare uno stile categorizzato a tutte le geometrie in base al fatto che il prezzo medio della casa sia più piccolo o superiore a 10000€ per metro quadrato:

    "price_m2" > 10000

  • Utilizzando lo strumento «Seleziona per espressione …», selezionare tutte le geometrie che rappresentano aree di «Alta densità di popolazione» e il cui prezzo medio di casa è superiore a 10000€ per metro quadrato:

    "density_level" = 'High population density' and "price_m2" > 10000

    L’espressione precedente potrebbe anche essere usata per definire quali elementi etichettare o mostrare sulla mappa.

  • Creare un simbolo diverso (tipo) per il layer, usando il generatore di geometrie:

    point_on_surface( $geometry )

  • Dato un elemento puntuale, genera una linea chiusa (usando make_line) intorno alla sua geometria:

    make_line(
  -- using an array of points placed around the original
  array_foreach(
    -- list of angles for placing the projected points (every 90°)
    array:=generate_series( 0, 360, 90 ),
    -- translate the point 20 units in the given direction (angle)
    expression:=project( $geometry, distance:=20, azimuth:=radians( @element ) )
  )
)

  • In un’etichetta del layout di stampa, visualizzare il nome degli elementi « airports» che si trovano all’interno dell’elemento « Map 1 « del layout:

    with_variable( 'extent',
               map_get( item_variables( 'Map 1' ), 'map_extent' ),
               aggregate( 'airports', 'concatenate', "NAME",
                          intersects( $geometry, @extent ), ' ,'
                        )
             )

13.1.1.4. Salvare le Espressioni

Usando il pulsante fileSave Aggiungi l’espressione corrente alle espressioni utente sopra il riquadro dell’editor di espressioni, puoi salvare le espressioni importanti a cui vuoi avere accesso rapido. Queste sono disponibili nel gruppo Espressioni utente nel pannello centrale. Sono salvate sotto il user profile (<userprofile>/QGIS/QGIS3.ini file) e disponibili in tutte le finestre di dialogo delle espressioni all’interno di tutti i progetti del profilo utente corrente.

Un insieme di strumenti disponibili sopra la cornice dell’editor di espressioni ti aiuta a gestire le espressioni utente:

  • fileSaveAggiungi l’espressione corrente alle espressioni dell’utente: memorizza l’espressione nel profilo dell’utente. Un’etichetta e un testo di aiuto possono essere aggiunti per una facile interpretazione.

  • symbologyEdit Modifica l’espressione selezionata dalle espressioni utente, così come il relativo testo di aiuto e l’etichetta

  • deleteSelected Rimuovi l’espressione selezionata dalle espressioni utente

  • sharingImport Importa le espressioni utente da un file .json nella cartella del profilo utente attivo

  • sharingExport Esporta Espressioni Utente come file .json; tutte le espressioni utente sono condivise nel profilo utente QGIS3.ini

13.1.2. Editor delle Funzioni

Con la scheda Editor delle Funzioni, puoi scrivere le tue funzioni nel linguaggio Python. Ciò fornisce un modo pratico e comodo per affrontare esigenze particolari che non sarebbero coperte dalle funzioni predefinite.

../../../_images/function_editor.png

Fig. 13.2 La scheda Editor delle Funzioni

Per creare una nuova funzione:

  1. Premi il pulsante symbologyAdd Nuovo File.

  2. Inserisci un nome da utilizzare nel modulo che compare e premi OK.

    Un nuovo oggetto con il nome da te fornito viene aggiunto nel pannello sinistro della scheda Editor delle Funzioni; si tratta di un file .py basato sul file del modello predefinito di QGIS e memorizzato nella cartella /python/expressions sotto la directory attiva user profile.

  3. Il pannello di destra mostra il contenuto del file: un template di script python. Aggiorna il codice e il suo aiuto in base alle tue esigenze.

  4. Premi il pulsante start Salva e Carica Funzioni. La funzione scritta viene aggiunta all’albero delle funzioni nella scheda Espressione, di default nel gruppo Custom.

  5. Goditi la tua nuova funzione.

  6. Se la funzione necessita di miglioramenti, abilita la scheda Editor delle Funzioni, fai le modifiche e premi nuovamente il pulsante start Salva e Carica Funzioni per renderle disponibili nel file, quindi in qualsiasi scheda di espressione.

Le funzioni personalizzate Python sono memorizzate nella directory del profilo utente, il che significa che ad ogni avvio di QGIS, caricherà automaticamente tutte le funzioni definite con il profilo utente corrente. Tieni presente che le nuove funzioni vengono salvate solo nella cartella /python/expressions e non nel file di progetto. Se condividi un progetto che utilizza una delle tue funzioni personalizzate, dovrai anche condividere il file .py nella cartella /python/expressions.

Per eliminare una funzione personalizzata:

  1. Abilita la scheda Editor delle Funzioni.

  2. Seleziona la funzione nella lista

  3. Premi il symbologyRemove Rimuove il file funzioni selezionato. La funzione viene rimossa dalla lista e il file .py corrispondente viene eliminato dalla cartella del profilo utente.

Esempio

Ecco un breve esempio su come creare la propria funzione my_sum che opererà con due valori.

from qgis.core import *
from qgis.gui import *

@qgsfunction(args='auto', group='Custom')
def my_sum(value1, value2, feature, parent):
    """
    Calculates the sum of the two parameters value1 and value2.
    <h2>Example usage:</h2>
    <ul>
      <li>my_sum(5, 8) -> 13</li>
      <li>my_sum("field1", "field2") -> 42</li>
    </ul>
    """
    return value1 + value2

Il decoratore @qgsfunction accetta i seguenti argomenti:

  • args: il numero di argomenti. Quando si usa l’argomento args='auto', il numero di argomenti della funzione richiesti sarà calcolato in base al numero di argomenti con cui la funzione è stata definita in Python (minus 2 - feature, and parent). Con args = -1, viene accettato qualsiasi numero di argomenti.

  • L’argomento ``group”” indica il gruppo in cui la funzione deve essere elencata nella finestra di dialogo Espressione.

  • usesgeometry=True se l’espressione richiede l’accesso alla geometria dell’elemento. Per default False.

  • handlesnull=True se l’espressione ha una gestione personalizzata per i valori NULL. Se False (default), il risultato sarà sempre NULL ogni volta che qualsiasi parametro è NULL.

  • referenced_columns=[elenco]: Un array di nomi di attributi che sono richiesti alla funzione. Il valore predefinito è [QgsFeatureRequest.ALL_ATTRIBUTES].

La funzione ammette i seguenti argomenti:

  • il numero e il tipo di parametri che vuoi passare alla funzione, impostati prima dei seguenti argomenti.

  • feature: l’elemento corrente

  • parent: l’oggetto QgsExpression.

  • context: Se c’è un argomento chiamato context trovato in ultima posizione, questa variabile conterrà un oggetto QgsExpressionContext, che dà accesso a varie informazioni aggiuntive come le variabili dell’espressione. Ad esempio, context.variable( 'layer_id' )

La funzione dell’esempio precedente può quindi essere utilizzata nelle espressioni:

../../../_images/customFunction.png

Fig. 13.3 Funzione personalizzata aggiunta alla scheda Espressione

Ulteriori informazioni sulla creazione di codice Python possono essere trovate nel Cookbook PyQGIS per gli sviluppatori.