Gimptalk - Premier Gimp Community: GIMP Scripting 101 - Gimptalk - Premier Gimp Community

Jump to content

  • 2 Pages +
  • 1
  • 2
  • You cannot start a new topic
  • You cannot reply to this topic

GIMP Scripting 101

#1 User is offline   fencepost 

  • Retired Staff
  • PipPipPip
  • Group: Retired Staff
  • Posts: 2,646
  • Joined: 01-March 05

Posted 04 January 2008 - 08:27 PM

December 26, 2008: Tutorial updated to work with GIMP 2.6.

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

Posted Image

and the following window will appear:

Posted Image

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 Help Menu > Procedure Browser:

Posted Image

and the following window will appear:

Posted Image

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.

Posted Image

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:

Posted Image

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:

Posted Image

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):

Posted Image

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.

Posted Image

As we did for creating the image, copy and paste the “gimp-layer-new” into the SFC by clicking the "Apply" Button:

Posted Image

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:

Posted Image

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”.

Posted Image

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”

Posted Image

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:

Posted Image

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:

Posted Image

Hit the enter key and, if you’ve done everything correctly, the following should appear:

Posted Image

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.

Posted Image

Click the "Apply" Button to copy the Procedure from the PB and paste it into the SFC as before.

Posted Image

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.

Posted Image

Hit the Enter key and the following should appear:

Posted Image

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.

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"

Posted Image

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.

Posted Image

Now, to fill it with a color we need a single value that’s made up of red ®, 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.

Posted Image

Hit the enter key and you should get this in the SFC:

Posted Image

But, more importantly, your foreground color swatch on the main GIMP window should now be blue. Is it?

Posted Image

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.

Posted Image

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.

Posted Image

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:

Posted Image

Hit the Enter key and your image should now look like this:

Posted Image

and here’s what my layer dialog looks like showing my layer name:

Posted Image

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
0

#2 User is offline   Fatal Edge 

  • Retired Staff
  • PipPipPip
  • Group: Retired Staff
  • Posts: 3,053
  • Joined: 11-June 06
  • LocationStaffordshire, England

Posted 04 January 2008 - 09:34 PM

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.

0

#3 User is offline   fencepost 

  • Retired Staff
  • PipPipPip
  • Group: Retired Staff
  • Posts: 2,646
  • Joined: 01-March 05

Posted 04 January 2008 - 10:05 PM

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
0

#4 User is offline   The_Inferno_Man 

  • Member
  • PipPip
  • Group: Members
  • Posts: 33
  • Joined: 02-December 07

Posted 04 January 2008 - 10:11 PM

Good Tutorial! :h:
Posted Image
0

#5 User is offline   PhotoComix 

  • GT Senior Moderator
  • Group: Senior Moderators
  • Posts: 11,288
  • Joined: 13-June 05

Posted 05 January 2008 - 12:27 AM

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
0

#6 User is offline   fencepost 

  • Retired Staff
  • PipPipPip
  • Group: Retired Staff
  • Posts: 2,646
  • Joined: 01-March 05

Posted 05 January 2008 - 05:41 AM

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:
0

#7 User is offline   ccbarr 

  • Advanced Member
  • PipPipPip
  • Group: Members
  • Posts: 1,705
  • Joined: 23-February 06

Posted 05 January 2008 - 07:36 AM

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.
0

#8 User is offline   fencepost 

  • Retired Staff
  • PipPipPip
  • Group: Retired Staff
  • Posts: 2,646
  • Joined: 01-March 05

Posted 05 January 2008 - 05:07 PM

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 8) 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.
0

#9 User is offline   Alz 

  • Member
  • PipPip
  • Group: Members
  • Posts: 32
  • Joined: 16-April 07

Posted 05 January 2008 - 05:46 PM

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

#10 User is offline   guapo456 

  • Member
  • PipPip
  • Group: Members
  • Posts: 31
  • Joined: 07-November 07

Posted 06 January 2008 - 05:18 AM

good...
Posted Image

Flow-Designs.::Novice::.
0

#11 User is offline   PhotoComix 

  • GT Senior Moderator
  • Group: Senior Moderators
  • Posts: 11,288
  • Joined: 13-June 05

