GIMP Python Programming

@for Developers
@author Kai Ruhl
@since 2013-01

GIMP is the free Photoshop, and can do everything but the most advanced things. It is scripted primarily in Lisp, but Python access is also possible. This takes two forms: (1) from the inside, as a plugin and (2) from the outside, as a script. Here, only Linux is covered.

A basic guide is available in the GIMP python documentation. Good cheat sheet from the GIMP book. Also, have a look at my movie-frame-edit example, and the Frederic Jaume article.

1 Plugins (inside)

GIMP plugins go into the $HOME/.gimp-2.8/plug-ins directory and are simple Python files starting #!/usr/bin/env python. Make sure the executable flag is set on the file (chmod a+x myplugin.py). In the file, three steps are necessary:

• importing the GIMP libraries via from gimpfu import *
• writing a function of arbitrary name with at least two parameters: image and drawable (layer)
• registering it using the register() function provided by gimpfu.
• call main() once at the end.
  

But one by one. First, in the file, do the import and define a function taking image and drawable parameters (more are possible, then GIMP will open a dialog).

#!/usr/bin/env python

from gimpfu import *

def my_python_function(timg, tdrawable):
    first_layer = timg.layers[0]
    first_layer.name = "my first action"

register("my_gimp_name", "short desc", "long desc", "author", "owner", "year",
         "<Image>/Filters/YourChoice", "* or RGB* or other filetypes",
         [func-inargs but not timg/tdrawable], [func-outargs (leave_empty)],
         my_python_function)

main()

Here, we get the first layer from the image and change its name. The function needs to be registered with a whole lot of options that tell GIMP where to place the plugin and how to describe it. Details are in the GIMP python documentation.

But using a text editor is kind of unituitive. Rather use the Python console of GIMP, via Filters->Python-Fu->Console. If you want to assign a shortcut to this (I use it often), do Edit->Keyboard Shortcuts and search for python-fu-console. While you are at it, assign one to the procedure browser to (Help->Procedure Browser otherwise).

Speaking of the procedures: To actually do something, you need the procedure database or pdb object; the procedure browser tells you which procedures exist. Note: The browser was originally written for Lisp, in Python dashes ("-") become underscores ("_"), run-mode parameters are omitted, and -1 becomes None.

Open an image with GIMP, go into the console and try something like this:

timg = gimp.image_list()[0]
tdrawable = pdb.gimp_image_get_active_drawable(timg)
pdb.gimp_image_set_filename(timg, "Desktop/mytest.xcf")
pdb.gimp_context_set_foreground("#fff")
nlayer = pdb.gimp_text_layer_new(timg, "My shiny Text", "Sans", 50, 0)
nlayer.name = "layer name"
pdb.gimp_image_add_layer(timg, nlayer, 0)
pdb.gimp_layer_set_offsets(nlayer, 50, 250)
pdb.gimp_drawable_set_visible(nlayer, True)

The timg/tdrawable bit is not necessary when you are in a plugin, but in the console it is. Setting the filename sets both nlayer.name (basename only) and nlayer.filename (full path). Layers can be loaded or created, scaled, offsetted, made visible and so forth. Just browse the pdb and look at what is there.

After you are done with this, put everything into a plugin and you should be able to find it under Filters->YourChoice.

2 Scripting (outside)

Sometimes scripting from the outside is more desirable. However there is really no good way for this. The most promising one is to write a plugin and then call that from the outside.

gimp --no-interface --batch '(python-fu-my-gimp-name RUN-NONINTERACTIVE "param1_string" param2_int)' '(gimp-quit 1)'

Note that the underscores ("_") are dashes ("-") again. See also the bottom of the GIMP python documentation.