Chapter 13. Scripting

Table of Contents

1. Plugins
1.1. Introduction
1.2. Using Plugins
1.3. Installing New Plugins
1.4. Writing Plugins
2. Using Script-Fu Scripts
2.1. Script-Fu?
2.2. Installing Script-Fus
2.3. Do's and Don'ts
2.4. Different Kinds Of Script-Fus
2.5. Standalone Scripts
2.6. Image-Dependent Scripts
3. A Script-Fu Tutorial
3.1. Getting Acquainted With Scheme
3.2. Variables And Functions
3.3. Lists, Lists And More Lists
3.4. Your First Script-Fu Script
3.5. Giving Our Script Some Guts
3.6. Extending The Text Box Script
3.7. Your script and its working

1. Plugins

1.1. Introduction

One of the nicest things about GIMP is how easily its functionality can be extended, by using plugins. GIMP plugins are external programs that run under the control of the main GIMP application and interact with it very closely. Plugins can manipulate images in almost any way that users can. Their advantage is that it is much easier to add a capability to GIMP by writing a small plugin than by modifying the huge mass of complex code that makes up the GIMP core. Many valuable plugins have C source code that only comes to 100-200 lines or so.

Several dozen plugins are included in the main GIMP distribution, and installed automatically along with GIMP. Most of them can be accessed through the Filters menu (in fact, everything in that menu is a plugin), but a number are located in other menus. In many cases you can use one without ever realizing that it is a plugin: for example, the "Normalize" function for automatic color correction is actually a plugin, although there is nothing about the way it works that would tell you this.

In addition to the plugins included with GIMP , many more are available on the net. A large number can be found at the GIMP Plugin Registry [GIMP-REGISTRY], a web site whose purpose is to provide a central repository for plugins. Creators of plugins can upload them there; users in search of plugins for a specific purpose can search the site in a variety of ways.

Anybody in the world can write a GIMP plugin and make it available over the web, either via the Registry or a personal web site, and many very valuable plugins can be obtained in this way ­ some are described elsewhere in the User's Manual. With this freedom from constraint comes a certain degree of risk, though: the fact that anybody can do it means that there is no effective quality control. The plugins distributed with GIMP have all been tested and tuned by the developers, but many that you can download were just hacked together in a few hours and then tossed to the winds. Some plugin creators just don't care about robustness, and even for those who do, their ability to test on a variety of systems in a variety of situations is often quite limited. Basically, when you download a plugin, you are getting something for free, and sometimes you get exactly what you pay for. This is not said in an attempt to discourage you, just to make sure you understand reality.

[Warning] Warning

Plugins, being full-fledged executable programs, can do any of the things that any other program can do, including install back-doors on your system or otherwise compromise its security. Don't install a plugin unless it comes from a trusted source.

