Developing Gimp plugins using Python

One topic of my last post “Converting gif animations to mpq files on Ubuntu” was my decision to create my own text animation using Gimp. My goal was to create a nice looking animation of text typed in a terminal. A very simple task. You just have to create a layer for each new letter that should be displayed. Finally you append the time in milliseconds, the image should be displayed and the replace flag, which forces gimp to replace the previous layer if the new one should be displayed. Finally your layer stack should look like this:

Layer #n (300ms) (replace)
Layer #n-1 (25ms) (replace)
...
Layer #2 (25ms) (replace)
Layer #1 (25ms) (replace)

However, you might want to change the time a layer is displayed, which is not really a problem as you just have to change the layer name, but in my case I had to rename about 100 layers. That is really time consuming and in most cases I had to change the display time very often until I had the animation speed I was happy with. That sucks! But there are good news: Python rocks and it is very easy to build Gimp plugins using Python!

To write your own Gimp plugin using Python you utilize the following three libraries:

• gimpfu : GUI library
• gimp : The main library (imported with gimpfu)
• gimpenums : Important constants (imported with gimpfu)

To conclude: Import gimpfu! So let’s take a look at the code.

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

def renameAllLayers(img, name, millis):
	counter = len(img.layers)-1

	for layer in img.layers:
		layer.name = name + ' #' + str(counter) + ' (' + str(millis) + 'ms) (replace)'
		counter -= 1

register(
	proc_name=("bornageek_rename_all_layers"),
	label=("Rename all layers"),
	blurb=("Rename all layers so they include all missing flags"),
	help=("Help?"),
	author=("Andreas Schickedanz"),
	copyright=("www.bornageek.com"),
	date=("2013"),
	menu=("<img/>/Avedo Scripts/Layer Renamer"),
	imagetypes=("*"),
	params=[
		(PF_IMAGE, 'img', 'Select an image', None),
		(PF_STRING, 'name', 'The layer\'s name', 'Layer'),
 		(PF_INT, 'millis', 'Milliseconds to display a frame', 100),
	],
	results=[],
	function=(renameAllLayers)
)

main()

To run this scipt save it as renameLayers.py within the hidden gimp folder inside your home directory (~/.gimp-2.8/plug-ins) or create a own one like ~/.gimp/plugins. Then open Gimp and tell it where it could find this plugin. Therefore go to Edit -> Preferences, expand the “Folders” node and add your directory under “Scripts”. Finally restart Gimp. You should noew see a new entry “Avedo Scripts” within the menu. Selecting it shows a single entry “Rename Layers” within a submenu. If you just started gimp without opening an image this entry should be greyed out. To test it create a new image open the layers view and add some new layers named what ever you want. Now you should be able to execute the script which should open a dialog asking to enter a layer name and the amount of milliseconds to display a single layer. Hitting “Ok” should finally result in a renamed layer stack.

Great? Then let’s take a look at the code.

The second line of the scipt is responsible for loading all needed libraries. Remember that this also loads the gimp and gimpenums libraries.

from gimpfu import *

This import is followed by the declaration of the actual Python function that implements the actual plugin. In this case the function receives just three arguments. The first argument is the cureently selected image, the second the layer name entered within the dialog and the third the amount of milliseconds entered.

def renameAllLayers(img, name, millis):

The command in the first line of the function counts the currently available image layers.

counter = len(img.layers)-1

Within the following loop, the script iterates over all layers and renames each layer by changing the name attribute of the layer class.

layer.name = 'Layer #' + str(counter) + ' (35ms) (replace)'

After that the layer counter is incremented and the function is registered with Gimp. Therefore you use the Gimp function register which receives the following paramters:

• proc_name : The function name within Gimp
• label : The name of the plugin
• blurb : A short description of the plugin
• help : A help text
• author : The author’s name
• copyright : A copyright text and/or license
• date : The creation date
• menu : Menu path to the plugin
• imagetypes : Image types supported by this plugin
• params : A input parameter list
• results : A list of restult parameters
• function : The actual python function that should be called

The params parameter holds a list of input parameters, which are passed to the python function specified by the function parameter. Each input parameter is a tuple of the format (type, name, description, default [, extra]), where type could be one of the following constants specified within gimpenums.

Note that gimpfu automatically will specify a run_type, image and drawable parameter for you, so you do not have to add them yourself.

That’s it. You wrote your first Gimp plugin using Python. But before you start writing you own plugin here are some hints for you.

When you are writing your script, you should observe a few rules:

1. Start with small steps, so you save time tracing your code.
2. Use the integrated Python console to test commands (Filters -> Python-Fu -> Console).
3. If your script does not show up in the menu, search for it within the registered functions (use “Browse…” from the Python console).

If you follow this hints/rules you should be able to write some really useful Gimp plugins in less then one hour. If you would like to see a more advanced plugin than the one I presented in this post, stay tuned for my next post where I will show you a plugin I am currently working on.

Until then, happy coding.