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!" I appreciate it very much. I would especially like to thank Fatal Edge for his suggestion on a better way to use the Script-Fu Console and Procedure Browser to get Procedures into the Console. This was an excellent suggestion that I didn't know about and his suggestions have been incorporated herein. Thank you!

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.

Also, the gimpdome.com forum (where this tutorial was first posted) automatically resizes images that are posted above a certain size. I'm not sure if GT will do this too, but if it does, to view the image in full-size, best quality, Firefox users can right-click on the image and choose View Image. I *believe* IE users can just click on the image and a full-size image will open in a new window. Not sure about IE, but I've read that works.

Let's begin!

The Script-Fu Console

The 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. (Thanks, Fatal Edge!)

Keep the Script-Fu Console Window open, as we will be using it frequently.

The Procedure Browser

The 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 Xtns 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 (Thanks, FatalEdge!) Keep the Procedure Browser Window open, as we will be using it frequently.

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.

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!

Let’s Create a Layer

We 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 (Note my screenshot above....NORMAL MODE does not have a hyphen in-between the two words. If I hit the Enter key at this point, it would return an error). 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”.



Getting the Layer into the Image

We’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 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.

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

Looks like a great introduction to scripting. I would suggest one thing though, which is to alter how you bring up the console and browser. There's an easier way to do things.

Open the Script-Fu console first. Then click that browse button by the small text box. This will launch the Procedure Browser and link it to the console. This might not seem all too important until you notice doing it this way adds an extra button to the Procedure Browser that isn't there when opening via the Xtns menu option.

Instead of copying + pasting the procedures between windows you can just click "apply" from the Procedure Browser and it'll send the procedure (complete with parameter placeholders) into the textbox of the Script-fu console.

So, for example, if I clicked apply when "gimp-drawable-fill" is selected "(gimp-drawable-fill drawable fill-type)" would be sent to the Script-Fu Console for me.

Well, shiitake mushroom! That sure does simplify matters immensely. I definitely like that way! :l: I'll modify the screenshots and text a bit to incorporate your way because my posted steps of getting the procedures into the Console, while fairly quick, pale in comparison to yours. Thanks again.

Art

Good Tutorial! :h:

I so really needed a tutorial as this on script fu, i will need some time to metabolize and then try..(here is late night) anyway seems very clear and detailed, i will tell more after practicing it

Thanks again for the suggestions, Fatal Edge! I've incorporated them into the tutorial and modified the screenshots/text accordingly. Of course, it's a bit late here, so it's highly likely that I've left something out or made something unclear. If anyone comes across anything you need clarification on, please don't hesitate to ask.

WOOT! Made it to the Official Tutorial Section! :l:

This is a very welcome tutorial. Thank you for posting this tutorial Art. Your tutorials are usually well documented and well explained. I look forward to digging into this tutorial at some time. :h:

Edit: I just took the time to follow the tutorial and was able to achieve the same final result. You didn't throw in too much complexity so I felt like I got a nice foundation to build on for your next scripting tutorial. In fact, it was fun following along on your tutorial. Thanks again for this tutorial. As a side note, it's probably good that you are a beginning script writer writing this. My sense is that because of that, it will be easier for beginners to follow and be successful at this.

Question: When I ran the gimp-display-new procedure, my image had an odd pattern filled in it. Once I did the gimp-drawable-fill procedure, the entire layer was filled with the solid blue color and the pattern was gone. I tried this again by adding another layer to the image using the gimp-layer-new procedure and that layer too had an odd pattern filled in. I then did a gimp-drawable-fill and used a TRANSPARENT-FILL and that got rid of the pattern and made the layer as I would expect to see a normal transparent layer. What is the reason for the odd patterns that ended up in my default layers until I filled them? Thanks.

Hi, Rich! Thanks for the feedback and kind words. Glad you found it useful. Hopefully the follow-up tutorial will be as beneficial.

As far as the random patterns on the layers, you're correct, that's what's supposed to happen and I failed to add that to the tutorial because my new image was nearly transparent and I forgot about that part. Here's why: We've created an image and added a layer to it, but GIMP doesn't know what to fill it with and just adds random colors until told otherwise. You could type in the SFC the following Procedure: (gimp-edit-clear drawable) in my case it would be (gimp-edit-clear to clear the contents of the layer. But, it's not entirely necessary since we're instructing GIMP to fill it with color in the next step.

I've added that information to the tutorial. Thanks for reminding me.

Nice tutorial Art :h:
I'll definately try this later :h:

good...

Well took 4 day to face it but i did and then was much simpler then i thought

I get my red square (i can't resist to change something, and you already did the blue one).

So now i'm busy to play with all the possible variants as fill with a gradient or a pattern ...i must try Plasma or noise too

and then see if looking for "blur" i could get to blur the plasma or noise filling...

Well , i feel impatient to see what is next :h: