Gimp Python Documentation

1.1. What is it?

Gimp-Python is a scripting extension for Gimp, similar to Script-Fu. The main difference is in what is called first. In Script-Fu, the script-fu plugin executes the script, while in Gimp-Python the script is in control.

In fact, you will find that the Gimp-Python scripts start with the line #!/usr/bin/python. The gimp extension is loaded with the familiar import command.

Another point of difference between Gimp-Python and Script-Fu is that Gimp-Python stores images, layers, channels and other types as objects rather than just storing their ID. This allows better type checking that is missing from Script-Fu, and allows those types to act as objects, complete with attributes and methods.

Also, Gimp-Python is not limited to just calling procedures from the PDB. It also implements the rest of libgimp, including tiles and pixel regions, and access to other lower level functions.

1.2. Installation

Gimp-python consists of a Python module written in C and some native python support modules. You can build pygimp with the commands:

./configure
make
make install

This will build and install gimpmodule and its supporting modules, and install the sample plugins in gimp's plugin directory.

2.1. An Example Plugin

As in a lot of manuals, the first thing you examine is an example, so here is an example. I have included it before explaining what it does to allow more advanced programmers to see the structure up front. It is a translation of the clothify Script-Fu extension:

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

have_gimp11 = gimp.major_version > 1 or \
	      gimp.major_version == 1 and gimp.minor_version >= 1

def python_clothify(timg, tdrawable, bx=9, by=9,
		    azimuth=135, elevation=45, depth=3):
	bx = 9 ; by = 9 ; azimuth = 135 ; elevation = 45 ; depth = 3
	width = tdrawable.width
	height = tdrawable.height
	img = gimp.image(width, height, RGB)
	layer_one = gimp.layer(img, "X Dots", width, height, RGB_IMAGE,
			       100, NORMAL_MODE)
	img.disable_undo()
	if have_gimp11:
		pdb.gimp_edit_fill(layer_one)
	else:
		pdb.gimp_edit_fill(img, layer_one)
	img.add_layer(layer_one, 0)
	pdb.plug_in_noisify(img, layer_one, 0, 0.7, 0.7, 0.7, 0.7)
	layer_two = layer_one.copy()
	layer_two.mode = MULTIPLY_MODE
	layer_two.name = "Y Dots"
	img.add_layer(layer_two, 0)
	pdb.plug_in_gauss_rle(img, layer_one, bx, 1, 0)
	pdb.plug_in_gauss_rle(img, layer_two, by, 0, 1)
	img.flatten()
	bump_layer = img.active_layer
	pdb.plug_in_c_astretch(img, bump_layer)
	pdb.plug_in_noisify(img, bump_layer, 0, 0.2, 0.2, 0.2, 0.2)
	pdb.plug_in_bump_map(img, tdrawable, bump_layer, azimuth,
			     elevation, depth, 0, 0, 0, 0, TRUE, FALSE, 0)
	gimp.delete(img)

register(
	"python_fu_clothify",
	"Make the specified layer look like it is printed on cloth",
	"Make the specified layer look like it is printed on cloth",
	"James Henstridge",
	"James Henstridge",
	"1997-1999",
	"<Image>/Filters/Artistic/Clothify",
	"RGB*, GRAY*",
	[
		(PF_INT, "x_blur", "X Blur", 9),
		(PF_INT, "y_blur", "Y Blur", 9),
		(PF_INT, "azimuth", "Azimuth", 135),
		(PF_INT, "elevation", "elevation", 45),
		(PF_INT, "depth", "Depth", 3)
	],
	[],
	python_clothify)

main()

2.2. Import Modules

In this plugin, a number of modules are imported. The important ones are:

• gimpfu: this module provides a simple interface for writing plugins, similar to what script-fu provides. It provides the GUI for entering in parameters in interactive mode and performs some sanity checks when registering the plugin.

  By using "from gimpfu import *", this module also provides an easy way to get all the commonly used symbols into the plugin's namespace.

• gimp: the main part of the gimp extension. This is imported with gimpfu.

• gimpenums: a number of useful constants. This is also automatically imported with gimpfu.

