It is currently Thu Mar 28, 2024 9:53 am


All times are UTC - 5 hours [ DST ]



Post new topic Reply to topic  [ 22 posts ]  Go to page 1, 2  Next
Author Message
 Post subject: GIMP Scripting 101
PostPosted: Wed Dec 11, 2013 8:22 pm  (#1) 
Offline
Script Coder
User avatar

Joined: Apr 13, 2010
Posts: 244
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 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

Image

and the following window will appear:

Image

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

Image

and the following window will appear:

Image

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.

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.

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:

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:

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

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!

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

Image

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

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:

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

Image

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

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:

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:

Image

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

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.

Image

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

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.

Image

Hit the Enter key and the following should appear:

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.

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

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.

Image

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.

Image

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

Image

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

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.

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.

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:

Image

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

Image

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

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

_________________
I'd rate you as an upper-middle-lower-mod with pro-novice-inter tendencies.....and a twist of lime! Of course, my rating scale is completely objectively subjective, but ALWAYS consistently inconsistent.


Share on Facebook Share on Twitter Share on Orkut Share on Digg Share on MySpace Share on Delicious Share on Technorati
Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Wed Dec 11, 2013 8:27 pm  (#2) 
Offline
GimpChat Member
User avatar

Joined: Mar 23, 2012
Posts: 7301
Location: Göteborg at last!
A useful tutorial. I've often thought about creating scripts but I haven't got around to learning yet. I'll be following these tutorials - thank you very much FP.


Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Wed Dec 11, 2013 9:04 pm  (#3) 
Offline
Global Moderator
User avatar

Joined: Nov 16, 2011
Posts: 5128
Location: Metro Vancouver, BC
Nice one fencepost, I'll definitely be giving your tutorial a go. :bigthup
Like Erisian one day I would like to try learning how to writing a script, mostly for the personal satisfaction of knowing I could do it if need be. I admire and am always amazed with the great script writers we have in the Gimp community.

_________________
Image
Gimp 2.8.18, Linux, median user
Gimp Chat Tutorials Index
Spirit Bear (Kermode)


Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Wed Dec 11, 2013 9:47 pm  (#4) 
Offline
GimpChat Member
User avatar

Joined: Dec 08, 2013
Posts: 1088
Very nice, Quick and concise. Thankyou.

_________________
Image


Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Wed Dec 11, 2013 10:22 pm  (#5) 
Offline
GimpChat Member
User avatar

Joined: May 16, 2010
Posts: 14709
Location: USA
Thanks Fencepost. :)

_________________
Image
Edmund Burke nailed it when he said, "The only thing necessary for the triumph of evil is for good men to do nothing."


Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Thu Dec 12, 2013 5:49 am  (#6) 
Offline
GimpChat Member
User avatar

Joined: Jan 20, 2013
Posts: 591
Very nice work, fencepost. You lift up the community of the gimp to the highest summits.

_________________
Image


Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Thu Dec 12, 2013 6:18 am  (#7) 
Offline
Global Moderator
User avatar

Joined: Apr 07, 2010
Posts: 14182
I agree, Fencepost has brought a lot of good scripts, excellent tutorials to this forum and it is very nice to see him back.

_________________
Image


Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Thu Dec 12, 2013 9:38 am  (#8) 
Offline
Script Coder
User avatar

Joined: Apr 13, 2010
Posts: 244
Y'all are very welcome. I know it's a lot of information, but scripting was fun for me to learn and I wanted to share....not only for your benefit, but mine. So when I go away from graphics and come back, I can re-learn it again. LOL

_________________
I'd rate you as an upper-middle-lower-mod with pro-novice-inter tendencies.....and a twist of lime! Of course, my rating scale is completely objectively subjective, but ALWAYS consistently inconsistent.


Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Thu Dec 12, 2013 9:41 am  (#9) 
Offline
Global Moderator
User avatar

Joined: Apr 07, 2010
Posts: 14182
Nice job on your scripting tute FP. I will leave that to all the smart guys/gals... and we do have lots of them here on this forum.
BTW, love the avatar, even if it does make me dizzy.

_________________
Image


Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Thu Dec 12, 2013 9:46 am  (#10) 
Offline
Script Coder
User avatar

Joined: Apr 13, 2010
Posts: 244
Thanks, molly! That was a fun avatar to make and only takes about 10 minutes to do it manually. With my "move layers" script, it could probably be faster. ;)

_________________
I'd rate you as an upper-middle-lower-mod with pro-novice-inter tendencies.....and a twist of lime! Of course, my rating scale is completely objectively subjective, but ALWAYS consistently inconsistent.


Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Thu Dec 12, 2013 3:04 pm  (#11) 
Offline
GimpChat Member
User avatar

Joined: Feb 14, 2012
Posts: 426
I'm going to give this scripting thing a try fencepost.

Pegleg


Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Thu Dec 12, 2013 4:01 pm  (#12) 
Offline
Script Coder
User avatar

Joined: Apr 13, 2010
Posts: 244
PegLeg44 wrote:
I'm going to give this scripting thing a try fencepost.

Pegleg


:bigthup Go for it!

_________________
I'd rate you as an upper-middle-lower-mod with pro-novice-inter tendencies.....and a twist of lime! Of course, my rating scale is completely objectively subjective, but ALWAYS consistently inconsistent.


Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Thu Dec 12, 2013 5:36 pm  (#13) 
Offline
GimpChat Member
User avatar

Joined: Feb 14, 2012
Posts: 426
If I wanted to start a script with a new-from-visible then what would the perimeters for image and Destination image be.

(gimp-layer-new-from-visible image dest-image name)

Where might I find a list of things that I could use for different perimeters? Like Image and Layer etc.

What perimeter can be used to make a new layer from visible on the current open image be it with or without layers.

Pegleg


Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Thu Dec 12, 2013 10:15 pm  (#14) 
Offline
Script Coder
User avatar

Joined: Apr 13, 2010
Posts: 244
Many of the answers to your questions are presented in this tutorial. I have a couple more tutorials that I'm in the process of posting here (have to relink all of the pictures) and they describe the steps you need for creating a real script.

_________________
I'd rate you as an upper-middle-lower-mod with pro-novice-inter tendencies.....and a twist of lime! Of course, my rating scale is completely objectively subjective, but ALWAYS consistently inconsistent.


Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Thu Dec 12, 2013 10:44 pm  (#15) 
Offline
GimpChat Member
User avatar

Joined: Feb 14, 2012
Posts: 426
Yes, now I see all the different perimeter functions that can be used in PB listed on the right side.

If I don't create the layer in the SFC then I don't know the image ID #. There must be code that I use as the ID # that copies all the layers that are visible.

I look forward to the other tutorial you have in mind.

Alan


Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Thu Dec 12, 2013 10:51 pm  (#16) 
Offline
Script Coder
User avatar

Joined: Apr 13, 2010
Posts: 244
Step 4 answers that question, specifically the third screenshot of Step 4. The other tutorials have already been posted for a couple of years on gimptalk.com, but the links to the screenshots are no longer any good and have to be updated.

_________________
I'd rate you as an upper-middle-lower-mod with pro-novice-inter tendencies.....and a twist of lime! Of course, my rating scale is completely objectively subjective, but ALWAYS consistently inconsistent.


Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Fri Dec 13, 2013 12:55 pm  (#17) 
Offline
GimpChat Member
User avatar

Joined: Feb 14, 2012
Posts: 426
I've followed through the tutorial and understand it. Get the image ID, use it to create a layer ID, Use them to add the layer, getting it to work using gimp-display-new etc.

But if I have an image already open I don't know how to get the image ID. Or maybe there's some other procedure that should be used.

I would like to try and make a script that can do the same thing on an already open image that you would get if you simply click [Layer] [New From Visible].

I think this SFC and PB is interesting.


Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Fri Dec 13, 2013 2:33 pm  (#18) 
Offline
Script Coder
User avatar

Joined: Apr 13, 2010
Posts: 244
The image ID can be found at the top left corner of the main GIMP window.

Attachment:
ImageID.png
ImageID.png [ 7.71 KiB | Viewed 2280 times ]

_________________
I'd rate you as an upper-middle-lower-mod with pro-novice-inter tendencies.....and a twist of lime! Of course, my rating scale is completely objectively subjective, but ALWAYS consistently inconsistent.


Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Fri Dec 13, 2013 5:29 pm  (#19) 
Offline
Script Coder
User avatar

Joined: Apr 23, 2010
Posts: 1553
Location: not from Guildford after all
PegLeg44 wrote:
But if I have an image already open I don't know how to get the image ID. Or maybe there's some other procedure that should be used.

Within the Script-fu console, you can determine the image ID using several different methods.
If you have your Preferences configured suitably and have a window manager that displays a title bar, the image ID will appear after the filename in the windows title bar. The ID follows the filename, separated by a hyphen.

If the above isn't available, you can oftentimes see the same name in the status line of GIMP's image window. Again, it follows the image name separated by a hyphen convention. The image ID is typically followed by a ".0", but the zero is actually the 'display ID' and, if you have opened more than one display for the image (using "Image->View->New View"), it may be different.

If you open the Images dock ("Image->Windows->Dockable Dialogs->Images") you will see a list of available images, with the image/file name followed by a hyphen, followed by the image ID. You will also find this information (name-#) at the top of any of the dialogs that appear when you perform interactive image commands (e.g., Canvas Size, Print Size, Scale Image). The second point is worth noting because it works for Layers and Paths, which otherwise don't have their IDs displayed in the corresponding dock (e.g., you can open the Scale Layer dialog to find the layer ID).

_________________
Any sufficiently primitive technology is indistinguishable from a rock.


Top
 Post subject: Re: GIMP Scripting 101
PostPosted: Fri Dec 13, 2013 5:56 pm  (#20) 
Offline
Script Coder
User avatar

Joined: Apr 13, 2010
Posts: 244
Thanks, saulgoode. Nice to "see" you again!

_________________
I'd rate you as an upper-middle-lower-mod with pro-novice-inter tendencies.....and a twist of lime! Of course, my rating scale is completely objectively subjective, but ALWAYS consistently inconsistent.


Top
Post new topic Reply to topic  [ 22 posts ]  Go to page 1, 2  Next

All times are UTC - 5 hours [ DST ]


   Similar Topics   Replies 
No new posts Attachment(s) Scripting GEGL functions

52

No new posts Attachment(s) Normal Map scripting function

6

No new posts Attachment(s) Scripting my head into a wall - Any help would be appreciated

1



* Login  



Powered by phpBB3 © phpBB Group