12.1. Expressões

Com base em dados de camada e funções pré-criadas ou definidas pelo usuário, Expressões oferecem uma maneira poderosa de manipular valor de atributo, geometria e variáveis ​​para alterar dinamicamente o estilo de geometria, o conteúdo ou a posição do rótulo, o valor do diagrama, a altura de um item de layout, selecionar alguns recursos, criar um campo virtual, …

Nota

Uma lista das funções e variáveis padrões para escrever expressões pode ser encontrada em Lista de funções, com informações detalhadas e exemplos.

12.1.1. O Construtor de string de expressão

A caixa de diálogo principal para construir expressões, o Construtor de string de expressão está disponível em muitas partes no QGIS e, pode ser acessado quando:

• clicando no botão ;

• selecionando feições com a ferramenta ^{Selecionar por Expressão…};

• editando atributos com a ferramenta ^{Calculadora de Campo};

• manipulação de parâmetros de simbologia, rótulo ou item de layout com a ferramenta ^{Substituição de dados definida} (veja Data defined override setup);

• Construindo uma camada de símbolo geradora de geometria ;

• Realizando algum geoprocessamento.

O diálogo Construtor de Expressão oferece acesso a:

• Aba de Expressão, a qual ajuda a escrever e verificar a expressão a ser usada, graças a uma lista predefinida de funções;

• Aba Editor de Função a qual ajuda a expandir a lista de funções por meio de criações customizadas de novas funções.

12.1.1.1. A interface

A aba Expressão fornece a interface principal para escrever expressões usando funções, campos de camada e valores. Ele contém os seguintes widgets:

Fig. 12.1 A guia Expressão

• Uma área de edição de expressão para digitar ou colar expressões. O preenchimento automático está disponível para acelerar a escrita de expressões:

  • Variáveis ​​correspondentes, nomes de funções e nomes de campos para o texto de entrada são mostrados abaixo: use as setas Up e Down para navegar pelos itens e pressione Tab para inserir na expressão ou basta clicar no item desejado.

  • Os parâmetros de função são mostrados ao preenchê-los.

  O QGIS também verifica a correção da expressão e destaca todos os erros usando:

  • Sublinhado: para funções desconhecidas, argumentos errados ou inválidos;

  • Marcador: para todos os outros erros (por exemplo, parênteses ausentes, caracteres inesperados) em um único local.

  Dica

  Documente sua expressão com comentários

  Ao usar expressões complexas, é uma boa prática adicionar texto como um comentário com várias linhas ou comentários embutidos para ajudá-lo a se lembrar.

  /*
  Labels each region with its highest (in altitude) airport(s)
  and altitude, eg 'AMBLER : 264m' for the 'Northwest Artic' region
  */
  with_variable(
    'airport_alti', -- stores the highest altitude of the region
    aggregate(
      'airports',
      'max',
      "ELEV", -- the field containing the altitude
      -- and limit the airports to the region they are within
      filter := within( $geometry, geometry( @parent ) )
    ),
      aggregate( -- finds airports at the same altitude in the region
        'airports',
        'concatenate',
        "NAME",
        filter := within( $geometry, geometry( @parent ) )
          and "ELEV" = @airport_alti
      )
      || ' : ' || @airport_alti || 'm'
      -- using || allows regions without airports to be skipped
  )
  

• Acima do editor de expressões, um conjunto de ferramentas ajuda você a:

  • ^{Limpar o editor de expressão}

  • criar e gerenciar expressões de usuário

• No editor de expressões, você encontra:

  • um conjunto de operadores básicos para ajudá-lo a construir a expressão

  • uma indicação do formato esperado de saída quando você está definindo propriedades de feição

  • uma Visualização de saída ao vivo da expressão, avaliada na primeira feição da camada por padrão. Você pode navegar e avaliar outras feições da camada usando a caixa de combinação Feição (os valores são obtidos da propriedade Nome em Exibição da camada).

    Em caso de erro, ele o indica e você pode acessar os detalhes com o hiperlink fornecido.

• Um seletor de funções exibe a lista de funções, variáveis, campos … organizados em grupos. Está disponível uma caixa de pesquisa para filtrar a lista e encontrar rapidamente uma função ou campo específico. Clicar duas vezes em um item o adiciona ao editor de expressão.

• Um painel de ajuda exibe ajuda para cada item selecionado no seletor de funções.

  Dica

  Pressione Ctrl+Click ao passar com o mouse sobre o nome de uma função em uma expressão para exibir automaticamente sua ajuda na caixa de diálogo.

  A ferramenta de valores de campo exibida quando um campo é selecionado no seletor de função ajuda a buscar atributos de feições:

  • Procure um valor de campo específico

  • Exibe a lista de valores Todos únicos ou 10 Amostras. Também disponível ao clicar com o botão direito.

    Quando o campo é mapeado com outra camada ou conjunto de valores, ou seja, se a ferramenta de campo for do tipo Referência de relação, Relação de valor ou Mapa de valores, é possível listar todos os valores do campo mapeado (da camada, tabela ou lista referenciada). Além disso, você pode filtrar esta lista para Mostrar apenas valores em uso no campo atual.

  Clicar duas vezes em um valor de campo na ferramenta o adiciona ao editor de expressão.

  Dica

  O painel direito, mostrando as funções de ajuda ou valores de campo, pode ser recolhido (invisível) na caixa de diálogo. Pressione o botão Mostrar valores ou Mostrar ajuda para exibir de novo.

