Definição🔗

Python-Fu e a interface de scripting Python do GIMP. A partir do GIMP 2.10 ela usa GObject Introspection (gi.repository), o que permite acessar toda a API C do GIMP (libgimp) com chamadas Python idiomadas. Além disso, o módulo tradicional gimpfu expõe o objeto pdb, um wrapper de conveniência que espelha todos os procedimentos do PDB como métodos Python.

Use Python-Fu quando: precisa de bibliotecas Python externas (Pillow, NumPy, requests); quer lógica estruturada com classes e tratamento de exceções; ou pretende escrever um plugin moderno no estilo GIMP 3.

Conceitos🔗

flowchart TB
    A[Script .py] --> B{Estilo}
    B -->|gimpfu clássico| C[from gimpfu import *]
    B -->|GObject moderno| D[from gi.repository import Gimp, GimpUi]
    C --> E[Objeto pdb]
    D --> F[Módulo Gimp]
    E --> G[Chamada PDB]
    F --> G
    G --> H[libgimp core]
    H --> I[GEGL / Imagem]

Conceitos-chave:

• GObject Introspection — gi.repository expõe tipos C (como Gimp.Image) como classes Python. Use gi.require_version('Gimp', '3.0') antes de importar para garantir compatibilidade de versão.
• pdb — objeto mágico que expõe cada procedimento do PDB como método. Substitui hifens por underscores: gimp-drawable-desaturate vira pdb.gimp_drawable_desaturate(...).
• Wrappers de retorno — pdb.gimp_file_load(...) retorna tupla (status, image_id, drawable_id) no estilo moderno, ou uma lista no estilo antigo. Use desempacotamento: image = pdb.gimp_file_load(...)[1].
• register() / main() — gimpfu prove decoradores para registrar scripts como procedimentos PDB sem boilerplate.

Fluxo de Uso🔗

flowchart TD
    A[Testar no console: Filtros > Python-Fu > Console] --> B[Validar expressão]
    B --> C[Escrever arquivo .py]
    C --> D{Plugin ou script?}
    D -->|Script simples| E[from gimpfu import * + register + main]
    D -->|Plugin moderno| F["class GimpPlugin(Gimp.PlugIn): ..."]
    E --> G[Copiar para ~/.config/GIMP/2.10/plug-ins/]
    F --> G
    G --> H[Reiniciar GIMP]
    H --> I[Aparece em Filtros / Arquivos]

Exemplos Práticos🔗

Exemplo 1 — Console Python-Fu (estilo moderno)

Abra Filtros > Python-Fu > Console e teste:

import gi
gi.require_version('Gimp', '3.0')
from gi.repository import Gimp
print(Gimp.version())

A função imprime a versão completa do GIMP. Para inspecionar a API, use dir(Gimp) ou help(Gimp.Image.new).

Exemplo 2 — Criar uma imagem e salvar

#!/usr/bin/env python3
from gimpfu import *

def criar_imagem_azul(largura, altura):
    image = pdb.gimp_image_new(largura, altura, RGB)
    layer = pdb.gimp_layer_new(image, largura, altura,
                               RGBA_IMAGE, "Fundo", 100, LAYER_MODE_NORMAL)
    pdb.gimp_image_insert_layer(image, layer, None, 0)
    pdb.gimp_edit_fill(layer, FILL_BACKGROUND)
    pdb.gimp_context_set_background((0.2, 0.4, 0.8))
    pdb.gimp_edit_fill(layer, FILL_BACKGROUND)
    pdb.gimp_image_flatten(image)
    display = pdb.gimp_display_new(image)
    return image

register(
    "python_fu_criar_imagem_azul",
    "Criar imagem azul",
    "Cria uma imagem RGB preenchida com azul",
    "Autor",
    "Copyright 2024",
    "2024",
    "<Image>/File/Create/Azul...",
    "",
    [
        (PF_INT, "largura", "Largura", 800),
        (PF_INT, "altura", "Altura", 600),
    ],
    [],
    criar_imagem_azul)

main()

Salve em ~/.config/GIMP/2.10/plug-ins/criar_azul.py, marque como executável (chmod +x) e reinicie o GIMP. Aparecerá em Arquivo > Create > Azul....

