The GIMP

Copyright (C) 1995 Peter Mattis and Spencer Kimball

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by Peter Mattis or Spencer Kimball.

The GIMP Copying Conditions

The GIMP is free; this means that everyone is free to use it and free to redestribute it on a free basis. The GIMP is not in the public domain; it is copyrighted and there are restrictions on its distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of the GIMP that they might get from you.

Specifically, we want to make sure that you have the right to give away copies of the GIMP, that you receive source code or else can get it if you want it, that you can change the GIMP or use pieces of it in new free programs, and that you know you can do these things.

To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights. For example, if you distribute copies of the GIMP, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights.

Also, for our own protection, we must make certain that everyone finds out that there is no warranty for the GIMP. f the GIMP is modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will no reflect on our reputation.

The precise conditions of the licenses for the GIMP are found in the General Public Licenses that accompanies it.

Genesis of the GIMP

The GIMP arose from the ashes of a hideously crafted cs164 (compilers) class project. The setting: early morning. We were both weary from lack of sleep and the terrible strain of programming a compiler in LISP. The limits of our patience had long been exceeded, and yet still the dam held.

And then it happened. Common LISP messily dumped core when it could not allocate the 17 MB it needed to generate a parser for a simple grammar using "jyack". An unbelieving moment passed, there was one shared look of disgust, and then our project was vapor. We had to write something...ANYTHING...useful. Something in C. Something that did not rely on nested lists to represent a bitmap. Thus, the GIMP was born.

Like the phoenix, glorious, new life sprung out of the burnt remnants of LISP and jyacc. Ideas went flying, decisions were made, the GIMP began to take form.

An image manipulation program was the consensus. A program which would at the very least lessen the necessity of using commercial software under "Windoze" or on the "Macintoy". A program that would provide the features missing from the other X painting and imaging tools. A program that would help maintain the long tradition of excellent and free UNIX applications.

Six months later, we've reached an early BETA stage. We want to release now to start working on compatibility issues and cross platform stability. Also, we feel now that the program is actually usable and would like to see other interested programmers developing plug-ins and various file format support.

Introduction to the GIMP

The GIMP is designed to provide an intuitive graphical interface to a variety of image editing operations. The following list describes parts of the GIMP's functionality.

Creating, modifying and using selections

A selection is defined as the currently active region of an image. Selections can be made with single pixel precision, and can be arbitrarily complex. A GIMP selection is represented graphically by a boundary line drawn around the represented region. The line appears to move, and so is easy to discern even when used with a complex image. This moving lines can at times be distracting, or obscure important image information; they can be toggled on or off via the (/Edit/Selection Toggle) menu item.

Selections are created and modified using the suite of selection tools which include: rectangular, elliptical, free hand, fuzzy, bezier, and intelligent. Each successive use of a tool replaces the current selection with a new one. However, the current selection can be changed instead of replaced by holding down either the shift or control keys. The shift key has the effect of taking the union of the current selection and the new selection. The control key takes the difference.

While a selection is active in an image window, operations only affect the portion of the image which is inside the selection. Effects filters, for example, only change the pixels defined by the active selection. The various painting tools work in the same fashion.

Editing Selections

Intuitively, clicking with the mouse inside a selection allows the selection to be dragged to a new location. This functionality is only present when one of the selection tools is the active tool. The GIMP represents a selection being dragged by its outline or its bounding box. The bounding box is useful when the outlines become very complex and the host machine is slow. The default is to use the selection's outline, but bounding boxes can be enabled through a command line switch or an X resource.

Selected regions can be precisely positioned using the keyboard's cursor keys. Holding down the shift key has the effect of increasing the step size of each movement.

Standard editing functions are available for use on selections. In a basic sense, cut, copy, & paste work on selected image areas just like they might work on selected text. Cutting a selected region removes both the selection and the associated image region, replacing the former pixel colors with the background color. The cut selection is now stored in a global buffer, from which the cut selection can be pasted any number of times. Copying has the same effect as cut, but does not remove the selection being copied. Successive copies or cuts replace the former contents of the global buffer.

Paste copies the selection in the global buffer to the current image, replacing the image's selection, if one existed. It positions the new selection so that its center corresponds to the center of the former selection. If there was no fomer selection, the pasted selection is centered with respect to the entire image.

A selection that is pasted or moved is considered to be floating. That is, the contents of the image under it are preserved. Moving a floating selection to a new location restores the image previously hidden to its former state. A floating selection can be anchored by a invoking the (/Edit/Selection Anchor) menu item. This effectively replaces the contents of the image underneath with the contents of the floating selection, and does away with the "floating" status. Modifying a floating selection's boundary with selection tools has the same effect.

The transparency of floating selections can be modified through the (Edit/Paste Opacity) menu item. This invokes a dialog with a slider that control the percentage of the floating buffer's opacity. 100% corresponds to no transparency or full opacity. The lower the opacity is set to, the more transparent the floating buffer becomes until at 0%, the floating buffer is invisible and only the image under it can be seen.

