Blog SIG & Territórios

Desenvolver um plugin QGIS pode parecer algo reservado a programadores experientes. Na realidade, com algumas bases e uma boa metodologia, é perfeitamente possível criar seus próprios plugins, mesmo sem grande experiência em programação.

Neste tutorial, vamos descobrir para que servem os plugins QGIS, por que eles são tão úteis no dia a dia e, principalmente, como um plugin QGIS é estruturado: quais arquivos o compõem e qual é o papel de cada um.

Esta série de artigos é destinada a usuários do QGIS iniciantes em Python, professores, técnicos de órgãos públicos e todas as pessoas que desejam automatizar seus processamentos ou criar ferramentas adaptadas às suas necessidades profissionais.

Introdução

O QGIS é hoje um dos SIG open source mais utilizados no mundo. Sua riqueza funcional é impressionante, mas o que realmente faz sua força é sua capacidade de extensão por meio dos plugins.

Um plugin QGIS permite adicionar funcionalidades personalizadas: automatizar tarefas repetitivas, criar ferramentas adaptadas a uma atividade específica, testar novos métodos ou simplesmente facilitar o trabalho diário.

Este tutorial é deliberadamente voltado a pessoas sem grande experiência em programação. O objetivo não é transformá-lo em um desenvolvedor Python avançado, mas fornecer as bases necessárias para:

• compreender como funciona um plugin QGIS,
• modificar um plugin existente,
• criar suas próprias ferramentas simples e úteis.

A ideia é aprender apenas o essencial de Python e da arquitetura do QGIS para se tornar autônomo.

Por que desenvolver seus próprios plugins QGIS?

Automatizar tarefas repetitivas

Se você usa o QGIS com frequência, provavelmente já executou várias vezes as mesmas operações:

• carregar camadas,
• aplicar estilos,
• executar uma sequência de processamentos,
• exportar resultados.

Um plugin permite agrupar todas essas ações em um único botão.

Adaptar o QGIS à sua atividade profissional

As necessidades de um geógrafo, professor, técnico de prefeitura ou pesquisador nem sempre são totalmente atendidas pelas ferramentas padrão. Um plugin pode integrar:

• regras de negócio,
• verificações de consistência,
• cálculos específicos.

Aprender programação de forma progressiva

Desenvolver um plugin QGIS é uma excelente porta de entrada para o Python:

• o resultado é concreto e visual,
• os erros geralmente são fáceis de identificar,
• é possível avançar passo a passo.

Compartilhar (ou manter para uso próprio)

Um plugin pode permanecer estritamente pessoal, ser compartilhado dentro de uma equipe ou ser publicado oficialmente no repositório de plugins do QGIS.

Do que é composto um plugin QGIS?

Um plugin QGIS é, antes de tudo, uma pasta contendo vários arquivos. Cada um tem um papel bem definido. A boa notícia é que não é necessário compreender tudo em profundidade desde o início.

Aqui está a estrutura mínima de um plugin:

MeuPlugin/
├── __init__.py
├── metadata.txt
├── meu_plugin.py
└── resources.qrc (opcional)

Vamos analisar esses arquivos.

O arquivo __init__.py

Este é o ponto de entrada do plugin.

Seu papel principal é informar ao QGIS qual classe Python deve ser carregada quando o plugin é ativado.

Exemplo simplificado:

def classFactory(iface):
    from .meu_plugin import MeuPlugin
    return MeuPlugin(iface)

Neste momento, basta lembrar que:

• este arquivo é obrigatório,
• ele faz a ligação entre o QGIS e o código principal do plugin.

Explicação linha por linha

1️⃣ def classFactory(iface):

✔ O QGIS procura obrigatoriamente uma função com esse nome: classFactory

Quando o QGIS lê o plugin, ele chama automaticamente:

classFactory(iface)

e transmite:

• iface = a interface do QGIS (objeto QgisInterface)

Esse objeto dá acesso a:

• o mapa (mapCanvas),
• o menu Plugins,
• a barra de ferramentas,
• a camada ativa,
• mensagens e logs,
• etc.

➡️ É o objeto central que permite ao plugin interagir com o QGIS.

2️⃣ from .meu_plugin import MeuPlugin

O ponto (.) significa: “no mesmo diretório que este arquivo”.

O QGIS carrega então a classe principal a partir de:

meu_plugin.py

Essa classe contém:

• initGui() → adiciona ações, menus e ícones,
• unload() → remove os elementos do plugin,
• as funções de negócio (ativação de ferramentas, exibição de janelas, etc.).

➡️ É a classe principal do plugin, aquela que controla tudo.

3️⃣ return MeuPlugin(iface)

O QGIS espera uma instância da classe, e não a classe em si.

Portanto:

• a classe MeuPlugin é instanciada,
• a interface do QGIS (iface) é passada como parâmetro.

O QGIS usará esse objeto para:

• chamar initGui() ao ativar o plugin,
• chamar unload() ao desativá-lo.

➡️ É a criação concreta do plugin dentro do QGIS.

📌 Resumo

👉 __init__.py indica ao QGIS qual classe usar para o plugin.
👉 A função classFactory() é obrigatória em todo plugin QGIS.
👉 iface fornece acesso completo à interface do QGIS.
👉 O plugin só começa realmente a funcionar após a instanciação:

MeuPlugin(iface)

O arquivo metadata.txt

Este arquivo é fundamental: sem ele, o QGIS não reconhece o plugin.

Ele contém as informações gerais:

• nome do plugin,
• descrição,
• autor,
• versão,
• versão mínima do QGIS.

Exemplo:

[general]
name=Meu primeiro plugin
description=Um plugin simples para aprender
version=0.1
author=Seu nome
qgisMinimumVersion=3.16

É esse arquivo que aparece no gerenciador de plugins do QGIS.

O arquivo principal Python (ex.: meu_plugin.py)

É aqui que está o coração do plugin.

Normalmente encontramos:

• a classe principal do plugin,
• os métodos initGui() e unload(),
• o código que adiciona um botão ou menu no QGIS.

De forma bem esquemática:

class MeuPlugin:
    def __init__(self, iface):
        self.iface = iface

    def initGui(self):
        pass

    def unload(self):
        pass

Não se preocupe se isso ainda parecer confuso: cada elemento será explicado progressivamente nos próximos artigos.

Arquivos opcionais, mas muito comuns

Interfaces gráficas (.ui)

O QGIS utiliza o Qt para interfaces gráficas. Os arquivos .ui são criados com o Qt Designer, sem escrever código.

Eles permitem construir janelas com:

• botões,
• listas suspensas,
• campos de entrada.

Recursos (resources.qrc)

Este arquivo serve para agrupar:

• ícones,
• imagens,
• outros recursos gráficos.

Ele é compilado em Python para ser utilizado no plugin.

O que você precisa reter por enquanto

Neste estágio, o essencial é compreender que:

• um plugin QGIS é uma estrutura de arquivos, não um programa complexo,
• cada arquivo tem um papel específico,
• é possível criar plugins simples e muito úteis com pouco código.

E no próximo artigo?

No próximo artigo, veremos:

• como criar um plugin vazio com o Plugin Builder,
• onde posicionar os arquivos,
• como carregar e testar o plugin no QGIS.

O objetivo será obter um primeiro plugin funcional, mesmo que ele ainda não faça quase nada.

👉 O mais importante não é ir rápido, mas compreender cada etapa.

Si cet article vous a intéressé et que vous pensez qu'il pourrait bénéficier à d'autres personnes, n'hésitez pas à le partager sur vos réseaux sociaux en utilisant les boutons ci-dessous. Votre partage est apprécié !

Atilio Francois