Exemplo 3 — Dessaturar todas as camadas de uma imagem

def dessaturar_tudo(image, drawable):
    pdb.gimp_image_undo_group_start(image)
    for layer in image.layers:
        pdb.gimp_drawable_desaturate(layer, DESATURATE_LUMINOSITY)
    pdb.gimp_image_undo_group_end(image)
    pdb.gimp_displays_flush()

A iteração sobre image.layers retorna objetos drawable; cada um pode receber gimp_drawable_desaturate diretamente. O undo group permite reverter tudo de uma vez.

Exemplo 4 — Aplicar Gaussian Blur seletivamente

import os
import glob

def processar_lote(pasta):
    arquivos = glob.glob(os.path.join(pasta, "*.png"))
    for arq in arquivos:
        image = pdb.gimp_file_load(arq, arq)[1]
        drawable = pdb.gimp_image_get_active_drawable(image)
        pdb.gimp_image_undo_group_start(image)
        pdb.plug_in_gauss(image, drawable, 3.0, 3.0, 0)
        saida = arq.replace(".png", "_blur.png")
        pdb.gimp_file_save(image, drawable, saida, saida)
        pdb.gimp_image_delete(image)
        pdb.gimp_image_undo_group_end(image)

processar_lote("/tmp/imagens")

Esse script pode ser invocado a partir do console Python-Fu ou rodado em modo batch. Note o pdb.gimp_file_load retorna uma tupla (status, image, drawable) no GIMP 3; em 2.10 retorna uma lista.

Exemplo 5 — Plugin moderno (estilo Gimp.PlugIn)

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import sys
import gi
gi.require_version('Gimp', '3.0')
from gi.repository import Gimp, GLib

class HelloPlugin(Gimp.PlugIn):
    def do_query_procedures(self):
        return ["hello-py3"]

    def do_create_procedure(self, name):
        procedure = Gimp.ImageProcedure.new(self, name,
                                            Gimp.PDBProcType.PLUGIN,
                                            self.run, None)
        procedure.set_image_types("*")
        procedure.set_menu_label("Hello Python 3")
        procedure.add_menu_path('<Image>/Filters/Hello/')
        procedure.set_documentation("Hello world plugin",
                                    "Exibe uma mensagem de boas-vindas",
                                    name)
        return procedure

    def do_set_i18n(self, name):
        return False

    def run(self, procedure, run_mode, image, drawables, config, run_data):
        Gimp.message("Ola do GIMP 3 via Python 3!")
        return procedure.new_return_values(Gimp.PDBStatusType.SUCCESS, GLib.Error())

Gimp.main(HelloPlugin.__gtype__, sys.argv)

A classe Gimp.PlugIn substitui o antigo register()/main(). Os métodos do_query_procedures, do_create_procedure, do_set_i18n e run são obrigatórios; Gimp.main() conecta o plugin ao GIMP no momento da execução.

Comparativo Python-Fu vs Script-Fu🔗

Aspecto	Python-Fu	Script-Fu
Sintaxe	Moderna, identada	S-expressions (Lisp)
Bibliotecas externas	Sim (pip no venv)	Não
Tratamento de erros	try/except nativo	limitado
Performance de bootstrap	Ligeiramente mais lenta	Quase instantânea
Curva de aprendizado	Baixa para quem conhece Python	Alta para quem não conhece Lisp

Diretórios de Instalação🔗

Plataforma	Caminho
Linux	~/.config/GIMP/2.10/plug-ins/
macOS	~/Library/Application Support/GIMP/2.10/plug-ins/
Windows	%APPDATA%\GIMP\2.10\plug-ins\

Para o script aparecer como procedimento, salve-o em uma pasta com o mesmo nome do arquivo (sem extensão): ~/.config/GIMP/2.10/plug-ins/criar_azul/criar_azul.py. Marque como executável no Linux/macOS.

Referências🔗

• GIMP Docs — Python-Fu Submenu
• GIMP Docs — Python plug-in writing Tutorial
• GIMP Docs — Scripting and writing plug-ins