Adicionando Ferramentas GRASS

GRASS modules can be run from QGIS GRASS Tools if QGIS was started from a GRASS shell or if a GRASS mapset was opened from QGIS. The modules work with GRASS data only.

É fácil alterar o menu e adicionar novos módulos porque o menu e os módulos são definidos em ficheiros de configuração XML. Em baixo é descrito como escrever novos módulos e alterar a árvore do menu.

Configuração do módulo

Informação básica

As opções de cada módulo que aparecem no separador _*Opções_* do módulo são criadas de acordo com a combinação da definição no ficheiro QGM (módulo QGIS GRASS) e definições das opções no módulo GRASS ou script GRASS — GMO (opções do módulo GRASS). Cada opção no QGM está ligado a um (ou mais) GMO, muitas vezes é útil se não for necessário para ver o GMO. O GMO são saídas dos módulo GRASS se for executado com a opção _*–interface-description_*, o ficheiro de saída é em formato XML, por exemplo:

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.

Aqui está um exemplo de um ficheiro de configuração:

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

  • label — descrição usada na árvore do menu
  • module — nome do módulo ou script executável do GRASS.

Etiquetas opcionais

Cada etiqueta qgisgrassmodule pode contem uma ou mais etiquetas opcionais:

  • option — corresponde à etiqueta do parâmetro GMO, exemplo:
<option key="elevation" />
  • flag — corresponde à etiqueta do GMO flag, exemplo:
<flag key="o" answer="on" hidden="yes" />
  • field — para camadas vetoriais defina um atributo do campo, a opção é criada com uma caixa de combinação com os campos disponíveis. Por exemplo (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" />

Opção comum/ sinalizar etiquetas de atributos

  • key — nome da opção do módulo no GMO.
  • answer — valor padrão (reescreve o valor GMO padrão); o valor «on» irá trocar ao sinalizar.
  • hidden — a opção não irá aparecer na janela do diálogo, mas o módulo irá ser executado com esta opção (hidden=»yes»).
  • label — opção do rótulo
  • advanced — «yes» or «no», por defeito é «no». Se definir como «yes» a opção/flag é adicionado para inicializar no painel escondido de opções avançadas e o botão «Exibir opções avançadas>>» é exibido nas opções simples (básico, padrão)
  • version_min — versão mínima do GRASS para a que a opção/flag seja válida
  • version_max — versão máxima do GRASS para a que a opção/flag seja válida

Opções específicas da etiqueta atributos

  • typeoption — esta opção pode ser usada com a camada vetorial para definir o nome da opção do tipo de entrada, quando o módulo corre, o tipo de camada vetorial selecionado será usado para essa opção. Por exemplo (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 — equivalente ao typeoption da camada.

  • typmask — para ficheiros de entrada vetoriais esta opção define tipos permitidos. Apenas camadas definidas pelo tipo são exibidas no ficheiro de entrada. Veja v.overlay.or.qgm como exemplo.

Etiqueta de campo específico para atributos

  • layer — o atributo chave da opção que define o vetor deste campo que deve usar

  • type — defines o tipo de campos de atributo que deverão ser adicionados ao campo da combobox, por exemplo

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

    Significa que apenas atributos de campo do tipo inteiro e de precisão decimal irão aparecer na caixa de combinação. Veja v.what.vect como (2 vetores diferentes).

Nos bastidores

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 — se a tabela do rótulo é definida no QGM é usada como a opção do rótulo, se não estiver definido é usada uma etiqueta do rótulo da opção do GMO e se não estiver definida o GMO é usada uma etiqueta de descrição
  • 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
  • rótulo multiple values — se uma opção é do tipo múltipla com uma lista definida de valores possíveis (como a opção de upload do v.distance) e um rótulo de descrição é definido para o valor do rótulo no GMO então é usado como rótulo de caixa de verificação

Imagem

Cada módulo deve ser representado com uma imagem/ícone que simboliza a funcionalidade dos módulos. As imagens são armazenadas em plugins/grass/modules como ficheiros SVG (.svg) or PNG (.png).

Atualmente são suportados 3 esquemas para a imagem:

  • 1 imagem
  • 2 imagens — O QGIS irá criar um ícone: 1 -> 2
  • 3 imagens — O QGIS irá criar um ícone: 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 GRASS QGIS

Porque pode demorar muito tempo até o novo script ser adicionado ao lançamento estável do GRASS e porque alguns scripts podem ser úteis para a interface QGIS GUi é possível adicionar um script “GRASS” ao QGIS. Os scripts devem seguir os requerimentos gerias para scripts GRASS e estão localizados em gis/src/plugins/grass/scripts.

Gerar regras para novos módulos

Ferramentas GRASS são normalmente para novos utilizadores e não muito para utilizadores avançados. As regras básicas são:

  • Cada módulo deve ter 3 ou menos opções; se for necessário adicionar mais opções, deverá ser discutido antecipadamente
  • A definição do módulo deve ser robusta para que não permite o utilizador correr o módulo com a opção errada. Se não estiver ainda suportado para um determinado tipo de opção o módulo não deve ser adicionado ao menu

Regras específicas para a descrição do módulo

  • Evite a 3.º pessoa para verbos, ex.: «Exportar raster» em vez de «Exporta raster»
  • Evite desnecessários «map», «layer» e «file», ex.: «Exportar raster» em vez de «Exportar camada do mapa raster»
  • Evite desnecessários «GRASS», ex.: «Exportar raster» em vez de «Exportar GRASS raster»
  • Evite «alan», ex.: «Exportar raster» em vez de «Exporta um raster»
  • Evite palavras de preenchimento, ex.: «Exportar raster» em vez de «Permite a exortação de um raster»
  • Evite «Converter»: use «Exportar» ou «Importar». Converter deve ser para conversões interna no GRASS (ex.: de raster para vetor)
  • Devem aparecer acrónimos em maiúsculas, ex.: ASCII em vez de ascii
  • Em caso de dúvida, por favor verifique módulos semelhantes existentes para manter a consistência

Opções que não podem ser usadas atualmente

Tecnicamente, qualquer opção pode ser usada. Alguns tipos de opções contudo não podem ser suportadas, por exemplo aqueles que dependem de outra opção. Aqui está uma lista (provavelmente incompleta) de opções que não estão ainda suportadas e não devem ser usadas atualmente:

  • Ficheiro de entrada OGR dsn/layer (v.in.ogr)

Módulos que podem ser adicionados

Foram adicionados a maioria dos módulos. Se necessita de adicionar mais, entre em contacto com a lista de discussão de desenvolvimentos do QGIS, e indique os módulos que acha que são mais importantes para serem adicionados.

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

See also here for discussion on GRASS-QGIS relevant module list.

Módulos a serem obsoletos

Lista a seguir os módulos que devem ser removidos, com a razão dessa sugestão (por exemplo: alguns módulos relacionados com as projeções são difíceis de entender, e de não têm uso geral). Por favor tenha em atenção: alguns módulos não foram testados rigorosamente. Por favor teste-os e se descobrir algum problema reporte-o no redmine (melhor ainda: corrija-o e mande um patch).