This is a short document describing the various Open Source tools and techniques available for working with panoramas in a non-GUI environment. The examples are based on Linux experience, but most of them should work on OS X or Windows with minor modifications at most.

This document is also useful for understanding what happens 'under the hood' in hugin itself and recommended reading for anyone looking to work with the hugin sourcecode.

Why would you do that?

Creating and manipulating panoramas is something that should obviously be done in a graphical tool. This is true, but perhaps you find that you are spending more time operating a computer than being a photographer. This is an indication that something is wrong - The computer exists to do the boring work and scripting is one way to make this happen.

PanoTools 'Scripting'

The file format first used in Helmut Dersch's Panorama tools is often referred to as a 'script', but a 'PanoTools' script is really a data file describing a 'panorama stitching project'.

Although these original PanoTools are obsolete, the file format is alive and well with several variations used as project files by PTGui, PTAssembler, hugin and related tools. These files are simple plain-text, sometimes it is useful to modify them directly with a text editor - Further on we will introduce various methods for manipulating them via the 'programming' kind of scripts.

Simple command-line stitching

Lets start with a basic but common use case: Photographers with quality panoramic tripod heads can reproduce identical sets of photos every time, in this situation there is no need to create a new stitching project for every panorama, it is enough to use a single project as a template.

This example takes a pre-existing project called template.pto, created with three photos. It uses nona for remapping, and enblend for blending the remapped photos into a finished TIFF image:

The first nona command creates three remapped TIFF images called out0000.tif, out0001.tif etc... the list of input images can be substituted with any set of identically sized photos. The second enblend command uses these TIFF files as input and merges them to a file called finished.tif.

Creating hugin projects on the command-line

The entire panorama creation process can be performed on the command-line, and therefore scripted, doing this involves a series of steps similar to the workflow in a GUI tool.

Pruning control points

This still isn't a finished panorama, at the very least this involves optimising the camera positions and then rendering the output.

You could go ahead and optimise this project file straight away, but this can be a bit hit and miss. First it is a good idea to clean up the control points. There are currently two useful tools for cleaning control points: celeste removes points from areas of sky and ptoclean removes points with large error distances, first celeste_standalone:

Optimising photometric parameters

Photos have photometric exposure variables which can be optimised in much the same way as aligning positions. Doing this can remove brightness, white balance and vignetting differences between photos, giving better blending or allowing creation of HDR images.

vig_optimize does the equivalent job for photometric parameters as autooptimiser does for geometric parameters. It doesn't have an equivalent of the autooptimiser -a 'auto' mode, so you need to indicate in the .pto project which parameters are 'variables', use a tool such as ptovariable:

Makefile stitching system

This simple stitching process works well on the command-line, but it gets increasingly complicated when dealing with bracketed stacks of photos, these are necessary for exposure blending with enfuse or HDR creation with hugin_hdrmerge.

Luckily hugin understands about stacks and is capable of breaking-up a project into each of the stitching tasks: rendering, assembling stacks and blending. These targets are written to a standard Makefile formatted file whenever a project is saved or stitched, e.g when you save project.pto using the hugin GUI, project.pto.mk is saved also. Stitching is then performed not by the hugin GUI, but by GNU make which processes the targets in the Makefile, resulting in the final stitched panorama.

Creating Makefiles with pto2mk

This functionality is also available for use with any .pto project with the command-line pto2mk tool:

One of the advantages of using make on the command-line is that re-running this command will only redo necessary work. If none of the input files have changed, then make will finish immediately; however if one of the input or intermediate files has changed, say by modifying an alpha channel, then only the tasks necessary to integrate that image into the final panorama will be redone.

make options

make supports multiple targets, by default hugin creates an 'all', it also creates a 'clean' target that deletes intermediate files. So you can clean up afterwards like so:

make -f project.pto.mk clean

Internal variables can be overriden by environment variables using the '-e' flag, so to stitch using the alternative nona-mask tool instead of nona, use something like this:

NONA=nona-mask make -e -f project.pto.mk

Alternatively variables can be simply appended to the end of any make command, this does exactly the same thing:

make -f project.pto.mk NONA=nona-mask

In a shell such as bash, setting the environment will modify internal variables for the rest of the session:

Parallel make

make supports parallel processing for machines with multiple cores/processors with the '-j' parameter, so for a 16 core system this command will stitch using 16 parallel processes:

make -j 16 -f project.pto.mk NONA='nona -t 1'

(note that by default nona uses all available cores, in this case it needs to be limited to one thread so that 16 instances of nona can run at the same time)

Stitching queues

Processing a series of projects one after another is simple enough, this command will stitch all the projects in a folder:

for file in *.pto.mk; do make -f $file; done

For more advanced command-line stitching, a tool like distmake will manage a queue of Makefile stitching jobs, and even load-balance multiple machines over a network.

Makefile plugins

A Makefile can be extended with additional targets by creating a second Makefile that includes the original hugin .pto.mk Makefile. For instance a plugin Makefile called 'Makefile.psd.mk' might define a new target called 'ldr_psd' that assembles a multilayer PSD file for manual blending in a tool such as the Gimp:

Holding it all together with panostart

The .pto.mk Makefile helps with the stitching at the end of the process, but doesn't help with the bits at the beginning such as: identifying which photos go in which panorama, generating control points, pruning and optimising.

panostart is a prototype tool that does it all. Given a list of photos in a folder, it identifies likely panoramas by comparing EXIF timestamps and writes a meta-Makefile containing: rules for generating .pto projects with match-n-shift, rules for generating corresponding .pto.mk Makefiles with pto2mk, rules for stitching the projects with make, plus some other rules for creating useful distributable output.

A typical panostart command for dealing with a folder full of photos taken with a pocket point-and-shoot camera on auto-exposure might look like this:

Some of the resulting panoramas will have position, cropping and stitching errors. Fix these by editing the relevant .pto projects in hugin or another tool, when you type make again on the command-line, only those projects that have changed will be restitched.

Another advantage of doing things this way is reproducibility: delete all the (enormous) TIFF output panoramas and all you need to keep permanently are the photos, the meta-Makefile and the associated .pto projects. If you ever need to recreate the TIFF panoramas in the future, just type make. If you know the name of the TIFF file you want, just type 'make project.tif' and only a single panorama will be processed.

Panotools::Script for manipulating project files

The name is a historical mistake, Panotools::Script is a perl library for working with hugin .pto projects, though it could be extended in the future to cover any of the related file formats. Many of the command-line tools described in this document are written with this library.

Here is a trivial script, all it does is open and save a .pto project, it also resets the output ('p' Panorama line) angle of view to 360 degrees (v360), the projection format to equirectangular (f2) and the output pixel size to 4096x2048 pixels (w4096 h2048):

erect2planet - Create a .pto project for extracting a 'little planet' from an equirectangular image

erect2mercator - Create a .pto project for extracting a mercator view from an equirectangular image

Older tools

Helmut Dersch's PTOptimizer and PTStitcher were the original command-line tools. These are not really recommendable any more as they require an older, buggier version of the libpano12 library, they are closed source so don't work on modern systems such as OS X or 64bit Linux, and are lacking in features compared to modern replacements such as autooptimiser and nona.

Useful Image processing tools

ImageMagick - Many utilities for converting, manipulating and resizing images

GraphicsMagick - A fork of ImageMagick with many improvements

libtiff - Supplied with useful tools such as tiffcp for joining and recompression, and tifficc for adding ICC colour profiles