Important

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

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:

• en cliquant sur le bouton ;

• en sélectionnant des entités à l’aide de l’outil ^{Sélectionner les entités en utilisant une expression…};

• en éditant les attributs à l’aide par exemple de l’outil ^{Calculatrice de champ};

• en manipulant la symbologie, les étiquettes, les propriétés des éléments du composeur avec l’outil ^{Valeurs définies par des données} (voir Valeurs définies par des données);

• en paramétrant un symbole de couche de type générateur de géométrie ;

• lors de certains géotraitements.

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 Éditeur de fonction 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 :

Fig. 13.1 L’onglet Expression

• Une zone d’édition d’expressions pour saisir ou coller des expressions. L’auto-complétion est disponible pour accélérer la rédaction 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 Haut et Bas 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 :

  • ^{Effacer l’éditeur d’expression}

  • Créer et gérer les expressions de l’utilisateur

• Sous l’éditeur d’expression, 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

  • Un Aperçu du résultat de l’expression (jusqu’à 60 caractères) évaluée par défaut sur la première entité de la couche. Pour visualiser le texte de l’aperçu au-delà des 60 caractères, vous pouvez passer votre curseur sur le texte pour afficher une info-bulle contenant l’intégralité du résultat. Pour copier le texte de l’aperçu de sortie dans votre presse-papiers, faites un clic droit sur le texte et sélectionnez Copier la valeur de l’expression.

    Vous pouvez parcourir et évaluer les autres entités de la couche en utilisant la liste déroulante Entité (les valeurs sont tirées de la propriété nom d’affichage 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 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 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é au SQL, vous connaissez probablement des requêtes du type select fields from layer where condition ou update layer set field = new_value where condition pour sélectionner ou mettre à jour des données. 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) ayant un champ (hauteur):

   • en appuyant sur l’outil ^{Sélectionner par expression} vous indiquez déjà 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.

• Sélectionner les entités qui se superposent à une zone naturelle dans la couche « lands »

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

• Dénombrer pour chaque entité le nombre de bâtiments qu’elle contient

  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

Le bouton ^{Ajouter l’expression actuelle aux expressions de l’utilisateur} au-dessus de la zone de rédaction de l’expression permet d’enregister les expressions importantes auxquelles vous souhaitez avoir rapidement accès. Elles sont disponibles sous le groupe Expressions de l’utilisateur dans le panneau central. Elles sont sauvegardées dans le profil utilisateur (fichier <userprofile>/QGIS/QGIS3.ini) et disponibles dans toutes les fenêtres d’expression de tous les projets ouverts avec ce profil utilisateur.

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

• ^{Ajouter 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.

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

• ^{Supprimer l’expression sélectionnée des expressions de l’utilisateur}

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

• ^{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 Éditeur 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.

Fig. 13.2 L’onglet Éditeur de fonctions

Pour créer une nouvelle fonction :

1. Appuyez sur le bouton ^{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 Éditeur 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 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 Éditeur de fonctions, effectuez les modifications et appuyez à nouveau sur le bouton 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 Éditeur de fonction.

2. Sélectionnez la fonction dans la liste

3. Appuyez sur le ^{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

Voici une courte illustration de comment créer une fonction my_sum qui opérera avec deux valeurs.

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

Le décorateur @qgsfunction accepte les arguments suivants :

• args : le nombre d’arguments. Lorsque l’argument args='auto' est utilisé, le nombre d’arguments requis par la fonction correspond au nombre d’arguments définis dans la fonction en Python, moins 2 ( feature et parent). Avec args = -1, vous pouvez passer n’importe quel nombre d’arguments.

• L’argument group indique le groupe dans lequel la fonction sera affichée dans la liste des expressions.

• usesgeometry=True : si l’expression nécessite l’accès à la géométrie des entités. Par défaut, False.

• handlesnull=True : si l’expression a une gestion particulière des valeurs NULL. Si False (la valeur par défaut), le résultat sera toujours NULL dès lors qu’un des paramètres est NULL.

• referenced_columns=[list] : une liste des noms de champs requis par la fonction. La valeur par défaut est [QgsFeatureRequest.ALL_ATTRIBUTES].

La fonction elle-même permet les arguments suivants :

• tout type et nombre de paramètres que vous souhaitez passer à la fonction, définis avant les arguments ci-après.

• feature : l’entité en cours

• parent : l’objet de la classe QgsExpression

• context : s’il y a un argument nommé context en dernière position, cette variable contiendra un objet QgsExpressionContext qui permet l’accès à des informations additionnelles telles que les variables d’expression. Par exemple, context.variable( 'layer_id' )

Le précédent exemple de fonction peut ensuite être utilisé dans les expressions :

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.