GIMP Script Fu Templates

I have spent the last couple of days hacking on The GIMP's scripting engine. It's a bit tricky to pick up, since the developers of GIMP chose to use Scheme (a Lisp variant) as their scripting language. That didn't bother me too much. However, their documentation on scripting isn't that great. This post is to hopefully help some poor soul who has to write their own GIMP scripts.

There are two kingdoms of scripts for The GIMP: standalone and image-dependent. A standalone script starts with no image, collects some user parameters (or not), and is expected to produce a new image. An image-dependent script requires an open image to process, collects some user parameters (or not), and is expected to modify the selected layer.

A bare-bones standalone script looks like the following:

(define
 (script-fu-template-standalone)
 (let*
  (
   (image (car (gimp-image-new 256 256 RGB)))
  )
  
  (gimp-context-push)
  (gimp-image-undo-disable image)
  
  ; Implementation goes here
  
  (gimp-image-undo-enable image)
  (gimp-context-pop)
  
  (gimp-image-clean-all image)
  (gimp-display-new image)
 )
)

(script-fu-register
 "script-fu-template-standalone"
 "MENU LABEL"
 "DESCRIPTION"
 "AUTHOR"
 "COPYRIGHT"
 "CREATION DATE"
 "" ; empty string because script creates a new image
)

(script-fu-menu-register
 "script-fu-template-standalone"
 "<Image>/File/Create/GROUPING"
)

A bare-bones image-dependent script looks like the following:

(define
 (script-fu-template-image-dependent image layer)
 (let* ()
  (gimp-context-push)
  (gimp-undo-push-group-start image)
  
  ; Implementation goes here ;
  
  (gimp-undo-push-group-end image)
  (gimp-context-pop)

  (gimp-displays-flush)
 )
)

(script-fu-register
 "script-fu-template-image-dependent"
 "MENU LABEL"
 "DESCRIPTION"
 "AUTHOR"
 "COPYRIGHT"
 "CREATION DATE"
 "RGB*"

 SF-IMAGE      "Image"             0
 SF-DRAWABLE   "Drawable"          0 
)

(script-fu-menu-register
 "script-fu-template-image-dependent"
 "<Image>/Filters/GROUPING"
)

Additional parameters can be passed into the end of the script-fu-register function call. If you do so, you also need to declare them in the definition of your script method. A list of parameter types can be found here.

The GIMP has a handy command to list all available scripting functions under its 'Help -> Procedure Browser' menu. It will even list any custom scripts you have created, so be sure to fill in the description, author, copyright, and creation date strings.

During development of your scripts, when you are frequently making changes, you will need to run the 'Filters -> Script-Fu -> Refresh Scripts' menu command. This will cause The GIMP to grab your latest changes so that the next time you run your script it will be running the latest version.

Happy scripting!