PyQGIS · Material de apoyo para la clase de Programación en Ambientes de SIG (PASIG)

Fundamentos de Creación de Complementos de QGIS con PyQGIS

¿Qué es un complemento de QGIS?

Un complemento (plugin) es una extensión que se instala dentro de QGIS para agregarle funciones nuevas: botones, menús, ventanas, herramientas de procesamiento, etc. Los complementos que ves en el Administrador de complementos de QGIS están escritos, en su gran mayoría, en Python usando PyQGIS.

¿Para qué sirve crear uno?

En los ejercicios anteriores creaste herramientas de procesamiento (scripts que aparecen en la Caja de herramientas). Un complemento va un paso más allá: permite construir una interfaz gráfica propia (ventanas con botones, listas desplegables, cuadros de texto) para que otras personas usen tu análisis sin tener que tocar código. También sirve para distribuir tu trabajo: puedes empaquetarlo y compartirlo con la comunidad de QGIS.

Conceptos básicos para entenderlo

1. Piezas que forman un complemento

Un complemento es una carpeta con varios archivos. Los más importantes son:

  • __init__.py: el "punto de entrada". QGIS lo busca al cargar el complemento y llama a la función classFactory para crear el objeto principal.
  • metadata.txt: un archivo de texto con los datos del complemento (nombre, descripción, versión, autoría y versiones de QGIS compatibles). QGIS lo lee para mostrar el complemento en el Administrador.
  • El archivo .py principal: contiene la clase del complemento, donde se programa la lógica.
  • Los archivos .ui: describen el diseño de las ventanas. Se crean de forma visual con Qt Designer, sin escribir código.
  • pb_tool.cfg: configuración de la herramienta pb_tool, que ayuda a desplegar y empaquetar el complemento.

2. La clase del complemento y sus métodos

Igual que en las herramientas de procesamiento, un complemento es una clase de Python. QGIS espera encontrar en ella ciertos métodos con nombres específicos:

Estructura mínima de un complemento
# __init__.py
def classFactory(iface):
    from .mi_complemento import MiComplemento
    return MiComplemento(iface)


# mi_complemento.py
class MiComplemento:

    def __init__(self, iface):
        # iface es la conexión con la interfaz de QGIS
        self.iface = iface

    def initGui(self):
        # Se ejecuta al activar el complemento: aquí se crean botones y menús
        pass

    def unload(self):
        # Se ejecuta al desactivarlo: aquí se eliminan los botones y menús
        pass

    def run(self):
        # Se ejecuta al presionar el botón: aquí se muestra la ventana y se programa la lógica
        pass
  • classFactory(iface): función que QGIS llama para crear el complemento. Recibe iface y devuelve un objeto de nuestra clase.
  • __init__(self, iface): constructor de la clase; guarda iface para usarlo después.
  • initGui(): agrega los elementos del complemento a la interfaz de QGIS (barras de herramientas y menús).
  • unload(): quita esos elementos cuando el complemento se desactiva, para no dejar botones "huérfanos".
  • run(): contiene lo que sucede cuando el usuario usa el complemento.

3. iface: la puerta hacia QGIS

iface (objeto QgisInterface) es la referencia a la ventana de QGIS que se ejecuta. Con ella se accede a la barra de menús, a la barra de herramientas, a la capa activa, al lienzo del mapa, etc.

4. Qt, PyQt y Qt Designer

  • Qt: la biblioteca con la que está construida la interfaz de QGIS (ventanas, botones, listas).
  • PyQt: permite usar Qt desde Python. En QGIS se importa desde qgis.PyQt.
  • Qt Designer: programa visual, incluido con QGIS, para diseñar ventanas arrastrando elementos (widgets). Guarda el diseño en un archivo .ui.
  • Widgets de QGIS: además de los widgets de Qt, QGIS ofrece los suyos, como QgsMapLayerComboBox, una lista desplegable con las capas del proyecto.

5. Señales y funciones (signals y slots)

Cada elemento de la ventana emite señales cuando el usuario interactúa con él (por ejemplo, clicked al hacer clic en un botón). Para que algo suceda, se conecta la señal a una función de Python:

