Show Your Colors

As the third correction of raw images, I often adjust the white balance. If a digital photo does not exhaust the full range of possible pixel values from 0 to 255 for each of the three channels (red, green, blue), images often lack vibrancy and appear flat (Figure 4).

Figure 4: Before the white balance correction, the histogram shows narrowly distributed values and the image appears flat.

If you prefer brighter colors and higher contrast, you can fire up a useful tool in Gimp under Colors | Auto | White Balance; this adjusts the pixel values of the three channels so that their distribution in the histogram covers the entire intensity bandwidth. This doesn't always look good, but it sometimes gives boring pictures the necessary pizzazz (Figure 5).

Figure 5: White balance makes the histogram wider and the image more vivid.

However, my initial search for the corresponding Gimp function in the Procedure Browser and in the Plugin Browser was unsuccessful. But luckily, Gimp's source code on GitHub is visible to everyone (Figure 6), and a short search for the Automatic white balance string in the repository showed that the corresponding Gimp procedure goes by the name of drawable_levels_stretch().

Figure 6: A look at the Gimp source code on GitHub reveals that the function for white balance is called drawable_levels_stretch.

This function is again documented in the Procedure Browser and only requires the drawable of the image as a parameter. I quickly added the call at line 26 of Listing 2, and it became part of the image processing process.

One Step Forward, One Step Back

Gimp naturally treats the three actions of scaling, sharpening, and color correction of the image as three separate actions. If a user changes their mind afterwards and clicks on the Undo menu entry, they would have to do this three times in a row, which is annoying, because they actually only initiated a single combined action via a mouse click in the menu. The solution is to call gimp_image_undo_group_start() in line 10 and the corresponding ..._end() in line 28.

They define all three intermediate actions as a single undo unit, so that Gimp will roll them back atomically, just like it will roll them forward as one step when asked to do so. Figure 7 shows that even Gimp's Edit menu now shows the last action not as the white balance (which was last to run), but as Sharpen and Scale, which is the name of the combined action we used in the plugin code for the whole enchilada to happen in one go.

Figure 7: Thanks to undo_group_start() and ...end(), Gimp can reverse the actions in one go.

I hope this issue's examples have shown that Gimp's Python API has access to all internal functions and that it is easy to bundle workflows consisting of many small steps, attach them to a menu and run them in one fell swoop. This eliminates drudgery for the user, saves time, and eliminates errors humans inevitably make.

The Author

Mike Schilli works as a software engineer in the San Francisco Bay area, California. Each month in his column, which has been running since 1997, he researches practical applications of various programming languages. If you email him at mailto:mschilli@perlmeister.com he will gladly answer any questions.