14.2. Expressions

Basées sur des données de couches et des fonctions préconstruites ou définies par l’utilisateur, les Expressions offrent un moyen puissant de manipuler la valeur des attributs, la géométrie et les variables afin de modifier dynamiquement le style de géométrie, le contenu ou la position de l’étiquette, la valeur pour le diagramme, la hauteur d’un élément de mise en page, de sélectionner certaines entités, de créer un champ virtuel, …

Note

Une liste des fonctions et des variables par défaut pour l’écriture des expressions se trouve à l’adresse Liste des fonctions, avec des informations détaillées et des exemples.

14.2.1. L’éditeur d’expression

L” éditeur d’expression, principale fenêtre de création des expressions, est accessible en maints endroits dans QGIS, et particulièrement:

La fenêtre de l’éditeur d’expression vous donne accès à:

  • l’onglet Expression qui, grâce à un large panel de fonctions prédéfinies, vous permet d’écrire et de vérifier l’expression à utiliser;

  • l’onglet Function Editor tab qui permet d’étendre cette liste par la création de vos propres fonctions.

14.2.1.1. L’interface

L’onglet Expression fournit l’interface principale pour écrire des expressions en utilisant des fonctions, des champs de couche et des valeurs. Il contient les widgets suivants :

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

Fig. 14.65 L’onglet Expression

  • Une zone d’édition d’expressions pour taper ou coller des expressions. L’auto-complétion est disponible pour accélérer l’écriture des expressions :

    • Les noms de variables, de fonctions ou d’attributs correspondants au texte d’entrée sont indiqués en-dessous : utiliser les touches de flèches Up et Down de votre clavier pour naviguer entre les éléments proposés et appuyer sur la touche Tab pour insérer l’élément dans l’expression ou bien cliquer sur l’élément souhaité.

    • Les paramètres des fonctions sont affichés lors de leur complétion.

    QGIS vérifie également la validité de votre expression et met en valeur les erreurs avec :

    • Un soulignement : pour les fonctions inconnues, fausses ou des arguments invalides ;

    • Un surlignage : pour toutes les autres erreurs (par exemple une parenthèse manquante, un caractère inattendu) à une position.

    Astuce

    Documentez vos expressions avec des commentaires

    Lorsque vous utilisez une expression complexe, il est conseillé d’ajouter du texte soit comme commentaire multiligne, soit dans la ligne pour vous aider à vous en souvenir.

    /*
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
)

  • Au-dessus de l’éditeur d’expressions, un ensemble d’outils vous aide :

  • Sous l’expression éditeur, vous trouvez :

    • un ensemble d’opérateurs de base pour vous aider à construire l’expression

    • une indication du format de sortie attendu lorsque vous définissez les données par les propriétés des entités

    • une Prévisualisation de la sortie de l’expression, évaluée sur la première entité de la couche par défaut. Vous pouvez parcourir et évaluer les autres entités de la couche en utilisant la combobox Entité (les valeurs sont tirées de la propriété display name de la couche).

      En cas d’erreur, il l’indique et vous pouvez accéder aux détails grâce à l’hyperlien fourni.

  • Un sélecteur de fonctions affiche la liste des fonctions, des variables, des champs… organisés par groupes. Une boîte de recherche est disponible pour filtrer la liste et trouver rapidement une fonction particulière ou un champ. Double-cliquer sur le nom d’un objet l’ajoute au texte de l’expression en cours de rédaction dans la zone d’éditeur.

  • Un onglet d’aide affiche l’aide pour chaque objet sélectionné dans le sélecteur de fonction.

    Astuce

    Faites un Ctrl+Clic lorsque vous survolez le nom d’une fonction dans une expression pour afficher automatiquement son aide dans la boîte de dialogue.

    Le widget des valeurs d’un champ affiché lorsqu’un champ est sélectionné dans le sélecteur de fonction permet de récupérer les attributs des entités :

    • Rechercher une valeur de champ particulière

    • Afficher la liste des valeurs de Toutes les valeurs uniques ou Echantillon de 10 valeurs. Egalement disponible en cliquant sur le bouton droit de la souris.

      Lorsque le champ est mappé avec une autre couche ou un ensemble de valeurs, c’est-à-dire si le widget field widget est de type RelationReference, ValueRelation ou ValueMap, il est possible de lister toutes les valeurs du champ mappé (de la couche, table ou liste référencée). De plus, vous pouvez filtrer cette liste en utilisant la fonction checkbox Seules les valeurs en cours d’utilisation dans le champ courant.

    Un double-clic sur la valeur d’un champ dans le widget l’ajoute à l’éditeur d’expressions.

    Astuce

    Il arrive que le panneau de droite, qui montre l’aide des fonctions ou les champs des valeurs soit caché (invisible) dans la boîte de dialogue. Cliquer sur les boutons Montrer les valeurs ou Montrer l’aide pour le faire réapparaître.

14.2.1.2. Écrire une expression

Les expressions QGIS sont utilisées pour sélectionner des entités ou fixer des valeurs. L’écriture d’une expression dans QGIS suit certaines règles :

  1. Le dialogue définit le contexte : si vous êtes habitué au SQL, vous connaissez probablement des requêtes du type select features from layer where condition ou update layer set field = new_value where condition. Une expression QGIS a également besoin de toutes ces informations, mais l’outil que vous utilisez pour ouvrir le dialogue de création d’expressions en fournit des parties. Par exemple, une couche (bâtiment) avec un champ (hauteur) :

    • en appuyant sur l’outil expressionSelectSélectionner par expression cela signifie que vous voulez « sélectionner des entités de bâtiments ». La condition est la seule information que vous devez fournir dans le widget d’expression de texte, par exemple, tapez "hauteur" > 20" pour sélectionner les bâtiments qui sont plus hauts que 20.

    • Une fois cette sélection effectuée, en appuyant sur le bouton calculateField Calculatrice de champ et en choisissant « height » comme Mettre à jour le champ existant, vous fournissez déjà la commande « update buildings set height = ??? où height > 20 ». Les seuls éléments restants que vous devez fournir dans ce cas sont la nouvelle valeur, par exemple, entrez simplement 50 pour définir la hauteur des bâtiments sélectionnés précédemment.

  2. Attention aux guillemets : les guillemets simples renvoient un littéral, donc un texte placé entre des guillemets simples ('145') est interprété comme une chaîne. Les guillemets doubles vous donneront la valeur de ce texte, donc utilisez-les pour les champs ("myfield"). Les champs peuvent également être utilisés sans guillemets (myfield). Pas de guillemets pour les chiffres (3.16).

    Note

    Les fonctions prennent normalement comme argument une chaîne de caractères pour le nom du champ. Faites: :

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

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

Astuce

Utiliser des paramètres nommés pour faciliter la lecture des expressions

Certaines fonctions nécessitent le réglage de nombreux paramètres. Le moteur d’expression supporte l’utilisation de paramètres nommés. Cela signifie qu’au lieu d’écrire l’expression cryptique clamp( 1, 2, 9), vous pouvez utiliser clamp( min:=1, value:=2, max:=9). Cela permet également de changer d’argument, par exemple clamp( value:=2, max:=9, min:=1). L’utilisation de paramètres nommés permet de clarifier à quoi se réfèrent les arguments d’une fonction d’expression, ce qui est utile lorsque vous essayez d’interpréter une expression plus tard !

14.2.1.3. Exemples d’applications

  • À partir de la calculatrice de champs, calculez un champ « pop_density » en utilisant les champs « total_pop » et « area_km2 » existants: :

    "total_pop" / "area_km2"

  • Étiqueter ou catégoriser les entités en fonction de leur surface: :

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

  • Mettre à jour le champ « density_level » avec les catégories basées sur les valeurs de « 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

  • Appliquer un style catégorisé à l’ensemble des entités selon que le prix moyen des maisons est inférieur ou non à 10000€ le mètre carré:

    "price_m2" > 10000

  • En utilisant l’outil « Sélectionner à l’aide d’une expression… », sélectionner toutes les entités qui représentent des surfaces avec une « grande densité de population » et dont le prix moyen des maisons est supérieur à 10000€ le mètre carré:

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

    L’expression précédente pourrait également être utilisée pour définir les entités à étiqueter ou à montrer sur la carte.

  • Créez un symbole (type) différent pour la couche, en utilisant le générateur de géométrie: :

    point_on_surface( $geometry )

  • Etant donné une entité ponctuelle, générez une ligne fermée (en utilisant make_line) autour de sa géométrie: :

    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 ) )
  )
)

  • Afficher dans une étiquette le nom de toutes les entités « airports » visibles dans l’élément de carte « Map 1 » de la mise en page:

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

14.2.1.4. Sauvegarde des expressions

En utilisant le bouton fileSave Ajouter l’expression courante aux expressions de l’utilisateur au-dessus du cadre de l’éditeur d’expressions, vous pouvez sauvegarder les expressions importantes auxquelles vous voulez avoir un accès rapide. Celles-ci sont disponibles dans le groupe Expressions utilisateur dans le panneau du milieu. Elles sont enregistrées sous le profil utilisateur (fichier <userprofile>/QGIS/QGIS3.ini) et sont disponibles dans tous les dialogues d’expression à l’intérieur de tous les projets du profil utilisateur actuel.

Un ensemble d’outils disponibles au-dessus du cadre de l’éditeur d’expressions vous aide à gérer les expressions des utilisateurs :

  • fileSaveAjouter l’expression courante aux expressions de l’utilisateur : stocker l’expression dans le profil de l’utilisateur. Une étiquette et un texte d’aide peuvent être ajoutés pour faciliter l’identification.

  • symbologyEdit Modifier l’expression sélectionnée parmi les expressions utilisateur, ainsi que leur aide et leur libellé

  • deleteSelected Supprimer l’expression sélectionnée des expressions de l’utilisateur

  • sharingImport Importer des expressions utilisateur depuis un fichier .json dans le dossier du profil utilisateur actif

  • sharingExport Exporter les expressions utilisateur comme un fichier .json ; toutes les expressions utilisateur dans le profil utilisateur QGIS3.ini sont exportées

14.2.2. Éditeur de fonctions

Avec l’onglet editeur de fonction, vous pouvez écrire vos propres fonctions en langage Python. Cela fournit un moyen pratique et confortable de répondre à des besoins particuliers qui ne seraient pas couverts par les fonctions prédéfinies.

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

Fig. 14.66 L’onglet Éditeur de fonctions

Pour créer une nouvelle fonction :

  1. Appuyez sur le bouton signPlus Nouveau Fichier.

  2. Entrez un nom à utiliser dans le formulaire qui apparaît et appuyez sur OK.

    Un nouvel élément du nom que vous fournissez est ajouté dans le panneau de gauche de l” onglet Editeur de fonctions; il s’agit d’un fichier Python .py basé sur le fichier modèle QGIS et stocké dans le dossier /python/expressions sous le répertoire du profil utilisateur en cours.

  3. Le panneau de droite affiche le contenu du fichier: un modèle de script python. Mettez à jour le code et son aide en fonction de vos besoins.

  4. Appuyez sur le bouton start Enregistrer et charger les fonctions. La fonction que vous avez écrite est ajoutée à l’arborescence des fonctions dans l’onglet Expression, par défaut sous le groupe Personnalisé.

  5. Profitez donc de votre nouvelle fonction.

  6. Si la fonction nécessite des améliorations, activez l’onglet Editeur de fonctions, effectuez les modifications et appuyez à nouveau sur le bouton start Enregistrer et charger les fonctions pour les rendre disponibles dans le fichier, donc dans n’importe quel onglet d’expression.

Les fonctions Python personnalisées sont stockées sous le répertoire du profil utilisateur, ce qui signifie qu’à chaque démarrage de QGIS, il chargera automatiquement toutes les fonctions définies avec le profil utilisateur actuel. Sachez que les nouvelles fonctions ne sont enregistrées que dans le dossier /python/expressions et non dans le fichier de projet. Si vous partagez un projet qui utilise l’une de vos fonctions personnalisées, vous devrez également partager le fichier .py dans le dossier /python/expressions.

Pour supprimer une fonction personnalisée :

  1. Activez l’onglet Editeur fonction.

  2. Sélectionnez la fonction dans la liste

  3. Appuyez sur le signMinus Supprimer la fonction sélectionnée. La fonction est supprimée de la liste et le fichier .py correspondant est supprimé du dossier du profil de l’utilisateur.

Exemple

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 Fonction personnalisée ajoutée à l’onglet Expression

Plus d’informations sur la création de code Python peuvent être trouvées dans Développement PyQGIS - Livre de recettes.