# Combining Multiple Images with Enblend 4.0-753b534c819d

## Enblend

This manual is for Enblend (version 4.0-753b534c819d, 4 December 2009), a tool for compositing images in such a way that the seam between the images is invisible, or at least very difficult to see.

## 1 Overview

Enblend overlays multiple TIFF images using the Burt-Adelson multiresolution spline algorithm.1 This technique tries to make the seams between the input images invisible. The basic idea is that image features should be blended across a transition zone proportional in size to the spatial frequency of the features. For example, objects like trees and windowpanes have rapid changes in color. By blending these features in a narrow zone, you will not be able to see the seam because the eye already expects to see color changes at the edge of these features. Clouds and sky are the opposite. These features have to be blended across a wide transition zone because any sudden change in color will be immediately noticeable.

Enblend expects each input file to have an alpha channel. The alpha channel should indicate the region of the file that has valid image data. Enblend compares the alpha regions in the input files to find the areas where images overlap. Alpha channels can be used to indicate to Enblend that certain portions of an input image should not contribute to the final image.

Enblend does not align images. Use a tool such as hugin or PanoTools to do this. The TIFF files produced by these programs are exactly what Enblend is designed to work with. Sometimes these GUIs allow you to select feathering for the edges of your images. This treatment is detrimental to Enblend. Turn off feathering by deselecting it or setting the feather width to zero.

Enblend blends the images in the order they are specified on the command line. You should order your images according to the way that they overlap, for example from left-to-right across the panorama. If you are making a multi-row panorama, we recommend blending each horizontal row individually, and then running Enblend a last time to blend all of the rows together vertically.

Enblend reads all layers of multi-layer images, like, for example, multi-directory TIFF images2. The input images are processed in the order they appear on the command line. Multi-layer images are processed from the first layer to the last before Enblend considers the next image on the command line.

Find out more about Enblend on its SourceForge web page.

## 2 Workflow

Enblend and Enfuse are parts of a chain of tools to assemble images.

• Enblend combines a series of pictures taken at the same location but in different directions.
• Enfuse merges photos of the same subject at the same location and same direction, but taken with varying exposure parameters.

Figure:photographic-workflow shows where Enblend and Enfuse sit in this tool chain.

Figure 2.1: Photographic workflow with Enblend and Enfuse.

Take Images
Take multiple images to form a panorama, an exposure series, a focus stack, etc.
          There is one exception with Enfuse when a single raw image is
converted multiple times to get several – typically differently
“exposed” – images.


Exemplary Benefits

• Many pictures taken from the same vantage point but showing different viewing directions. – Panorama
• Pictures of the same subject exposed with different shutter speeds. – Exposure series
• Images of the same subject focussed at differing distances. – Focus stack

Remaining Problem: The “overlayed” images may not fit together, that is the overlay regions may not match exactly.

Convert Images
Convert the raw data exploiting the full dynamic range of the camera and capitalize on a high-quality conversion.
Align Images
Align the images so as to make them match as well as possible.
          Again there is one exception and this is when images naturally align.
For example, a series of images taken from a rock solid tripod with a
cable release without touching the camera, or images taken with a
shift lens, can align without further user intervention.


This step submits the images to affine transformations. If necessary, it rectifies the lens' distortions (e.g. barrel or pincushion), too. Sometimes even luminance or color differences between pairs of overlaying images are corrected (“photometric alignment”).

Benefit: The overlay areas of images match as closely as possible given the quality if the input images and the lens model used in the transformation.

Remaining Problem: The images may still not align perfectly, for example, because of parallax errors, or blur produced by camera shake.

Combine Images
Enblend and Enfuse combine the aligned images into one.

Benefit: The overlay areas become imperceptible for all but the most mal-aligned images.

Remaining Problem: Enblend and Enfuse write images with an alpha channel. (For more information on alpha channels see Understanding Masks.) Furthermore, the final image rarely is rectangular.

Postprocess
Postprocess the combined image with your favorite tool. Often the user will want to crop the image and simultaneously throw away the alpha channel.

View

Print

Enjoy

## 3 Invocation

enblend [OPTIONS] [--output=IMAGE] INPUT...

Assemble the sequence of images INPUT... into a single IMAGE.

Input images are either specified literally or via so-called response files (see below). The latter are an alternative to specifying image filenames on the command line.

### 3.1 Response Files

A response file contains names of images or other response filenames. Introduce response file names with an at-character (‘@’).

Enblend and Enfuse process the list INPUT strictly from left to right, expanding response files in depth-first order. (Multi-layer files are processed from first layer to the last.) The following examples only show Enblend, but Enfuse works exactly the same.

Solely image filenames.
Example:
          enblend image-1.tif image-2.tif image-3.tif


The ultimate order in which the images are processed is: image-1.tif, image-2.tif, image-3.tif.

