GIMP Scripting

Basics

• Scripting the GIMP can be done easily using the Python API. You can write pure Python scripts, and you don't need to use Scheme at all.

• The Python API actually wraps the PDB. The PDB code is written in C so is fast. You can use PDB calls in your Python code, or use the object oriented API. The only advantage in using the OO API is cleaner code - no performance gain there, since the Python API wraps PDB anyway.

• In your script, you need to have the register() function and a main() function which can be empty, in addition to your actual function which executes what you want. Here are the arguments for the register function (with an example):
  • "generate_rounded_corners": Name of the plugin (how to call it programmatically with Script-Fu)
  • "This is a test Python plugin." : Textual description
  • "It creates and saves an image.": Other description (extended, not sure here)
  • "Elvanör": Author
  • "Jean-Noël Rivasseau": Copyright owner
  • "2007": Date
  • "_Rounded Corners...": Name of the plugin (in the GIMP menus)
  • "RGB*, GRAY*": Modes accepted (??)
  • []: Arguments to this plugin
  • []: Return values of this plugin, only useful in non interactive mode
  • generateRoundedCorners: Python callback function (essential!)
  • menu="<Image>/Filters/Render/Rounder Corners": Path in the menus

• In the previous list, the arguments list has the following syntax:
  • PF_STRING: type of argument
  • "targetDirectory": argument name
  • "The directory in which will be saved the images": description
  • "/srv/": Default value. This is used *only* in the interface, eg. when using the plugin non interactively you must always pass the correct number of arguments.

• The _() function that you can see used in example plug-ins is for internationalization. The "_R" in "_Rounded Corners..." is for the mnemonic, eg the key that will be associated as a shortcut in the interface.

Plugins

• The scripts should be stored in the plug-ins directory of the general Gimp directory (controlled by GIMP2_DIRECTORY). All should have executable permission!

• The following error:

LibGimpBase-WARNING **: gimp-console: gimp_wire_read(): error

essentially means that Gimp could not parse a Python script, eg the script that. This happens if you store a plain Python file in the plug-ins directory. For this reason only actual plug-in scripts should be present in that directory, helpers should go elsewhere.

• The file pluginrc contains information about the registered plugins. It can safely be deleted and will be regenerated by querying the plug-ins.

• You cannot import a plugin into another plugin and expect this to work. The solution is to refactor common functions into separate modules.

Writing and Debugging Python Scripts

• You can make your image appear on the GUI with the following command:

display = pdb.gimp_display_new(image)

• Already opened images can be used in the Python console:

imagesList = gimp.image_list()

• A recommended way to debug your scripts is to run each command separately in the Python console. You can also exit from a Python script by using the return() statement.

• A primitive way to get basic information displayed by your scripts is to use the gimp_message function, which will display a string on the GIMP's GUI.

• Fore more advanced debugging, writing to a log file (from within Python) is mandatory.
• Loading GIMP from a shell (as opposed to starting it from within a desktop environment such as KDE) gives you a stack trace when an exception happens! This is invaluable information, so you should *always* start Gimp from the console when developping Python scripts.

Python API / Bindings

• For operations on a layer, you must add the layer to the image first. Else you will get an execution error.

• In the PDB, some functions like pdb.gimp_text_fontname allows to specify -1 as a DRAWABLE argument (to create a new layer). Using the Python API this does not work, and should be replaced with None.

• Functions returning more than one argument must effectively be bound to the correct number of arguments (even if some of these will be null).

newLayer, newImage = pdb.some_function() # not newImage = pdb.some_function() even if the newLayer will be null

Layers

• Copying a layer from one image to another is best done using gimp_layer_new_from_drawable(). The new layer must still be added to the destination image.
• Duplicating a layer on an image is done via gimp_layer_copy(). Here too you must add the copy to the image before working on it.
• Moving a layer can be done using the gimp_layer_translate() function. Be careful of the gimp-drawable-offset() which translates the *content* of the layer.
• Tiling a layer can be done via the plug_in_tile() PDB function.

