Adición de herramientas GRASS

Los módulos GRASS pueden ser ejecutados desde las GRASS Tools de QGGIS si QGIS fue iniciado desde una shell GRASS o si un mapset GRASS fue abierto desde QGIS. Los módulos solo trabajan con datos GRASS.

Es fácil modificar el menú y adicionar nuevos módulos porque tanto el menú como los módulos están definidos en archivos de configuración XML. Se describe abajo como escribir nuevos módulos y modificar el árbol de menú.

Módulo de configuración

Antecedentes

The options of each module shown in module’s_*Options_*tab are created according to combination of definition in QGM (QGIS GRASS module) file and options definition in GRASS module or GRASS script — GMO (GRASS module options). Because each option in QGM is linked to one (or more) GMO, it is often useful if not necessary to see GMO. GMO are output by GRASS module if it is run with _*–interface-description_* option, the output is in XML format, for example:

r.to.vect --interface-description

Some GRASS modules have too many options which can be confusing for beginners. In QGM it is possible to define only some of them and possibly set some default values and/or hide some options with certain value. That means that more QGIS-GRASS modules can be defined for each GRASS module. For example the module r.to.vect was divided into three QGIS-GRASS modules with predefined «feature» option. The QGM definition is written in XML format file with extension .qgm, one for each QGIS-GRASS module. Configuration files are stored in _*qgis/src/plugins/grass/modules*_ directory and installed in _*share/qgis/grass/modules*_ directory. The name of the file should start with GRASS module name + a word describing the specific task. For example, the module which extracts vector lines from raster is called r.to.vect.line.qgm.

Aquí tiene un ejemplo de un archivo de configuración:

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

  • etiqueta – descripción usada en árbol de menú
  • module — nombre del ejecutable o script del módulo GRASS

Pestañas de opción

Cada pestaña del módulo de grass en qgis puede contener una o más de una opción:

  • opción — corresponde a la etiqueta de parámetro GMO, por ejemplo:
<option key="elevation" />
  • flag — corresponds to GMO flag tag, example:
<flag key="o" answer="on" hidden="yes" />
  • field — for vector layers defines attribute field, the option is created as combobox with available fields. For example (v.to.db.qgm):
<field key="column" layer="map" type="integer,double" label="Attribute field" />
  • selection — this is quite interesting and useful type of option. It allows to define list of GRASS vector categories using QGIS interface. Features (and their categories, GRASS feature ID equivalent) can be selected either with “Select Features” tool or in the attribute table. The list of categories is updated dynamically. Example (v.extract.list.qgm):
<selection key="list" layerid="input" label="Cats" />

Atributos comunes de etiqueta opción/bandera

  • key — name of module option in GMO.
  • answer — default value (overwrites GMO default value); value «on» will switch on a flag.
  • hidden — the option will not appear in the dialog, but module will be run with this option (hidden=»yes»).
  • etiqueta — opción etiqueta
  • advanced — «yes» or «no», default is «no». If set to «yes», the option/flag is add to initially hidden advanced options panel and «Show advanced options >>» button is shown under simple (basic,standard) options
  • version_min — versión GRASS mínima para la cual esta opción/bandera es válida
  • version_max — máxima versión GRASS para la cual esta opción/bandera es válida

Option tag specific attributes

  • typeoption — this option can be used with vector layer to define the name of vector input type option, when module is run, the type of selected vector layer will be used for that option. For example (v.overlay.or.qgm):

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

    It means that if a layer is selected from combobox of this option the _*atype*_ option is automaticaly set to the layer’s type, and thus _*atype*_ does not have to be added at all.

  • layeroption — equivalent of typeoption for layer.

  • typmask — for vector input option defines allowed types. Only the layers of one of defined type are displayed in input. See v.overlay.or.qgm for example.

Field tag specific attributes

  • layer — the key attribute of the option which defines the vector this field should depend on

  • type — defines types of attribute fields which should be added to the field combobox, for example

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

    Significa que sólo los campos atributos de tipo entero y doble precisión aparecerán en el combobox. Vea v.what.vect para ejemplo (2 vectores diferentes).

