Automating Image Construction with Script-Fu

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

Procedures Covered:

• (gimp-display-new ...)
• (gimp-image-new width height image-type)
• (gimp-image-add-layer ...)
• (gimp-layer-new image width height ...)

Contents:

• Introduction
• Using Script-Fu
  • The Script-Fu Console
  • Script-Fu Script Files
  • Image and Layer IDs
  • Further Preparation
  • Drawing
• Some Useful Procedures
  • gimp-airbrush
  • gimp-paintbrush
  • gimp-ellipse-select
• Some Useful Links

Introduction

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.

• First, you need to set the foreground and background color. Each of these is set to a list of three values between 0 and 255 (the red component, the green component, and the blue component of the color).

  (gimp-palette-set-background (list 255 255 255))
  (gimp-palette-set-foreground (list 0 0 255))
  

• Next, you need to select a brush to use.

  (gimp-brushes-set-brush "Circle (03)")
  

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

Drawing

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:

• image-id, the id of the image;
• x, the x coordinate of the upper-left corner;
• y, the y coordinate of the upper-left corner;
• width, the width of the rectangle;
• height, the height of the rectangle;
• operation, one of ADD, SUB, REPLACE, and INTERSECT;
• feather, for the purpose of feathering (we'll come back to this later, for now, use 0); and
• feather-radius, for which we'll also use 0.

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.

gimp-airbrush

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

• layer, the id of the layer in which you wish to draw;
• pressure, the pressure of the airbrush (between 0 and 100);
• strokes, two times the number of coordinates for the path; and
• path, an array of values giving the coordinates in the path.

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
               50
               10
               (float-array 10 10 
                            100 10
                            100 100
                            10 100
                            10 10))

gimp-paintbrush

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:

• layer, the layer in that image that really holds the drawing;
• fade_out_distance, how much the paintbrush fades as it moves through the path (when it hits the distance, the pressure is 0);
• strokes, two times the number of coordinates for the path;
• path, an array of values giving the coordinates in the path;
• method, the method by which the paintbrush is placed, either CONTINUOUS or INCREMENTAL; and
• gradiant_length, the length over which the color gradiant is spread (use 0 for no color gradiant).

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)

gimp-ellipse-select

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).

• image, the image
• x, the x coordinate of the upper-left-corner of the rectangle that contains the ellipse
• y, the y coordinate of the upper-left-corner of the rectangle that contains the ellipse
• width, the width of that rectangle
• height, the height of that rectangle
• selection, the way in which the area should be selected. I typically use REPLACE (this is a new selection), but you can also use ADD (select additional area), SUB (select less), and INTERSECT (select intersection).
• antialias, 0 for off, 1 for on; I tend to leave this as 0
• feather, which I suggest you leave at 0
• feather-radius, which I suggest you leave at 0

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.