Writing Plugins for GIMP in Python

By: Akkana Peck
Wednesday, April 8, 2009 11:23:20 PM EST
URL: http://www.linuxplanet.com/linuxplanet/tutorials/6720/1/

Creating a Script

Have you ever wished you could automate a few functions in GIMP? Today's article will show you how to use Python to write simple GIMP plug-ins.

If you have gimp installed via your Linux distro, GIMP-Python is probably already included. To make sure, look for a Filters->Python-Fu menu. If you built your own GIMP and don't have the Python-fu, it may be that you didn't have python-gtk2 or python-gtk2-dev installed when you built it. Install them and re-run configure and you should be able to rebuild gimp with Python support. (In Ubuntu, you should have Xtns -> Python Fu-- ed.)

GIMP-Python scripts live under your home directory, in .gimp-2.6/plug-ins/. If you're using a different GIMP version, like 2.4 or 2.7, change the name appropriately. So edit a file there -- for example, $HOME/.gimp-2.6/plug-ins/pytest -- and start with the following headers: 

#!/usr/bin/env python

from gimpfu import *
The "shebang" line tells Linux this is a Python script, and the second line tells Python that you'll be using the "gimpfu" library.

One more step: your file needs to be executable. So run 

chmod 755 $HOME/.gimp-2.6/plug-ins/pytest
or, if you prefer, use your file manager to make it executable. Now you have a runnable GIMP-Python script.

Registering Your New Plugin

All GIMP plug-ins, regardless of language, need to call register to tell GIMP they exist. Here's a skeleton of a GIMP-Python plug-in showing how to register. Copy and paste this into pytest so you can see how it works: 

def python_pytest(img, layer) :
    # Actual plug-in code will go here
    return

register(
       	"python_fu_pytest",
	"Does something",
	"Does something terribly useful",
	"Your name",
	"Your name",
	"2009",
	"Py Test...",
	"*",
	[
	],
	[],
	python_pytest,
        menu="<Image>/Filters/Distorts")

main()

What does all that mean? The first part, def python_pytest, is the routine that will do the real work ... but for now, it's just a placeholder. It takes two arguments, the image and layer to work on. Any plug-in that modifies an existing image must use at least these two arguments. Plug-ins that create new images don't need them.

register is next. It takes quite a list of arguments:

  • A python_fu name by which your function will be available to other GIMP scripts;
  • Short and long descriptions of what the plug-in does;
  • The name of the author and the copyright holder (usually the same person) and the copyright date;
  • The name the plug-in should use in the menus;
  • The types of images your plug-in can handle (RGB, greyscale, indexed or all). If it can work on any type of image, use "*"; if it creates a new image rather than operating on an existing one, use "";
  • Any parameters the plug-in might show to the user -- I'll show how to use these in a future article;
  • Any return values. Most python scripts leave this blank, or [];
  • The name of the function that does the work, python_pytest;
  • Where in the menus you want the function to show up.

Whew! Quite a lot of arguments, but usually you can copy most of them from some other plug-in and just change the values; you don't have to remember all of that.

Does it Register?

Once you have your plug-in's skeleton in place, it's time to see if it registers right. Quit GIMP if it's already running, re-start it, and see if your plug-in shows up in the menu -- in this case, somewhere under Filters->Distorts (Figure 1).

Problems? If it doesn't show up, make sure your python script is executable, and try running gimp from the commandline. If there are any syntax errors in the script, it'll tell you. If no errors are being printed but your plug-in still isn't showing up, try gimp --verbose and watch to see if it's finding the script.

Writing the plug-in

Once you have your plug-in showing up in the menus, the rest is easy! Just call functions to do the same things you would have done yourself in GIMP. For this short article, let's do something very simple: flip the current image upside down.

How do you figure out how to do that? With the GIMP Procedure browser, available from GIMP's Help menu. In GIMP 2.4 and earlier it was in the Xtns menu inside the Toolbox window.

Open the Procedure Browser and search for flip (Figure 2).

There are a lot of different flip routines there; for now, let's pick one that looks simple, gimp-image-flip.

The Procedure Browser shows that it takes two parameters: the image to flip, and a flip-type that can be ORIENTATION-HORIZONTAL (0) or ORIENTATION-VERTICAL (1).

Here's how that translates into Python: 

def python_pytest(img, layer) :
    pdb.gimp_image_flip(img, ORIENTATION_VERTICAL)

Make that change to your pytest file, and try it! No need to restart again -- once you've registered, GIMP knows where the file is and will pick up whatever changes you make. You only need to restart when you change something in the register() function.

So run Filters->Distorts->Py Test, and voilà! The image is flipped upside down (Figure 3). It's that simple.

In the next article, I'll show you how to use plug-in arguments to make a plug-in that does something much more useful.

Akkana Peck is a freelance programmer whose credits include a tour as a Mozilla developer. She's also the author of Beginning GIMP: From Novice to Professional.

Copyright Jupitermedia Corp. All Rights Reserved.