Ajouter les outils GRASS

Les modules GRASS peuvent être lancés depuis les Outils GRASS de QGIS si QGIS a été ouvert depuis une console GRASS ou si un jeu de données GRASS a été ouvert dans QGIS. Ces modules ne fonctionnent qu’avec des données GRASS.

Il est facile de modifier le menu et d’y ajouter de nouveaux modules car le menu et les modules sont configurés via des fichiers XML. Ci-dessous, voici comment écrire de nouveaux modules et comment modifier l’arborescence du menu.

Configuration du module

Contexte

Les options de chaque module affichées dans l’onglet _*Options_* du module sont créées en se basant sur la définition présente dans le fichier QGM (QGIS GRASS module) ainsi que la définition présente dans le module GRASS ou le script GRASS GMO (GRASS module options). Etant donné que chaque option dans le QGM est liée à une (ou plusieurs) option(s) dans le GMO, il est souvent nécessaire de consulter le fichier GMO. Les GMO sont extraits par le module GRASS lorsqu’il est lancé avec l’option _*–interface-description_*, la sortie étant au format XML, par exemple:

r.to.vect --interface-description

Certains modules GRASS ont trop d’options qui peuvent être confuses pour des débutants. Dans le fichier QGM, il est possible de n’en définir que certaines et de leur attribuer une valeur par défaut ou de cacher certaines options. Cela signifie que plusieurs modules QGIS-GRASS peuvent être définis pour un module GRASS. Par exemple le module r.to.vect a été séparé en trois modules QGIS-GRASS avec des options prédéfinies. La définition QGM est écrite en XML avec une extension en .qgm, un fichier par module QGIS-GRASS. Les fichiers de configuration sont stockés dans le répertoire _*qgis/src/plugins/grass/modules*_ et installés dans le répertoire _*share/qgis/grass/modules*_. Le nom du fichier doit commencer par le nom du module GRASS + un mot décrivant la tâche. Par exemple, le module qui extrait des lignes vecteur depuis un raster est appelé r.to.vect.line.qgm.

Voici un exemple de fichier de configuration :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE qgisgrassmodule SYSTEM "http://mrcc.com/qgisgrassmodule.dtd">
<qgisgrassmodule label="Generate aspect map from DEM" module="r.slope.aspect">
       <option key="elevation" />
       <option key="aspect" />
</qgisgrassmodule>

Attributs-étiquettes qgisgrassmodule

  • label — description utilisée dans l’arbre du menu
  • module — nom du module GRASS exécutable ou scripté

Etiquettes d’option

Chaque étiquette qgisgrassmodule peut contenir une ou plusieurs options:

  • option – correspond à l’étiquette du paramètre GMO, par exemple:
<option key="elevation" />
  • flag — correspond à l’étiquette de drapeau GMO, par exemple:
<flag key="o" answer="on" hidden="yes" />
  • field — défini l’attribut de champ pour les couches vecteur, l’option est créée sous forme de liste déroulante avec les champs disponibles. Par exemple (v.to.db.qgm):
<field key="column" layer="map" type="integer,double" label="Attribute field" />
  • selection — il s’agit d’un type d’option intéressant et utile. Elle permet de définir une liste de catégories de vecteurs GRASS en utilisant l’interface de QGIS. Les entités (et leurs catégories, l’équivalent de l’identifiant GRASS) peuvent être choisies soit par l’outil “Selection des entités” ou dans la table d’attributs. La liste des catégories est mise à jour dynamiquement. Par exemple (v.extract.list.qgm):
<selection key="list" layerid="input" label="Cats" />

Attributs-étiquettes pour les options/drapeaux courants

  • key — nom de l’option du module GMO
  • answer — valeur par défaut (écrase la valeur par défaut du GMO); la valeur « on » s’applique à un drapeau.
  • hidden — l’option n’apparaîtra pas dans la boîte de dialogue mais le module l’utilisera quand-même (hidden= »yes »).
  • label — label de l’option
  • advanced — « yes » ou « no », la valeur par défaut étant « no ». Si la valeur vaut « yes », l’option ou drapeau est ajouté(e) au panneau initialement masqué des options avancées. Le bouton « Montrer les options avancées >> » est affiché pour les options simples (basique, standard).
  • version_min — version minimum de GRASS pour laquelle cette option ou ce drapeau est valide.
  • version_max — version maximale de GRASS pour laquelle cette option ou ce drapeau est valide.

Attributs-étiquettes sépcifiques

  • typeoption — cette option est utilisée avec les couches vecteur pour définir le nom de l’option du type de vecteur d’entrée. Lorsque le module est lancé, le type de la couche vecteur sélectionnée est utilisé pour cette option. Par exemple (v.overlay.or.qgm):

    <option key="ainput" typeoption="atype" layeroption="alayer" typemask="area,line" />
    

    Cela signifie que si une couche est sélectionnée dans la liste déroulante, l’option _*atype*_ reçoit automatiquement le type de la couche et que cette variable n’a pas à être ajoutée.

  • layeroption — équivalent à typeoption pour une couche (non vecteur).

  • typemask — définit les types de couches vecteur d’entrée autorisés. Seules les couches de l’un des types définis seront affichées en entrée. Voir v.overlay.or.qgm comme exemple.

Attributs spécifiques des champs

  • layer — l’attribut essentiel de l’option qui détermine le vecteur qui dépend de ce champ.

  • type — définit le type des champs d’attribut qui doivent être ajouté à la liste déroulante des champs, par exemple:

    <field key="column" layer="map" type="integer,double" label="Attribute field" />
    

    Cela signifie que seuls les champs d’attribut de type entier ou réel double seront présents dans la liste déroulante. Consultez v.what.vect comme exemple (2 vecteurs différents).