Detrás de escena

The idea QGIS-GRASS modules implementation is to use maximum information from GMO and only simplify the interface. Here are described some rules how information from GMO are used and in which order if not all of them are defined in GMO.

  • label — if label attribute is defined in QGM it is used as option label, if it is not defined GMO option label tag is used and if it is not defined GMO option description tag is used
  • tooltip — (appeares on mouseover the option) if label is defined (either in QGM or GMO) and description is defined in GMO (thus label and description differ) the GMO description tag is used for tooltip
  • multiple values label — if an option is type multiple with defined list of possible values (like upload option of v.distance) and description tag is defined for value tag in GMO then it is used as checkbox label

Imagen

Each module must be represented also by a picture/icon which symbolizes the modules functionality. The pictures are also stored in plugins/grass/modules as SVG (.svg) or PNG (.png) files.

Actualmente existen 3 esquemas soportados para la imagen:

  • 1 imagen
  • 2 imágenes — QGIS creará ícono: 1 -> 2
  • 3 imágenes — QGIS creará ícono: 1 + 2 -> 3

The name of the picture starts with QGIS-GRASS module name to which is appended picture number, for example: v.overlay.and.1.svg, v.overlay.and.2.svg, v.overlay.and.3.svg. It is possible to combine SVG and PNG pictures.

SVG and PNG pictures can be generated from QGIS using Map Composer. The size of PNG images should be larger than the expected icon size, because it is expected to be later used in automatically generated documentation, where pictures will be used in larger size.

scripts QGIS GRASS

Because it can take long time until a new script is added to stable GRASS release and because some scripts can be useful only for QGIS GUI interface it is possible to add a “GRASS” script to QGIS. The scripts should follow general requirements for GRASS scripts and they are located in qgis/src/plugins/grass/scripts.

Reglas generales para nuevos módulos

GRASS Tools are intended mostly for beginners and not very experienced users. The basic rules are:

  • Each module should have 3 or less options; if it seems to be necessary to add more options, it should be discussed beforehand
  • Module definition should be robust so that it doesn’t allow a user to run a module with wrong option. If there is not yet support for certain type of option the module should not be added to menu

Reglas específicas para descripciones de módulo

  • Evite 3ra persona para verbos, e.g. «Exportar ráster» en vez de «Exporta ráster»
  • Evite «mapa», «capa» y «archivo» innecesario, e.g. «Exportar ráster» en vez de «Exportar capa ráster del mapa»
  • Evite «GRASS» innecesario, por ejemplo «Exportar ráster» en vez de «Exportar ráster GRASS»
  • Evite «a|an», e.g. «Exportar ráster» en vez de «Exporta ráster»
  • Avoid padding words, e.g. «Export raster» instead of «Allows the export of a raster»
  • Evite «Convertir»: en vez, use «Exportar» o «Importar». Convertir debería usarse para conversiones internas de GRASS (ej.: de ráster a vector)
  • Los acrónimos deberían estar en mayúsculas, por ej. ASCII en vez de ascii
  • En caso de duda, por favor revise los complementos similares existentes para mantener consistencia

Opciones que no pueden usarse actualmente

Technically, any option can be used. Some kinds of options however are not yet well supported, for example those which depend on other option. Here is a list (probably incomplete) of options which are not yet well supported and so should not be used at present:

  • entrada dsn/capa OGR (v.in.org)

Módulos que pueden ser adicionados

Most modules have been added. If you need additional ones, please write to the qgis development mailing list, and list hereafter the modules you think are most important to be added.

You should post the name of a new QGIS-GRASS module, the name of the GRASS module and the options which you want to use. For example:

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

Vea aquí también la discusión sobre la lista de módulos relevante a GRASS-QGIS.

Módulos a darse como obsoletos

List hereafter the modules who should be removed, with a rationale for this suggestion (e.g.: some modules related to projections are difficult to understand, and of no general use). Please note: some modules have not been thoroughly tested. Please test them, and if you find any issue report it to the redmine (better still: fix it yourself and send the patch).