[Top] [Prev] [Next] [Bottom]

Writing a Script Fu

A Scheme Tutorial for Gimp Users: Athour Dov Grobgeld; Copyright 1997 by Dov Grobgeld License GPL.

Introduction

One of the wonderful features of GIMP is that it all its functionality may be accessed through scripting. The major scripting language for the GIMP that has been attached to it today is Scheme. This document will try to be a brief introduction to Scheme, just teaching the essentials in order to write script-fu scripts, without getting into the programming language theory that is so typical of other Scheme references.

Expressions

Scheme is a lisp variants and all expressions are surrounded by parens. E.g. a list which will calculate the sum of 3 and 4 is written

The + sign is the addition function and 3 and 4 are the first and second parameters to this function. Expressions may be nested, so the expression (3+4)*(5/6) would in Scheme be written

White space has no importance so the above expression may as well be written:

Functions

Aside from the four arithmetic functions that are represented through the symbol + - * / there are lots of other functions built into the language. All of them have the form

Additional functions may be defined by the user through the define keyword. E.g. a function that calculates the square value of its single argument may be declared like this

and this function may be called through

Variables and lists

Variables may be declared and set through the set! command. (These variables will be global but this should not bother the casual gimp programmer). Here are a couple of assignments:

Lisp and its variants make heavy use of lists. Script-fu is no exception and it uses e.g. a list of three elements to write a RGB color. E.g. the color orange would be written

The ' sign is necessary in order to tell scheme that this is a literal list. If the ' was omitted scheme would try to look up a function with the name 255 and send it the two parameters 127 and 0, which is obviously not what we wants.

To create a variable called orange with the above value and then set the background color to it we may do

car, cdr and friends (*)

A list in Scheme is always composed of a head and a tail. The head is the first entry in the list, and the tail is the list of the rest of the elements. This means that the list (255 127 63) really means (255 (127 (63 ()))) but Scheme allows the previous form as a shortcut. The car function is used to return the head of the list and the cdr (usually pronounced cudder) is used to get the tail of the list.

[The following is a test of the above functions which may interactively be conducted in the Script-Fu console.]

To get the blue component of a color it is necessary to apply the cdr function twice and then the car function.

This is very unconvenient to write. Therefore there have been defined abreviations of the form cadr, cddr, caddr, etc that concatinate the operations described above. The previous expression may therefore much more conveniently be written:

For the Script-Fu writer one of the most important uses of the car function is to access the returned values from the built-in gimp functions. All gimp-functions return a list, and even if the list contains only one element it must be accessed by car. This is e.g. the case for the important functions gimp-new-image and gimp-new-layer used below.

Local variables (*)

More experienced scheme programmers mostly use local variables instead of the global variables described above. This is considered better programming practice and this construct should be recognized in order to be able to read others ScriptFu scripts.

Local variables are declared through the the let keyword as in the following example:

The GIMP PDB

All functionality of GIMP is available through the procedural database (PDB). Each procedural database function has a corresponding scheme function mapping. E.g.

produces a new gimp image of type RGB and size 100x150.

In version 0.99.12 was included a browser for all the functions in the PDB. This browser is available from the main menu through Xtns>DB BROWSER. E.g. the DB Browser screen for uni-img, which we will define in the example below looks like this:

For the scheme progammer this information shows that uni-img may be called with three parameters of the types INT32, STRING and COLOR. The different types will be explained below.

Registering the script with Script-Fu

After a function has been written it has to be registered with script-fu before it can be used. This is done through the scheme function script-fu-register. The registering has following purposes:

1.Choose the place of the script in the Script-Fu pulldown menus. 
2.Tell script-fu the type of parameters the script takes and give 
these parameters default values. 
3.Register the script as a command in the PDB.

The last point above actually means that a script is from Gimp's viewpoint in no way different from a built-in command or a plugin command. As long as a command is registered in the PDB it can be called by any script or plugin.

The parameters of script-fu-register may be divided into two groups. The first group of seven parameters must always be given. These are:

1.The name of the lisp function. 
2.The position of the script in the gimp menus.
3.A help string describing the function of the script. 
4.The script author
5.The script copyright. 
6.Script date. 
7.List of valid image types for the script. This only has a meaning on 
scripts operating on images that already exist. 

After these seven parameters have been given, follows a list of the parameters required by the script. Each parameter is given as a group of three items:

1.The type of the parameter. Valid types are 
            SF-COLOR 
                  An RGB color. 
            SF-TOGGLE 
                  A true or false value. 
            SF-IMAGE 
            SF-DRAWABLE 
            SF-VALUE 
                  Any scalar value, string, integer, or floating point. 
2.A label for script-fu to display when querying for the parameter.
3.A default value. 

A commented scrip

The following script uni.scm receives two parameter from the user, the size of the image, and a color and goes on to produce a uniform image of the requested size and the requested color. Not very useful, but it shows the essential steps in producing a script-fu script.

; Define the function of the script and list its parameters
        ; The parameters will be matched with the parameters listed
        ; below in script-fu-register.
        (define (uni-img size color)
          ; Create an img and a layer
          (set! img (car (gimp-image-new size size RGB)))
          (set! layer (car (gimp-layer-new img size size RGB "layer 
1" 100 NORMAL)))

          ; The following is done for all scripts
          (gimp-image-disable-undo img)
          (gimp-image-add-layer img layer 0)

          ; Here is where the painting starts. We now have an image
          ; and layer and may paint in the layer through the PDB 
functions.
          (gimp-palette-set-background color)
          (gimp-edit-fill img layer)

          ; The following is also done for all script
          (gimp-display-new img)
          (gimp-image-enable-undo img)))

          ; Finally register our script with script-fu. 
          (script-fu-register "uni-img" 
                              "/Xtns/Script-Fu/Tutorials/Uniform image"
                              "Creates a uniform image"
                              "Dov Grobgeld"
                              "Dov Grobgeld"
                              "1997"
                              "" 
                              SF-VALUE "size" "100"
                              SF-COLOR "color" '(255 127 0)))

It is also possible to access this script through the Script-Fu console by typing the command

Painting areas with selections

In uni-img we called the procedure gimp-edit-fill to fill the whole image. Looking at the info for gimp-edit-fill in the DB browser we find the following:

A simple use of this function which selects the rectangle (x,y,width,height)=(0,25,100,50), paints this region blue, and releases the selection looks as follows:

Loops

TBD...

Floating selections

TBD...