Advanced selection usage

There is support in GIMP selections for an alpha value at each pixel in the selected area. That is, each pixel can have a value from 0 to 255 associated with it. This extra data is used by the GIMP in more complex operations such as anti-aliasing and image composition.

Cutting a selection from an image uses this alpha value to determine how much of a former pixel should remain behind and how much should be cut. If the alpha value is 255, then the entire pixel will be removed, and only the background color will remain. If the alpha value is 0, then nothing will be cut and the pixel on the image will remain the same. If the alpha value is 127, then half of the pixel's previous color will be cut, and what remains will be a 50/50 combination of the background color and the former pixel color.

A floating selection uses the alpha value to blend the color of the pixel it represents with the color underneath that pixel. The effect is transparency in the floating selection. This essentially is how floating selections can achieve anti-aliasing.

A selection's alpha channel can be edited through the menu item: (/Edit/Selection To Mask), which represents the current selection as an editable grayscale image. White in the image corresponds to an alpha value of 255. Black in the image similarly corresponds to an alpha value of 0. Shades of gray represent all of the intermediate values. This image is identical in every respect to a standard grayscale image, and can be modified in the same ways.

The grayscale image created by (/Edit/Selection To Mask) can be converted back into a selection via the (/Edit/Selection From Mask) menu item. This call pops up a dialog with an option menu requesting the mask source image. It then translates the shades of gray into a new selection with the corresponding alpha values.

Because the global buffer discussed previously can only hold one selection, named selection buffers are supported by the GIMP. Instead of the usual (/Edit/Cut) or (/Edit/Copy), using (/Edit/Cut Named) or (/Edit/Copy Named) pops up a dialog box asking for the name of the new buffer. In this fashion, an arbitrary number of selections can be saved and recalled at convenient times. (/Edit/Paste Named) calls a dialog box which allows any of the previously saved buffers to be pasted.

The selection tools

The GIMP currently supports six different selection tools. In order of appearance in the tool box they are: rectangle, ellipse, free, fuzzy, bezier, and intelligent. Each tool has its advantages and disadvantages--no one tool is clearly superior to the others. In general, a combination of tools proves to be the optimal strategy for complex selection tasks. Following is a more complete description of each tool, including strengths and weaknesses as well as features.

Rectangle and ellipse selection tools

These tools are self-explanatory. Rectangles and ellipses can be placed in an image by clicking in the image window with the left mouse button. The width and height are specified by dragging the mouse with the button still pressed. Holding down the `Shift' and `Control' keys simultaneously keeps the width and height equal, effectively producing squares or circles. As with all selection tools, holding down `Shift' when the rectangle or ellipse is initially placed adds the resulting shape to the current selection; `Control' subtracts from the current selection.

Free selection tool

Free select allows an arbitrarily complex curve to be drawn with the mouse which is then scan converted into a polygon and incorporated into the current selection. Free select is especially good for "touching up" selections--either subtracting extraneous pixels or adding a few missing pixels. Selecting large complex shapes is possible, but time consuming and inaccurate.

Fuzzy selection tool

Fuzzy select or "magic wand" is initiated by specifying a seed pixel with the left mouse button. The resulting selection will include the seed pixel and contiguous pixels of similar color. Essentially, the selection flows outward from the seed pixel until it reaches pixels which are sufficiently dissimilar in color. The threshold value which determinates what is "sufficient" can be dynamically set by dragging the mouse with the left button still pressed. Moving left or up decreases the threshold, shrinking the selection. Moving right or down increases the threshold, enlarging the selection. When the proposed selection is satisfactory, it can be combined with the current selection by releasing the left mouse button. Subsequent use of the fuzzy tool will start with the final threshold value of the previous use.

Fuzzy selections are well suited to selecting objects of near constant color. Unfortunately, objects of this nature seldom appear in images. When used in conjunction with other tools, however, fuzzy select proves invaluable. It is especially effective in subtracting background pixels from roughly drawn boundaries.

Bezier selection tool

Bezier select allows the interactive creation of closed bezier curves. The curves are made up of a series of segments and the segments are in turn made up of a series of points. Clicking the left mouse button when this tool is active places an anchor point. Clicking and dragging places an anchor point and allows the specification of the next control point on the curve which is then placed when the button is released. While moving a control point, the anchor point can be moved by holding down the `Control' key. The continuity between curve segments can be controlled by using the `Shift' key. Holding down the `Shift' key while a control point is being moved causes the continuity between to segments to be disrupted. Releasing the `Shift' key causes it to be restored. (This allows for the creation of sharp corners on the curve). Control points are displayed as squares and anchor points as circles. The active point (whether it is a control or anchor point) is displayed filled while all other points or unfilled.

The curve is changed into a selection by clicking inside of it. Similar to other selection tools, holding down `Shift' adds to the current selection while holding down `Control' subtracts from the current selection.

