GIMP 3.0 Python Plugins

GIMP 3.0 has released and has numerous new features making it a better choice for image editing than GIMP 2.10. However one issue is that GIMP 3 brings major breaking changes to the Python plugin architecture meaning that plugins need to be rewritten to work with GIMP 3.  To help with that, here is a short guide to resources and hints for writing Python plugins for GIMP 3 or porting your old ones.

Cartoon of python plugging into GIMP

The Official Docs

The official documentation for writing Python plugins for GIMP consists of:

Other Useful Documentation Sources

https://gitlab.gnome.org/GNOME/gimp/-/tree/master/plug-ins/python has numerous useful example scripts written in python to give you a feel for plugin structure and possibilities

https://github.com/akkana/gimp-plugins has some more useful examples with both GIMP 2 and GIMP 3 version in some cases allowing comparison

https://z-uo.medium.com/create-python3-plugin-for-gimp-the-basics-94ede94e9d1f covers getting up and running in Linux and some ways to access documentation from within GIMP

https://gimpchat.com/viewtopic.php?f=9&t=21349 gives a nice overview of the conversion of an existing GIMP 2 script to a GIMP 3 version

https://barefootliam.blogspot.com/2022/10/gegl-plug-ins-for-gimp-part-one-using.html and https://barefootliam.blogspot.com/2022/12/gegl-plug-ins-for-gimp-part-two-gegl.html give some useful general information about GEGL

Sources of Help Inside GIMP

From the  Python Console  (Filters > Development > Python-Fu > Python Console) you can run help(‘modules’). This will let you know what python modules are installed by default and available for use in GIMP (be aware that installing extra libraries is a pain). Note that potentially useful libraries like Numpy, Pandas and open-CV are NOT installed, however you do have sys, os, math, gi, graphlib, random, csv, re (for regex) and a lot of other useful basic libraries. Docs for many of these standard libraries can be found at https://docs.python.org/3/library/

The menu item Help > Procedure Browser can be very useful for getting information on available procedures and their required parameters. Sadly it does not seem to provide a function’s return types.

You can also see some example python plugin scripts included with GIMP 3.0 by going to the C:\Users\<user>\AppData\Local\Programs\GIMP 3\lib\gimp\3.0\plug-ins folder and searching for *.py files. histogram-export.py is quite a useful one to look at since it uses several kinds of input widget in its menu, interacts with the files system and with image layers and properties

Key Points to Note

Your plugin must be placed in the correct folder. You can find the relevant folder to install your plugin by looking at the folders listed under Edit > Preferences > Folders > Plug-ins. You need to create a folder there and then inside that place your python plugin file which must have the same name as the containing folder (except ending in .py). Failure to do this means your plugin will not register and will not work.

Its worth knowing that you do not have to restart GIMP to trial changes to your plugin unless the changes affect its registration, just edit the Python file, save it and you should see your changes immediately. The exceptions to this are changes to registration and anything which causes the plugin to crash so that you get a warning to restart GIMP.

Available built in procedures can either be called directly from the gi library or they can be retrieved  from the GPD using gi.repository.Gimp.get_pdb().lookup_procedure  as detailed here . Note that if using a procedure directly, you can pass the parameters in directly as function parameters. if you retrieve the function using a lookup into a variable (say procedure), then you have to assign each parameter in turn using procedure.set _property() and then run the procedure with procedure.run() which can get rather longwinded.

Be very wary of inadvertently passing backslashes to Gio.File.new_for_path which is used to create filename objects for use with loading and saving functions. While outputting the contents of one of these objects on Windows might make it appear that backslashes are acceptable, it appears that only forward slashes will work as folder separators in file name strings fed to this method. This seems to be because backslashes are being treated as escape characters, so double backslashes may also work.

Some of the enum constants provided in the docs are prepended with GIMP_ in the documentation for instance in https://developer.gimp.org/api/3.0/libgimp/enum.RunMode.html there is a value listed as GIMP_RUN_NONINTERACTIVE but the actual command you need is Gimp.RunMode.NONINTERACTIVE and not Gimp.RunMode.GIMP_RUN_NONINTERACTIVE this also applies to ImageBaseType and ImageType enums.

The documentation is also fond of referring to methods using names such as gimp_image_get_file when the actual call is Gimp.Image.get_file(). Be wary in such cases, the classes need to be capitalised, but the methods are lower case

Note that if a call is wrong your plugin may crash. On the other hand it may just halt at that point leading to mystifying partial completions. In this case you may need to intersperse the code with debugging statements to identify the error. This is detailed below.

Some early versions of GIMP 3 on windows had broken Python support so if your plugin is not working, try reinstalling with GIMP 3.0.4 or above. A quick way to check is to see whether you can get the Python console via Filters > Development > Python-Fu > Python Console. If you can’t see this and can’t a python console, then you likely have a bugged version of GIMP.

Debugging

At the most basic level, if you start Gimp from a terminal or with gimp-console.exe (Windows) the output of any print instructions will appears in the console

The next step up is to use GIMP’s error console. Go to Windows > Dockable Dialogs > Error Console to enable the error console (which appears on the right along with your other dockable dialogues). Its symbol is a small warning sign. Any Gimp.message statements in your script will now print to this console. It can be worth going a step further by adding a small debug procedure to your plugin along the lines of

from gi.repository import Gimp

DEBUG_LEVEL = 2
def debug(message:str, level=1):
    if level &amp;amp;gt;= DEBUG_LEVEL:
        Gimp.message(message)

debug("This will print at DEBUG_LEVEL = 2", 2)
debug("This will not print since it needs DEBUG_LEVEL = 1")

This allows you to easily change how verbose your console messages are for easier debugging.

There are also additional utilities you can use apparently if you are on Linux https://developer.gimp.org/resource/analyze-plug-ins-tutorial/ and some information on debugging for Windows https://developer.gimp.org/resource/debug-plug-ins/#windows

That is all for now. Hopefully soon I will be back with some example plugins of my own to share with you.

Script Fu

If you are looking for instructions to write GIMP 3 plugins in Script Fu rather than Python, this is a good starting point: https://script-fu.github.io/funky/

 

2 Replies to “GIMP 3.0 Python Plugins”

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.