12.1.1.2. Escrevendo uma expressão

As expressões QGIS são usadas para selecionar feições ou definir valores. Escrever uma expressão no QGIS segue algumas regras:

1. A caixa de diálogo define o contexto: se você está acostumado com SQL, provavelmente conhece consultas do tipo select features from layer where condition ou update layer set field = new_value where condition. Uma expressão QGIS também precisa de todas essas informações, mas a ferramenta que você usa para abrir a caixa de diálogo do construtor de expressões fornece partes delas. Por exemplo, dada uma camada (building) com um campo (height):

   • clicando na ferramenta ^{Selecionar por expressão} significa que você quer “selecionar feições de edifícios”. A condição é a única informação que você precisa fornecer no elemento de texto de expressão, por exemplo, digite "altura" > 20 para selecionar construções maiores que 20.

   • com esta seleção feita, pressionando o ^{Calculadora de campo} e escolhendo “altura” como Atualizar campo existente, você já fornece o comando “atualizar edifícios definir altura = ??? onde altura > 20”. Os únicos bits restantes que você precisa fornecer neste caso são o novo valor, por exemplo basta digitar 50 na caixa de texto do editor de expressão para definir a altura dos edifícios selecionados anteriormente.

2. Preste atenção às aspas: aspas simples retornam um literal, então um texto colocado entre aspas simples ('145') é interpretado como uma string. Aspas duplas lhe darão o valor desse texto, então use-as para campos ("meucampo"). Os campos também podem ser usados ​​sem aspas (meucampo). Sem aspas para números (3.16).

   Nota

   As funções normalmente tomam como argumento uma string para o nome do campo. Utilize:

   attribute( @atlas_feature, 'height' ) -- returns the value stored in the "height" attribute of the current atlas feature
   

   E não:

   attribute( @atlas_feature, "height" ) -- fetches the value of the attribute named "height" (e.g. 100), and use that value as a field
                                         -- from which to return the atlas feature value. Probably wrong as a field named "100" may not exist.
   

Dica

Use parâmetros nomeados para facilitar a leitura da expressão

Algumas funções requerem que muitos parâmetros sejam configurados. O mecanismo de expressão suporta o uso de parâmetros nomeados. Isso significa que em vez de escrever a expressão enigmática clamp( 1, 2, 9), você pode usar clamp( min:=1, valor:=2, max:=9). Isso também permite que os argumentos sejam trocados, por exemplo. clamp( valor:=2, max:=9, min:=1). O uso de parâmetros nomeados ajuda a esclarecer a que se referem os argumentos de uma função de expressão, o que é útil quando você está tentando interpretar uma expressão posteriormente!

12.1.1.3. Alguns casos de uso de expressões

• Na Calculadora de Campo, calcule um campo “pop_density” usando os campos “total_pop” e “area_km2” existentes:

  "total_pop" / "area_km2"
  

• Rotule ou categorize feições com base em sua área:

  CASE WHEN $area > 10 000 THEN 'Larger' ELSE 'Smaller' END
  

• Atualiza o campo “density_level” com categorias de acordo com os valores de “pop_density”:

  CASE WHEN "pop_density" < 50 THEN 'Low population density'
       WHEN "pop_density" >= 50 and "pop_density" < 150 THEN 'Medium population density'
       WHEN "pop_density" >= 150 THEN 'High population density'
  END
  

• Aplicar um estilo categorizado para todas as feições de acordo com condição do preço médio da casa ser maior ou maior do que 10000€ por metro quadrado:

  "price_m2" > 10000
  

• Usando a ferramenta “Selecionar por Expressão…”, selecione todas as feições representativas de áreas de “Alta densidade populacional” e as quais possuem valor médio da casa maior do que 10000€ por metro ²:

  "density_level" = 'High population density' and "price_m2" > 10000
  

  A expressão anterior também pode ser usada para definir quais feições rotular ou mostrar no mapa.

• Crie um símbolo (tipo) diferente para a camada, usando o gerador de geometria:

  point_on_surface( $geometry )
  

• Dado uma feição de ponto, gere uma linha fechada (usando make_line) em torno de sua geometria:

  make_line(
    -- using an array of points placed around the original
    array_foreach(
      -- list of angles for placing the projected points (every 90°)
      array:=generate_series( 0, 360, 90 ),
      -- translate the point 20 units in the given direction (angle)
      expression:=project( $geometry, distance:=20, azimuth:=radians( @element ) )
    )
  )
  

