GRASS-gereedschappen toevoegen

Modules voor GRASS kunnen worden uitgevoerd vanuit QGIS GRASS Tools als QGIS werd gestart vanuit een shell voor GRASS of als een mapset voor GRASS werd geopend in QGIS. De modules werken alleen met gegevens voor GRASS.

Het is eenvoudig om het menu aan te passen en nieuwe modules toe te voegen omdat zowel het menu als de modules zijn gedefinieerd in de XML configuratiebestanden. Hieronder wordt beschreven hoe nieuwe modules te schrijven en de menuboom aan te passen.

Configuratie van module

Achtergrond

De opties voor elke module die wordt weergegeven op de tab _*Options_* van de modules worden gemaakt in overeenstemming met de combinatie van de definitie in het bestand QGM (QGIS GRASS module) en de definitie van de opties in GRASS module of GRASS script — GMO (GRASS moduleopties). Omdat elke optie in QGM is gekoppeld aan één (of meer) GMO, is het vaak handig, of zelfs noodzakelijk, om de GMO te bekijken. GMO’s worden uitgevoerd door de module van GRASS als die wordt uitgevoerd met de optie _*–interface-description_*, de uitvoer is in de indeling XML, bijvoorbeeld:

r.to.vect --interface-description

Sommige modules voor GRASS hebben teveel opties, die gebruikers in verwarring kunnen brengen. In QGM is het mogelijk om slechts enkele ervan te definiëren en is het mogelijk enkele standaardwaarden in te stellen en/of sommige opties met een bepaalde waarde te verbergen. Dat betekent dat meer modules voor QGIS-GRASS kunnen worden gedefinieerd voor elke module van GRASS. De module r.to.vect werd bijvoorbeeld opgedeeld in drie modules voor QGIS-GRASS met de vooraf gedefinieerde optie voor “feature”. De definitie voor QGM is geschreven in een bestand in de indeling XMLmet de extensie .qgm, één voor elke module van QGIS-GRASS module. Configuratiebestanden zijn opgeslagen in de map _*qgis/src/plugins/grass/modules*_ en geïnstalleerd in de map _*share/qgis/grass/modules*_. De naam van het bestand zou moeten beginnen met de naam van de module van GRASS + een woord dat de specifieke taak beschrijft. Bijvoorbeeld: de module die vectorlijnen uit een raster uitneemt is genaamd r.to.vect.line.qgm.

Hier is een voorbeeld van een configuratiebestand:

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

qgisgrassmodule tagattributen

  • label — omschrijving, gebruikt in de menuboom
  • module — naam van het uitvoerbare bestand of script voor de module van GRASS.

Optie-tags

Elke tag qgisgrassmodule mag één of meer optietags bevatten:

  • option — correspondeert met de parametertag GMO, bijvoorbeeld:
<option key="elevation" />
  • flag — correspondeert met de GMO flagtag, biojvoorbeeld:
<flag key="o" answer="on" hidden="yes" />
  • field — voor vectorlagen definieert dit het veld voor het attribuut, de optie wordt gemaakt als combinatievak met de beschikbare velden. Bijvoorbeeld (v.to.db.qgm):
<field key="column" layer="map" type="integer,double" label="Attribute field" />
  • selection — dit is een zeer interessant en nuttig type option. Het maakt het mogelijk een lijst van GRASS vectorcategorieën te definiëren met behulp van de interface van QGIS. Objecten (en hun categorieën, equivalent voor het GRASS object-ID) kunnen worden geselecteerd ofwel met het gereedschap ‘Objecten selecteren’ of in de attributentabel. De lijst met categorieën wordt dynamisch bijgewerkt. Voorbeeld (v.extract.list.qgm):
<selection key="list" layerid="input" label="Cats" />

