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.

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.

+

+

== Generating the project file ==

+

+

Most of [[hugin]] tools take a pto file as input and output. So the first step is to create this pto file. For this purpose use [[pto_gen]].

+

pto_gen *.jpg

+

will put all jpg files in the current directory into one project file with a default name. You can also specify single images and your own project name

+

pto_gen -o project.pto image1.jpg image2.jpg image3.jpg

+

You can specify more options to the project (see [[pto_gen]] for details).

== Generating control points ==

== Generating control points ==

−

There are a number of tools available for generating [[control points]] from groups of photos, such as [[autopano-sift]], [[autopano-sift-c]], [[panomatic]] and [[match-n-shift]]. Here is an example using autopano-sift-c:

+

There are a number of tools available for generating [[control points]] from groups of photos, like [[cpfind]]. Here is an example using cpfind

+

cpfind --multirow -o project.pto project.pto

+

+

Hint: Other control points generator, such as [[autopano-sift]], [[autopano-sift-c]], [[panomatic]] and [[match-n-shift]] take a list of images instead of a project. In this case the pto generation and control point generation are one step. Here is an example for autopano-sift-c:

If you need finer control above the optimisation, set the parameter which should be optimized with [[pto_var]] and then run [[autooptimiser]] with switch -n:

+

+

pto_var --opt y,p,r -o project.pto project.pto

+

autooptimiser -n -o project.pto project.pto

([[PToptimizer]] is an alternative geometrical optimiser)

([[PToptimizer]] is an alternative geometrical optimiser)

Line 74:

Line 90:

autooptimiser -m -o project.pto project.pto

autooptimiser -m -o project.pto project.pto

−

For full manual control for photometric parameters use [[vig_optimize]]. This program does the equivalent job for photometric parameters as [[autooptimiser]] does for geometric parameters. You need to indicate in the .pto project which parameters are 'variables'. For this task you can edit the .pto file or use a tool such as [[ptovariable]]:

+

For full manual control for photometric parameters use [[vig_optimize]]. This program does the equivalent job for photometric parameters as [[autooptimiser]] does for geometric parameters. You need to indicate in the .pto project which parameters are 'variables'. For this task you can edit the .pto file or use a tool such as [[pto_var]] or [[ptovariable]]:

ptovariable --vignetting --response --exposure project.pto

ptovariable --vignetting --response --exposure project.pto

vig_optimize -o project.pto project.pto

vig_optimize -o project.pto project.pto

+

+

pto_var --opt Vb,Vx,Ra,EeV -o project.pto project.pto

+

vig_optimize -o project.pto project.pto

+

+

== Setting output options ==

+

+

For setting the output option (like on the [[Hugin_Stitcher_tab|stitcher tab]]) use [[pano_modify]]:

Revision as of 16:52, 19 February 2014

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 less used today, 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.

Generating the project file

Most of hugin tools take a pto file as input and output. So the first step is to create this pto file. For this purpose use pto_gen.

pto_gen *.jpg

will put all jpg files in the current directory into one project file with a default name. You can also specify single images and your own project name

pto_gen -o project.pto image1.jpg image2.jpg image3.jpg

You can specify more options to the project (see pto_gen for details).

Generating control points

There are a number of tools available for generating control points from groups of photos, like cpfind. Here is an example using cpfind

cpfind --multirow -o project.pto project.pto

Hint: Other control points generator, such as autopano-sift, autopano-sift-c, panomatic and match-n-shift take a list of images instead of a project. In this case the pto generation and control point generation are one step. Here is an example for autopano-sift-c:

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.

For doing an automatic photometric optimisation like Hugin's assistant, run autooptimiser with -m switch:

autooptimiser -m -o project.pto project.pto

For full manual control for photometric parameters use vig_optimize. This program does the equivalent job for photometric parameters as autooptimiser does for geometric parameters. You need to indicate in the .pto project which parameters are 'variables'. For this task you can edit the .pto file or use a tool such as pto_var or 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