Glimmer Labs Presents . . .
Script Fu for Schemers

Generating GIMP Images with Script-Fu

Summary: In this laboratory, you will begin to investigate the ways in which you can use Scheme to program the GNU Image Manipulation Program. Because you will often be nesting procedures within other procedures, is important to keep in mind what your procedures are returning, and what you are giving procedures as arguments.

• Exercises
  • Exercise 0: Getting Started
  • Exercise 1: Drawing Your First Images
  • Exercise 2: Experimenting With Variations
  • Exercise 3: Designing Your Own Images
  • Exercise 4: Other Procedures
  • Exercise 5: Unpacking gsfu-line

Exercises

Exercise 0: Getting Started

a. Start the GIMP by typing gimp in a terminal window. If you haven't run the GIMP before, you should allow the GIMP to do the normal installation procedure.

b. Select Console from the Script-Fu menu available from under the Xtns menu in the primary GIMP palette. You should see a window appear with some text at the top and an entry box at the bottom. This is the console for interacting with Script-Fu, which is based on a variant of Scheme called SIOD.

c. Type a few, simple, one-line Scheme expressions to see what happens. For example, you might ask for a few simple sums, extract parts of lists, or whatever.

d. I've written a few procedures and defined a few constants that you may find helpful as you work with Script-Fu. You can make a copy (particularly if you're not working in MathLAN).

Load them with

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

Exercise 1: Drawing Your First Images

