Writing GIMP Python plug-ins

Notes about writing Python plug-ins for the GNU Image Manipulation Program (GIMP).

The documentation for GIMP Python aka PyGIMP aka Python-fu is woeful.

The official docs are here, [link].

Some web pages for beginners to start with:

• http://zwell.net/content/pygimp.html
• http://www.neuraldump.com/2017/01/program-python-plug-ins-for-gimp-hello-gimp-world/
• https://web.archive.org/web/20150808044417/http://www.exp-media.com:80/content/extending-gimp-python-python-fu-plugins-part-1
• http://tinker.kotaweaver.com/blog/?p=81
• http://muras.eu/2012/05/06/Basic-python-script-for-Gimp/
• https://patdavid.net/2014/02/getting-around-in-gimp-plug-ins-and.html
• http://gimpbook.com/scripting/ (view the slides)
• http://gimpbook.com/scripting/notes.html
• https://www.ibm.com/developerworks/library/os-autogimp/
• http://wiki.elvanor.net/index.php/GIMP_Scripting
• https://gimplearn.net/viewtopic.php/How-to-write-Plug-in-for-GIMP-in-Python?p=10844#p10844

Python scripts are considered plug-ins, not scripts, so must be located in Plug-Ins folders.

The Plug-Ins folders are added in GIMP’s Edit>Preferences>Folders>Plug-Ins setting.

Most of the plug-ins distributed with GIMP are compiled .exe files, so written in C, and thus not helpful for Python-fu but their source can be studied here [link].

After installing a plug-in by copying a Python script to a Plug-Ins folder, GIMP must be restarted to register the plug-in.

After editing a plug-in’s registration functions, GIMP must be restarted. No restart required if changing only the other functions with the working code for the plug-in.

The structure of a typical plugin is shown below. Another template is found here.

The “procedure_name” will have “python-fu-“ prepended if it doesn’t start with any of the following: “python-", “python_”, “extension-“, “extension_”, “plug-in-“, “plug_in_”, “file-“ or “file_”. No illegal characters like $#@ space allowed.

The “procedure name” is what is registered in GIMP’s Procedural Database (PDB) so it must be unique and will appear in the PDB Browser. It is also the name used when registering load and save handlers.

“blurb” is a brief description of the plug-in.

“help message” is a long description of the plug-in or additional information that will appear in the PDB browser when the procedure is selected.

“author” and “copyright” are author and copyright holder names respectively.

“year” is year plug-in created.

“My plug-in” is the label that will appear for the plug-in in GIMP’s menus. It is also the name for the plug-in in the Plug-In Browser.

“*” is the image type the plug-in works with.

• “” or None means no image is required. Usually used when an image will be created.
• “RGB” means an RGB image must be selected. Plug-in will be disabled in the menu if an RGB image isn’t selected.
• “RGB*” means an RGB image with or without an alpha channel must be selected or else plug-in menu item disabled.
• "RGBA" means an RGB image with an alpha channel  must be selected
• “GRAY” means a GRAYSCALE image must be selected.
• “GRAY*” means a GRAYSCALE image with or without alpha must be selected.
• "GRAYA" means a GRAYSCALE image with an alpha channel must be selected.
• “INDEXED” means an INDEXED image must be selected.
• "INDEXEDA" means an INDEXED image with alpha must be selected.
• "INDEXED*" means an INDEXED image with or without alpha must be selected.
• “*” means any type image must be selected.

Combine image types by separating with commas or tabs or spaces, e.g. “RGB,GRAY”.

The input parameters must be 4-tuples of (type, “name”, “description” , default).

• type is one of the PF_* types defined in gimpfu.py. Examples are PF_INT for an integer type, PF_FLOAT for a floating point type, PF_STRING for a string type and PF_IMAGE for an image type.
• name is the name of the parameter. Can be different to the Python function parameter names. No illegal characters allowed e.g. &$@ space etc.
• description appears as the label for the field in the input dialog and  description that appears in the PDB browser.
• default is a default value for the parameter – must be the same type or None. The default values are used to set the values in the input dialog.

Specify as many input parameters as there are in the plugin_func and in the same order.

The output parameters must be 3-tuples of (type, “name”, “description”).

• type is one of the PF_* types.
• name is the name of the parameter used by GIMP. No illegal characters.
• description is a description for the PDB Browser.

Specify as many output parameters as returned by the plugin_func and in same order.

plugin_func is the name of the Python function that is called to do the work of the plug-in. Must have the same number of parameters as there are input parameters. The parameters are matched to the corresponding input parameters and the return values are matched to the output parameters.

“menu” is the location in GIMP's menus. Must be a path separated by “/” and must start with one of the following.