Selections

• Don't forget that selection operations must specify an operation mode (CHANNEL_OP_ADD, CHANNEL_OP_REPLACE...).
• Using the bucket fill function over a supposedly empty selection seems to still have some effect. So be careful about "empty selections" (when you use the rectangle selection tool with a width of 0 for example).

Gradients

• There does not seem to be any gradient Python class, so the only way is to make direct calls to the PDB.

Colors

• You can easily convert between RGB, HSV, HSL programmatically. You can also easily change these values. However, automatically attempting some operations is rather hard (such as automatically obtaining a darker / lighter version of a color).

• There are no constants for black, white... colors in the Python module.

Help

• You can obtain built-in documentation about the API by using dir (gimp) in the Python Gimp shell. You should import gimpfu first.

• Another way is to use help() on a defined variable, for example a layer.

List of types in Python

• PF_INT8 = PDB_INT8
• PF_INT16 = PDB_INT16
• PF_INT32 = PDB_INT32
• PF_INT = PF_INT32
• PF_FLOAT = PDB_FLOAT
• PF_STRING = PDB_STRING
• PF_VALUE = PF_STRING
• PF_COLOR = PDB_COLOR
• PF_COLOUR = PF_COLOR
• PF_REGION = PDB_REGION
• PF_DISPLAY = PDB_DISPLAY
• PF_IMAGE = PDB_IMAGE
• PF_LAYER = PDB_LAYER
• PF_CHANNEL = PDB_CHANNEL
• PF_DRAWABLE = PDB_DRAWABLE
• PF_VECTORS = PDB_VECTORS
• PF_TOGGLE = 1000
• PF_BOOL = PF_TOGGLE
• PF_SLIDER = 1001
• PF_SPINNER = 1002
• PF_ADJUSTMENT = PF_SPINNER
• PF_FONT = 1003
• PF_FILE = 1004
• PF_BRUSH = 1005
• PF_PATTERN = 1006
• PF_GRADIENT = 1007
• PF_RADIO = 1008
• PF_TEXT = 1009
• PF_PALETTE = 1010
• PF_FILENAME = 1011
• PF_DIRNAME = 1012

Obsolete:

• #PF_INT8ARRAY = PDB_INT8ARRAY
• #PF_INT16ARRAY = PDB_INT16ARRAY
• #PF_INT32ARRAY = PDB_INT32ARRAY
• #PF_INTARRAY = PF_INT32ARRAY
• #PF_FLOATARRAY = PDB_FLOATARRAY
• #PF_STRINGARRAY = PDB_STRINGARRAY
• #PF_SELECTION = PDB_SELECTION
• #PF_BOUNDARY = PDB_BOUNDARY
• #PF_PATH = PDB_PATH
• #PF_STATUS = PDB_STATUS

• Note that you cannot currently pass an array to a Python Gimp script, since PF_STRINGARRAY has been removed (see this bug for reference). One workaround is to pass a string with special separators (like slashes), and split it into an array inside the Python code.

Launching GIMP from outside

• When loading GIMP with gimp-console for example, it will load an interpreter (the default is the Script-Fu one - but you can change that to the Python one if you want). This interpreter will then execute commands given to it (via the -b command line option for example).

• If you call Gimp from Java (via an external process), don't surround the Script-fu commands with single quotes. These are only needed if you launch Gimp from the shell, so that Gimp knows it's a string. If you use them in Java, it won't work since you will pass a string to script-fu rather than a command (Bash did not act the same way).

• You can change the base directory of Gimp (for settings, tile cache, plugins etc) by setting the environment variable GIMP2_DIRECTORY. This is very useful as it allows you to run Gimp when the user does not have a home directory (for example the Tomcat user). In Java there is an convenient way to set the environment variables for running a native process.

• gimp-console has a --verbose option which can be useful.

• Passing very long strings (eg, XML format strings) to the Python environment in Gimp won't work: there seems to be a limit to the number of characters you may send. The obvious workaround is to pass the path to a file and read the file within Python.