Single response file.
Example:
          enblend @list


where file list contains

          img1.exr
img2.exr
img3.exr
img4.exr


Ultimate order: img1.exr, img2.exr, img3.exr, img4.exr.

Mixed literal names and response files.
Example:
          enblend @master.list image-09.png image-10.png


where file master.list comprises of

          image-01.png
@first.list
image-04.png
@second.list
image-08.png


first.list is

          image-02.png
image-03.png


and second.list contains

          image-05.png
image-06.png
image-07.png


Ultimate order: image-01.png, image-02.png, image-03.png, image-04.png, image-05.png, image-06.png, image-07.png, image-08.png, image-09.png, image-10.png,

#### 3.1.1 Response File Format

Response files contain one filename per line. Blank lines or lines beginning with a sharp sign (‘#’) are ignored; the latter can serve as comments. Filenames that begin with an at-character (‘@’) denote other response files. Table:response-file-format states a formal grammar of response files in EBNF.

 response-file ::= line* line ::= (comment | file-spec) [‘\r’] ‘\n’ comment ::= space* ‘#’ text file-spec ::= space* ‘@’ filename space* space ::= ‘ ’ | ‘\t’

where text is an arbitrary string and filename is any filename.

Table 3.1: EBNF definition of the grammar of response files.

In a response file relative filenames are used relative the response file itself, not relative to the current-working directory of the application.

The above grammar might unpleasantly surprise the user in the some ways.

Whitespace trimmed at both line ends
For convenience, whitespace at the beginning and at the end of each line is ignored. However, this implies that response files cannot represent filenames that start or end with whitespace, as there is no quoting syntax. Filenames with embedded whitespace cause no problems, though.
Comments in response files always occupy a complete line. There are no “line-ending comments”. Thus, in
          # exposure series
img-0.33ev.tif # "middle" EV
img-1.33ev.tif
img+0.67ev.tif


only the first line contains a comment, whereas the second line includes none. Rather, it refers to a file called ‘img-0.33ev.tif # "middle" EV.

An at-sign invariably introduces a response file, even if the filename's extension hints towards an image.

If Enblend or Enfuse do not recognize a response file, they will skip the file and issue a warning. To force a file being recognized as a response file add one of the following syntactic comments to the first line of the file.

     response-file: true
enblend-response-file: true
enfuse-response-file: true


Finally, here is an example of a valid response file.

     # 4\pi panorama!

# These pictures were taken with the panorama head.
@round-shots.list

# Freehand sky shot.
zenith.tif

# "Legs, will you go away?" images.


Comments that follow the format described in Table:response-file-syntactic-comment are treated as instructions how to interpret the rest of the response file. A syntactic comment is effective immediately and its effect persists to the end of the response file, unless another syntactic comment undoes it.

 syntactic-comment ::= space* ‘#’ space* key space* ‘:’ space* value key ::= (‘A’ .. ‘Z’ | ‘a’ .. ‘z’ | ‘-’)+

where value is an arbitrary string.

Table 3.2: EBNF definition of the grammar of syntactic comments in response files.

Unknown syntactic comments are silently ignored.

#### 3.1.3 Globbing Algorithms

The three equivalent syntactic keys

• glob,
• globbing, or
• filename-globbing

control the algorithm that Enblend or Enfuse use to glob filenames in response files.

All versions of Enblend and Enfuse support at least two algorithms: literal, which is the default, and wildcard. See Table:globbing-algorithms for a list of all possible globbing algorithms. To find out about the algorithms in your version of Enblend or Enfuse team up the options --version and --verbose.

literal
Do not glob. Interpret all filenames in response files as literals. This is the default.

Please keep in mind that whitespace at both ends of a line in a response file always gets discarded.

wildcard
Glob using the wildcard characters ‘?’, ‘*’, ‘[’, and ‘]’.

The W*N32 implementation only globs the filename part of a path, whereas all other implementations perform wildcard expansion in all path components. Also see glob(7).

none
Alias for literal.
shell
The shell globbing algorithm works as literal does. In addition, it interprets the wildcard characters ‘{’, ‘}’, and ‘~’. This makes the expansion process behave more like common UN*X shells.
sh
Alias for shell.

Table 3.3: Globbing algorithms for the use in response files

Example:

     # Horizontal panorama
# 15 images

# filename-globbing: wildcard

image_000[0-9].tif
image_001[0-4].tif


### 3.2 Common Options

Common options control some overall features of Enblend.

-a
Pre-assemble non-overlapping images before each blending iteration.

This overrides the default behavior which is to blend the images sequentially in the order given on the command line. Enblend will use fewer blending iterations, but it will do more work in each iteration.

--compression=COMPRESSION
Write a compressed output file.

Depending on the output file format Enblend accepts different values for COMPRESSION.

JPEG
COMPRESSION is a JPEG quality level ranging from 0–100.
TIFF
COMPRESSION is one of the keywords:
NONE
Do not compress. This is the default.
DEFLATE
Use the Deflate compression scheme also called ZIP-in-TIFF. Deflate is a lossless data compression algorithm that uses a combination of the LZ77 algorithm and Huffman coding.
LZW
Use Lempel-Ziv-Welch (LZW) adaptive compression scheme. LZW compression is lossless.
PACKBITS
Use PackBits compression scheme. PackBits is particular variant of run-length compression. It is lossless.

Any other format
Other formats do not accept a COMPRESSION setting.

However, VIGRA automatically compresses png-files with the Deflate method.

-h
--help
Print information on the available options and exit.
-l LEVELS
--levels=LEVELS
Use at most this many LEVELS for pyramid 3 blending if LEVELS is positive, or reduce the maximum number of levels used by −LEVELS if LEVELS is negative.

The number of levels used in a pyramid controls the balance between local and global image features (contrast, saturation, ...) in the blended region. Fewer levels emphasize local features and suppress global ones. The more levels a pyramid has, the more global features will be taken into account.

As a guideline, remember that each new level works on a linear scale twice as large as the previous one. So, the zeroth layer, the original image, obviously defines the image at single-pixel scale, the first level works at two-pixel scale, and generally, the n-th level contains image data at 2^n-pixel scale. This is the reason why an image of width×height pixels cannot be deconstructed into a pyramid of more than $⌊{log}_{2}\left(min\left(\mathit{width},\mathit{height}\right)\right)⌋$levels.

If too few levels are used, “halos” around regions of strong local feature variation can show up. On the other hand, if too many levels are used, the image might contain too much global features. Usually, the latter is not a problem, but is highly desired. This is the reason, why the default is to use as many levels as is possible given the size of the overlap regions. Enblend may still use a smaller number of levels if the geometry of the overlap region demands.

Positive values of LEVELS limit the maximum number of pyramid levels. Depending on the size and geometry of the overlap regions this may or may not influence any pyramid. Negative values of LEVELS reduce the number of pyramid levels below the maximum no matter what the actual maximum is and thus always influence all pyramids.

The valid range of the absolute value of LEVELS is 1 to 29.

-o
--output=FILE
Place output in FILE.

If --output is not specified, the default is to put the resulting image in a.tif.

-v
--verbose[=LEVEL]
Without an argument, increase the verbosity of progress reporting. Giving more --verbose options will make Enblend more verbose. Directly set a verbosity level with a non-negative integral LEVEL.

Each level includes all messages of the lower levels.

Level
Messages
0
only warnings and errors
1
2
3
reading of response files, color conversions
4
image sizes, bounding boxes and intersection sizes
5
detailed information on the optimizer runs (Enblend only)
6
estimations of required memory in selected processing steps

The default verbosity level of Enblend is 1.

-V
--version
Output information on the Enblend version.

Team this option with --verbose to inquire about configuration details, like the extra features that have been compiled in.

-w
--wrap=MODE
Blend around the boundaries of the panorama.

With this option Enblend treats the panorama of width w and height h as an infinite data structure, where each pixel P(x, y) of the input images represents the set of pixels S_P(x, y)4.

MODE takes the following values:

none
open
This is a “no-op”; it has the same effect as not giving --wrap at all. The set of input images is considered open at its boundaries.
horizontal
Wrap around horizontally: ${S}_{P}\left(x,y\right)=\left\{P\left(x+mw,y\right):m\text{ in }Z\right\}\text{.}$This is useful for 360° horizontal panoramas as it eliminates the left and right borders.
vertical
Wrap around vertically: ${S}_{P}\left(x,y\right)=\left\{P\left(x,y+nh\right):n\text{ in }Z\right\}\text{.}$This is useful for 360° vertical panoramas as it eliminates the top and bottom borders.
both
horizontal+vertical
vertical+horizontal
Wrap around both horizontally and vertically: ${S}_{P}\left(x,y\right)=\left\{P\left(x+mw,y+nh\right):m,n\text{ in }Z\right\}\text{.}$In this mode, both left and right borders, as well as top and bottom borders, are eliminated.

Specifying --wrap without MODE selects horizontal wrapping.

-x
Checkpoint partial results to the output file after each blending step.

### 3.3 Extended Options

Extended options control the image cache, the color model, and the cropping of the output image.

-b BLOCKSIZE
Set the BLOCKSIZE in kilobytes (KB) of Enblend's image cache.

This is the amount of data that Enblend will move to and from the disk at one time. The default is 2048KB, which should be ok for most systems. See Tuning Memory Usage for details.

Note that Enblend must have been compiled with the image-cache feature for this option to be effective. Find out about extra features with enblend --version --verbose.

-c
Use the CIECAM02 color appearance model for blending colors.

The input files should have embedded ICC profiles if this option is specified. If no ICC profile is present, Enblend will assume that the image uses the sRGB color space. The difference between this option and Enblend's default color blending algorithm is very slight and will only be noticeable when areas of different primary colors are blended together.

-d
--depth=DEPTH
Force the number of bits per channel and the numeric format of the output image.

Enblend always uses a smart way to change the channel depth to assure highest image quality (at the expense of memory), whether requantization is implicit because of the output format or explicit with option --depth.

• If the output-channel width is larger than the input-channel width of the input images, the input images' channels are widened to the output channel width immediately after loading, that is, as soon as possible. Enblend then performs all blending operations at the output-channel width, thereby preserving minute color details which can appear in the blending areas.
• If the output-channel width is smaller than the input-channel width of the input images, the output image's channels are narrowed only right before it is written to disk, that is, as late as possible. Thus the data benefits from the wider input channels for the longest time.

All DEPTH specifications are valid in lowercase as well as uppercase letters. For integer format, use

8, uint8
Unsigned 8bit; range: 0..255
int16
Signed 16bit; range: −32768..32767
16, uint16
Unsigned 16bit; range: 0..65535
int32
Signed 32bit; range: −2147483648..2147483647
32, uint32
Unsigned 32bit; range: 0..4294967295

For floating-point format, use

r32, real32, float
IEEE754 single precision floating-point, 32bit wide, 24bit significant
• Minimum normalized value: $1.2×{10}^{-38}$
• Epsilon: $1.2×{10}^{-7}$
• Maximum finite value: $3.4×{10}^{38}$

r64, real64, double
IEEE754 double precision floating-point, 64bit wide, 53bit significant
• Minimum normalized value: $2.2×{10}^{-308}$
• Epsilon: $2.2×{10}^{-16}$
• Maximum finite value: $1.8×{10}^{308}$

If the requested DEPTH is not supported by the output file format, Enblend warns and chooses the DEPTH that matches best.

The OpenEXR data format is treated as IEEE754 float internally. Externally, on disk, OpenEXR data is represented by “half” precision floating-point numbers.

OpenEXR half precision floating-point, 16bit wide, 10bit significant

• Minimum normalized value: $9.3×{10}^{-10}$
• Epsilon: $2.0×{10}^{-3}$
• Maximum finite value: $4.3×{10}^{9}$

-f WIDTHxHEIGHT
-f WIDTHxHEIGHT+xXOFFSET+yYOFFSET
Set the size of the output image manually to WIDTH×HEIGHT. Optionally specify the X-OFFSET and Y-OFFSET, too.

This option is useful when the input images are cropped TIFF files, such as those produced by nona. The stitcher nona is part of Hugin. See Helpful Programs.

-g
Save alpha channel as “associated”. See the TIFF documentation for an explanation.

Gimp (before version 2.0) and Cinepaint (see Helpful Programs) exhibit unusual behavior when loading images with unassociated alpha channels. Use option -g to work around this problem. With this flag Enblend creates the output image with the associated alpha tag set, even though the image is really unassociated alpha.

--gpu
Use the graphics card – in fact the graphics processing unit (GPU) – to accelerate some computations.

This is an experimental feature that may not work on all systems. In this version of Enblend, 4.0-753b534c819d, only mask optimization strategy 1 benefits from this option.

Note that GPU-support must have been compiled into Enblend for this option to be available. Find out about this feature with enblend --version --verbose.

-m CACHESIZE
Set the CACHESIZE in megabytes (MB) of Enblend's image cache.

This is the amount of memory Enblend will use for storing image data before swapping to disk. The default is 1024MB which is good for systems with 3–4gigabytes (GB) of RAM. See Tuning Memory Usage for details.

Note that Enblend must have been compiled with the image-cache feature for this option to be effective. Find out about extra features with enblend --version --verbose.

These options control the generation and the usage of masks.

--anneal=TAU[:DELTA-E-MAX[:DELTA-E-MIN[:K-MAX]]]
Set the parameters of the Simulated Annealing optimizer used in Optimizer Strategy 1 (see Table:optimizer-strategies).
TAU
TAU is the temperature reduction factor in the Simulated Annealing; it also can be thought of as “cooling factor”. The closer TAU is to one, the more accurate the annealing run will be, and the longer it will take.

Append a percent sign (‘%’) to specify TAU as a percentage.

Valid range: $0<\mathit{TAU}<1\text{.}$

The default is 0.75; values around 0.95 are reasonable. Usually, slower cooling results in more converged points.

DELTA-E-MAX
DELTA-E-MIN
DELTA-E-MAX and DELTA-E-MIN are the maximum and minimum cost change possible by any single annealing move.

Valid range: $0<\mathit{DELTA-E-MIN}<\mathit{DELTA-E-MAX}\text{.}$

In particular they determine the initial and final annealing temperatures according to: