Чтобы получить доступ к функциям GIMP, мы начинаем с import gi. Этот модуль может определить, какие функции доступны в каждом модуле, определённом посредством «интроспекции объектов». Для нас это означает, что мы импортируем все связанные с GIMP модули, которые могут нам понадобиться, через вызовы gi.repository.

Для базовой функциональности может быть достаточно только модулей Gimp и GimpUi. Если необходимо запускать расширение из командной строки, вам даже не потребуется GimpUi. Начнём с примера.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
#   GIMP - The GNU Image Manipulation Program
#   Copyright (C) 1995 Spencer Kimball and Peter Mattis
#
#   gimp-tutorial-plug-in.py
#   sample plug-in to illustrate the Python plug-in writing tutorial
#   Copyright (C) 2023 Jacob Boerema
#
#   This program is free software: you can redistribute it and/or modify
#   it under the terms of the GNU General Public License as published by
#   the Free Software Foundation; either version 3 of the License, or
#   (at your option) any later version.
#
#   This program is distributed in the hope that it will be useful,
#   but WITHOUT ANY WARRANTY; without even the implied warranty of
#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#   GNU General Public License for more details.
#
#   You should have received a copy of the GNU General Public License
#   along with this program.  If not, see <https://www.gnu.org/licenses/>.

import sys

import gi
gi.require_version('Gimp', '3.0')
from gi.repository import Gimp
gi.require_version('GimpUi', '3.0')
from gi.repository import GimpUi
from gi.repository import GLib
      

Мы начинаем с импорта sys, который нам понадобится в конце для доступа к sys.argv, после чего import gi сообщает Python, что ему нужно загрузить модуль gi. Этот модуль используется для доступа к специальным функциям GIMP через «интроспекцию объектов».

В следующей строке мы сообщаем gi, что нам требуется версия API GIMP 3.0 (это расширение не будет работать с более старыми версиями GIMP). Следующая строка запрашивает импорт всех функций, классов и т. д. из модуля Gimp.

Следующие две строки делают то же самое для GimpUi. GimpUi содержит все элементы, связанные с интерфейсом GIMP. Если вы планируете создать расширение, которое будет вызываться только из командной строки, то вам это не понадобится. Мы завершаем импорт GLib, который нам понадобится позже для доступа к GLib.Error.

There are other optional modules that you can use, too, like Gegl and many others, but we won't go into that here.

GIMP должен знать, какие функции доступны, какие возможности они поддерживают и какое место в меню использовать. Для этого мы определяем класс, производный от класса Gimp.PlugIn.

A minimal plug-in needs at least the following functions defined in this class:

Теперь рассмотрим это подробнее. Ниже не приведена первая часть кода Python, показанная выше. Здесь показана только базовая структура вашего класса.

class MyFirstPlugin (Gimp.PlugIn):
    def do_query_procedures(self):
        return [ "jb-plug-in-first-try" ]

    def do_set_i18n (self, name):
        return False

    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("My first Python plug-in")
        procedure.add_menu_path('<Image>/Filters/Tutorial/')

        procedure.set_documentation("My first Python plug-in tryout",
                                    "My first Python 3 plug-in for GIMP 3",
                                    name)
        procedure.set_attribution("Your name", "Your name", "2023")

        return procedure

    def run(self, procedure, run_mode, image, drawables, config, run_data):
        Gimp.message("Hello world!")
        # do what you want to do, then, in case of success, return:
        return procedure.new_return_values(Gimp.PDBStatusType.SUCCESS, GLib.Error())
      

Let's take a closer look at do_query_procedures. In the line return [ "jb-plug-in-first-try" ] we tell GIMP what the name of our procedure is: we call it "jb-plug-in-first-try". This is the name that will be shown in GIMP's Procedure Browser.

В расширении может быть определено более одной процедуры. В этом случае необходимо перечислить все имена, разделяя их запятой.

Рекомендуется начинать все процедуры с ваших инициалов или какой-либо другой узнаваемой или уникальной метки. Таким образом, меньше вероятность, что ваше имя будет совпадать с именем расширения кого-то другого, что может сбить GIMP с толку. Кроме того, вы можете назвать его так, как вам нравится.

Далее мы сообщаем GIMP, что не поддерживаем переводы, возвращая False в вызове do_set_i18n. Действия, выполняемые при необходимости перевода расширения, выходят за рамки этого руководства.

Функция do_create_procedure — это место, где выполняется большая часть инициализации для GIMP.

Каждое расширение запускается вызовом Gimp.main.

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

Единственное, что нужно изменить в этой строке для вашего расширения — имя класса расширения, здесь называемого «MyFirstPlugin».

Ниже мы представляем весь сценарий на языке Python, который должен запускаться, если ему дано правильное имя в каталоге с таким же именем в месте, которое известно GIMP. Он покажет сообщение «Hello world!» в консоли ошибок или во всплывающем диалоговом окне.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
#   GIMP - The GNU Image Manipulation Program
#   Copyright (C) 1995 Spencer Kimball and Peter Mattis
#
#   gimp-tutorial-plug-in.py
#   sample plug-in to illustrate the Python plug-in writing tutorial
#   Copyright (C) 2023 Jacob Boerema
#
#   This program is free software: you can redistribute it and/or modify
#   it under the terms of the GNU General Public License as published by
#   the Free Software Foundation; either version 3 of the License, or
#   (at your option) any later version.
#
#   This program is distributed in the hope that it will be useful,
#   but WITHOUT ANY WARRANTY; without even the implied warranty of
#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#   GNU General Public License for more details.
#
#   You should have received a copy of the GNU General Public License
#   along with this program.  If not, see <https://www.gnu.org/licenses/>.

import sys

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

from gi.repository import GLib

class MyFirstPlugin (Gimp.PlugIn):
    def do_query_procedures(self):
        return [ "jb-plug-in-first-try" ]

    def do_set_i18n (self, name):
        return False

    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("My first Python plug-in")
        procedure.add_menu_path('<Image>/Filters/Tutorial/')

        procedure.set_documentation("My first Python plug-in tryout",
                                    "My first Python 3 plug-in for GIMP 3.0",
                                    name)
        procedure.set_attribution("Your name", "Your name", "2023")

        return procedure

    def run(self, procedure, run_mode, image, drawables, config, run_data):
        Gimp.message("Hello world!")
        # do what you want to do, then, in case of success, return:
        return procedure.new_return_values(Gimp.PDBStatusType.SUCCESS, GLib.Error())

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