Conectar una señal a una función
self.dlg.boton_calcular.clicked.connect(self.calcular)

def calcular(self):
    capa = self.dlg.combo_capas.currentLayer()
    print(capa.name())
  • self.dlg.boton_calcular: el botón, identificado con el nombre que se le dio en Qt Designer.
  • .clicked.connect(self.calcular): indica que, al hacer clic, se ejecute la función calcular.
  • currentLayer(): devuelve la capa elegida en el QgsMapLayerComboBox.

6. Herramientas de apoyo

  • Plugin Builder: complemento de QGIS que genera la plantilla base (carpeta y archivos) a partir de un formulario.
  • Plugin Reloader: complemento que recarga tu complemento sin reiniciar QGIS, útil para probar cambios.
  • pb_tool: herramienta de línea de comandos para desplegar y empaquetar el complemento.

Pasos generales para la creación de un complemento de QGIS

Esta es la secuencia recomendada para crear tu primer complemento desde cero.

1. Configurar el entorno y las herramientas requeridas

  • Asegúrate de contar con QGIS, una instalación de Python y un editor de código o IDE (como VS Code o PyCharm).
  • Dentro de QGIS, instala dos complementos clave desde el Administrador de complementos: Plugin Builder (para generar la plantilla base) y Plugin Reloader (para recargar tu complemento en tiempo real sin tener que reiniciar QGIS).
  • Opcionalmente, instala la herramienta de línea de comandos pb_tool ejecutando pip install pb_tool y configura las rutas de las bibliotecas de Python de QGIS en las opciones de tu IDE para habilitar el autocompletado.

2. Definir la funcionalidad del complemento

  • Antes de escribir código, determina con claridad qué tarea realizará el complemento y cómo interactuará con el usuario.

3. Generar la estructura base con Plugin Builder

  • Abre Plugin Builder desde la interfaz de QGIS.
  • Completa los campos requeridos en el formulario: Class name (en CamelCase), Module name (en minúsculas con guiones bajos), Plugin name, descripción corta, versión mínima/máxima de QGIS compatible y datos de autoría.
  • Selecciona el tipo de plantilla que necesitas (por ejemplo, Tool button with dialog, Tool button with dock widget o Processing provider) y el menú de QGIS donde se ubicará.
  • Selecciona la carpeta de destino y genera la estructura de archivos base (.py, .ui, pb_tool.cfg, entre otros).

4. Diseñar la interfaz gráfica en Qt Designer

  • Abre Qt Designer (herramienta que se incluye con la instalación de QGIS) y abre el archivo con extensión .ui que generó el Plugin Builder.
  • Agrega los elementos requeridos a la ventana (botones, etiquetas o widgets específicos de QGIS como QgsMapLayerComboBox para desplegar las capas activas).
  • Guarda los cambios y toma nota de los nombres asignados a cada widget para referenciarlos más adelante en el código.

5. Desplegar e integrar el complemento en QGIS

  • Despliega el complemento en el directorio de complementos de QGIS ejecutando el comando pb_tool deploy en tu terminal o copiando manualmente la carpeta del complemento a la ruta de complementos de QGIS.
  • Abre QGIS, activa tu complemento en el Administrador de complementos y configura Plugin Reloader vinculándolo a tu complemento para facilitar las pruebas.

6. Programar la lógica en Python

  • Abre y edita el archivo de código principal (.py).
  • Conecta las señales (signals) de la interfaz visual a funciones en Python (por ejemplo, asociando la señal clicked de un botón a la ejecución de una función).
  • Utiliza las API de PyQGIS y PyQt para manipular la lógica del proyecto o extraer información de las capas. Con cada modificación de código, ejecuta Plugin Reloader dentro de QGIS para visualizar los cambios inmediatamente.

7. Empaquetar y publicar (opcional)

  • Cuando tu complemento funcione correctamente y desees distribuirlo, genera un paquete comprimido utilizando el comando pb_tool zip.
  • Sube el archivo .zip resultante al repositorio oficial de complementos de QGIS (QGIS Plugin Repository / QGIS Hub) para compartirlo con la comunidad.
Volver a PASIG II