Algemene optie/vlag tagattributen

  • key — naam van de moduleoptie in GMO.
  • answer — standaard waarde (overschrijft standaard waarde GMO); waarde “on” zal een vlag inschakelen.
  • hidden — de optie zal niet in het dialoogvenster verschijnen, maar de module zal worden uitgevoerd met deze optie (hidden=”yes”).
  • label — optie label
  • advanced — “yes” of “no”, standaard is “no”. Indien ingesteld op “yes”, wordt de optie/vlag toegevoegd aan het initieel verborgen gevorderde optiepaneel en de knop “Show advanced options >>” wordt weergegeven onder de eenvoudige (basic,standard) opties
  • version_min — minimale versie van GRASS waarvoor deze optie/vlag geldig is
  • version_max — maximale versie van GRASS waarvoor deze optie/vlag geldig is

Optietag specifieke attributen

  • typeoption — deze optie kan worden gebruikt met vectorlagen om de naam van het type vectorinvoer te definiëren, wanneer de module wordt uitgevoerd, het type geselecteerde vectorlaag zal worden gebruikt voor die optie. Bijvoorbeeld (v.overlay.or.qgm):

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

    Het betekent dat als een laag is geselecteerd uit een combinatievak van deze optie de optie _*atype*_ automatisch wordt ingesteld op het type van de laag, en dus hoeft _*atype*_ in het geheel niet te worden toegevoegd.

  • layeroption — equivalent van typeoption voor de laag.

  • typmask — voor vectorinvoer optie definieert de toegestane typen. Alleen de lagen van één van de gedefinieerde typen worden weergegeven in de invoer. Zie v.overlay.or.qgm voor ene voorbeeld.

Veldtag specifieke attributen

  • layer — het sleutelattribuut van de optie wat de vector definieert waarvan dit veld afhankelijk is

  • type — definieert typen attribuutvelden die zouden moeten worden toegevoegd aan het combinatievak voor het veld, bijvoorbeeld

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

    Het betekent dat alleen de attribuutvelden van de typen integer en double precisie zullen verschijnen in het combinatievak. Zie v.what.vect voor een voorbeeld (2 verschillende vectoren).

Achter de schermen

Het idee van de implementatie van de modules QGIS-GRASS is om maximale informatie uit GMO te gebruiken en alleen de interface te vereenvoudigen. Hier worden enkele regels beschreven over hoe informatie vanuit GMO wordt gebruikt en in welke volgorde als zij niet allemaal zijn gedefinieerd in GMO.

  • label — als het attribuut label is gedefinieerd in QGM wordt het gebruikt als optielabel, als het niet is gedefinieerd wordt de GMO-optie tag label gebruikt en als het niet is gedefinieerd wordt de GMO-optie tag description gebruikt
  • tooltip — (verschijnt bij cursor boven de optie) als een label is gedefinieerd (ofwel in QGM of in GMO) en beschrijving is gedefinieerd in GMO (dus label en beschrijving verschillen van elkaar) wordt de tag van de beschrijving in GMO gebruikt voor de Helptip
  • multiple values label — als een optie van het type multiple is met ee gedefinieerde lijst van mogelijke waarden (zoals de optie upload van v.distance) en de description tag is gedefinieerd voor de value tag in GMO dan wordt het gebruikt als een label voor een keuzevak

Afbeelding

Elke module moet ook worden weergegeven door een afbeelding/pictogram die de functionaliteit van de module symboliseert. De afbeeldingen worden ook opgeslagen in plugins/grass/modules als SVG- (.svg) of PNG- (.png) bestanden.

Momenteel worden 3 schema’s voor de afbeelding ondersteund:

  • 1 picture
  • 2 pictures — QGIS zal pictogram maken: 1 -> 2
  • 3 pictures — QGIS zal pictogram maken: 1 + 2 -> 3

De naam van de afbeelding begint met de naam van de module voor QGIS-GRASS waaraan een nummer voor de afbeelding is toegevoegd, bijvoorbeeld: v.overlay.and.1.svg, v.overlay.and.2.svg, v.overlay.and.3.svg. Het is mogelijk om afbeeldingen SVG en PNG te vombineren.

Afbeeldingen SVG en PNG kunnen vanuit QGIS worden gegenereerd met behulp van Printvormgeving. De grootte van PNG-afbeeldingen zou groter kunnen zijn dan de verwachte afmeting va het pictogram, omdat wordt verwacht dat ze later worden gebruikt in automatisch gegenereerde documentatie, waar afbeeldingen in ene grotere afmeting worden gebruikt.

QGIS GRASS scripts

Omdat het lang kan duren voor een nieuw script wordt toegevoegd aan een stabiele uitgave van GRASS en omdat sommige scripts alleen handig zou kunnen zijn voor de GUI-interface van QGIS is het mogelijk om een ‘GRASS’-script toe te voegen aan QGIS. De scripts zouden algemene vereisten voor GRASS-scripts moeten volgen en zij worden geplaatst in qgis/src/plugins/grass/scripts.

Algemene regels voor nieuwe modules

GRASS Tools zijn vooral bedoeld voor beginners en niet erg ervaren gebruikers. De basisregels zijn:

  • Elke module zou 3 of minder opties moeten hebben; als het nodig lijkt te zijn om meer opties toe te voegen, zou dat van tevoren moeten worden besproken
  • De definitie van een module zou robuust moeten zijn zodat het een gebruiker niet toestaat de module uit te voeren met een verkeerde optie. Als er nog geen ondersteuning is voor een bepaald type optie zou de module niet moeten worden toegevoegd aan het menu

Specifieke regels voor omschrijvingen van modules

  • Vermijd de 3e persoon voor werkwoorden, bijv. “Export raster” in plaats van “Exports raster”
  • Vermijd onnodige “map”, “layer” en “file”, bijv. “Export raster” in plaats van “Export raster map layer”
  • Vermijd onnodige “GRASS”, bijv. “Export raster” in plaats van “Export GRASS raster”
  • Vermijd “a|an”, bijv. “Export raster” in plaats van “Export a raster”
  • Vermijd overbodige woorden, bijv. “Export raster” in plaats van “Allows the export of a raster”
  • Vermijd “Convert”: gebruik in plaats daarvan “Export” of “Import”. Convert zou moeten worden gebruikt voor interne conversies binnen GRASS (bijv. van raster naar vector)
  • Acroniemen zouden in hoofdletters moeten staan, bijv. ASCII in plaats van ascii
  • Controleer, in geval van twijfel, de bestaande soortgelijke plug-ins om consistentie te behouden

Opties die momenteel niet kunnen worden gebruikt

Technisch gezien kan elke optie worden gebruikt. Sommige soorten opties worden echter nog niet goed ondersteund, bijvoorbeeld die welke afhankelijk zijn van een andere optie. Hier is een lijst (waarschijnlijk niet volledig) van opties die nog niet goed worden ondersteund en momenteel nog niet gebruikt zouden moeten worden:

  • OGR input dsn/layer (v.in.ogr)

Modules die kunnen worden toegevoegd

De meeste modules zijn toegevoegd. Als u aanvullende nodig heeft, schrijf dan naar de mailinglijst voor ontwikkelaars van QGIS, en vermeld daar de modules waarvan u denkt dat zij het meest belangrijk zijn om te worden toegevoegd.

U zou de naam van een nieuwe module voor QGIS-GRASS moeten posten, de naam van de module van GRASS en de opties die u wilt gebruiken. Bijvoorbeeld:

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

Zie ook hier voor bespreken van GRASS-QGIS relevante lijst met modules.

Modules die komen te vervallen

Vermeld hieronder de modules die zouden moeten worden verwijderd, met een omschrijving voor deze suggestie (bijv.: sommige modules gerelateerd aan projecties ziijn moeilijk te begrijpen en niet van algemeen nut). Onthoud echter: sommige modules zijn niet grondig getest. Test ze zelf en als u een probleem ermee ontdekt, rapporteer het aan Redmine (nog beter: repareer het zelf en stuur de patch).