Gimp: How To Write a Script-Fu Macro

The Script-Fu Procedure Browser is a fairly intuitive browser that helps to find the function you want, perhaps corresponding to a GIMP menu function without having to resort to reading a manual. It also gives syntax and arguments for each function and a useful search feature.

To open the Script-Fu Procedure Browser, from the GIMP window use the following menu:

"GNU Manipulation Program": Filters -> Script-Fu -> Consule

(This may vary depending on the version of GIMP being used)

Once you know the syntax of the various commands you need you can put them together to form a function that performs the series of operations you require.

Gimp commands can be used directly from the command-line.

Start a Terminal window either from X11 (X11 is Apples version of the X Server and must be installed in order to run GIMP see this article about installing GIMP if you don't have X11) and start gimp using the full path to the gimp executable file, which for an Apple Mac would probably be:

X11 Applications -> Terminal

OR

Macintosh HD -> Applications -> Utilities -> Terminal

(from Linux just open an xterm)

Start gimp in batch-mode either with the full path as below (or just gimp -b if you are using linux)

/Applications/Gimp.app/Contents/Resources/bin/gimp -b -

Then type the Script-Fu commands at the gimp prompt e.g.

> (gimp-image-new 256 256 RGB)
(1)
>(gimp-display-new 1)
(1)

The (1) is the image-id for the new-image, returned by the first function and may not be (1) and is the argument in the second command.

Now you have established the commands you want to use they can be combined into a new function inside a let* statement. e.g. here is an example of creating a new image, passing the image-id to the variable img-id, creating a new layer (lay-id) filling that layer, then displaying the image created:

(define (create-simple-image)
(let* ((img-id (car (gimp-image-new 512 512 RGB)))
(lay-id (car (gimp-layer-new img-id 512 512 RGB-IMAGE "layer-name" 100 NORMAL-MODE))))
(gimp-drawable-fill lay-id BG-IMAGE-FILL)
(gimp-image-add-layer img-id lay-id 0)
(gimp-display-new img-id)
img-id))

the image-id ("img-id") is then returned after the function is run as shown below:

> (create-simple-image)
7

car is the first part of a list, cdr the rest of the list and cadr is the first part of the rest of the list (the same as in the languages Lisp and Skill)

O.K. That's all very well, but not very useful for manipulating photographs. If you have scanned photos from a digital scanner or photos in a digital camera you may want to process them for use on a web-page or emails etc.

Here is an example of function that will read a jpeg file, adjust the levels (gimp-level-stretch automatically adjusts the levels histogram) and change the size of the photo (i.e. change the number of pixels) then writes out a new jpeg file:

(define (photo-shrink width height input output)
(let* ((image (car (file-jpeg-load 1 input output)))
(drawable (car (gimp-image-active-drawable image))))
(gimp-levels-stretch drawable)
(gimp-image-scale image width height)
(file-jpeg-save 1 image drawable output output 0.8 0 1 1 "" 0 1 0 0))
)

alternatively the function (file-jpeg-load ... ) could have been used in the same way to read a TIFF file from a scanner (and other functions exist for other file formats)

This can then be called from the Gimp command-line like this:

> (photo-shrink 100 100 "IMG_0665.JPG" "IMG_0665-z.JPG")

which will read the file "IMG_0665.JPG", fix the exposure and shrink it to 100 x 100 pixels and output the file "IMG_0665-z.JPG"

After writing a function it can then be registered to allow it's use from a GIMP menu, using the script-fu-register function. Alternatively after defining the function on the GIMP command line it can be used repeatedly from the command line or as a batch process (See below)

(script-fu-register
"macro-name" ; Function Name
"macro-name" ; Menu Label
"Do something to a photo..."
"Andy" ; author
"Andy" ; copyright
"2009-11-19" ; date created
"" ; image type that script works on

; Any Other Variables that need to be defined... (need to check documentation for the these options)

)

The scripts should be saved to a text file in directory ~/.gimp-2.6/scripts/ e.g. create-simple-image.scm then run

Script-Fu -> Refresh Scripts

to load the scripts in the scripts directory.