Hue Rotation Using the Gimp

In which we talk a little about scripting in the Gimp, a little about colours and as only as much as is necessary about Scheme.

If you've ever looked at a picture and decided that it would look great with a different palette then you'll see where I'm coming from with this. Think about graphics resources you use in a game. Like a red brick wall. Now suppose you'd rather it was a yellow brick wall. Suppose furthur that you're not really a great artist, but you've got a whole bunch of great graphics resources for free (as in speech, if you mean to republish it).

You can easily move from one part of the colour spectrum to another with a hue rotation. The term comes from the measurement of colour hue in the Hue-Saturation-Value (or HSV) colour model. The hue measurement can be thought of as how far across the rainbow you're going. The colours of the rainbow are arranged in a circle, so the measurement is done in degrees. All a hue rotation does then is to change each replace each colour with the colour that's a given number of degrees away on that circle.

It's not hard to find the hue-stauration tool in the Gimp. It's on the Colour Tools Submenu of the Tools Menu. You can use the tool to do a hue rotation and adjust some other parameters for the selected part of the image. That part is pretty easy. If it was just one red brick wall texture then that's how I'd do it. Suppose that you have to do this operation a lot however. Suppose you have a bunch of red brick walls, maybe ten or twenty variations of the same wall - to keep the game interesting. Now that's not a huge amount of work to do once, but it can be enough to slow a developer down or tempt them to skip it and just use the pictures as they are. That's the point when I decide I need to do a little automation. For a little project like this I want to reduce the chance of making a mistake on one or two graphics and also I want to speed it up from 30 seconds each to 10 seconds each.

The Gimp is my general image editor of choice. I have a love/hate relationship with the Gimp, but it's been getting better ever since I found the tutorial on How to Draw a Straight Line with it (I still feel like some profanity belongs in that tutorial's title). Ever since I first started using the Gimp I've been trying to script it. Somehow the scripting language, Scheme, has never made sense to me. It's not just because Scheme is a functional programming language; I've used Miranda before and I've done things in AutoLisp with a thick manual. Maybe it's that the scheme interpreter that the Gimp uses is SIOD and I couldn't make SIOD work in the Gimp with some general Scheme examples. Of course I never understood the separation back when I started with the Gimp so the impenetrable nature of scripting was just another source of frustration for me. Knowing what I know now, here's a reference for SIOD if you want to know more about it. What I'd really like to see is someone make a shim that lets you write scripts in a more popular language like Javascript.

Anyway, whining aside, I've finally got a simple script to work in the Gimp that helps in the situation described above. The central function that I want to use is gimp-hue-saturation. I experimented by bringning up the SIOD command line interpreter and trying some commands. You can call this function directly from the Scheme command line interpreter. Get the interpreter window from the menu "Xtns ⇒ Script-Fu ⇒ Script-Fu Console". Then try these commands:

(set! image 1)
(gimp-selection-all image)
(gimp-hue-saturation (car (gimp-image-get-active-drawable image)) 0 20 0 0)

Enter these lines into the SIOD command line one at a time. The only change you need to make is the '1' in the first line. Each image editing window in the Gimp has a number after the title (like 1.0, 2.0 or 17.0). The number increments for each image you have opened. The number is used to access that image in scripts and plugins, kind of like a file handle. So what the three lines in my simple example above do could be rewritten in a non-functional pseudocode as follows:

  1. image = 1
  2. select all of image number image
  3. rotate the hue of the active drawable in image by 20 °
Similar to the way an image has a number available to access it, a drawable has a number that can be used to access it as well. In this case the drawable we're accessing is the selected part of the image. Drawables can be other things too, but I don't know what. The function gimp-image-get-active-drawable takes an image number and provides the selection within that image (as a drawable). We selected the entire image with the gimp-selection-all function. The car wrapper gets the first element of a list. Everything that comes from the Gimp's API functions is returned as a list, in this case a list of just one item.

In the interest of brevity (this has gone on way longer than I thought it would), here's the rest of my simple script:

(define (script-fu-hue-rotate image )
(gimp-selection-all image)
(gimp-hue-saturation (car (gimp-image-get-active-drawable image)) 0 20 0 0)

This script defines a function script-fu-hue-rotate which takes a parameter image(of course this is the image number as described earlier). If you copy all this and paste it into SIOD, you'll be able to call the function from the console for each of your images. There are other ways to accelerate this further with the Gimp's batch processing mode. Another choice is to register the function on the Script-Fu menu. There are lots of places that explain how to register this function on a menu like other Script-Fu tools. I might come back to this one day and explain it as well, but not right now.

One more caveat: this won't work as-is with an indexed palette such as those in a GIF image. For that you'll need to call (gimp-image-convert-rgb image) before doing the hue rotation, and (gimp-image-convert-indexed image 0 0 256 0 0 "") (or some variation - and watch those quotes when copying and pasting) to convert it back.

I hope I've clarified scripting the Gimp more than I've confused it for you. Good luck.

Your rating: None Average: 3.3 (4 votes)

[...] This tutorial explains how to change the palette of an image, and goes over scripting it too! Oooer! Scheme? ugh! Related Stories (hue, rotation, using, gimp) [...]

[...] While we’re on the subject of the Gimp, here’s a clever idea: put it on a memory stick. These are Windows instructions, anyone care to follow up with a Linux version? [...]

[...] I’ve learned piles of scripting languages for the purposes of automating different steps of the software I build, but I’ve only started in the last few years to do the same thing for some art resources. Working in a scripted way with graphics is a lot tougher than scripting manipulations of text and numeric data though. While the Max Script and MEL will be mostly new to me, I’ve found that ImageMagick can be great both on the command line and as a tool for ActiveX-aware languages. I’ve also had some success with building graphics in SVG then using Apache Batik in a batch file to make raster output when needed. In the Gimp, Scheme has been a stumbling block, but I have done one snippet for the Gimp with Script-Fu on hue rotation. [...]