L’envers du décor

L’idée de l’implémentation des modules QGIS-GRASS est d’utiliser le maximum d’informations des fichiers GMO et de simplifier l’interface. Voici quelques règles sur la manière dont sont utilisées les informations GMO et dans quel ordre elles sont utilisées si elles ne sont pas toutes définies dans le GMO.

  • label — si un attribut de label est défini dans le fichier QGM, il est alors utilisé comme label de l’option, s’il n’est pas défini dans le GMO, le label d’option est utilisé. Si ce dernier n’est pas défini dans le GMO, l’étiquette de description d’option est utilisée.
  • tooltip — (apparaît lors du déplacement de la souris sur l’option) si un label est défini (soit dans le QGM ou le GMO) et qu’une description est définie dans le GMO (le label et la description sont différents), alors l’étiquette de description du GMO est utilisée comme infobulle.
  • label multiple values — si l’option a un type multiple avec une liste des valeurs possible (comme les options de chargement de v.distance) et qu’une étiquette de description est définie pour la valeur dans le GMO alors elle sera utilisée comme label de case à cocher.

Icône

Chaque module doit être représenté par une icône qui symbolise la fonction du module. Les icône sont stockées dans le répertoire plugins/grass/modules au format SVG (.svg) ou PNG (.png).

Actuellement, il existe 3 schémas pour les images:

  • 1 image
  • 2 images — QGIS créera l’icône: 1 -> 2
  • 3 images — QGIS crééra l’icône: 1 + 2 -> 3

Le nom de l’image commence par le nom du module QGIS-GRASS auquel est ajouté un numéro d’image, par exemple: v.overlay.and.1.svg, v.overlay.and.2.svg, v.overlay.and.3.svg. Il est possible de combiner des images SVG et PNG.

Les images PNG et SVG peuvent être générées depuis le Composeur de cartes de QGIS. La taille des images PNG est généralement plus volumineuse que la taille de l’icône car il est attendu qu’elles seront utilisées plus tard dans la documentation générée automatiquement où les images utilisées ont une taille plus grande.

Scripts GRASS pour QGIS

Étant donné qu’il peut se passer beaucoup de temps pour qu’un nouveau script soit ajouté à la version stable de GRASS et parce que certains scripts peuvent être utiles seulement pour l’interface graphique de QGIS, il est possible d’ajouter des scripts “GRASS” à QGIS. Les scripts doivent suivre les règles des scripts GRASS et il sont situés dans le répertoire qgis/src/plugins/grass/scripts.

Règles générales pour les nouveaux modules

Les Outils GRASS sont plutôt destinés aux novices et pas pour les utilisateurs avancés. Les règles de base sont les suivantes :

  • Chaque module doit proposer au plus 3 options ; s’il semble nécessaire d’en ajouter, cela doit être discuté au préalable.
  • Le module doit être robuste de telle sorte qu’il ne soit pas possible de lancer le module avec de mauvaises options. S’il n’y a pas de documentation sur certaines options, le module ne doit pas être ajouté au menu.

Règles spécifiques pour les descriptions de modules

  • Évitez la 3ème personne pour les verbes, par exemple utilisez « Exporter le raster » au lieu de « Exporte le raster »
  • Évitez les termes superflus tels que « carte », « couche » et « fichier », par exemple « Exporter le raster » au lieu de « Exporter la couche raster »
  • Évitez le terme « GRASS » quand il n’est pas nécessaire, par exemple « Exporter le raster » au lieu de « Exporter le raster GRASS »
  • Évitez l’emploi de « un/une » ou « des », par exemple « Exporter le raster » au lieu de « Exporter un raster »
  • Évitez les mots superflus, par exemple « Exporter le raster » au lieu de « Permettre l’export du raster »
  • N’employez pas le verbe « Convertir », utilisez « Exporter » ou « Importer ». Le terme convertir doit être utilisé pour des conversions internes à GRASS (par exemple d’un raster vers un vecteur).
  • Les acronymes doivent être écrits en majuscule, par exemple ASCII au lieu de ascii
  • En cas de doute, référez-vous à des modules similaires pour maintenir la cohérence

Options ne pouvant pas être utilisée pour le moment

Techniquement n’importe quelle option peut être employée. Certains types d’options ne sont pas gérées correctement, par exemple, celles qui dépendent d’une autre option. Voici une liste (probablement incomplète) d’options qui ne sont pas gérées correctement et qui ne devraient pas être utilisées pour le moment:

  • Couche ou DSN OGR (v.in.ogr) en entrée

Modules qui peuvent être ajoutés

La majorité des modules peuvent être ajoutés. Si vous en avez besoin de plus, merci d’écrire sur la liste de diffusion de développement de QGIS et de lister les modules que vous pensez être les plus important à ajouter.

Vous devriez publier le nom d’un nouveau module QGIS-GRASS ainsi que le module GRASS et les options que vous souhaitez utiliser. Par exemple:

r.to.vect.area: r.to.vect input output feature=area

Consultez également la liste des modules GRASS-QGIS pertinents.

Modules obsolètes

Voici une liste de modules qui devraient être supprimés avec une explication sur leur problème (ex: certains modules liés aux projections sont difficiles à comprendre et ne sont pas d’une grande utilité). Merci de note que certains modules n’ont pas été complètement testés. Merci de les tester et de remonter une erreur sous redmine (ou mieux encore de faire la correction vous-même et d’envoyer un patch).