• <Image> for the Image window main menu
• <Load> to appear in the Open Image dialog. Only need <Load> no further path.
• <Save> to appear in the Export Image dialog. Only need <Save> no further path.
• <Toolbox> is deprecated - same as <Image> but all input parameters appear in an input dialog.
• <Layers> to appear in the popup menu when right-click in Layers window
• <Channels> to appear in the popup menu when right-click in Channels window
• <Buffers> to appear in the popup menu when right-click in Buffers window
• <Brushes> to appear in the popup menu when right-click in Brushes window
• <Patterns> to appear in the popup menu when right-click in Patterns window
• <Palettes> to appear in the popup menu when right-click in Palettes window
• <Gradients> to appear in the popup menu when right-click in Gradients window
• <Colormap> to appear in the popup menu when right-click in Colormap window
• <Vectors> to appear in the popup menu when right-click in Paths window
• <Fonts>
• <ToolPresets>
• <Dynamics> 

Some deprecated menu paths will be changed by GIMP, e.g. <Toolbox>/Xtns will become <Image>/Filters/Extensions. See  https://git.gnome.org/browse/gimp/tree/app/plug-in/plug-in-menu-path.c

If <Image> is specified, if the first input parameter is a PF_IMAGE it will be automatically set to the selected image. A PF_IMAGE specified in any other position will appear as an image selector in an input dialog.

If <Image> is specified, if first parameter is a PF_IMAGE then if the second parameter is a PF_DRAWABLE it will be automatically set to the active layer. A PF_DRAWABLE specified in any other position will appear as a layer selector in an input dialog.

If <Image> is specified, if the first input parameter is a PF_IMAGE and second parameter is a PF_DRAWABLE and there are no more input parameters then an input dialog will not appear and the plug-in runs non-interactively.

If <Load> is specified, the first two input parameters must be PF_STRING types and these will be set to the filename and raw-filename supplied by the Open File dialog. The plug-in will work non-interactively (no input dialog) unless the following trick is used.

Specify a PF_STRING as the third parameter. This parameter will be useless – cannot use it. It won’t appear in the input dialog. Now add input parameters for parameters you wish to appear in the input dialog as normal.

If <Load> is specified, then a PF_IMAGE output parameter must be specified as first parameter.

A <Save> plugin requires the following input parameters.

1. PF_IMAGE which will be set to the selected image
2. PF_DRAWABLE which will be set to the active layer
3. PF_STRING which will be set to the filename from the Export Image dialog
4. PF_STRING which will be set to the raw filename from the Export Image dialog

Required parameters are specified in gimp_plug_in_procedure_add_menu_path().

WARNING: There is another way to specify the location of the plug-in’s label in GIMP’s menus and it has a different behaviour.

The preferred way, shown above, is to specify the menu parameter either in twelfth position (params[11]) or using the named parameter, “menu”.

The old, deprecated way to specify the menu is to include it as part of the plug-in’s label parameter.

If the old way is used you do not specify all the input parameters because some will be automatically added as follows.

• <Image> will insert a PF_IMAGE as first input parameter and a PF_DRAWABLE as second parameter. These will be set to the active image and active layer.
• <Save> will insert a PF_IMAGE as first input parameter and a PF_DRAWABLE as second parameter and two PF_STRING parameters as the third and fourth parameters. These will be set to the active image, active layer, filename, and raw-filename respectively.
• <Load> will insert two PF_STRING parameters as the first and second parameters. These will be set to the filename and raw-filename respectively.

Remember to allow for these extra input parameters in your Python plugin_func.

To debug on Windows redirect output to a file.

Can also send messages using gimp.message(msg).

For debugging, open the Error Console by adding an Error Console tab otherwise messages popup in a dialog.

gimpfu.py is located at "C:\Program Files\Gimp-2.8\lib\gimp\2.0\python\gimpfu.py" on a default installation.

gimpfu._run() is where plugin_func is called. Changes to _run() don't need to restart GIMP.

gimpfu._query() is where menu is registered and procedure installed in PDB. _query() is only called when registration is changed so also needs GIMP restarted to see affect of any changes.

Commands

• img   = gimp.Image(width , height, type = RGB) creates an image object called img.
• layer = gimp.Layer(image, "name", width, height, type = RGB_IMAGE, opacity = 100.0, mode = NORMAL_MODE) creates a layer object called layer.
• img.insert_layer(layer, ) inserts a layer into an image.

 

Example Scripts

<Vectors>

• http://gimp-path-tools.sourceforge.net/index.shtml

<Load>

• https://github.com/sapper-trle/Gimp-Plugins/blob/master/file-load-trle.py
• https://git.gnome.org/browse/gimp/tree/plug-ins/pygimp/plug-ins/file-openraster.py 
• https://github.com/jsbueno/gimp_zxspectrum/blob/master/file-zxspectrum.py