14.2. 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.

14.2.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.

14.2.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. 14.65 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 si definiscono i dati delle proprietà degli elementi.

    • una istantanea Anteprima dell’espressione, valutata sul primo elemento del Layer predefinito. Puoi sfogliare e valutare altre proprietà del layer usando il menu a tendina Elemento (i valori sono presi dalla display name proprietà 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 :ref:` field widget <edit_widgets>` è 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 aiuto per recuperarlo.

14.2.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 usate per aprire la finestra di dialogo del costruttore di espressioni ne fornisce una parte. Per esempio, fornendo un layer (building) con un campo (height):

    • Usando lo strumento expressionSelectSeleziona per espressione significa che vuoi «selezionare gli elementi dagli edifici». 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 «height» come Aggiorna campo esistente, fornisci già il comando «update buildings set height = ??? where height > 20». L’unico dato rimanente che devi fornire in questo caso è il nuovo valore, per esempio inserisci semplicemente 50 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!

14.2.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 ), ' ,'
                            )
                 )
    

14.2.1.4. Salvare le Espressioni

Usando il pulsante fileSave :sup: 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 profilo dell’utente (file <userprofile>/QGIS/QGIS3.ini) e disponibili in tutte le finestre di dialogo delle espressioni in 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:

  • fileSave:sup: Aggiungi 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

14.2.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. 14.66 La scheda Editor delle funzioni

Per creare una nuova funzione:

  1. Premi il pulsante signPlus New 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 :ref:`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 richiede 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. Abilitare la scheda Editor delle funzioni.

  2. Selezionare la funzione nella lista

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

Esempio

Here’s a short example on how to create your own my_sum function that will operate with two values.

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

When using the args='auto' function argument the number of function arguments required will be calculated by the number of arguments the function has been defined with in Python (minus 2 - feature, and parent). The group='Custom' argument indicates the group in which the function should be listed in the Expression dialog.

It is also possible to add keywords arguments like:

  • usesgeometry=True if the expression requires access to the features geometry. By default False.

  • handlesnull=True if the expression has custom handling for NULL values. If False (default), the result will always be NULL as soon as any parameter is NULL.

  • referenced_columns=[list]: An array of attribute names that are required to the function. Defaults to [QgsFeatureRequest.ALL_ATTRIBUTES].

The previous example function can then be used in expressions:

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

Fig. 14.67 Funzione personalizzata aggiunta alla scheda Espressione

Ulteriori informazioni sulla creazione di codice Python possono essere trovate nel PyQGIS cookbook.