These caveats apply as much to the Plugin Registry as to any other source of plugins. The Registry is available to any plugin creator who wants to use it: there is no systematic oversight. Obviously if the maintainers became aware that something evil was there, they would remove it. (That hasn't happened yet.) There is, however, for GIMP and its plugins the same warranty as for any other free software: namely, none.

[Caution] Caution

Plugins have been a feature of GIMP for many versions. However, plugins written for one version of GIMP can hardly ever be used successfully with other versions. They need to be ported: sometimes this is easy, sometimes not. Many plugins are already available in several versions. Bottom line: before trying to install a plugin, make sure that it is written for your version of GIMP.

1.2. Using Plugins

For the most part you can use a plugin like any other GIMP tool, without needing to be aware that it is a plugin. But there are a few things about plugins that are useful to understand.

One is that plugins are generally not as robust as the GIMP core. When GIMP crashes, it is considered a very serious thing: it can cost the user a lot of trouble and headache. When a plugin crashes, the consequences are usually not so serious. In most cases you can just continuing working without worrying about it.

[Note] Note

Because plugins are separate programs, they communicate with the GIMP core in a special way: The GIMP developers call it talking over a wire. When a plugin crashes, the communication breaks down, and you will see an error message about a wire read error.

[Tip] Tip

When a plugin crashes, GIMP gives you a very ominous-looking message telling you that the plugin may have left GIMP in a corrupted state, and you should consider saving your images and exiting. Strictly speaking, this is quite correct, because plugins have the power to alter almost anything in GIMP, but for practical purposes, experience has shown that corruption is actually quite rare, and many users just continue working and don't worry about it. Our advice is that you simply think about how much trouble it would cause you if something went wrong, and weigh it against the odds.

Because of the way plugins communicate with GIMP, they do not have any mechanism for being informed about changes you make to an image after the plugin has been started. If you start a plugin, and then alter the image using some other tool, the plugin will often crash, and when it doesn't will usually give a bogus result. You should avoid running more than one plugin at a time on an image, and avoid doing anything to the image until the plugin has finished working on it. If you ignore this advice, not only will you probably screw up the image, you will probably screw up the undo system as well, so that you won't even be able to recover from your foolishness.

1.3. Installing New Plugins

The plugins that are distributed with GIMP don't require any special installation. Plugins that you download yourself do. There are several scenarios, depending on what OS you are using and how the plugin is structured. In Linux it is usually pretty easy to install a new plugin; in Windows, it is either easy or very hard. In any case, the two are best considered separately.

1.3.1. Linux / Unix-sytem like systems

Most plugins fall into two categories: small ones whose source code is distributed as a single .c file, and larger ones whose source code is distributed as a directory containing multiple files including a Makefile.

For a simple one-file plugin, call it borker.c, installing it is just a matter of running the command gimptool-2.0 --install borker.c. This command compiles the plugin and installs it in your personal plugin directory, ~/gimp-2.4/plugins unless you have changed it. This will cause it to be loaded automatically the next time you start GIMP. You don't need to be root to do these things; in fact, you shouldn't be. If the plugin fails to compile, well, be creative.

Once you have installed the plugin, how do you activate it? The menu path is determined by the plugin itself, so to answer this you need to either look at the documentation for the plugin (if there is any), or launch the Plugin Description dialog (from Xtns/Plugins Details) search the plug-in by its name and look of the Tree view tab. If you still don't find, finally explore the menus or look at the source code in the Register section -- whichever is easiest.

For more complex plugins, organized as a directory with multiple files, there ought to be a file inside called either INSTALL or README, with instructions. If not, the best advice is to toss the plugin in the trash and spend your time on something else: any code written with so little concern for the user is likely to be frustrating in myriad ways.

Some plugins (specifically those based on the GIMP Plugin Template) are designed to be installed in the main system GIMP directory, rather than your home directory. For these, you will need to be root to perform the final stage of installation (when issuing the make install command).

If you install in your personal plugin directory a plugin that has the same name as one in the system plugin directory, only one can be loaded, and it will be the one in your home directory. You will receive messages telling you this each time you start GIMP. This is probably a situation best avoided.

1.3.2. Windows

Windows is a much more problematic environment for building software than Linux. Every decent Linux distribution comes fully supplied with tools for compiling software, and they are all very similar in the way they work, but Windows does not come with such tools. It is possible to set up a good software-building environment in Windows, but it requires either a substantial amount of money or a substantial amount of effort and knowledge.

What this means in relation to GIMP plugins is the following: either you have an environment in which you can build software, or you don't. If you don't, then your best hope is to find a precompiled version of the plugin somewhere (or persuade somebody to compile it for you), in which case you simply need to put it into your personal plugin directory. If you do have an environment in which you can build software (which for present purposes means an environment in which you can build GIMP), then you no doubt already know quite a bit about these things, and just need to follow the Linux instructions.

1.3.3. Apple Mac OS X

How you install plugins on OS X mostly depends on how you installed GIMP itself. If you were one of the brave and installed GIMP through one of the package managers like fink [DARWINORTS] or darwinports, [FINK] the plugin installation works exactly the way it is described for the Linux platform already. The only difference is, that a couple of plugins might be even available in the repository of you package manager, so give it a try.

If you on the other hand are one of the Users that preferred to grab a prebuild GIMP package like, you most probably want to stick to that prebuild stuff. So you can try to get a prebuild version of the plugin of you dreams from the author of the plugin, but I'd not want to bet on this. Building your own binaries unfortunately involves installing GIMP through one of the package managers mentioned above.

1.4. Writing Plugins

If you want to learn how to write a plugin, you can find plenty of help at the GIMP Developers web site [GIMP-DEV-PLUGIN]. GIMP is a complex program, but the development team has made strenuous efforts to flatten the learning curve for plugin writing: there are good instructions and examples, and the main library that plugins use to interface with GIMP (called libgimp) has a well-documented API. Good programmers, learning by modifying existing plugins, are often able to accomplish interesting things after just a couple of days of work.