To create an image in the GIMP, you need to follow a number of steps (perhaps these are steps you'd expect from your own attempts to write instructions for using the GIMP), including creating the image, adding a layer in which to draw, selecting colors, and applying various tools. In this exercise, you'll step through some of the basic commands. Enter each of the commands in the console window.

a. Define the width and height of your new image with

(define width 256)
(define height 384)

b. Create and name your new image with

(define image (car (gimp-image-new width height 0)))

The image will not yet appear. Script-Fu assumes that you may want to do some things with the image before you show it on the screen. You use car because gimp-image-new returns a one-element list consisting of the ID of the image. (No, I don't know why it returns a list; it just does.) The 0 argument tells the GIMP you want it to use the RGB color mode, in which the color of each pixel is stored as three numbers, each ranging from 0 to 255. The first number represents the Red value, the second Green, and the last Blue. Though it may be useful to work with images in other color modes at times, the way we manipulate images with Scheme in these labs depends on using RGB, so we'll just stick with that. You can see the other available color modes from the Script-fu procedure browser.

c. You need layers in order to draw, so now we are going to create that layer.

(define layer (car (gimp-layer-new image width height 0 "Layer" 100 0)))

gimp-layer-new takes a lot of arguments, so here is an explanation of them:

• image, the image to add the layer to. The GIMP uses integers to represent images. You can confirm this by typing (image) into the Script-fu console.
• width, the width of the new layer in pixels. Should probably match your image, so we use the same number we defined earlier.
• height, the height of the new layer.
• type, tells the layer what color mode to use. 0 specifies RGB, which is what we want. Other types are found in the procedure database.
• name, the name for the newly created layer, can be anything you like, as long as you provide it as a string.
• opacity, the opacity of the layer, as a percent. This is a float value, so you can enter a number with a decimal. Opacity ranges from 0% to 100%, and since we want to see our layer, we set it to 100.
• mode, specifies the layer combination mode, which deals with how you see things on overlapping layers. 0 is the default, GIMP_NORMAL_MODE, but other modes and specifiers can be seen in the Procedure Browser.

When the new layer is created, it is not yet a part of image, so we have to add it with

(gimp-image-add-layer image layer 0)

where the 0 specifies the layer position, which we won't worry about for now.

d. We're now ready to show the image. You need only one line.

(gimp-display-new image)

e. You may see that your image already contains some stuff (typically random garbage). That's because Script-Fu allocates some area of memory for your image without bothering to clear out the old contents of that memory.

You can clear your image with a few commands.

(gimp-selection-all image)     ; Select everything
(gimp-edit-clear layer)        ; Do "Clear" from the "Edit" menu
(gimp-selection-none image)    ; Select nothing

In the future, you should probably clear the image before diplaying it.

f. Now you're almost ready to draw. In order to draw, you need a foreground color and a background color.

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

WHITE is a constant value defined in utils.scm, not built in to the GIMP. Be aware of that. The list of three numbers given to gimp-palette-set-foreground is the RGB color mode in action. Your foreground color should now be blue. Remember, RGB mixes like light, not ink, so 0,0,0 is black, while 255,255,255 is white.

g. You also need a brush.

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

h. As some of you discovered on the first day, the simplest drawing technique is to select something and then "stroke" it. If you don't know, "stroking" is telling the GIMP to apply the brush to a selection, cutting out the hassle of drawing freehand with a mouse. We can use that technique to draw a box from Script-fu.

(gimp-rect-select image 10 10 100 100 REPLACE 0 0)
(gimp-edit-stroke layer)
(gimp-selection-none image)

The parameters to gimp-rect-select are

• image, the image to select from;
• left, the x coordinate of the upper-left coordinate of the selection;
• top, the y coordinate (moving down from the top) of the upper-left coordinate of the selection;
• width, the width of the selection;
• height, the height of the selection;
• operation, whether you want to ADD to the current selection, SUBtract from the current selection, or REPLACE the current selection (I recommend you use REPLACE)
• feather, which I recommend you set to 0
• feather-radius, which I recommend you set to 0

i. We can also use that technique to draw a circle in a different color

(gimp-palette-set-foreground (list 255 0 0))
(gimp-ellipse-select image 50 50 80 80 REPLACE 0 0 0)
(gimp-edit-stroke image layer)
(gimp-selection-none image)

The parameters to gimp-ellipse-select are similar to those of gimp-rect-select except that there's an additional antialias parameter that precedes the feather parameter.

j. The other common way to paint things is with one of the brush tools. I've written a simple painting procedure that takes six parameters: the image, the layer, the x coordinate of the starting point, the y coordinate of starting point, the x coordinate of the ending point, and the y coordinate of the ending point.

(gimp-palette-set-foreground (list 0 255 0))  ;Change the color to green
(gsfu-line layer 50 50 200 50)
(gsfu-line layer 200 50 50 200)
(gsfu-line layer 50 200 50 50)

For future reference, the (gsfu-image width height) from the utils.ss file creates an image, creates and adds a layer, clears the image, and displays the results automatically, returning a two-element list consisting of image number and layer number.

Exercise 2: Experimenting With Variations

As you may guess, it is possible to vary most of the drawing commands given in the previous exercise. Clearly, any command that takes parameters that describe locations on the screen can have different locations. In addition, you should be able to change the colors and brushes you use.

a. In the previous exercise, you wrote a command to draw a box. Try varying the numbers used in that command and see what happens.

b. The RGB color mode has already been explained, but it can be fun and educational to try to mix your own colors. Experiment with numeric color variations. You may find it helpful to use the GIMP color picker.

c. To see a list of all GIMP brushes, try

(gimp-brushes-get-list "")

You need the "" because gimp-brushes-get-list expects a string by which to filter brushes. Thus, if you entered "Circle", you would only see a list of brushes with "Circle" in the name. See what brushes there are, and try some out.

Exercise 3: Designing Your Own Images

a. Using the commands that you learned in the previous exercise, tell the GIMP to create a new image in which you use Script-Fu to draw something interesting (perhaps a stick figure, perhaps something more complicated).

b. What advantages, if any, are there to using Script-Fu to create that image?

Exercise 4: Other Procedures

Script-Fu and the GIMP come with an astonishing collection of procedures. You can get a terse list of these procedures by selecting DB Browser from the Xtns menu or by clicking on Browse... in the Script-Fu console.

Spend a few minutes exploring the list.

Exercise 5: Unpacking gsfu-line

Here is the code for gsfu-line, which you used earlier.

(define gsfu-line
  (lambda (image layer x1 y1 x2 y2)
     (gimp-paintbrush image layer 0 4 
                      (float-array x1 y1 x2 y2))))

I wrote gsfu-line and float-array to shield you from the wonders (horrors?) of some of the built-in procedures.

By reading the comments for gimp-paintbrush you should be able to find out better ways of drawing more complex objects.

Use gimp-paintbrush to draw a triangle.

History

Tuesday, 3 April 2001 [Samuel A. Rebelsky]

• Designed.

Wednesday, 4 April 2001 [Samuel A. Rebelsky]

• Written.
• Released.

Thursday, 25 May 2006 [Ian Bone-Rundle]

• Rewritten for updated Script-Fu libraries.
• Added some explanatory text.

Thursday, 1 June 2006 [Samuel A. Rebelsky]

• Minor cleanup.