Tegan's Tech Talk - GIMP Scripting Part Two

This is the continuation of me learning how to batch script in GIMP. Most of my readers aren't going to have any interest in this, it's mostly for my own edification, and possibly to help someone else who is looking for information via a search engine and stumbles on this. In the first part, I explained my quest. In this part, I explain my script-fu.

The easiest way for me to look at my script is to present the script as it finally ended up, then dissect it. So here's my final script:

(define (script-fu-mylevels infile outfile)
(let* ((img (car (gimp-file-load 1 infile infile)))
(drawable (car (gimp-image-get-active-drawable img))))

(gimp-levels drawable 0 25 225 1.0 0 255)

(gimp-file-save 1 img drawable outfile outfile)))

(script-fu-register "script-fu-mylevels"
"/Xtns/Script-Fu/Tools/My Levels"
"My Levels"
"tomcat"
"tomcat"
"2007-05-17"
""
SF-FILENAME "Infile" "infile.bmp"
SF-FILENAME "Outfile" "outfile.bmp")

There are really only two main parts to this. The first starts at "define", and the other starts at "script-fu-register".

You can read about the "script-fu-register" bit on this page. It is a necessary step, but it's just basic script-fu stuff. In short, this section tells GIMP what the script is. It doesn't need much editing in my non-interactive script. By the way, "tomcat" is the guy who helped me figure this whole thing out, thanks Tomcat!

So let's get into the meat of the script, the part that starts with "define". It's easiest to take this apart a section at a time.

This bit:

(script-fu-mylevels infile outfile)

just says "I'm naming this this thing 'script-fu-mylevels' and it accepts two variables, 'infile' and 'outfile'" This is important, infile and outfile are my two main variables. When I run this script, I have to include BOTH for the script to run correctly.

The next two lines load the file and get it ready to edit. Not much I can really say about them, since I don't entirely understand what each bit does. I do know that the "1" in there tells the script to run non-interactive... so it doesn't need any input after it starts running.

The really important bit for me is the next line:

(gimp-levels drawable 0 25 225 1.0 0 255)

There's a menu in GIMP called the Procedure Browser (Xtns->Procedure Browser). Using this tool you can find the script version of every single command available in GIMP.

In my case I wanted to use the levels command, so I did a search in the Procedure Browser for "levels" and found an item called gimp-levels. When you have an item selected in the Procedure Browser, over in the right pane you see the parameters that the item needs. In the case of gimp-levels I was sure it was the right one because the various parameters matched the inputs available on the menu item.

Going through the rest of the line in my script-fu, "drawable" is an internal variable set earlier and refers to the image that's been loaded. The "0" is the channel, if I use "1" it would only affect the red levels, "2" would affect green levels and so on. "25" is the lowest input. When you start the levels item in GIMP it starts at 0, in my script I'm upping it to 25 to increase the dark level in my image. The "225" is similar, it starts as 255, so I'm lowering it to increase the light level in my image. If you know how the levels menu item works, you'll understand this. If you don't... well, just know that those are the only two settings I've changed from default. The next three numbers are just set at the defaults, "1.0", "0" and "255".

Pulling it all together, this line says, "Take the image we loaded, run gimp-levels on it with the following parameters". In reality, very simple. Not so easy to understand for a beginner. This line in the script would change completely depending on what item you use from the Procedure Browser, and what variables need to be set for it.

The last line of my script-fu

(gimp-file-save 1 img drawable outfile outfile)

just tells the computer to save the file, using the variable outfile as the name.

The next step is to take that script-fu and save it as a text file with a .scm extension (mylevels.scm), and put into the scripts directory (in my case C:\Documents and Settings\User\.gimp-2.2\scripts). The next time I load GIMP, this script will be added to the list of scripts I can use.

Whew! So that's the script-fu side of it. Next step is to run this sucker!