The bezier selection tool is particularly well suited for selecting curved regions of an image, such as the outline of a teapot. Conversely, it is inadequate for selecting regions which contain a lot of variation.

Intelligent selection tool

Intelligent selection or "intelligent scissors" is a computationaly expensive tool that often provess well worth the extra CPU cycles. This tool is specifically for selecting well definined objects in an image. Selections are created by placing control points at appropriate positions along the edges of the desired object. The intelligence of the tool is its ability to discern a path between each set of adjacent control points that corresponds closely to the object's edge. Clicking the left mouse button on the image displays a target cursor specifying where the control point will be placed when the button is released. Dragging the mouse with the button still pressed moves the target cursor as well. Instead of following the mouse cursor exactly, the target cursor "jumps" to the nearest perceived edge in the image. This behavior is useful because good results using this tool are achieved with control points that lie on strong edges. It can be disabled by holding down the `Shift' key while dragging the mouse.

To finish the selection, specify the last control point as the original control point, which connects the boundary. Control points can be modified by dragging them to new positions. New control points can be inserted by clicking on the curves between any set of existing control points. Clicking inside the connected boundary results in the final selection. As with other tools, holding down `Shift' adds to the current selection while holding down `Control' subtracts from the current selection.

Though smarter than most other selection tools, intelligent select is stupid compared to the average human, so it is not surprising that it is prone to foolish errors. By adding additional control points--explicitly defining where the edge of the object is--this tool can be shown the error of its ways. Intelligent select is especially good at selecting objects with strong, well defined edges. When these conditions do not exist, the bezier selection tool is a better choice. Some errors that the tool makes are very difficult to correct by adding additional control points. In these cases, using free selection or fuzzy selection to "touch up" the intelligent selection makes sense.

Extending the GIMP

Plug-ins are external programs which offer an easy method of extending parts of the GIMP's functionality. Basically, they can be used to operate on images perform such useful tasks as loading and saving images to disk as fell as applying various effects filters. Plug-ins are easy to write, easy to use and a vary nice solution to the problem of bloating the main program with a lot of code that rarely gets used.

How to Use Plug-ins

Plug-ins, as part of their functionality, must be easily accessible from within the GIMP. This is accomplished by putting them within easy reach in the image popup menu which is accessed by clicking the right mouse button within the image. The user need only select the appropriate plug-in from the choices for it to run.

Actually, the above is a simplification of the actual mechanism. The GIMP uses a configuration file that is parsed at startup to determine which plug-ins should be accessible to the user. The configuration file allows the user to specify a hierarchy of menus in which the plug-ins lie. The configuration file also specifies a search path to look through in order to find the actual location of the plug-in binaries.

File plug-ins work slightly differently than other plug-ins. They are accessed semi-invisibly when the user opens or saves a file using the (file/open) or (file/save) commands. The correct file plug-in is determined by examining the extension used to save or open the file. (ie. If a file "temp.jpg" is opened then the "jpeg" file plug-in will be used). The configuration file described above provides a mapping between extensions and file plug-ins. The user can also specify a particular file plug-in to use when opening and saving files which overrides the extension mechanism. This allows a file to be opened or saved which doesn't have an extension.

Many of the plug-ins provide simple dialog interfaces to parameters that affect their operation. These dialogs share the common theme that clicking the "ok" button has the effect of applying the plug-in and clicking the "cancel" button has the effect of canceling the plug-in.

The Standard Plug-ins

The GIMP is distributed with an assortment of plug-ins to extend its functionality. Some of these plug-ins, the file plug-ins for instance, should be viewed as integral parts of the GIMP since using the GIMP would be difficult without them.

Plug-ins are broken into 3 categories. File plug-ins load and save files to disk. Filter plug-ins perform effects on an image. These effects modify the image and are restricted to take place within the current selection. And lastly, channel operations operate on entire images at a single time and perform such operations as duplicate and composite. Below is a list of the plug-ins that come with the GIMP and a short description of their operation.

Programing for Plug-ins

Plug-ins are simply ordinary programs that are run by the GIMP. They communicate with the GIMP using a simple message passing system that currently works using a combination of unix pipes and shared memory.

The message passing system allows plug-ins to access services provided by the GIMP, such as creating and displaying an image. It is, however, too low level to be used for everyday programming. The solution is a high level library that provides another layer on top of the message passing system. It is this library and its usage that will be described.

Initializing the plug-in library

The library is very easy to initialize. Simply call the "gimp_init" function at startup and pass in the "argc" and "argv" values. The programmer should not disturb the values of "argc" and "argv". They contain values that the library needs in order to initialize the message passing system. Specifically, they contain the file descriptor numbers of the pipes used to communicate with the GIMP. The "gimp_init" function returns 1 on success and 0 on failure.

Getting and operating on images

Creating and using dialogs

An example of a filter plug-in

An example of a file plug-in

An example of a channel operation