Fundamentals of Computer Science 1 (CS151 2003S)

Automating Image Construction with Script-Fu

Summary: We investigate Script-Fu, the programming language used within the Gimp.

Procedures Covered:



As you've seen, the Gimp provides a fairly comprehensive set of image manipulation tools, similar to those you might find in Photoshop or other modern graphics program. However, the Gimp also has a special aspect that sets it apart, and which makes it an appropriate topic for the course: the Gimp has a built-in programming language, based on Scheme, called Script-Fu.

Script-Fu is much like the Scheme you've encountered in DrScheme. However, it has some key differences which we discuss later. For now, you should note that some things will go seriously wrong and Script-Fu is not very friendly when errors occur.

Using Script-Fu

There are a variety of ways to use Script-Fu, just as there are a variety of ways to use DrScheme.

The Script-Fu Console

The simplest way to use Script-Fu in the Gimp is to enter one-line Scheme commands in what is called the Script-Fu Console. You can bring up the console by selecting Console from the Script-Fu menu available from under the Xtns menu in the primary Gimp palette.

Once the console is up, you type commands into it just like you type commands into the interaction pane in DrScheme.

Script-Fu Script Files

Another alternative is to create a script and save it in a file. You can then load that file into DrScheme, either by changing the Script-Fu initialization file or by typing

(load "filename")

in the Script-Fu console.

For now, you should load my set of Script-Fu utilities, using the amazingly long command

(load "/home/rebelsky/Web/Glimmer/ScriptFu/Code/gsfu.scm")

You'll also use this technique of creating a file and then loading it when you write your own procedures for Script-fu. That's how you'll generally create your own procedures. We'll return to this technique in a later reading and lab.

Image and Layer IDs

Most Script-Fu drawing commands take an image id or a layer id as a parameter. Each of these is an integer. These integers typically start with 1. You can get the values of various images or layers with various commands. The simplest such command is the one for creating images, (gimp-image-new width height RGB), which creates a new image and returns a list containing only the id of the image. (Yes, a one-element list is silly, but all Script-Fu commands return lists.) You should always use the constant RGB as the last parameter.

You can also get the list of ids of the current images with (gimp-image-list). However, the list of ids is not presented in a readily usable form. You can look at it to see the list of ids, but you can't easily write Scheme code to get them immediately.

Once you have the id of an image, you can get the id of all the layers in the image with (gimp-image-get-layers image-id). Once again, the return value is somewhat puzzling. You can also get get a list containing the id of the active layer with (gimp-image-get-active-layer image-id).

Further Preparation

Once you've created an image and layer (or extracted the image and layer), you need to set all sorts of details before you can draw.

Note that you can also do these steps manually, rather than typing the Script-Fu for them.


Finally, you're ready to draw with Script-Fu. The easiest way to do so is by selecting an area of the image and then stroking it. The gimp-rect-select procedure takes an astounding number of parameters:

You can then stroke the selection in a specified layer with (gimp-edit-stroke layer-id).

Some Useful Procedures

You can find an amazingly long list of available procedures by selecting DB Browser ... from under the Xtns menu. Here are some you may find particularly useful.


The gimp-airbrush procedure draws an image using the current airbrush. It takes four parameters:

You can use float-array (one of my utilities) to create the array of floats.

For example, here is some code to draw a square.

(gimp-airbrush image layer
               (float-array 10 10 
                            100 10
                            100 100
                            10 100
                            10 10))


The gimp-paintbrush procedure traces a path using the current paintbrush. You can set the current paintbrush with (gimp-brushes-set-brush brushname). You can get a list of brushes with (gimp-brushes-list).

The gimp-paintbrush procedure takes six parameters:

Here is some fairly simple paintbrush code.

(gimp-palette-set-foreground BLUE)
(gimp-brushes-set-brush "Diagonal Star (11)")
(gimp-paintbrush layer 180 6 
  (float-array 10 10 200 200 100 20) CONTINUOUS 0)
(gimp-palette-set-foreground BLUE)
(gimp-brushes-set-brush "Circle Fuzzy (05)")
(gimp-paintbrush layer 0 4
  (float-array 10 10 100 200) CONTINUOUS 0)


The gimp-ellipse-select procedure selects an elliptical region. You can then stroke, fill, or do something else with that region. There are a surprising number of parameters: Note that you specify ellipses in terms of the rectangles that they fit within (if you draw a picture, it will all make sense).

Some Useful Links

Mike Terry's Black Belt School of Script-Fu. Assumes that you have never programmed in Scheme before. Uses all sorts of things that real Schemers may scream at. However, this seems to be the closest thing out there to an official tutorial.



Wednesday, 3 April 2001 [Samuel A. Rebelsky]

Thursday, 23 October 2002 [Samuel A. Rebelsky]

Sunday, 30 March 2003 [Samuel A. Rebelsky]

Monday, 31 March 2003 [Samuel A. Rebelsky]


Disclaimer: I usually create these pages on the fly, which means that I rarely proofread them and they may contain bad grammar and incorrect details. It also means that I tend to update them regularly (see the history for more details). Feel free to contact me with any suggestions for changes.

This document was generated by Siteweaver on Tue May 6 09:31:06 2003.
The source to the document was last modified on Mon Mar 31 13:43:25 2003.
This document may be found at

You may wish to validate this document's HTML ; Valid CSS! ; Check with Bobby

Samuel A. Rebelsky,