align_image_stack is a command-line tool to align overlapping images to facilitate HDR creation, Exposure blending[*], extended Depth of Field, and Stereoscopic[*] images.

Usage

align_image_stack [options] input_files

Options: modes of operation

As main switch you have to specify which type of results align_image_stack should produce. It can be a pto file for further tweaking, multiple tiff files for further processing with other programs or a HDR file. You can also combine these switches and output so several different output formats at once.

-p file

Output .pto file. (Useful for debugging, or further refinement.)

-a prefix

Align images, output as prefix_xxxx.tif.

-o output

Merge images to HDR, generate output.hdr.

Options: modifiers

The workflow of align_image_stack can be divided into several steps:

Load all images and provide some necessary information about the images
Find interest points in first image
Correlate interest points with second image
Repeat step 2 and 3 for each consecutive image pair
Optimize positions and lens parameters
Remap all images and output result files

There are several switches which affects only parts of the process. These will be described in the following.

General switches

-v

Verbose, print progress messages. Repeat for higher verbosity (prints more progress messages).

-h

Display help.

 --align-to-first

Align all images to the first one instead of the default workflow of matches of all consecutive image pairs. This activates also the --use-given-order option.

Image information

You need to provide some information about the images so align_image_stack can assume some pre requirement for the processing. It tries to read these information from the EXIF data, but if these data are missing or incomplete you need to provide these on the command line.

-e

Assume input images are full frame fish eye (default: rectilinear).

-f HFOV

Approximate horizontal field of view[*] of input images. Use if EXIF info not complete.

-l

Assume input files are in linear color space.

--distortion

Try to load distortion information from lens database. That has the advantage that during the remapping step the lens distortion and the corrections of the image positions are done in one processing step.

--use-given-order

Use the image order as given from command line. By default (without this switch) images will be sorted by exposure values as found in EXIF data.

Control point detection

The internal processing in this step is done on a scaled down image for speed reason. The first image is split into gsize x gsize subregions. In each subregion num interest points are created.

-s scale

Scale down image by 2^scale (default: 1 [2x downsampling]). Scaling down images will improve speed at the cost of accuracy. This affects only the internal processing.

-g gsize

Break image into a rectangular grid (gsize x gsize) and attempt to find num control points in each section (default: 5 [5x5 grid] )

-c num

Number of control points (per grid, see option -g) to create between adjacent images (default: 8).

--corr=num

Correlation threshold for identifying control points (default: 0.9). If there is some blur in the images try to decrease this value to e.g. 0.8 or 0.7.

Optimization phase

By default only the image position (yaw, pitch and roll) are optimized. For special use cases you can optimize further parameters like field of view or lens distortion.

-m

Optimize field of view for all images, except for first. Useful for aligning focus stacks with slightly different magnification.

-d

Optimize radial distortion for all images, except for first.

-i

Optimize image center shift for all images, except for first.

-x

Optimize X coordinate of the camera position.

-y

Optimize Y coordinate of the camera position.

-z

Optimize Z coordinate of the camera position. Useful for aligning more distorted images.

-t num

After a first optimization run the result is checked and all control points with an error higher than num pixels are removed. The default value is 3. Then a second optimizer runs follows with only the "good" control points.

Generating stereo image pairs

Align_image_stack can also be used for the alignment of stereoscopic images, see [1] for more details about these options

-S

Assume stereo images - allow horizontal shift of control points. Adds all control points as "horizontal lines".

-A

Align stereo window - this activates also the -S switch. Adds one "normal" control point that is the nearest point, so that everything will appear behind the display plane.

-P

Align stereo window with pop-out effect - this activates also the -S switch. Adds one "normal" control point that is the nearest point from the border areas, so that the center of the image may appear in front of the display plane.

Remapping stage

The follow switches affect the process of remapping of the individual images

-C

Auto crop the image to the area covered by all images, otherwise the result files can contain transparent (black) borders which are not covered from all images

 --dont-remap-ref

Don't output the remapped reference image (the first image specified at the command line).

 --gpu

Use GPU for remapping

Align image stack