This tutorial was originally hosted at gimptalk.com/gimpdome.com. Gimpdome is now gone and the image links are broken at gimptalk (I'll fix those later), but I wanted to post the tutorial here. Some of the information I provide is probably dated because it was prepared for use with GIMP version 2.6. It's been a LONG time since I've done any scripting and I don't know what those errors are, but I will correct them as I find them. Due to time limitations, I probably won't be updating this tutorial again, so I leave it in your hands.
I would like to specifically thank saulgoode and Fatal Edge for spending some of their time to assist me with my scripting questions. I try to learn as much on my own as possible, but in this case, I really couldn't have gotten off to a good start without their assistance. So, "Thanks, Guys!"
As a way of giving back, I wanted to show you how I started out in scripting using GIMP's Procedure Browser and the Script-Fu Console to create a simple image. This tutorial is very similar to some you may have seen around the web. I'm not trying to rip theirs off, but those are a bit dated and there have been major improvements to the Procedure Browser and Script-Fu Console since those were prepared. Later, in a future tutorial, we will build upon this information to create actual scripts that will run from GIMP's main window and from within an open image window.
Disclaimer: This is a beginner tutorial written by a beginner. I am very new to scripting and can only share the basics. I won't be covering the Scheme language, which is one of several languages that you can use to create GIMP scripts. I probably will make several errors in the way I describe things, simply because I don't know the correct terminology nor all the ins-and-outs of programming. So, in that regard, I hope you will forgive me. Hopefully, my descriptions will be helpful enough to you to start creating your own scripts and let you experience GIMP at a greater level.
Let's begin!
1. The Script-Fu ConsoleThe Script-Fu Console will allow us to directly enter the commands (aka Procedures) to return results. It is here that we will instruct GIMP to create the new image. To access the Script-Fu Console, go to the GIMP main window and select the Xtns Menu > Script-Fu > Script-Fu Console
and the following window will appear:
You will notice the "Browse" Button on the Script-Fu Console, click it to open up the Procedure Browser. Keep the Script-Fu Console Window open, as we will be using it frequently.
2. The Procedure BrowserThe GIMP Procedure Browser is an interface that allows us to see behind the GIMP curtain and look at the various Procedures we use everytime we work with GIMP and what information we need to provide if we are going to utilize the Procedures in the way of scripting. Another way to access the Procedure Browser, go the GIMP main window and select the Help Menu > Procedure Browser:
and the following window will appear:
Notice the "Apply" Button at the bottom of the Procedure Browser. This will come in handy real soon. Keep the Procedure Browser Window open, as we will be using it frequently.
3. How do we tell GIMP to create an image?In order for us to create an image, we need to step back and ponder what's really going on.
1. We need an image (or a container for our layers, channels, paths, etc.). What do need to know about our image? Dimensions would be important and type (RGB, grayscale, indexed).
2. Next, in this example, we need a layer so we can add stuff. What might be important about layers? How about dimensions, opacity, blend modes, etc. (we will cover the other items in just a few minutes, but be thinking about it!)
3. We've created our image and a layer, but what's in the layer right now? Nothing yet. We've got to tell GIMP to add something to it. In our case, we will fill it with color. But, we've got to tell the Script-Fu Console how to do it.
4. If we create our image and add a layer to it will it automatically show up on the screen? Well, if we're doing from the GIMP interface, the answer is "yes", but from the Script-Fu Console, the answer is "no". We have to tell GIMP to show us the results.
So, this is what we will do in the next few minutes. There will actually be a few more steps we'll be doing to accomplish our goal and we won't be doing them in the exact order described above, but I promise this will be painless! Now, with the background out of the way, let's start the process of creating an image from the Script-Fu Console and Procedure Browser.
Since the first thing we need to do is to create an image, go to your Procedure Browser (from here on out called PB), and type the word "image" in the Search box, see the attached screenshot below for reference.
Now, scroll down until you come to the Procedure called "gimp-image-new" (quotes added by me). In the right-hand part of the window, you'll see some VERY important information that we need to know and use. You'll see that "gimp-image-new" creates a new image with the specified width, height, type. (ie... 200 X 200 RGB, etc.).
Under the Parameters section, you'll see width, height, and type. The Parameters are what GIMP expects you to fill in. If you don't fill them in or fill them in incorrectly, you'll get an error.
Under the Return Values section you'll see that if we give GIMP the correct information, GIMP will return a new display (remember, it will be behind the scenes until we tell the Script-Fu Console to show it to us).
The Additional Information section also gives us some very useful information. I won't cover it here, but you need to be aware of it and read it for each Procedure.
4. Let's create an image!Click on the "Apply" Button at the bottom of the PB window. This will paste the Procedure and the required parameters into the Script-Fu Console like so:
Notice that the cursor is also positioned in the correct location. This is a very NICE feature!
Now, we need to fill in the required Parameters before we do anything else. Remember when I said we had parameters that we need to include? Well, this is where we will enter them. In this example, we're going to create an image that is 200 pixels wide, 200 pixels high, and the type RGB. The PB tells us that our Parameters for this Procedure need to be in the following order width, height, type. Also, the SFC expects everything to be surrounded by parenthesis.
So, to create a 200 X 200 RGB image, we need to modify the statement we just pasted into the SFC to look like this:
(gimp-image-new 200 200 RGB) Put in a space between the “gimp-image-new” part and each of the parameters. Here's a screenshot of how the SFC input line should now look:
Next, hit the enter key and the SFC will return something like this (If you get an error, you typed something incorrectly and it needs to be re-entered):
Don't worry if your value is different, but write it down on a sheet of paper as the image ID....we'll be using it frequently! Remember earlier when I said that if we entered our Parameters correctly, GIMP will return a something? Well, the number that was returned in the above screenshot is the number GIMP has assigned to our new image....in my case, it's 2.
As I said, remember the number that the SFC gave to you, we'll need it in a minute. Before we continue, I want to add that I won’t be covering every little thing in detail like I did above. Everything we just did will be similar from here on out. I’ll be telling you what to type and what to expect, but there’s no need to address the steps in such detail. You’ll see! I promise!
5. Let’s Create a LayerWe have our image, but we need to create a layer to place in the image. To do that go back to the PB and type in layer as we did above for the image and scroll down until you get to “gimp-layer-new”. Under the parameters section, you’ll note that we have 7 items to specify to GIMP.
As we did for creating the image, copy and paste the “gimp-layer-new” into the SFC by clicking the "Apply" Button:
Here’s what’s happening:
The gimp-create-layer procedure is expecting 7 Parameters to be identified. The Parameters are as follows:
Image ID - That was given to us in when we created the image
Width -That’s how wide we want our layer. A layer can be larger or smaller than the image dimensions, but I’ll make mine equal to it.
Height - Same information as the width.
Type - The layer type
Name - This is the name that GIMP will add to the layer. Since it is a name (aka String) we need to enclose this information in quotes as shown.
Opacity - The layer’s opacity level.
Mode - The layer’s blend mode.
Here's what I have:
If you’re following along with me, the next thing you should do is fill in the information as shown, but replace my Image ID (which is “2”) with the one the SFC gave you. Make sure you put RGBA-IMAGE and NORMAL-MODE in all caps and separated by a hypen. Also, give the layer a unique name, but make sure you enclose it in quotes (remember, it's a string). Once you’re finished with that, hit the Enter key and, if you did everything correctly, the SFC will return another value as shown. This is the value assigned to our new layer. Write that number down, as we will need it later. Here’s the screenshot of my output from the SFC, my layer ID is “8”.
6. Getting the Layer into the ImageWe’ve created a layer, but it’s just a layer floating around in GIMP’s memory. We need to add it to the image. Go back to the PB and type in “add” and choose the Procedure “gimp-image-add-layer”
Again, you’ll see that this Procedure needs 3 parameters: the image ID, the layer ID, and the layer position. Well, we already know the image ID, and the layer ID, but we need to give it a position. That’s easy enough! As before, click the "Apply" Button to copy and paste the “gimp-image-add-layer” Procedure into the SFC:
Fill it in with the required Parameters (remember the order: image ID, layer ID, position). For me it’s (gimp-image-add-layer 2 8 0) 2 is my image ID, 8 is my layer ID and 0 (zero) is the first (uppermost) position. You substitute your image/layer ID’s, but keep the position as 0. Here's what I have:
Hit the enter key and, if you’ve done everything correctly, the following should appear:
If I correctly understand what I’ve read about scripting, the result “(#t)” means “TRUE”, which means GIMP has accepted your instruction and there are no errors. Plus, in this case, it means the layer has been added to our image.
When can I see this “so-called” image?Well, we’ve gone through these steps and I’m pretty sure you’re wondering if I’m making this up or if something really does exist. I know, I know….you want proof! Here’s your proof….Go back to the PB and type in “display” and scroll down to “gimp-display-new”. This Procedure requires one parameter, the Image ID.
Click the "Apply" Button to copy the Procedure from the PB and paste it into the SFC as before.
Then, as before, add the Image ID. My image ID is 2. Here's what my completed Procedure looks like: (gimp-display-new 2)….you substitute your image ID in place of 2.
Hit the Enter key and the following should appear:
Your image may be made up of a bunch of random colors, mine just so happens to be mostly transparent. The reason for this is that we've told GIMP to create a layer and to add it to the image, but up til now, we haven't filled it in with anything. So, GIMP fills it with random colors until it's instructed otherwise. If you want (I won't be covering this step, as we will be fixing it in the next step), you could type in the SFC: (gimp-edit-clear drawable) in my case it would be (gimp-edit-clear 8) to clear the contents of the layer. Also, look at your layer name to see if the name you gave it when we created the layer is there.
7. Transparent is good, but what about some color?Easy enough. Let’s change the foreground color and then fill our layer with the new foreground color. Go back to the PB and type in the word “Context”. Context Procedures set the “defaults” in GIMP. You could also type in “Foreground”. Choose the Procedure called "gimp-context-set-foreground".
You’ll notice that the Procedure expects one Parameter: a color. To fill in this parameter, we must do something a little different in the SFC. So, copy and paste the Procedure from the PB by clicking the "Apply" Button.
Now, to fill it with a color we need a
single value that’s made up of red (R), green (G), and blue (B). This single value is really made up of a list of 3 values (R, G, and B). To represent a list in the SFC, we use a single quote mark in front of a list of values, which are enclosed in parenthesis. So, here’s what the list will look like: ‘(R G B) I want to make our layer blue. Blue is represented in RGB fashion like so: 000 000 255. Substituting that into our list “template” above, we get: ‘(000 000 255) - GIMP will read this list as a single value. Now, combine it with our Procedure, you’ll get the following: (gimp-context-set-foreground ‘(000 000 255)) - Make sure you have the parenthesis correctly or you’ll get an error.
Hit the enter key and you should get this in the SFC:
But, more importantly, your foreground color swatch on the main GIMP window should now be blue. Is it?
We’re nearing the homestretch now! Let’s fill our layer with the foreground color. Go to the PB and type in fill and choose the “gimp-drawable-fill” Procedure.
This Procedure needs two Parameters: a drawable (which can be a layer, channel, mask, etc.) and a fill-type. Click the "Apply" Button to copy and paste the Procedure into the SFC.
Then add your layer ID for the drawable Parameter (mine is "8") and the fill type (use FOREGROUND-FILL and make sure it’s in all caps). The result should be like this:
Hit the Enter key and your image should now look like this:
and here’s what my layer dialog looks like showing my layer name:
We’re finished! Save your image, delete it, or do whatever you want with it. But, that's as far as we take it today. Try experimenting with the various Parameters or maybe even try out new Procedures. I know that this tutorial was pretty lengthy and I hope I helped and didn’t intimidate, overwhelm, or create more confusion. The next step of our scripting journey will take us from the PB/SFC to actually creating scripts with this information.
Let me know if you have any questions or need clarification. Please remember that I’m really new to this and complex questions are beyond my current scope of knowledge. With that, I thank you for reading….Happy GIMP’ing!
Art