Posted 10 January 2008 - 12:35 AM

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:
0

#12 User is offline   fencepost 

  • Retired Staff
  • PipPipPip
  • Group: Retired Staff
  • Posts: 2,646
  • Joined: 01-March 05

Posted 26 December 2008 - 02:42 PM

Tutorial updated to work with GIMP 2.6. My other scripting tutorials will be updated in the near future as time permits. Enjoy!

Art
0

#13 User is offline   caasi 

  • Member
  • PipPip
  • Group: Members
  • Posts: 10
  • Joined: 26-October 08

Posted 04 February 2009 - 11:27 PM

Nice tut. This really helped my out. I didn't understand scripting at all until I did this tutorial. Thanks.
0

#14 User is offline   annz08 

  • Newbie
  • Pip
  • Group: Members
  • Posts: 1
  • Joined: 14-March 09

Posted 14 March 2009 - 11:26 PM

i need help guyz..

i tryd the instruction .. but in the procedure browser part ,, i dont have the "apply-border"

im using GIMP 2.6.1

is der anything wrong bout it???

can sumbody help me????
0

#15 User is offline   PhotoComix 

  • GT Senior Moderator
  • Group: Senior Moderators
  • Posts: 11,288
  • Joined: 13-June 05

Posted 14 March 2009 - 11:48 PM

where in the tutorial there is a mention of apply border ?
What exactly you are trying to accomplish ?
0

#16 User is offline   saulgoode 

  • Retired Staff
  • PipPipPip
  • Group: Retired Staff
  • Posts: 5,324
  • Joined: 22-August 05

Posted 15 March 2009 - 04:26 AM

annz08 said:

i tryd the instruction .. but in the procedure browser part ,, i dont have the "apply-border"

I think you mean the "apply" button. The "Apply" button is only present if you have opened the Procedure DataBase browser from the Script-fu console -- if you opened the PDB browser using the "Procedure Browser" command in the Help Menu then it is not "connected" to your Script-fu console and there will be no "Apply" button.
Everybody makes their own fun. If you don't make it yourself it's not fun, it's entertainment.
0

#17 User is offline   Kitte 

  • Newbie
  • Pip
  • Group: Members
  • Posts: 2
  • Joined: 14-June 09
  • LocationDenmark

Posted 14 June 2009 - 10:25 PM

I couldn't make it work. But off c... Im so tired >_>
Posted Image

When life gives you a hundred reasons to cry,
show life that you have a thousand reasons to smile.
0

#18 User is offline   codyzapp 

  • Member
  • PipPip
  • Group: Members
  • Posts: 51
  • Joined: 02-September 08

Posted 15 June 2009 - 12:20 PM

great tutorial, really opened my eyes... i wanna see if i can create a script ive had on my mind for a few that i cant get anyone else to build for me.
0

#19 User is offline   photofinishron 

  • Newbie
  • Pip
  • Group: Members
  • Posts: 1
  • Joined: 06-August 10

Posted 06 August 2010 - 06:25 AM

So comment and a couple of questions.

Comment: Thanks was a good starter for scripting.

Questions:

1. When you get an error on the input of a procedure how do you edit it once it has been applied?

2. How do you save a script and where do you save it? I went through the whole tutorial and after saving the script I couldn't reload it.

Thanks

Ron
0

#20 User is offline   paynekj 

  • Member
  • PipPip
  • Group: Members
  • Posts: 381
  • Joined: 01-June 05
  • LocationUK

Posted 06 August 2010 - 09:14 AM

photofinishron said:

So comment and a couple of questions.

Comment: Thanks was a good starter for scripting.

Questions:

1. When you get an error on the input of a procedure how do you edit it once it has been applied?

2. How do you save a script and where do you save it? I went through the whole tutorial and after saving the script I couldn't reload it.

Thanks

Ron


I don't understand what you mean in your first question, but to answer the second you would be wise to read the next tutorial in the sequence:
GIMP Scripting 102a

Kevin
0

Share this topic:


  • 2 Pages +
  • 1
  • 2
  • You cannot start a new topic
  • You cannot reply to this topic