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.
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>
label — omschrijving, gebruikt in de menuboom
module — naam van het uitvoerbare bestand of script voor de module van GRASS.
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
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.
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).
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
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.
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.
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
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
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)
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.
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).