The pdb variable is a variable for accessing the procedural database. It is imported into the plugin's namespace with gimpfu for convenience.

2.3. Plugin Framework

With pygimp-0.4, the gimpfu module was introduced. It simplifies writing plugins a lot. It handles the run mode (interactive, non interactive or run with last values), providing a GUI for interactive mode and saving the last used settings.

Using the gimpfu plugin, all you need to do is write the function that should be run, make a call to register, and finally a call to main to get the plugin started.

If the plugin is to be run on an image, the first parameter to the plugin function should be the image, and the second should be the current drawable (do not worry about the run_mode parameter). Plugins that do not act on an existing image (and hence go in the toolbox's menus) do not need these parameters. Any other parameters are specific to the plugin.

After defining the plugin function, you need to call register to register the plugin with gimp (When the plugin is run to query it, this information is passed to gimp. When it is run interactively, this information is used to construct the GUI). The parameters to register are:

Most of these parameters are quite self explanatory. The menupath option should start with <Image%gt;/ for image plugins and <Toolbox>/ for toolbox plugins. The remainder of the menupath is a slash separated path to its menu item.

The params parameter holds a list parameters for the function. It is a list of tuples. Note that you do not have to specify the run_type, image or drawable parameters, as gimpfu will add these automatically for you. The tuple format is (type, name, description, default [, extra]). The allowed type codes are:

These values map onto the standard PARAM_* constants. The reason to use the extra constants is that they give gimpfu more information, so it can produce a better interface (for instance, the PF_FONT type is equivalent to PARAM_STRING, but in the GUI you get a small button that will bring up a font selection dialog).

The PF_SLIDER, PF_SPINNER and PF_ADJUSTMENT types require the extra parameter. It is of the form (min, max, step), and gives the limits for the spin button or slider.

The results parameter is a list of 3-tuples of the form (type, name, description). It defines the return values for the function. If there is only a single return value, the plugin function should return just that value. If there is more than one, the plugin function should return a tuple of results.

The final parameter to register is the plugin function itself.

After registering one or more plugin functions, you must call the main function. This will cause the plugin to start running. A GUI will be displayed when needed, and your plugin function will be called at the appropriate times.

3.1. The Gimp-Python Model

In Gimp-Python, the procedural database is represented by the object gimp.pdb. In most of my plugins, I make an assignment from gimp.pdb to pdb for convenience.

You can query the procedural database with pdb's method query. Its specification is:

pdb.query(name, [blurb, [help, [author, [copyright, [date, [type]]]]]])

Each parameter is a regular expression that is checked against the corresponding field in the procedural database. The method returns a list of the names of matching procedures. If query is called without any arguments, it will return every procedure in the database.

3.2. Procedural Database Procedures

Procedures can be accessed as procedures, or by treating pdb as a mapping objest. As an example, the probedure gimp_edit_fill can be accessed as either pdb.gimp_edit_fill or pdb['gimp_edit_fill']. The second form is mainly for procedures whose names are not valid Python names (eg in script-fu-..., the dashes are interpreted as minuses).

These procedure objects have a number of attribute:

A procedure object may also be called. At this point, Gimp-Python doesn't support keyword arguments for PDB procedures. Arguments are passed to the procedure in the normal method. The return depends on the number of return values:

• If there are zero return values, None is returned.

• If there is only a single return value, it is returned.

• If there are more return values, then they are returned as a tuple.

3.3. More Information

For more information on invoking PDB procedures, please see the example plugins. For information on individual procedures, please see the PDB Browser plugin (in the Xtns menu). It allows you to peruse to the database interactively.

4.1. Constructors and Object Deletion

There are a number of functions in the gimp module that are used to create the objects used to make up an image in Gimp. Here is a set of descriptions of these constructors:

When any of these objects get removed from memory (such as when their name goes out of range), the gimp thing it represents does not get deleted with it (otherwise when your plugin finished running, it would delete all its work). In order to delete the thing the Python object represents, you should use the gimp.delete procedure. It deletes the gimp thing associated with the Python object given as a parameter. If the object is not an image, layer, channel, drawable or display gimp.delete does nothing.

4.2. Configuration Information

There are a number of functions that can be used to gather information about the environment the plugin is running in:

4.3. Palette Operations

These functions alter the currently selected foreground and background.

4.4. Gradient Operations

These functions perform operations on gradients:

4.5. PDB Registration Functions

These functions either install procedures into the PDB or alert gimp to their special use (eg as file handlers).

For simple plugins, you will usually only need to use register from gimpfu.

4.6. Other Functions

These are the other functions in the gimp module.

4.7. Parasites

In gimp >= 1.1, it is possible to attach arbitrary data to an image through the use of parasites. Parasites are simply wrappers for the data, containing its name and some flags. Parasites have the following parameters:

Parasites also have the methods copy, is_type and has_flag.

There is a set of four functions that are used to manipulate parasites. They exist as functions in the gimp module, and methods for image and drawable objects. They are:

5.1. Image Object

This is the object that represents an open image. In this section, image represents a generic image object.

5.2. Channel Objects

These objects represent a Gimp Image's colour channels. In this section, channel will refer to a generic channel object.

5.3. Layer Objects

Layer objects represent the layers of a Gimp image. In this section I will refer to a generic layer called layer.

5.4. Drawable Objects

Both layers and channels are drawables. Hence there are a number of operations that can be performed on both objects. They also have some common attributes and methods. In the description of these attributes, I will refer to a generic drawable called drawable.

5.5. Tile Objects

Tile objects represent the way Gimp stores information. A tile is basically just a 64x64 pixel region of the drawable. The reason Gimp breaks the image into small pieces like this is so that the whole image doesn't have to be loaded into memory in order to alter one part of it. This becomes important with larger images.

In Gimp-Python, you would use Tiles if you wanted to perform some low level operation on the image, instead of using procedures in the PDB. This type of object gives a Gimp-Python plugin the power of a C plugin, rather than just the power of a Script-Fu script. Tile objects are created with either the drawable.get_tile() or drawable.get_tile2() functions. In this section, I will refer to a generic tile object named tile.

5.6. Pixel Regions

Pixel region objects give an interface for low level operations to act on large regions of an image, instead of on small 64x64 pixel tiles. In this section I will refer to a generic pixel region called pr. For an example of a pixel region's use, please see the example plugin whirlpinch.py.

6.1. The gimpenums Module

This module contains all the constants found in the header libgimp/gimpenums.h, as well as some extra constants that are available in Script-Fu.

6.2. The gimpfu Module

This module was fully described in an earlier section. It provides an easy interface for writing plugins, where you do not need to worry about run_modes, GUI's and saving previous values. It is the recommended module for writing plugins.

6.3. The gimpplugin Module

This module provides the framework for writing Gimp plugins in Python. It gives more flexibility for writing plugins than the gimpfu module, but does not offer as many features (such as automatic GUI building).

To use this framework you subclass gimpplugin.plugin like so:

import gimpplugin
class myplugin(gimpplugin.plugin):
	def init(self):
		# initialisation routines
		# called when gimp starts.
	def quit(self):
		# clean up routines
		# called when gimp exits (normally).
	def query(self):
		# called to find what functionality the plugin provides.
		gimp.install_procedure("procname", ...)
	# note that this method name matches the first arg of
	# gimp.install_procedure
	def procname(self, arg1, ...):
		# do what ever this plugin should do

6.4. The gimpshelf Module

This module gives a nicer interface to the persistent storage interface for Gimp plugins. Due to the complicated nature of Python objects (there is often a lot of connections between them), it can be difficult to work out what to store in gimp's persistent storage. The python interface only allows storage of strings, so this module wraps pickle and unpickle to allow persistentstorage of any python object.

Here is some examples of using this module:

>>> from gimpshelf import shelf
>>> shelf['james'] = ['forty-two', (42, 42L, 42.0)]
>>> shelf.has_key('james')
1
>>> shelf['james']
['forty-two', (42, 42L, 42.0)]

Anything you store with gimpshelf.shelf will exist until Gimp exits. This makes this interface perfect for when a plugin is executed with the run mode RUN_WITH_LAST_VALS.