Important

La traduction est le fruit d’un effort communautaire auquel vous pouvez vous joindre. Cette page est actuellement traduite à 85.95%.

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

13.1.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 à:

  • Expression tab which, thanks to a list of predefined functions, helps to write and check the expression to use;

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

13.1.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. 13.1 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 propriétés des entités à l’aide de leurs données

    • A live Output preview of the expression (up to 60 characters), evaluated on the first feature of the Layer by default. To view output preview text exceeding 60 characters, you can hover your cursor over the text to display a tooltip pop-up containing the entire output preview. To copy the output preview text onto your clipboard, right-click on the output preview text and select editCopy Copy Expression Value.

      You can browse and evaluate other features of the layer using the Feature combobox (the values are taken from the display name property of the layer).

      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 du champ 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.

13.1.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. La boîte de dialogue définit le contexte: si vous êtes habitué à SQL, vous connaissez probablement des requêtes du type sélectionner les entités dans la couche répondant à la condition or mettre à jour la couche en fixant le champ = nouvelle_valeur répondant à la condition*. Une expression QGIS a également besoin de toutes ces informations, mais l’outil que vous utilisez pour ouvrir la boîte de dialogue de construction d’expression en fournit une partie. Par exemple, avec une couche (bâtiments) 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.

    • avec cette sélection effectuée, en appuyant sur le bouton| Calculatrice de champs et en choisissant « hauteur » comme Mise à jour du champ existant,vous fournissez déjà la commande « update batiments set hauteur= ??? where hauteur > 20 ». Le seul élément restant à fournir dans ce cas est la nouvelle valeur, par exemple, entrez simplement 50 dans la zone de texte de l’éditeur d’expression pour définir la hauteur des bâtiments précédemment sélectionnés

  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 !

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

  • Select features that overlap a natural zone from the « lands » layer:

    overlay_intersects( layer:='lands', filter:="zone_type"='Natural' )

  • Count for each feature the number of buildings they contain:

    array_length( overlay_contains( layer:='buildings', expression:=@id ) )

  • 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 ), ' ,'
                        )
             )

13.1.1.4. Sauvegarde des expressions

Using the fileSave Add current expression to user expressions button above the expression editor frame, you can save important expressions you want to have quick access to. These are available from the User expressions group in the middle panel. They are saved under the user profile (<userprofile>/QGIS/QGIS3.ini file) and available in all expression dialogs inside all projects of the current user profile.

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

13.1.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. 13.2 L’onglet Éditeur de fonctions

Pour créer une nouvelle fonction :

  1. Appuyez sur le bouton symbologyAdd 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 symbologyRemove 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

The @qgsfunction decorator accepts the following arguments:

  • args: the number of arguments. When using the args='auto' 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). With args = -1, any number of arguments are accepted.

  • The group argument indicates the group in which the function should be listed in the Expression dialog.

  • 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 function itself allows following arguments:

  • any number and type of parameters you want to pass to your function, set before the following arguments.

  • feature : l’entité en cours

  • parent : l’objet de la classe QgsExpression

  • context: If there is an argument called context found at the last position, this variable will contain a QgsExpressionContext object, that gives access to various additional information like expression variables. E.g. context.variable( 'layer_id' )

The previous example function can then be used in expressions:

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

Fig. 13.3 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.