Pandora: a GIMP Plugin for Making Panoramas

(and Tips for Making Panoramas in GIMP)

Pandora is a GIMP script which helps in stitching together multiple images to make a panorama.

It does not find image matches automatically, but it does automate the most tedious part of making a panorama: creating a large image in which your component images are loaded as separate layers, with initial spacings and layer masks.

The original version of Pandora was written in C and needed to be compiled, but the new version is written in the GIMP's native scripting language, "script-fu", and should install easily on any platform and any version of GIMP.

Installing Pandora

To install, just download pandora-combine-0.9.3.scm (right click on the link and select "Save Link As"), placing it into your personal GIMP scripts folder (see the Edit->Preferences dialog, Folders category, and click on Scripts if you're not sure where that is.) For a longer discussion of how to install scripts, see the online GIMP User Manual or Chapter 11 of my book, Beginning GIMP: From Novice to Professional.

Note: if you have the "FX-Foundry" collection of GIMP scripts installed, you already have Pandora (though possibly not the latest version), but FX-Foundry changes the location of the menu items to FX-Foundry.>Multi-Layer Tools>Spread out layers. If you try to install Pandora in addition to FX-Foundry, you'll get errors since you'll have two competing copies of the same underlying functions.

How to Use Pandora

1. Load all the images as layers

The easiest way to do this is to create a new image (size doesn't matter), then do File->Open as Layers... from the image window. In the Open dialog, select all the components of the panorama (click on the first image, then shift-click on the last one to select everything in between; or control-click on individual images to add or subtract them) and click OK.

2. Delete the Background layer

Unfortunately there's no Open as Layers... from the toolbox menu, so creating a new image gave you an extra background layer that you don't need. Delete it: click on Background in the Layers dialog, then click the Delete button.

Note: if you don't normally show the Layers dialog, you'll definitely want it for making panoramas. It may already be visible, or docked as a tab with other dialogs such as Channels, Paths and History. If it's not visible, Ctrl-L will probably bring it up, or look for it in the Windows->Dockable Dialogs menu.

3. Run Pandora

You'll find Pandora under Filters->Pandora->Arrange as Panorama...

4. Set the overlap and direction

Set the overlap to the amount that each of your images overlaps the previous one, e.g. 30%, 60% or whatever.

Then figure out whether the bottom layer should be the leftmost one in the panorama, or the rightmost, and check or un-check "Top Layer on Right" accordingly.

If GIMP opened your images going right-to-left, and you'd prefer to make a panorama from left to right, you can use my reverse-layers.scm script-fu to fix that (it shows up as Layer->Stack->Reverse Layer Order). GIMP 2.4 will come with this built in.

Leave "Use Layer Masks" checked unless you have a reason to disable it.

Then click OK!

5. Tune Each Image's Position

Pandora will overlap the images by the amount you specified, with a layer mask created for each one to make its edge blend into the image before it. The next step is to fine-tune each image's position.

In the Layers dialog, turn off the visibility of all layers except the bottom two. Select the Move tool, and drag the second layer so that it matches the one underneath it as well as you can manage. Zoom in if you need to. The layer mask will make the second layer slightly transparent, so you can see how well the two layers overlap. They won't be perfect; don't worry too much about that yet.

Tip on moving layers: Each layer, except the bottom one, will have a layer mask (that's the black and white rectangle next to the layer preview in the Layers dialog). When you're moving a layer, make sure the layer itself is selected, and not the layer mask (make sure there's a white boundary around the layer preview on the left, not the black and white layer mask preview on the right).

When you're happy with the position of the second layer, go back to the Layers dialog and make the third layer visible, then in the image window, drag that one until it matches the second one. Repeat until you've adjusted all layers.

6. Fine-tune the Layer Masks

Because of lens warp, camera rotation and other factors, your images probably won't match perfectly. But you can tune that using the layer masks.

Choose the Paintbrush tool. Make the foreground color black and choose a fairly large brush.

In the Layers dialog, click on the layer mask for the second layer (its border will turn white, to show that it's selected). Then, back in the image window, paint everywhere the two images don't match very well. You should see the ghost of the second image disappear wherever you paint. Continue until the match looks good. You can also paint in white, or use the eraser tool, to make the second image show more.

When you're happy with your work, click on the second layer's icon in the Layers dialog (so you don't leave the mask selected by accident), click on the third layer's mask, and paint. Repeat until you're out of layers.

Of course you can adjust individual layers too, rotating them or applying brightness/contrast tools as needed.

Tips for stitching panoramas in GIMP

Books: My new book Beginning GIMP: From Novice to Professional has a step by step explanation of how to make panoramas by hand at the end of Chapter 10 (Pandora automates the first few steps of the process), along with tips on how to shoot good panoramas. Failing that, Grokking the Gimp, Chapter 7.5 has a good step-by-step tutorial written for GIMP 1.2.

Use layers: You really want each image as its own layer -- keep them that way until you're completely finished editing. It doesn't matter how new you are or how confusing you think layers are -- for panoramas they are absolutely the way to go. (It was physically painful watching my husband try to edit panoramas in photoshop without using layers.) I didn't really understand layers when I first started making panoramas, but working through the exercises with a book in hand helped a lot.

Selection boundaries:: View->Toggle Selection is your best friend. You can't match anything up with those selection and layer boundaries getting in the way. Ctrl-T is an easy way to toggle the selection boundaries on and off.

Save: Save frequently, every time you match up another edge. You never know when disaster might strike. Use Gimp's internal .xcf format. That way all the layer and mask information is preserved. When you're all finished, then resize (if appropriate) and save a separate copy as .jpg or whatever, but keep the .xcf around in case you ever need to edit it any more.

Master the Move Tool: In the move tool, the left, right, up, and down arrows move the selected layer by one pixel. Once you get close by dragging with the mouse, use the arrows to tweak the layers until they're perfect.

Layer visibility: In the layers dialog, clicking on the "eye" icon toggles a layer's visibility on and off -- very useful for matching two edges.

Mask visibility: Ctrl-clicking on the layer mask icon in the layers dialog toggles the use of the mask: you can go back to seeing the sharp edge of the layer without losing the mask.

Tune using transparency: You can use the transparency slider (after you've turned off the mask, if any) to let you see both images at once, and overlap as much of them as possible.

Moving layers as a group: Clicking on the blank area to the right of the "eye" visibility icon brings up a "chain link" icon. You can use this to tie multiple layers together so they can be moved as a group. This is great when you think you have everything matched, then you're scrolling around and you notice that the fourth and fifth layers of your nine-layer panorama are a couple of pixels off. Tie layers 1-4, or 5-9, together by turning on all of their chain links, then you can move them as a group.

Getting the sky right:: Matching skies are hard, for some reason. You can spend hours with the smudge and clone tools trying to match all the sky boundaries, but don't do it. If you have a clear blue sky with no clouds, my advice is not to work too hard to match the skies. Match everything else, then use something like the magic wand tool to select the sky (this will probably take several tries, fiddling with the Threshold value); then use the color picker to select a deep blue from the highest sky point you have as background, a faded blue from the lowest sky point as foreground, then bucket fill the selected area with a gradient.

The Older C Version of Pandora

Linux Journal had an Article about using the older C version of Pandora.

I probably won't be maintaining it now that I have the more portable script-fu version; but if you want to try the C version, here's how:

Download pandora-0.7.1.tar.gz.

Install it with these commands:

tar xzvf pandora-0.7.1.tar.gz
cd pandora-0.7.1
make install
which will build pandora and install it to your personal gimp directory. It tries to be smart about figuring out whether you have gimp 1.2, 2.0, or both, but if it gets it wrong, you can make install-1.2 or install-2.0 explicitly.

Pandora build requires gimptool, which is available on most linux distros (and Mac OS X) as part of a gimp-dev or gimp-devel package. You may also need a few other -devel packages, such as gtk-devel. SuSE linux users may also need to install XFree86-libs-dev in order to get the -lXi library. Gimptool is also available for Windows, I'm told, but I'm not sure of the details; try the Gimp Wiki for Windows building instructions.


9/3/2007: pandora-combine-0.9.3.scm
Use 0 in front of decimal numbers, e.g. 0.3; needed for GIMP 2.4. Thanks to schumaml.
2/3/2007: pandora-combine-0.9.2.scm
Don't choke on layers that already have a layer mask.
6/13/2006: pandora-combine-0.9.1.scm
Updates for Tiny-Fu (GIMP 2.3).
5/27/2006: pandora-combine-0.9.scm
Add the ability to reverse layers.
3/19/2006: pandora-combine-0.8.scm
Rewrite Pandora in script-fu so it can be used on systems without a compiler.
7/15/2005: 0.7:
Fix the Makefile so that it will build one 2.0 version, whichever gimptool-2.0 comes first in the path, as well as one 1.2 version. Unfortunately it can't currently build all 2.0 versions because of GIMP bug 310565.
9/25/2004: 0.7:
If no files have been added to the list, but files are selected in the picker, use that list (in alphabetical order).
Call gtk_main_quit from the dialog; gimp 2.0 won't remember plugin values unless we quit correctly.
Some code cleanup.
4/30/2004: 0.6:
Select the layer, not the mask, after creating the mask, because of changes in gimp 2.0.1.
2/16/2004: 0.5:
Fix a problem in the 1.2 compile (which only shows up with some versions of gcc).
2/10/2004: 0.4:
Update the build to call gimptool-2.0 instead of 1.3; make the default make target do nothing except print a message (it no longer installs without a make install).
11/27/2003: 0.3:
Fix busted compile under the most recent Gimp 1.3 (thanks to Andrew Burton and Sven Neumann).
Improve the file selection lists: multi selection and file remove.
Make Makefile a lot smarter.
Include this ChangeLog in the source dir.
2/3/2003: 0.2:
Put the UI all in one dialog. Introduce beginnings of pandora_match.
1/29/2003: 0.1:
First release.

Other panorama software for Linux

Linux Imaging
More of my Software
Shallowsky Home
mail me