• Em uma etiqueta de layout de impressão, exiba o nome das feições de “airports” que estão dentro do item “Mapa 1” do layout:

  with_variable( 'extent',
                 map_get( item_variables( 'Map 1' ), 'map_extent' ),
                 aggregate( 'airports', 'concatenate', "NAME",
                            intersects( $geometry, @extent ), ' ,'
                          )
               )
  

12.1.1.4. Salvando expressões

Usando o botão ^{Adicionar expressão atual às expressões do usuário} acima do quadro do editor de expressões, você pode salvar expressões importantes às quais deseja ter acesso rápido. Eles estão disponíveis no grupo Expressões do usuário no painel do meio. Eles são salvos no user profile (<userprofile>/QGIS/QGIS3.ini file) e estão disponíveis em todas as caixas de diálogo de expressão dentro de todos os projetos do perfil de usuário atual.

Um conjunto de ferramentas disponíveis acima do quadro do editor de expressão ajuda a gerenciar as expressões do usuário:

• ^{Adicionar a expressão atual às expressões do usuário}: armazena a expressão no perfil do usuário. Uma etiqueta e um texto de ajuda podem ser adicionados para facilitar a identificação.

• ^{Editar expressão selecionada a partir de expressões do usuário}, bem como sua ajuda e rótulo

• ^{Remover a expressão selecionada das expressões do usuário}

• ^{Importar expressões de usuário} de um arquivo .json para a pasta de perfil de usuário ativa

• ^{Exportar expressões do usuário} como um arquivo .json; todas as expressões do usuário no perfil do usuário QGIS3.ini são compartilhadas

12.1.2. Editor de Funções

Com a guia Editor de Funções, você pode escrever suas próprias funções na linguagem Python. Isso fornece uma maneira prática e confortável de abordar necessidades específicas que não seriam cobertas pelas funções predefinidas.

Fig. 12.2 A guia Editor de Funções

Para criar uma nova função:

1. Pressione o botão ^{Novo Arquivo}.

2. Digite um nome para usar no formulário que aparece e pressione OK.

   Um novo item com o nome que você fornece é adicionado no painel esquerdo da guia Editor de Funções; este é um arquivo Python .py baseado no arquivo de modelo QGIS e armazenado na pasta /python/expressions no diretório do perfil de usuário ativo.

3. O painel direito exibe o conteúdo do arquivo: um modelo de script python. Atualize o código e sua ajuda de acordo com suas necessidades.

4. Pressione o botão Salvar e Carregar Funções. A função que você escreveu é adicionada à árvore de funções na guia Expressão, por padrão, no grupo``Personalizada``.

5. Aproveite sua nova função.

6. Se a função precisar de melhorias, ative a guia Editor de Funções, faça as alterações e pressione novamente o botão Salvar e Carregar Funções para disponibilizá-las no arquivo, e portanto, em qualquer guia de expressão.

As funções personalizadas do Python são armazenadas no diretório de perfil do usuário, o que significa que, a cada inicialização do QGIS, ele carrega automaticamente todas as funções definidas no perfil do usuário atual. Esteja ciente de que novas funções são salvas apenas na pasta /python/expression e não no arquivo do projeto. Se você compartilha um projeto que utiliza uma de suas funções personalizadas, também precisará compartilhar o arquivo .py na pasta /python/expression.

Para excluir uma função personalizada:

1. Habilite a aba Editor de funções

2. Selecione a função na lista

3. Pressione o botão ^{Remover função selecionada}. A função é removida da lista e o arquivo .py correspondente é excluído da pasta de perfil do usuário.

Exemplo

Aqui está um pequeno exemplo de como criar sua própria função my_sum que irá operar com dois valores.

from qgis.core import *
from qgis.gui import *

@qgsfunction(args='auto', group='Custom')
def my_sum(value1, value2, feature, parent):
    """
    Calculates the sum of the two parameters value1 and value2.
    <h2>Example usage:</h2>
    <ul>
      <li>my_sum(5, 8) -> 13</li>
      <li>my_sum("field1", "field2") -> 42</li>
    </ul>
    """
    return value1 + value2

Ao usar o argumento de função args='auto' o número de argumentos de função necessários será calculado pelo número de argumentos com os quais a função foi definida em Python (menos 2 - function, e parent). O argumento group='Custom' indica o grupo no qual a função deve ser listada na caixa de diálogo Expressão.

Também é possível adicionar argumentos de palavras-chave como:

• usesgeometry=True se a expressão requer acesso à geometria das feições. Por padrão False.

• handlesnull=True se a expressão tiver tratamento personalizado para valores NULOS. Se False (padrão), o resultado sempre será NULO assim que qualquer parâmetro for NULO.

• referenced_columns=[list]`: Uma array de nomes de atributos que são necessários para a função. O padrão é [QgsFeatureRequest.ALL_ATTRIBUTES].

A função de exemplo anterior pode ser usada em expressões:

Fig. 12.3 Função Personalizada adicionada à guia Expressão

Informações adicionais sobre a criação de código Python podem ser encontradas em Passo-a-passo para desenvolvedor PyQGIS.