\input auxmac
\input texinfo


@c
@c Header
@c

@c %**start of header
@setfilename enblend.info
@include versenblend.texi
@settitle Combining Multiple Images with Enblend @value{VERSION}
@include auxmac.texi
@include varsenblend.texi
@include config-h.texi

@set default-image-cache-cachesize 1024@dmn{MB}
@set default-image-cache-blocksize 2048@dmn{KB}

@c Define a new index for syntactic comments.
@defcodeindex sc
@c Define a new index for options.
@defcodeindex op
@c %**end of header


@c
@c Categorization for the GNU Info System
@c

@dircategory Individual utilities

@direntry
* enblend: (enblend).                   Blend images using a multiresolution spline.
@end direntry


@c
@c Summary Description and Copyright
@c

@copying
This manual is for Enblend (version @value{VERSION}, @value{UPDATED}),
a tool for compositing images in such a way that the seam between the
images is invisible, or at least very difficult to see.

Copyright @copyright{} 2004--2014 @sc{Andrew Mihal}.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the @acronym{GNU} Free Documentation License,
Version 1.2 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts and no
Back-Cover Texts.  A copy of the license is included in the section
entitled ``@acronym{GNU} Free Documentation License''.
@end quotation
@end copying


@c
@c Title Page and Copyright
@c

@titlepage
@title Enblend
@subtitle Combining Multiple Images
@subtitle with Enblend version @value{VERSION}, @value{UPDATED}

@author Andrew Mihal

@page
@vskip 0pt plus 1fill
@insertcopying
@end titlepage


@c Enblend's TOC is so small that we do not need a Summary-TOC yet.
@c @ifnothtml
@c @summarycontents
@c @end ifnothtml
@contents


@c For the TeX output the List-of-Tables and List-of-Figures appear
@c right after the Table-of-Contents.  In all other formats they go
@c right before the indices.
@iftex
@c Adjust page number so that we get roman numerals for the
@c List-of-Tables and List-of-Figures.  This screws up Texinfo's page
@c count so that we must undo it later.
@tex
\global\pageno=-4
@end tex

@unnumbered List of Tables
@listoffloats Table


@unnumbered List of Figures
@listoffloats Figure
@end iftex


@c
@c ``Top'' Node and Master Menu
@c

@ifnottex
@node Top
@top Enblend

This manual is for Enblend (version@tie{}@value{VERSION},
@value{UPDATED}), a tool for compositing images in such a way that the
seam between the images is invisible, or at least very difficult to
see.
@end ifnottex

@menu
* Overview::                    Overview of Enblend's features
* Workflow::                    Enblend's role in making panoramas
* Invocation::                  Command line options and arguments
* Primary Seam Generators::     Differences between available seam generators
* Color Profiles::              How Enblend handles @acronym{ICC} color profiles
* Understanding Masks::         How to interpret masks and mask files
* Tuning Memory Usage::         Balancing @acronym{RAM} and swap
* Helpful Programs::            Useful other programs
* Bug Reports::                 How to write bug reports
* Authors::                     Major contributors
* FDL::                         @acronym{GNU} Free Documentation License
@ifnotdocbook
* Program Index::               Names of programs referenced
* Syntactic-Comment Index::     Keys of syntactic comments
* Option Index::                Index of all options
* General Index::               Topic index
@end ifnotdocbook
@end menu


@c
@c Document Body
@c

@node Overview
@chapter Overview

@c Undo the roman page numbering we used for the Table-of-Contents,
@c the List-of-Tables, and the List-of-Figures.
@tex
\global\pageno=1
@end tex

@cindex overview

@cindex Burt-Adelson multiresolution spline
Enblend overlays multiple images using the @sc{Burt}-@sc{Adelson}
multiresolution spline algorithm.@footnote{@sc{Peter J. Burt} and
@sc{Edward H. Adelson}, ``A Multiresolution Spline With Application to
Image Mosaics'', @acronym{ACM} Transactions on Graphics, @abbr{Vol@.}
2, @abbr{No@.} 4, October 1983, pages 217--236.}  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.

@cindex alpha channel
@cindex channel, alpha
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.

@pindex hugin
@pindex PanoTools
@cindex feathering, detrimental effect of
Enblend does @emph{not} align images.  Use a tool such as
@command{hugin} or PanoTools to do this.  The
@acronym{TIFF}@tie{}files produced by these programs are exactly what
Enblend is designed to work with.  Sometimes these @acronym{GUI}s
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.

@cindex multi-layer image
@cindex image, multi-layer
@cindex multi-directory @acronym{TIFF}
@cindex @acronym{TIFF}, multi-directory
@cindex @command{tiffcopy}
@cindex @command{tiffsplit}
Enblend reads all layers of multi-layer images, like, for example,
multi-directory @acronym{TIFF} images@footnote{Use utilities like,
e.g., @command{tiffcopy} and @command{tiffsplit} of LibTIFF to
manipulate multi-directory @acronym{TIFF} images.  @xref{Helpful
Programs}.}.  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.

@cindex SourceForge
Find out more about Enblend on its @uref{http://@/sourceforge.net/,
SourceForge} @uref{http://@/enblend.sourceforge.net/, web page}.


@node Workflow
@chapter Workflow
@cindex workflow

Enblend is a part of a chain of tools to assemble images.  It combines
a series of pictures taken at the same location but in different
directions.

@menu
* Standard Workflow::           The usual, all-in-one thing
* External Mask Manipulation::  Fiddling around with the masks yourself
@end menu


@node Standard Workflow
@section Standard Workflow
@cindex workflow, standard

@include workflow.texi


@node External Mask Manipulation
@section External Mask Manipulation
@cindex workflow, external mask manipulation

@include external-masks.texi


@node Invocation
@chapter Invocation
@cindex invocation

@command{enblend} [@var{OPTIONS}] [@code{--output=}@var{IMAGE}]
@var{INPUT}@enddots{}

@noindent
Assemble the sequence of images @var{INPUT}@dots{} into a single
@var{IMAGE}.

@cindex literal filename
@cindex filename, literal
@cindex response file
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.


@menu
* Image Requirements::          Input image requirements
* Response Files::              Files listing the images' names
* Common Options::              General options
* Extended Options::            Memory and @acronym{GPU} control
* Mask Generation Options::     Mask generation control
@end menu


@node Image Requirements
@section Image Requirements
@cindex input image requirements

All input images must comply with the following requirements.

@itemize
@item
Parts of the images overlap.

@item
Each image has an alpha channel also called ``mask''.

@item
The images agree on their number of channels:
@itemize --
@item
one plus alpha or
@item
three plus alpha.
@end itemize

This is, either all images are black-and-white (one channel and alpha
channel) or all are @acronym{RGB}-color images (three channels and
alpha channel).

@item
The images agree on their number of bits-per-channel, this is, their
``depth'':
@itemize --
@item
@code{UINT8},
@item
@code{UINT16},
@item
@code{FLOAT},
@item
etc.
@end itemize

See option@tie{}@option{--depth} below for an explanation of different
(output) depths.

@item
Enblend understands the images' filename extensions as well as their
file formats.

You can check the supported extensions and formats by calling Enblend
with the option pair @option{--version@tie{}--verbose} and scan the
output for @samp{Supported image formats} or @samp{Supported file
extensions}.
@end itemize

Moreover, there are some ``good practices'', which are not enforced by
the application, but almost certainly deliver superior results.

@itemize
@item
Either all files lack an @acronym{ICC} profile, or all images are
supplied with the @emph{same} @acronym{ICC} profile.

@item
If the images' meta-data contains resolution information
(``@acronym{DPI}''), it is the same for all pictures.
@end itemize


@node Response Files
@section Response Files
@cindex response file

@include filespec.texi


@node Common Options
@section Common Options
@cindex options, common

Common options control some overall features of Enblend.

Enblend accepts arguments to any option in uppercase as well as in
lowercase letters.  For example, @samp{deflate}, @samp{Deflate} and
@samp{DEFLATE} as arguments to the @code{--compression} option
described below, all instruct Enblend to use the @sc{Deflate}
compression scheme.  This manual denotes all arguments in lowercase
for consistency.

@table @code
@item -a
@opindex -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.

@item --compression=@var{COMPRESSION}
@opindex --compression
@cindex output file compression
@cindex compression
Write a compressed output file.

Depending on the output file format, Enblend accepts different values
for @var{COMPRESSION}.

@table @asis
@item @acronym{JPEG} format.
@cindex @acronym{JPEG} compression
@cindex compression, @acronym{JPEG}

The compression either is a literal integer or a keyword-option
combination.

@table @code
@item @var{LEVEL}
Set @acronym{JPEG} quality@tie{}@var{LEVEL}, where @var{LEVEL} is an
integer that ranges from 0--100.

@item jpeg[:@var{LEVEL}]
Same as above; without the optional argument just switch on (standard)
@acronym{JPEG} compression.

@item jpeg-arith[:@var{LEVEL}]
@cindex arithmetic @acronym{JPEG} compression
@cindex compression, arithmetic @acronym{JPEG}
Switch on arithmetic @acronym{JPEG} compression.  With optional
argument set the arithmetic compression@tie{}@var{LEVEL}, where
@var{LEVEL} is an integer that ranges from 0--100.
@end table

@item @acronym{TIF} format.
Here, @var{COMPRESSION} is one of the keywords:

@table @code
@item none
Do not compress.  This is the default.

@item deflate
@cindex deflate compression
@cindex compression, deflate
Use the @sc{Deflate} compression scheme also called
@acronym{ZIP}-in-@acronym{TIFF}.  @sc{Deflate} is a lossless data
compression algorithm that uses a combination of the @acronym{LZ77}
algorithm and @sc{Huffman} coding.

@item jpeg[:@var{LEVEL}]
@cindex compression, @acronym{JPEG}
Use @acronym{JPEG} compression.  With optional argument set the
compression@tie{}@var{LEVEL}, where @var{LEVEL} is an integer that
ranges from 0--100.

@item lzw
@cindex @acronym{LZW} compression
@cindex compression, @acronym{LZW}
Use @sc{Lempel}-@sc{Ziv}-@sc{Welch} (@acronym{LZW}) adaptive
compression scheme.  @acronym{LZW} compression is lossless.

@item packbits
@cindex packbits compression
@cindex compression, packbits
Use @sc{PackBits} compression scheme.  @sc{PackBits} is a particular
variant of run-length compression; it is lossless.
@end table

@item Any other format.
Other formats do not accept a @var{COMPRESSION} setting.

However, @uref{http://@/hci.iwr.uni-@/heidelberg.de/@/vigra/,
@acronym{VIGRA}} automatically compresses @file{png}-files with the
@sc{Deflate} method.
@end table

@item --layer-selector=@var{ALGORITHM}
@opindex --layer-selector
@cindex layer selection
@cindex layer selection
Override the standard layer selector algorithm, which is
@samp{@value{src::layer-selector}}.

This version of Enblend offers the following algorithms:
@table @code
@item all-layers
@cindex layer selection, all layers
Select all layers in all images.

@item first-layer
@cindex layer selection, first layer
Select only first layer in each multi-layer image.  For single-layer
images this is the same as @samp{all-layers}.

@item largest-layer
@cindex layer selection, largest-layer
Select largest layer in each multi-layer image, where the
``largeness'', this is the size is defined by the product of the layer
width and its height.  The channel width of the layer is ignored.  For
single-layer images this is the same as @samp{all-layers}.

@item no-layer
@cindex layer selection, no layer
Do not select any layer in any image.

This algorithm is useful to temporarily exclude some images in
response files.
@end table

@item -h
@itemx --help
@opindex -h
@opindex --help
Print information on the available options and exit.

@item -l @var{LEVELS}
@itemx --levels=@var{LEVELS}
@opindex -l
@opindex --levels
@cindex pyramid levels
@cindex levels, pyramid
Use at most this many @var{LEVELS} for pyramid @footnote{As
Dr.@tie{}Daniel Jackson correctly
@uref{http://stargate.wikia.com/@/wiki/@/The_@/Tomb, noted}, actually,
it is not a pyramid: ``Ziggaurat, it's a
@uref{http://en.wikipedia.org/@/wiki/@/Ziggaurat, Ziggaurat}.''}
blending if @var{LEVELS} is positive, or reduce the maximum number of
levels used by @minus{}@var{LEVELS} if @var{LEVELS} is negative;
@samp{auto} or @samp{automatic} restore the default, which is to use
the maximum possible number of levels for each overlapping region.

The number of levels used in a pyramid controls the balance between
local and global image features (contrast, saturation, @dots{}) 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 @math{n}-th
level contains image data at @power{2, n}-pixel scale.  This is the
reason why an image of
@math{width}@classictimes{}@/@math{height}@dmn{pixels} cannot be
deconstructed into a pyramid of more than
@ifinfo
@display
@math{floor(log_2(min(width, height)))}
@end display
@end ifinfo
@html
<mathinline xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
    <mrowinline>
        <mo>&LeftFloor;</mo>
        <mrowinline>
            <msubinline>
                <mo>log</mo>
                <mn>2</mo>
            </msubinline>
            <mo>&ApplyFunction;</mo>
            <mo>(</mo>
            <mrowinline>
                <mo>min</mo>
                <mo>&ApplyFunction;</mo>
                <mfencedinline>
                    <mi mathvariant="italic">width</mi>
                    <mi mathvariant="italic">height</mi>
                </mfencedinline>
            </mrowinline>
            <mo>)</mo>
        </mrowinline>
        <mo>&RightFloor;</mo>
    </mrowinline>
</mathinline>
@end html
@tex
$\lfloor \log_2(\min(\mathit{width}, \mathit{height})) \rfloor$
@end tex
@docbook
<inlineequation>
    <mml:math>
        <mml:apply>
            <mml:floor/>
            <mml:apply>
                <mml:log/>
                <mml:logbase>
                    <mml:cn>2</mml:cn>
                </mml:logbase>
                <mml:apply>
                    <mml:min/>
                    <mml:csymbol>
                        <mml:mi mathvariant="italic">width</mml:mi>
                    </mml:csymbol>
                    <mml:csymbol>
                        <mml:mi mathvariant="italic">height</mml:mi>
                    </mml:csymbol>
                </mml:apply>
            </mml:apply>
        </mml:apply>
    </mml:math>
</inlineequation>&nbsp;
@end docbook
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 @var{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
@var{LEVELS} reduce the number of pyramid levels below the maximum no
matter what the actual maximum is and thus always influence all
pyramids.  Use @samp{auto} or @samp{automatic} as @var{LEVELS} to
restore the automatic calculation of the maximum number of levels.

The valid range of the absolute value of @var{LEVELS} is
@value{src::minimum-pyramid-levels} to
@value{src::maximum-pyramid-levels}.

@item -o
@itemx --output=@var{FILE}
@opindex -o
@opindex --output
Place output in @var{FILE}.

@cindex @file{@value{src::default-output-filename}}
@cindex default output filename
@cindex output filename, default
If @option{--output} is not specified, the default is to put the
resulting image in @file{@value{src::default-output-filename}}.

@item --parameter=@var{KEY}[=@var{VALUE}]:@dots{}
@opindex --parameter
Set a @var{KEY}-@var{VALUE} pair, where @var{VALUE} is optional.  This
option is cumulative.  Separate multiple pairs with the usual numeric
delimiters.

This option has the negated form @option{--no-parameter},
@opindex --no-parameter
which takes one or more @var{KEY}s and removes them from the list of
defined parameters.  The special key@tie{}@samp{*} deletes all
parameters at once.

Parameters allow the developers to change the internal workings of
Enblend without the need to recompile.

@item -v
@itemx --verbose[=@var{LEVEL}]
@opindex -v
@opindex --verbose
Without an argument, increase the verbosity of progress reporting.
Giving more @option{--verbose}@tie{}options will make Enblend more
verbose.  Directly set a verbosity level with a non-negative integral
@var{LEVEL}.

Each level includes all messages of the lower levels.

@table @asis
@item Level
Messages

@item 0
only warnings and errors

@item 1
reading and writing of images

@item 2
mask generation, pyramid, and blending

@item 3
reading of response files, color conversions

@item 4
image sizes, bounding boxes and intersection sizes

@item 5
detailed information on the optimizer runs (Enblend only)

@item 6
estimations of required memory in selected processing steps
@end table

The default verbosity level of Enblend is
@value{src::default-verbosity-level}.

@item -V
@itemx --version
@opindex -V
@opindex --version
Output information on the Enblend version.

Team this option with @option{--verbose} to show configuration
details, like the extra features that have been compiled in.

@item -w
@itemx --wrap=@var{MODE}
@opindex -w
@opindex --wrap
@cindex 360@textdegree{} panoramas
@cindex wrap around
Blend around the boundaries of the panorama.

As this option significantly increases memory usage and computation
time only use it, if the panorama will be

@itemize
@item
consulted for any kind measurement, this is, all boundaries must match
as accurately as possible, or

@item
printed out and the boundaries glued together, or

@item
@cindex virtual reality
fed into a virtual reality (@abbr{VR}) generator, which creates a
seamless environment.
@end itemize

Otherwise, always avoid this option!

With this option Enblend treats the panorama of width@tie{}@math{w}
and height@tie{}@math{h} as an infinite data structure, where each
pixel@tie{}@math{P(x, y)} of the input images represents the set of
pixels
@ifinfo
@math{S_P(x, y)}
@end ifinfo
@html
<mathinline xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
    <mrowinline>
        <msubinline>
            <mi>S</mi>
            <mi>P</mi>
        </msubinline>
        <mfencedinline>
            <mi>x</mi>
            <mi>y</mi>
        </mfencedinline>
    </mrowinline>
</mathinline>
@end html
@tex
$S_P(x, y)$
@end tex
@docbook
<inlineequation>
    <mml:math>
        <mml:apply>
            <mml:csymbol>
                <mml:msub>
                    <mml:mi>S</mml:mi>
                    <mml:mi>P</mml:mi>
                </mml:msub>
            </mml:csymbol>
            <mml:ci>x</mml:ci>
            <mml:ci>y</mml:ci>
        </mml:apply>
    </mml:math>
</inlineequation>
@end docbook
@footnote{Solid-state physicists will be reminded of the
@uref{http://@/en.wikipedia.org/@/wiki/@/Born-@/von_@/Karman_@/boundary_@/condition,
@sc{Born}-@sc{von@tie{}K@'arm@'an} boundary condition}.}.

@var{MODE} takes the following values:

@table @samp
@item none
@itemx open
This is a ``no-op''; it has the same effect as not giving
@option{--wrap} at all.  The set of input images is considered open at
its boundaries.

@item horizontal
Wrap around horizontally:
@ifinfo
@display
@math{S_P(x, y) = @{P(x + m * w, y): m in Z@}.}
@end display
@end ifinfo
@html
<math xmlns="http://www.w3.org/1998/Math/MathML" display="separate">
    <mrow>
        <msub>
            <mi>S</mi>
            <mi>P</mi>
        </msub>
        <mfenced>
            <mi>x</mi>
            <mi>y</mi>
        </mfenced>
        <mo>=</mo>
        <mrow>
            <mo>&lcub;</mo>
            <mrow>
                <mi>P</mi>
                <mfenced>
                    <mrow>
                        <mi>x</mi>
                        <mo>+</mo>
                        <mi>m</mi>
                        <mo>&InvisibleTimes;</mo>
                        <mi>w</mi>
                    </mrow>
                    <mi>y</mi>
                </mfenced>
            </mrow>
            <mo>:</mo>
            <mrow>
                <mi>m</mi>
                <mtext>&ThickSpace;in&ThickSpace;</mtext>
                <mi>Z</mi>
            </mrow>
            <mo>&rcub;</mo>
        </mrow>
        <mtext>.</mtext>
    </mrow>
</math>
@end html
@tex
$$
    S_P(x, y) = \{P(x + m w, y): m \in Z\}.
$$
@end tex
@docbook
<informalequation>
    <mml:math>
        <mml:reln>
            <mml:eq/>
            <mml:apply>
                <mml:csymbol>
                    <mml:msub>
                        <mml:mi>S</mml:mi>
                        <mml:mi>P</mml:mi>
                    </mml:msub>
                </mml:csymbol>
                <mml:ci>x</mml:ci>
                <mml:ci>y</mml:ci>
            </mml:apply>
            <mml:set>
                <mml:bvar>
                    <mml:apply>
                        <mml:ci>P</mml:ci>
                        <mml:apply>
                            <mml:plus/>
                            <mml:ci>x</mml:ci>
                            <mml:apply>
                                <mml:times/>
                                <mml:ci>m</mml:ci>
                                <mml:ci>w</mml:ci>
                            </mml:apply>
                        </mml:apply>
                        <mml:ci>y</mml:ci>
                    </mml:apply>
                </mml:bvar>
                <mml:condition>
                    <mml:apply>
                        <mml:in/>
                        <mml:ci>m</mml:ci>
                        <mml:ci>Z</mml:ci>
                    </mml:apply>
                </mml:condition>
            </mml:set>
        </mml:reln>
    </mml:math>
</informalequation>
@end docbook

This is useful for 360@textdegree{} horizontal panoramas as it
eliminates the left and right borders.

@item vertical
Wrap around vertically:
@ifinfo
@display
@math{S_P(x, y) = @{P(x, y + n * h): m in Z@}.}
@end display
@end ifinfo
@html
<math xmlns="http://www.w3.org/1998/Math/MathML" display="separate">
    <mrow>
        <msub>
            <mi>S</mi>
            <mi>P</mi>
        </msub>
        <mfenced>
            <mi>x</mi>
            <mi>y</mi>
        </mfenced>
        <mo>=</mo>
        <mrow>
            <mo>&lcub;</mo>
            <mrow>
                <mi>P</mi>
                <mfenced>
                    <mi>x</mi>
                    <mrow>
                        <mi>y</mi>
                        <mo>+</mo>
                        <mi>n</mi>
                        <mo>&InvisibleTimes;</mo>
                        <mi>h</mi>
                    </mrow>
                </mfenced>
            </mrow>
            <mo>:</mo>
            <mrow>
                <mi>n</mi>
                <mtext>&ThickSpace;in&ThickSpace;</mtext>
                <mi>Z</mi>
            </mrow>
            <mo>&rcub;</mo>
        </mrow>
        <mtext>.</mtext>
    </mrow>
</math>
@end html
@tex
$$
    S_P(x, y) = \{P(x, y + n h): n \in Z\}.
$$
@end tex
@docbook
<informalequation>
    <mml:math>
        <mml:reln>
            <mml:eq/>
            <mml:apply>
                <mml:csymbol>
                    <mml:msub>
                        <mml:mi>S</mml:mi>
                        <mml:mi>P</mml:mi>
                    </mml:msub>
                </mml:csymbol>
                <mml:ci>x</mml:ci>
                <mml:ci>y</mml:ci>
            </mml:apply>
            <mml:set>
                <mml:bvar>
                    <mml:apply>
                        <mml:ci>P</mml:ci>
                        <mml:ci>x</mml:ci>
                        <mml:apply>
                            <mml:plus/>
                            <mml:ci>y</mml:ci>
                            <mml:apply>
                                <mml:times/>
                                <mml:ci>n</mml:ci>
                                <mml:ci>h</mml:ci>
                            </mml:apply>
                        </mml:apply>
                    </mml:apply>
                </mml:bvar>
                <mml:condition>
                    <mml:apply>
                        <mml:in/>
                        <mml:ci>n</mml:ci>
                        <mml:ci>Z</mml:ci>
                    </mml:apply>
                </mml:condition>
            </mml:set>
        </mml:reln>
    </mml:math>
</informalequation>
@end docbook
This is useful for 360@textdegree{} vertical panoramas as it
eliminates the top and bottom borders.

@item both
@itemx horizontal+vertical
@itemx vertical+horizontal
Wrap around both horizontally and vertically:
@ifinfo
@display
@math{S_P(x, y) = @{P(x + m * w, y + n * h): m, n in Z@}.}
@end display
@end ifinfo
@html
<math xmlns="http://www.w3.org/1998/Math/MathML" display="separate">
    <mrow>
        <msub>
            <mi>S</mi>
            <mi>P</mi>
        </msub>
        <mfenced>
            <mi>x</mi>
            <mi>y</mi>
        </mfenced>
        <mo>=</mo>
        <mrow>
            <mo>&lcub;</mo>
            <mrow>
                <mi>P</mi>
                <mfenced>
                    <mrow>
                        <mi>x</mi>
                        <mo>+</mo>
                        <mi>m</mi>
                        <mo>&InvisibleTimes;</mo>
                        <mi>w</mi>
                    </mrow>
                    <mrow>
                        <mi>y</mi>
                        <mo>+</mo>
                        <mi>n</mi>
                        <mo>&InvisibleTimes;</mo>
                        <mi>h</mi>
                    </mrow>
                </mfenced>
            </mrow>
            <mo>:</mo>
            <mrow>
                <mrow>
                    <mi>m</mi>
                    <mo>,</mo>
                    <mi>n</mi>
                </mrow>
                <mtext>&ThickSpace;in&ThickSpace;</mtext>
                <mi>Z</mi>
            </mrow>
            <mo>&rcub;</mo>
        </mrow>
        <mtext>.</mtext>
    </mrow>
</math>
@end html
@tex
$$
    S_P(x, y) = \{P(x + m w, y + n h): m, n \in Z\}.
$$
@end tex
@docbook
<informalequation>
    <mml:math>
        <mml:reln>
            <mml:eq/>
            <mml:apply>
                <mml:csymbol>
                    <mml:msub>
                        <mml:mi>S</mml:mi>
                        <mml:mi>P</mml:mi>
                    </mml:msub>
                </mml:csymbol>
                <mml:ci>x</mml:ci>
                <mml:ci>y</mml:ci>
            </mml:apply>
            <mml:set>
                <mml:bvar>
                    <mml:apply>
                        <mml:ci>P</mml:ci>
                        <mml:apply>
                            <mml:plus/>
                            <mml:ci>x</mml:ci>
                            <mml:apply>
                                <mml:times/>
                                <mml:ci>m</mml:ci>
                                <mml:ci>w</mml:ci>
                            </mml:apply>
                        </mml:apply>
                        <mml:apply>
                            <mml:plus/>
                            <mml:ci>y</mml:ci>
                            <mml:apply>
                                <mml:times/>
                                <mml:ci>n</mml:ci>
                                <mml:ci>h</mml:ci>
                            </mml:apply>
                        </mml:apply>
                    </mml:apply>
                </mml:bvar>
                <mml:condition>
                    <mml:apply>
                        <mml:and/>
                        <mml:apply>
                            <mml:in/>
                            <mml:ci>n</mml:ci>
                            <mml:ci>Z</mml:ci>
                        </mml:apply>
                        <mml:apply>
                            <mml:in/>
                            <mml:ci>m</mml:ci>
                            <mml:ci>Z</mml:ci>
                        </mml:apply>
                    </mml:apply>
                </mml:condition>
            </mml:set>
        </mml:reln>
    </mml:math>
</informalequation>
@end docbook

In this mode, both left and right borders, as well as top and bottom
borders, are eliminated.
@end table

Specifying @option{--wrap} without @var{MODE} selects horizontal
wrapping.

@item -x
@opindex -x
@cindex checkpoint results
@cindex results, checkpoint
Checkpoint partial results to the output file after each blending
step.
@end table


@node Extended Options
@section Extended Options
@cindex options, extended

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

@table @code
@item -b @var{BLOCKSIZE}
@opindex -b
@cindex image cache, block size
Set the @var{BLOCKSIZE} in kilobytes (@acronym{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 @value{default-image-cache-blocksize},
which should be ok for most systems.  See @ref{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
@code{enblend --version --verbose}.

@item -c
@itemx --ciecam
@opindex -c
@opindex --ciecam
@cindex color appearance model
@cindex @acronym{CIECAM02}
Force the use of the @acronym{CIECAM02} color appearance model for
blending colors instead of blending inside the @acronym{RGB} color
cube.

@cindex color profile
@cindex @acronym{ICC} profile
@cindex profile, @acronym{ICC}
@cindex @acronym{sRGB} color space
@cindex color space, @acronym{sRGB}
All input files should have identical @acronym{ICC} profiles when this
option is specified.  If no @acronym{ICC} profile is present, Enblend
assumes that all images use the @acronym{sRGB} color space.
@xref{Color Profiles}.

Please keep in mind that using @acronym{CIECAM02} blending may not
only change the colors in the output image, but Enblend may choose
different seam line routes as some seam-line optimizers are guided by
image differences.

This option can be negated; see option@tie{}@option{--no-ciecam}
below.

@item -d
@itemx --depth=@var{DEPTH}
@opindex -d
@opindex --depth
@cindex bits per channel
@cindex channel width
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@tie{}@option{--depth}.

@itemize
@item
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.

@item
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.
@end itemize

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

@table @asis
@item @code{8}, @code{uint8}
Unsigned 8@dmn{bit}; range: 0..255
@item @code{int16}
Signed 16@dmn{bit}; range: @minus{}32768..32767
@item @code{16}, @code{uint16}
Unsigned 16@dmn{bit}; range: 0..65535
@item @code{int32}
Signed 32@dmn{bit}; range: @minus{}2147483648..2147483647
@item @code{32}, @code{uint32}
Unsigned 32@dmn{bit}; range: 0..4294967295
@end table

For floating-point format, use

@c Minimum positive normalized value: 2^(2 - 2^k)
@c Epsilon: 2^(1 - n)
@c Maximum finite value: (1 - 2^(-n)) * 2^(2^k)

@table @asis
@c IEEE single: 32 bits, n = 24, k = 32 - n - 1 = 7
@item @code{r32}, @code{real32}, @code{float}
@cindex @acronym{IEEE754} single precision float
@cindex single precision float, @acronym{IEEE754}
@acronym{IEEE754} single precision floating-point, 32@dmn{bit} wide,
24@dmn{bit} significant

@itemize
@item
Minimum normalized value: @semilog{1.2, -38}
@item
Epsilon: @semilog{1.2, -7}
@item
Maximum finite value: @semilog{3.4, 38}
@end itemize

@c IEEE double: 64 bits, n = 53, k = 64 - n - 1 = 10
@item @code{r64}, @code{real64}, @code{double}
@cindex @acronym{IEEE754} double precision float
@cindex double precision float, @acronym{IEEE754}
@acronym{IEEE754} double precision floating-point, 64@dmn{bit} wide,
53@dmn{bit} significant

@itemize
@item
Minimum normalized value: @semilog{2.2, -308}
@item
Epsilon: @semilog{2.2, -16}
@item
Maximum finite value: @semilog{1.8, 308}
@end itemize
@end table

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

@cindex @acronym{OpenEXR}, data format
The @acronym{OpenEXR} data format is treated as
@acronym{IEEE754}@tie{}float internally.  Externally, on disk,
@acronym{OpenEXR} data is represented by ``half'' precision
floating-point numbers.

@c ILM half: 16 bits, n = 10, k = 16 - n - 1 = 5
@cindex @acronym{OpenEXR}, half precision float
@cindex half precision float, @acronym{OpenEXR}
@uref{http://@/www.openexr.com/@/about.html#@/features,
@acronym{OpenEXR}} half precision floating-point, 16@dmn{bit} wide,
10@dmn{bit} significant

@itemize
@item
Minimum normalized value: @semilog{9.3, -10}
@item
Epsilon: @semilog{2.0, -3}
@item
Maximum finite value: @semilog{4.3, 9}
@end itemize

@item -f @var{WIDTH}x@var{HEIGHT}
@itemx -f @var{WIDTH}x@var{HEIGHT}+x@var{XOFFSET}+y@var{YOFFSET}
@opindex -f
@cindex output image, set size of
@cindex canvas size
@cindex size, canvas
Ensure that the minimum ``canvas'' size of the output image is at
least @var{WIDTH}@classictimes{}@/@var{HEIGHT}.  Optionally specify
the @var{XOFFSET} and @var{YOFFSET}, too.

@pindex nona @r{(Hugin)}
@pindex hugin
This option only is useful when the input images are cropped
@acronym{TIFF} files, such as those produced by
@command{nona}@footnote{The stitcher @command{nona} is part of Hugin.
@xref{Helpful Programs}.}.

Note that option@tie{}@option{-f} neither rescales the output image,
nor shrinks the canvas size below the minimum size occupied by the
union of all input images.

@item --fallback-profile=@var{PROFILE-FILENAME}
@opindex --fallback-profile
@cindex profile, fallback
@cindex fallback profile
@cindex @acronym{CIECAM02}
Use the @acronym{ICC} profile in @var{PROFILE-FILENAME} instead of the
default @acronym{sRGB}.  See option@tie{}@option{--ciecam} and
@ref{Color Profiles}.

This option only is effective if the input images come without color
profiles and blending is performed in @acronym{CIECAM02} color
appearance model.

@item -g
@opindex -g
@cindex alpha channel, associated
Save alpha channel as ``associated''.  See the
@uref{http://@/www.awaresystems.be/@/imaging/@/tiff/@/tifftags/@/extrasamples.html,
@acronym{TIFF} documentation} for an explanation.

@pindex gimp
@pindex cinepaint
Gimp (before version@tie{}2.0) and CinePaint (@pxref{Helpful
Programs}) exhibit unusual behavior when loading images with
unassociated alpha channels.  Use option @option{-g} to work around
this problem.  With this flag Enblend will create the output image
with the associated alpha tag set, even though the image is really
unassociated alpha.

@item --gpu
@opindex --gpu
@cindex graphics processing unit
@cindex @acronym{GPU} (Graphics Processing Unit)
Use the graphics card -- in fact the graphics processing unit
(@acronym{GPU}) -- to accelerate some computations.

@cindex simulated annealing optimizer
@cindex optimizer, simulated annealing
This is an experimental feature that may not work on all systems.  In
this version of Enblend, @value{VERSION}, only mask optimization by
Simulated Annealing benefits from this option.

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

@item -m @var{CACHESIZE}
@opindex -m
@cindex image cache, cache size
Set the @var{CACHESIZE} in megabytes (@acronym{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
@value{default-image-cache-cachesize}, which is good for systems with
3--4@dmn{gigabytes} (@acronym{GB}) of @acronym{RAM}.  See @ref{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
@code{enblend --version --verbose}.

@item --no-ciecam
@opindex --no-ciecam
@cindex color appearance model
@cindex @acronym{CIECAM02}
Disable the use of the @acronym{CIECAM02} color appearance model for
blending colors.

See option@tie{}@option{--ciecam} for details.  Also see @ref{Color
Profiles}.
@end table


@node Mask Generation Options
@section Mask Generation Options
@cindex options, mask generation

These options control the generation and the usage of masks.

@table @code
@item --anneal=@var{TAU}[:@var{DELTA-E-MAX}[:@var{DELTA-E-MIN}[:@var{K-MAX}]]]
@opindex --anneal
@cindex optimize, anneal parameters
@cindex anneal parameters
@cindex simulated annealing optimizer
@cindex optimizer, simulated annealing
Set the parameters of the Simulated Annealing optimizer (see
@ref{Table:optimizer-strategies}).

@table @var
@item TAU
@var{TAU} is the temperature reduction factor in the Simulated
Annealing; it also can be thought of as ``cooling factor''.  The
closer @var{TAU} is to one, the more accurate the annealing run will
be, and the longer it will take.

Append a percent sign (@samp{%}) to specify @var{TAU} as a percentage.

Valid range: @value{src::minimum-anneal-tau} < @var{TAU} <
@value{src::maximum-anneal-tau}.

The default is @value{src::default-anneal-tau}; values around 0.95 are
reasonable.  Usually, slower cooling results in more converged points.

@item DELTA-E-MAX
@itemx DELTA-E-MIN
@var{DELTA-E-MAX} and @var{DELTA-E-MIN} are the maximum and minimum
cost change possible by any single annealing move.

Valid range: @value{src::minimum-anneal-deltae-min} <
@var{DELTA-E-MIN} < @var{DELTA-E-MAX}.

In particular they determine the initial and final annealing
temperatures according to:
@ifinfo
@display
                   DELTA-E-MAX
T_initial = ------------------------
            log(K-MAX / (K-MAX - 2))

                DELTA-E-MIN
T_final = ------------------------
          log(K-MAX^2 - K-MAX - 1)
@end display
@end ifinfo
@html
<math xmlns="http://www.w3.org/1998/Math/MathML" display="separate">
    <mtable>
        <mtr>
            <mtd>
                <mrow>
                    <msub>
                        <mi mathvariant="italic">T</mi>
                        <mi mathvariant="normal">initial</mi>
                    </msub>
                    <mo>=</mo>
                    <mfrac>
                        <mi mathvariant="italic">DELTA-E-MAX</mi>
                        <mrow>
                            <mo>log</mo>
                            <mo>&ApplyFunction;</mo>
                            <mo>(</mo>
                            <mrow>
                                <mi mathvariant="italic">K-MAX</mi>
                                <mo>/</mo>
                                <mo>(<mo>
                                <mrow>
                                    <mi mathvariant="italic">K-MAX</mi>
                                    <mo>-</mo>
                                    <mn>2</mn>
                                </mrow>
                                <mo>)<mo>
                            </mrow>
                            <mo>)</mo>
                        </mrow>
                    </mfrac>
                </mrow>
            </mtd>
        </mtr>

        <mtr>
            <mtd>
                <mrow>
                    <msub>
                        <mi mathvariant="italic">T</mi>
                        <mi mathvariant="normal">final</mi>
                    </msub>
                    <mo>=</mo>
                    <mfrac>
                        <mi mathvariant="italic">DELTA-E-MIN</mi>
                        <mrow>
                            <mo>log</mo>
                            <mo>&ApplyFunction;</mo>
                            <mo>(</mo>
                            <mrow>
                                <msup>
                                    <mi mathvariant="italic">K-MAX</mi>
                                    <mn>2</mn>
                                </msup>
                                <mo>-</mo>
                                <mi mathvariant="italic">K-MAX</mi>
                                <mo>-</mo>
                                <mn>1</mn>
                            </mrow>
                            <mo>)</mo>
                        </mrow>
                    </mfrac>
                </mrow>
            </mtd>
        </mtr>
    </mtable>
</math>
@end html
@tex
$$\eqalign{
  T_{\mathrm{initial}} & =
    {\mathit{DELTA-E-MAX} \over {\log(\mathit{K-MAX} / (\mathit{K-MAX} - 2))}} \cr
  T_{\mathrm{final}} & =
    {\mathit{DELTA-E-MIN} \over {\log(\mathit{K-MAX\/}^2 - \mathit{K-MAX} - 1)}} \cr
}$$
@end tex
@docbook
<informalequation>
    <mml:math>
        <mml:reln>
            <mml:eq/>
            <mml:csymbol>
                <mml:msub>
                    <mml:mi mathvariant="italic">T</mml:mi>
                    <mml:mi mathvariant="normal">initial</mml:mi>
                </mml:msub>
            </mml:csymbol>
            <mml:apply>
                <mml:divide/>
                    <mml:csymbol>
                        <mml:mi mathvariant="italic">DELTA-E-MAX</mml:mi>
                    </mml:csymbol>
                    <mml:apply>
                        <mml:log/>
                        <mml:apply other='display="scriptstyle"'>
                            <mml:divide/>
                            <mml:csymbol>
                                <mml:mi mathvariant="italic">K-MAX</mml:mi>
                            </mml:csymbol>
                            <mml:apply>
                                <mml:minus/>
                                <mml:csymbol>
                                    <mml:mi mathvariant="italic">K-MAX</mml:mi>
                                </mml:csymbol>
                                <mml:cn>2</mml:cn>
                            </mml:apply>
                        </mml:apply>
                    </mml:apply>
            </mml:apply>
        </mml:reln>
    </mml:math>
</informalequation>

<informalequation>
    <mml:math>
        <mml:reln>
            <mml:eq/>
            <mml:csymbol>
                <mml:msub>
                    <mml:mi mathvariant="italic">T</mml:mi>
                    <mml:mi mathvariant="normal">final</mml:mi>
                </mml:msub>
            </mml:csymbol>
            <mml:apply>
                <mml:divide/>
                    <mml:csymbol>
                        <mml:mi mathvariant="italic">DELTA-E-MIN</mml:mi>
                    </mml:csymbol>
                    <mml:apply>
                        <mml:log/>
                        <mml:apply>
                            <mml:minus/>
                        <mml:apply>
                            <mml:minus/>
                                <mml:apply>
                                    <mml:power/>
                                    <mml:csymbol>
                                        <mml:mi mathvariant="italic">K-MAX</mml:mi>
                                    </mml:csymbol>
                                    <mml:cn>2</mml:cn>
                                </mml:apply>
                                <mml:csymbol>
                                    <mml:mi mathvariant="italic">K-MAX</mml:mi>
                                </mml:csymbol>
                            </mml:apply>
                            <mml:cn>1</mml:cn>
                        </mml:apply>
                    </mml:apply>
            </mml:apply>
        </mml:reln>
    </mml:math>
</informalequation>
@end docbook

The defaults are: @var{DELTA-E-MAX}:
@value{src::default-anneal-deltae-max} and @var{DELTA-E-MIN}:
@value{src::default-anneal-deltae-min}.

@item K-MAX
@var{K-MAX} is the maximum number of ``moves'' the optimizer will make
for each line segment.  Higher values more accurately sample the state
space, at the expense of a higher computation cost.

Valid range: @var{K-MAX} @geq{} @value{src::minimum-anneal-kmax}.

The default is @value{src::default-anneal-kmax}.  Values around 100
seem reasonable.
@end table

@item --coarse-mask[=@var{FACTOR}]
@opindex --coarse-mask
@cindex mask, coarse
@cindex coarse mask
Use a scaled-down version of the input images to create the seam line.
This option reduces the number of computations necessary to compute
the seam line and the amount of memory necessary to do so.  It is the
default.

If omitted @var{FACTOR} defaults to
@value{src::default-coarseness-factor}, this means,
option@tie{}@option{--coarse-mask} shrinks the overlapping
@emph{areas} by a factor of
@math{@value{src::default-coarseness-factor}@classictimes{}@/@value{src::default-coarseness-factor}}.
With @var{FACTOR}@tie{}=@tie{}8 the total memory allocated during a
run of Enblend shrinks approximately by 80% and the maximum amount of
memory in use at a time is decreased to 60% (Enblend compiled with
image cache) or 40% (Enblend compiled without image cache).

Valid range: @var{FACTOR} = 1, 2, 3,@dots{}.

Also see @ref{Table:mask-generation}.

@float Table,Table:mask-generation
@multitable @columnfractions 0.2 0.35 0.35
@headitem @tab @code{--no-optimize} @tab @code{--optimize}

@item @code{--fine-mask}
@c no opt
@tab
Use @acronym{NFT} mask.

@c opt
@tab
Vectorize @acronym{NFT} mask, optimize vertices with simulated
annealing and @sc{Dijkstra's} shortest path algorithm, fill vector
contours.

@item @code{--coarse-mask}
@c no opt
@tab
Scale down overlap region, compute @acronym{NFT} mask and vectorize
it, fill vector contours.

@c opt
@tab
Scale down overlap region, vectorize @acronym{NFT} mask, optimize
vertices with simulated annealing and @sc{Dijkstra's} shortest path
algorithm, fill vector contours.
@end multitable

@caption{Various options that control the generation of masks.  All mask computations are based on the Nearest-Feature Transformation (@acronym{NFT}) of the overlap region.}

@shortcaption{Mask generation options}

@cindex nearest-feature transform (@acronym{NFT})
@cindex mask, generation
@end float

@item --dijkstra=@var{RADIUS}
@opindex --dijkstra
@cindex @sc{Dijkstra} radius
@cindex radius, @sc{Dijkstra}
Set the search @var{RADIUS} of the @sc{Dijkstra} Shortest Path
algorithm used in @sc{Dijkstra} Optimization (see
@ref{Table:optimizer-strategies}).

A small value prefers straight line segments and thus shorter seam
lines.  Larger values instruct the optimizer to let the seam line take
more detours when searching for the best seam line.

Valid range: @var{RADIUS} @geq{} @value{src::minimum-dijkstra-radius}.

Default: @value{src::default-dijkstra-radius}@dmn{pixels}.

@item --fine-mask
@opindex --fine-mask
@cindex mask, fine
@cindex fine mask
Instruct Enblend to employ the full-size images to create the seam
line, which can be slow.  Use this option, for example, if you have
very narrow overlap regions.

Also see @ref{Table:mask-generation}.

@item --image-difference=@var{ALGORITHM}[:@var{LUMINANCE-WEIGHT}[:@var{CHROMINANCE-WEIGHT}]]
@opindex --image-difference
@cindex image difference
@cindex difference image
@cindex luminance weight
@cindex weight, luminance
@cindex chrominance weight
@cindex weight, chrominance

Enblend calculates the difference of a pair of overlapping color
images when it generates the primary seam with a Graph-Cut or before
it optimizes a seam.  It employs a user-selectable @var{ALGORITHM}
that itself is controlled by the weights for luminance differences
@var{LUMINANCE-WEIGHT},
@ifinfo
@math{w_luminance}
@end ifinfo
@html
<mathinline xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
    <mrowinline>
        <msubinline>
            <mi>w</mi>
            <mtext>luminance</mtext>
        </msubinline>
    </mrowinline>
</mathinline>
@end html
@tex
$w_{\mathrm{luminance}}$
@end tex
@docbook
<inlineequation>
    <mml:math>
        <mml:csymbol>
            <mml:msub>
                <mml:mi mathvariant="italic">w</mml:mi>
                <mml:mi mathvariant="normal">luminance</mml:mi>
            </mml:msub>
        </mml:csymbol>
    </mml:math>
</inlineequation>
@end docbook
and color differences @var{CHROMINANCE-WEIGHT},
@ifinfo
@math{w_chrominance}.
@end ifinfo
@html
<mathinline xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
    <mrowinline>
        <msubinline>
            <mi>w</mi>
            <mtext>chrominance</mtext>
        </msubinline>
        <mtext>.</mtext>
    </mrowinline>
</mathinline>
@end html
@tex
$w_{\mathrm{chrominance}}$.
@end tex
@docbook
<inlineequation>
    <mml:math>
        <mml:csymbol>
            <mml:msub>
                <mml:mi mathvariant="italic">w</mml:mi>
                <mml:mi mathvariant="normal">chrominance</mml:mi>
            </mml:msub>
        </mml:csymbol>
    </mml:math>
</inlineequation>
@end docbook

For black-and-white images the difference is simple the absolute
difference of each pair of pixels.

@table @code
@item maximum-hue-luminance
@itemx maximum-hue-lum
@itemx max-hue-luminance
@itemx max-hue-lum
@itemx max
@cindex maximum hue-luminance
@cindex hue-luminance maximum
@cindex luminance-hue maximum
Calculate the difference@tie{}@math{d} as the maximum of the
differences of the luminances@tie{}@math{l} and hues@tie{}@math{h} of
each pair of pixels
@ifinfo
@math{P1}
@end ifinfo
@html
<mathinline xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
    <mrowinline>
        <msubinline>
            <mi>P</mi>
            <mn>1</mn>
        </msubinline>
    </mrowinline>
</mathinline>
@end html
@tex
$P_1$
@end tex
@docbook
<inlineequation>
    <mml:math>
        <mml:csymbol>
            <mml:msub>
                <mml:mi>P</mml:mi>
                <mml:cn>1</mml:cn>
            </mml:msub>
        </mml:csymbol>
    </mml:math>
</inlineequation>
@end docbook
and
@ifinfo
@math{P2}:
@end ifinfo
@html
<mathinline xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
    <mrowinline>
        <msubinline>
            <mi>P</mi>
            <mn>2</mn>
        </msubinline>
        <mtext>:</mtext>
    </mrowinline>
</mathinline>
@end html
@tex
$P_2$:
@end tex
@docbook
<inlineequation>
    <mml:math>
        <mml:csymbol>
            <mml:msub>
                <mml:mi>P</mml:mi>
                <mml:cn>2</mml:cn>
            </mml:msub>
        </mml:csymbol>
    </mml:math>
</inlineequation>
@end docbook

@ifinfo
@display
@math{d = max(w_luminance * |l(P_1) - l(P_2)|, w_chrominance * |h(P_1) - h(p_2)|)}
@end display
@end ifinfo
@html
<math xmlns="http://www.w3.org/1998/Math/MathML" display="separate">
    <mrow>
        <mi>d</mi>
        <mo>=</mo>
        <mrow>
            <mo>max</mo>
            <mo>&ApplyFunction;</mo>
            <mfenced>
                <mrow>
                    <msub>
                        <mi>w</mi>
                        <mtext>luminance</mtext>
                    </msub>
                    <mo>&times;</mo>
                    <mrow>
                        <mo>|</mo>
                        <mi>l</mi>
                        <mo>&ApplyFunction;</mo>
                        <mfenced>
                            <msub>
                                <mi>P</mi>
                                <mn>1</mn>
                            </msub>
                        </mfenced>
                        <mo>-</mo>
                        <mi>l</mi>
                        <mo>&ApplyFunction;</mo>
                        <mfenced>
                            <msub>
                                <mi>P</mi>
                                <mn>2</mn>
                            </msub>
                        </mfenced>
                        <mo>|</mo>
                    </mrow>
                </mrow>

                <mrow>
                    <msub>
                        <mi>w</mi>
                        <mtext>chrominance</mtext>
                    </msub>
                    <mo>&times;</mo>
                    <mrow>
                        <mo>|</mo>
                        <mi>h</mi>
                        <mo>&ApplyFunction;</mo>
                        <mfenced>
                            <msub>
                                <mi>P</mi>
                                <mn>1</mn>
                            </msub>
                        </mfenced>
                        <mo>-</mo>
                        <mi>h</mi>
                        <mo>&ApplyFunction;</mo>
                        <mfenced>
                            <msub>
                                <mi>P</mi>
                                <mn>2</mn>
                            </msub>
                        </mfenced>
                        <mo>|</mo>
                    </mrow>
                </mrow>
            </mfenced>
        </mrow>
    </mrow>
</math>
@end html
@tex
$$
    \eqalign{d = \max(& w_{\mathrm{luminance}} \times |l(P_1) - l(P_2)|, \cr
                      & w_{\mathrm{chrominance}} \times |h(P_1) - h(P_2)|) \cr}
$$
@end tex
@docbook
<informalequation>
    <mml:math>
        <mml:reln>
            <mml:eq/>
            <mml:ci>d</mml:ci>
            <mml:apply>
                <mml:max/>
                <mml:apply>
                    <mml:times/>
                    <mml:csymbol>
                        <mml:msub>
                            <mml:mi>w</mml:mi>
                            <mml:mi mathvariant="normal">luminance</mml:mi>
                        </mml:msub>
                    </mml:csymbol>
                    <mml:apply>
                        <mml:abs/>
                        <mml:apply>
                            <mml:minus/>
                            <mml:apply>
                                <mml:ci>l</mml:ci>
                                <mml:csymbol>
                                    <mml:msub>
                                        <mml:mi>P</mml:mi>
                                        <mml:cn>1</mml:cn>
                                    </mml:msub>
                                </mml:csymbol>
                            </mml:apply>
                            <mml:apply>
                                <mml:ci>l</mml:ci>
                                <mml:csymbol>
                                    <mml:msub>
                                        <mml:mi>P</mml:mi>
                                        <mml:cn>2</mml:cn>
                                    </mml:msub>
                                </mml:csymbol>
                            </mml:apply>
                        </mml:apply>
                    </mml:apply>
                </mml:apply>
                <mml:apply>
                    <mml:times/>
                    <mml:csymbol>
                        <mml:msub>
                            <mml:mi>w</mml:mi>
                            <mml:mi mathvariant="normal">chrominance</mml:mi>
                        </mml:msub>
                    </mml:csymbol>
                    <mml:apply>
                        <mml:abs/>
                        <mml:apply>
                            <mml:minus/>
                            <mml:apply>
                                <mml:ci>h</mml:ci>
                                <mml:csymbol>
                                    <mml:msub>
                                        <mml:mi>P</mml:mi>
                                        <mml:cn>1</mml:cn>
                                    </mml:msub>
                                </mml:csymbol>
                            </mml:apply>
                            <mml:apply>
                                <mml:ci>h</mml:ci>
                                <mml:csymbol>
                                    <mml:msub>
                                        <mml:mi>P</mml:mi>
                                        <mml:cn>2</mml:cn>
                                    </mml:msub>
                                </mml:csymbol>
                            </mml:apply>
                        </mml:apply>
                    </mml:apply>
                </mml:apply>
            </mml:apply>
        </mml:reln>
    </mml:math>
</informalequation>
@end docbook

This algorithm was the default for Enblend up to version@tie{}4.0.

@item delta-e
@itemx de
@cindex delta-E
Calulate the difference@tie{}@math{d} as the @sc{Euclidean} distance
of the pixels in L*a*b* space:
@ifinfo
@display
@math{d = sqrt(w_luminance * (L(P_1) - L(P_2))^2 +
         w_chrominance * (a(P_1) - a(P_2))^2 +
         w_chrominance * (b(P_1) - b(P_2))^2)}
@end display
@end ifinfo
@html
<math xmlns="http://www.w3.org/1998/Math/MathML" display="separate">
    <mrow>
        <mi>d</mi>
        <mo>=</mo>
        <msup>
            <mrow>
                <mo>(</mo>
                <mrow>
                    <msub>
                        <mi>w</mi>
                        <mtext>luminance</mtext>
                    </msub>
                    <mo>&times;</mo>
                    <msup>
                        <mrow>
                            <mo>(</mo>
                                <mi>L</mi>
                                <mo>&ApplyFunction;</mo>
                                <mfenced>
                                    <msub>
                                        <mi>P</mi>
                                        <mn>1</mn>
                                    </msub>
                                </mfenced>
                                <mo>-</mo>
                                <mi>L</mi>
                                <mo>&ApplyFunction;</mo>
                                <mfenced>
                                    <msub>
                                        <mi>P</mi>
                                        <mn>2</mn>
                                    </msub>
                                </mfenced>
                            <mo>)</mo>
                        </mrow>
                        <mn>2</mn>
                    </msup>
                </mrow>
                <mo>+</mo>
                <mrow>
                    <msub>
                        <mi>w</mi>
                        <mtext>chrominance</mtext>
                    </msub>
                    <mo>&times;</mo>
                    <msup>
                        <mrow>
                            <mo>(</mo>
                                <mi>a</mi>
                                <mo>&ApplyFunction;</mo>
                                <mfenced>
                                    <msub>
                                        <mi>P</mi>
                                        <mn>1</mn>
                                    </msub>
                                </mfenced>
                                <mo>-</mo>
                                <mi>a</mi>
                                <mo>&ApplyFunction;</mo>
                                <mfenced>
                                    <msub>
                                        <mi>P</mi>
                                        <mn>2</mn>
                                    </msub>
                                </mfenced>
                            <mo>)</mo>
                        </mrow>
                        <mn>2</mn>
                    </msup>
                </mrow>
                <mo>+</mo>
                <mrow>
                    <msub>
                        <mi>w</mi>
                        <mtext>chrominance</mtext>
                    </msub>
                    <mo>&times;</mo>
                    <msup>
                        <mrow>
                            <mo>(</mo>
                                <mi>b</mi>
                                <mo>&ApplyFunction;</mo>
                                <mfenced>
                                    <msub>
                                        <mi>P</mi>
                                        <mn>1</mn>
                                    </msub>
                                </mfenced>
                                <mo>-</mo>
                                <mi>b</mi>
                                <mo>&ApplyFunction;</mo>
                                <mfenced>
                                    <msub>
                                        <mi>P</mi>
                                        <mn>2</mn>
                                    </msub>
                                </mfenced>
                            <mo>)</mo>
                        </mrow>
                        <mn>2</mn>
                    </msup>
                </mrow>
                <mo>)</mo>
            </mrow>
            <mn>1/2</mn>
        </msup>
    </mrow>
</math>
@end html
@tex
$$
    \eqalign{d = (& w_{\mathrm{luminance}} \, \times (L(P_1) - L(P_2))^2 \; + \cr
                  & w_{\mathrm{chrominance}} \, \times (a(P_1) - a(P_2))^2 \; + \cr
                  & w_{\mathrm{chrominance}} \, \times (b(P_1) - b(P_2))^2)^{1/2}\cr}
$$
@end tex
@docbook
<informalequation>
    <mml:math>
        <mml:reln>
            <mml:eq/>
            <mml:ci>d</mml:ci>
            <mml:apply>
                <mml:power/>
                <!-- base -->
                <mml:apply>
                    <mml:csymbol><!-- empty --></mml:csymbol>
                    <mml:apply>
                        <mml:plus/>
                        <!-- first summand -->
                        <mml:apply>
                            <mml:times/>
                            <mml:csymbol>
                                <mml:msub>
                                    <mml:mi>w</mml:mi>
                                    <mml:mi mathvariant="normal">luminance</mml:mi>
                                </mml:msub>
                            </mml:csymbol>
                            <mml:apply>
                                <mml:power/>
                                <mml:apply>
                                    <mml:csymbol><!-- empty --></mml:csymbol>
                                    <mml:apply>
                                        <mml:minus/>
                                        <mml:apply>
                                            <mml:ci>L</mml:ci>
                                            <mml:csymbol>
                                                <mml:msub>
                                                    <mml:mi>P</mml:mi>
                                                    <mml:cn>1</mml:cn>
                                                </mml:msub>
                                            </mml:csymbol>
                                        </mml:apply>
                                        <mml:apply>
                                            <mml:ci>L</mml:ci>
                                            <mml:csymbol>
                                                <mml:msub>
                                                    <mml:mi>P</mml:mi>
                                                    <mml:cn>2</mml:cn>
                                                </mml:msub>
                                            </mml:csymbol>
                                        </mml:apply>
                                    </mml:apply>
                                </mml:apply>
                                <mml:cn>2</mml:cn>
                            </mml:apply>
                        </mml:apply>
                        <!-- second summand -->
                        <mml:apply>
                            <mml:times/>
                            <mml:csymbol>
                                <mml:msub>
                                    <mml:mi>w</mml:mi>
                                    <mml:mi mathvariant="normal">chrominance</mml:mi>
                                </mml:msub>
                            </mml:csymbol>
                            <mml:apply>
                                <mml:power/>
                                <mml:apply>
                                    <mml:csymbol><!-- empty --></mml:csymbol>
                                    <mml:apply>
                                        <mml:minus/>
                                        <mml:apply>
                                            <mml:ci>a</mml:ci>
                                            <mml:csymbol>
                                                <mml:msub>
                                                    <mml:mi>P</mml:mi>
                                                    <mml:cn>1</mml:cn>
                                                </mml:msub>
                                            </mml:csymbol>
                                        </mml:apply>
                                        <mml:apply>
                                            <mml:ci>a</mml:ci>
                                            <mml:csymbol>
                                                <mml:msub>
                                                    <mml:mi>P</mml:mi>
                                                    <mml:cn>2</mml:cn>
                                                </mml:msub>
                                            </mml:csymbol>
                                        </mml:apply>
                                    </mml:apply>
                                </mml:apply>
                                <mml:cn>2</mml:cn>
                            </mml:apply>
                        </mml:apply>
                        <!-- third summand -->
                        <mml:apply>
                            <mml:times/>
                            <mml:csymbol>
                                <mml:msub>
                                    <mml:mi>w</mml:mi>
                                    <mml:mi mathvariant="normal">chrominance</mml:mi>
                                </mml:msub>
                            </mml:csymbol>
                            <mml:apply>
                                <mml:power/>
                                <mml:apply>
                                    <mml:csymbol><!-- empty --></mml:csymbol>
                                    <mml:apply>
                                        <mml:minus/>
                                        <mml:apply>
                                            <mml:ci>b</mml:ci>
                                            <mml:csymbol>
                                                <mml:msub>
                                                    <mml:mi>P</mml:mi>
                                                    <mml:cn>1</mml:cn>
                                                </mml:msub>
                                            </mml:csymbol>
                                        </mml:apply>
                                        <mml:apply>
                                            <mml:ci>b</mml:ci>
                                            <mml:csymbol>
                                                <mml:msub>
                                                    <mml:mi>P</mml:mi>
                                                    <mml:cn>2</mml:cn>
                                                </mml:msub>
                                            </mml:csymbol>
                                        </mml:apply>
                                    </mml:apply>
                                </mml:apply>
                                <mml:cn>2</mml:cn>
                            </mml:apply>
                        </mml:apply>
                    </mml:apply>
                </mml:apply>
                <!-- power -->
                <mml:apply>
                    <mml:divide/>
                    <mml:cn>1</mml:cn>
                    <mml:cn>2</mml:cn>
                </mml:apply>
            </mml:apply>
       </mml:reln>
    </mml:math>
</informalequation>
@end docbook

This is the default in Enblend version@tie{}4.1 and later.

Note that the ``delta-E'' mentioned here has nothing to do with
@var{DELTA-E-MAX} and @var{DELTA-E-MIN} of
option@tie{}@option{--anneal}.
@end table

Both @var{LUMINANCE-WEIGHT} and @var{CHROMINANCE-WEIGHT} must be
non-negative, their sum must be positive.  Enblend automatically
normalizes the sum of @var{LUMINANCE-WEIGHT} and
@var{CHROMINANCE-WEIGHT} to one.  Thus
@samp{--image-difference=delta-e:2:1} and
@samp{--image-difference=delta-e:0.6667:0.3333} define the same
weighting function.

The default @var{LUMINANCE-WEIGHT} is @value{src::default-luminance-difference-weight}
and the default @var{CHROMINANCE-WEIGHT} is @value{src::default-chrominance-difference-weight}.

@cindex match quality
@cindex quality, match
At higher verbosity levels Enblend computes the true size of the
overlap area in pixels and it calculates the average and standard
deviation of the difference per pixel in the normalized luminance
interval@tie{}[0@dots{}1].  These statistical measures are based on
@var{ALGORITHM}, therefore they should only be compared for identical
@var{ALGORITHM}s.  The average difference is a rough measure of
quality with lower values meaning better matches.

@item --load-masks[=@var{IMAGE-TEMPLATE}]
@opindex --load-masks
@cindex mask, load
@cindex load mask
Instead of generating masks, use those in @var{IMAGE-TEMPLATE}.  The
default is @file{@value{src::default-mask-template}}.  The mask images
have to be a 8-bit grayscale images.

See @option{--save-masks} below for details.

@item --mask-vectorize=@var{DISTANCE}
@opindex --mask-vectorize
@cindex mask, vectorization distance
Set the mask vectorization @var{DISTANCE} Enblend uses to partition
each seam.  Thus, break down the seam to segments of length
@var{DISTANCE} each.

If Enblend uses a coarse mask (@option{--coarse-mask}) or Enblend
optimizes (@option{--optimize}) a mask it vectorizes the initial seam
line before performing further operations.  See
@ref{Table:mask-generation} for the precise conditions.
@var{DISTANCE} tells Enblend how long to make each of the line
segments called vectors here.

The unit of @var{DISTANCE} is pixels unless it is a percentage as
explained in the next paragraph.  In fine masks one mask pixel
corresponds to one pixel in the input image, whereas in coarse masks
one pixel represents for example
@value{src::default-coarseness-factor}@dmn{pixels} in the input image.

Append a percentage sign (@samp{%}) to @var{DISTANCE} to specify the
segment length as a fraction of the diagonal of the rectangle
including the overlap region.  Relative measures do not depend on
coarse or fine masks, they are recomputed for each mask.  Values
around 5%--10% are a good starting point.

This option massively influences the mask generation process!  Large
@var{DISTANCE} values lead to shorter, straighter, less wiggly, less
baroque seams that are on the other hand less optimal, because they
run through regions of larger image mismatch instead of avoiding them.
Small @var{DISTANCE} values give the optimizers more possibilities to
run the seam around high mismatch areas.

@cindex seam line, loops
@cindex loops in seam line
What should @emph{never} happen though, are loops in the seam line.
Counter loops with higher weights of @var{DISTANCE-WEIGHT} (in
option@tie{}@option{--optimizer-weights}), larger vectorization
@var{DISTANCE}s, @var{TAU}s (in option@tie{}@option{--anneal}) that
are closer to one, and blurring of the difference image with
option@tie{}@option{--smooth-difference}.  Use
option@tie{}@option{--visualize} to check the results.

Valid range: @var{DISTANCE} @geq{} @value{src::minimum-vectorize-distance}.

Enblend limits @var{DISTANCE} so that it never gets below
@value{src::minimum-vectorize-distance} even if it has been given as a
percentage.  The user will be warned in such cases.

Default: @value{src::coarse-mask-vectorize-distance}@dmn{pixels} for
coarse masks and @value{src::fine-mask-vectorize-distance}@dmn{pixels}
for fine masks.

@item --no-optimize
@opindex --no-optimize
@cindex optimize seam
@cindex seam optimization
Turn off seam line optimization.  Combined with
option@tie{}@option{--fine-mask} this will produce the same type of
mask as Enblend version@tie{}2.5, namely the result of a
@cindex nearest-feature transform (@acronym{NFT})
Nearest-Feature Transform (@acronym{NFT}).@footnote{@sc{Muhammad
H. Alsuwaiyel} and @sc{Marina Gavrilova}, ``On the Distance Transform
of Binary Images'', Proceedings of the International Conference on
Imaging Science, Systems, and Technology, June 2000, @abbr{Vols@.} I
and II, pages 83--86.}

Also see @ref{Table:mask-generation}.

@item --optimize
@opindex --optimize
@cindex optimize seam
@cindex seam optimization
Use a multi-strategy approach to route the seam line around mismatches
in the overlap region.  This is the default.
@ref{Table:optimizer-strategies} explains these strategies; also see
@ref{Table:mask-generation}.

@float Table,Table:optimizer-strategies
@table @asis
@dbtitle{Optimizer Strategies}
@item Simulated Annealing
Tune with option@tie{}@code{--anneal} = @var{TAU} : @var{DELTA-E-MAX}
: @var{DELTA-E-MIN} : @var{K-MAX}.

@uref{http://@/en.wikipedia.org/@/wiki/@/Simulated_@/annealing,
Simulated-Annealing}


@item @sc{Dijkstra} Shortest Path
Tune with option@tie{}@code{--dijkstra} = @var{RADIUS}.

@uref{http://@/en.wikipedia.org/@/wiki/@/Dijkstra_@/algorithm,
@sc{Dijkstra} algorithm}

@end table

@caption{Enblend's strategies to optimize the seam lines between images.}

@shortcaption{Optimizer strategies}

@cindex optimize strategy
@end float

@item --optimizer-weights=@var{DISTANCE-WEIGHT}[:@var{MISMATCH-WEIGHT}]
@opindex --optimizer-weights
@cindex optimizer weights
@cindex weights, optimizer
@cindex seam optimization

Set the weights of the seam-line optimizer.  If omitted,
@var{MISMATCH-WEIGHT} defaults to 1.

The seam-line optimizer considers two qualities of the seam line:

@itemize
@item
The distance of the seam line from its initial position, which has
been determined by @acronym{NFT} (see
option@tie{}@option{--no-optimize}).

@item
The total ``mismatch'' accumulated along it.
@end itemize

The optimizer weights@tie{}@var{DISTANCE-WEIGHT} and
@var{MISMATCH-WEIGHT} define how to weight these two criteria.
Enblend up to version@tie{}3.2 used 1:1.  This version of Enblend
(@value{VERSION}) uses
@value{src::default-optimizer-weight-distance}:@value{src::default-optimizer-weight-mismatch}.

A large @var{DISTANCE-WEIGHT} pulls the optimized seam line closer to
the initial postion.  A large @var{MISMATCH-WEIGHT} makes the seam
line go on detours to find a path along which the mismatch between the
images is small.  If the optimized seam line shows cusps or loops (see
option@tie{}@option{--visualize}), reduce @var{MISMATCH-WEIGHT} or
increase @var{DISTANCE-WEIGHT}.

Both weights must be non-negative.  They cannot be both zero at the
same time.  Otherwise, their absolute values are not important as
Enblend normalizes their sum.

@item --primary-seam-generator=@var{ALGORITHM}
@opindex --primary-seam-generator
@cindex primary seam generator
@cindex seam, primary generator
@cindex generator, seam
Select the algorithm responsible for generating the general seam route.

This is the @var{ALGORITHM} that produces an initial seam line, which
is the basis for later, optional optimizations (see
@option{--optimize}).  Nearest Feature Transform (@acronym{NFT}) is
the only algorithm up to and including Enblend version@tie{}4.0.
Version@tie{}4.1 adds a Graph-Cut (@acronym{GC}) algorithm.  In this
version of Enblend @acronym{NFT} is the default.

Valid @var{ALGORITHM} names are:

@table @asis
@item nearest-feature-transform
@itemx nft
@cindex nearest feature transform (@acronym{NFT})
Nearest Feature Transform
@item graph-cut
@itemx gc
@cindex graph-cut (@acronym{GC})
Graph-Cut
@end table

See @ref{Primary Seam Generators} for details.

@item --save-masks
@itemx --save-masks=@var{IMAGE-TEMPLATE}
@opindex --save-masks
@cindex mask, save
@cindex save mask
Save the generated masks to @var{IMAGE-TEMPLATE}.  The default is
@file{@value{src::default-mask-template}}.  Enblend saves masks as
8@dmn{bit} grayscale (single channel) images.  For accuracy we
recommend to choose a lossless format.

Use this option if you wish to edit the location of the seam line by
hand.  This will give you images of the right sizes that you can edit
to make your changes.  Later, use option@tie{}@option{--load-masks} to
blend the project with your custom seam lines.

@cindex save mask, only
@cindex only save mask
Enblend will stop after saving all masks unless
option@tie{}@option{--output} is given, too.  With both options given,
this is, @option{--save-masks} and @option{--output}, Enblend saves
all masks and then proceeds to blend the output image.

@var{IMAGE-TEMPLATE} defines a template that is expanded for each
input file.  In a template a percent sign (@samp{%}) introduces a
variable part.  All other characters are copied literally.  Lowercase
letters refer to the name of the respective input file, whereas
uppercase ones refer to the name of the output file (@pxref{Common
Options}).  @ref{Table:mask-template-characters} lists all variables.

A fancy mask filename template could look like this:

@example
%D/mask-%02n-%f.tif
@end example

It puts the mask files into the same directory as the output file
(@samp{%D}), generates a two-digit index (@samp{%02n}) to keep the
mask files nicely sorted, and decorates the mask filename with the
name of the associated input file (@samp{%f}) for easy recognition.

@item --smooth-difference=@var{RADIUS}
@opindex --smooth-difference
@cindex smooth difference image
@cindex blur difference image

@emph{This option has been deprecated.}

Smooth the difference image prior to seam-line optimization to get a
shorter and -- on the length scale of @var{RADIUS} -- also a
straighter seam-line.  The default is not to smooth.

If @var{RADIUS} is larger than zero Enblend blurs the difference
images of the overlap regions with a @sc{Gaussian} filter having a
radius of @var{RADIUS}@dmn{pixels}.  Values of 0.5 to 1.5@dmn{pixels}
for @var{RADIUS} are good starting points; use
option@tie{}@option{--visualize} to directly judge the effect.

When using this option in conjunction with
option@tie{}@code{--coarse-mask}=@/@var{FACTOR}, keep in mind that the
smoothing occurs @emph{after} the overlap regions have been shrunken.
Thus, blurring affects a @var{FACTOR}@classictimes{}@/@var{FACTOR}
times larger area in the original images.

Valid range: @var{RADIUS} @geq{} @value{src::minimum-smooth-difference}.

@item --visualize[=@var{VISUALIZE-TEMPLATE}]
@opindex --visualize
@cindex mask, optimization visualization
@cindex visualization of mask
Create an image according to @var{VISUALIZE-TEMPLATE} that visualizes
the unoptimized mask and the applied optimizations (if any).  The default is
@file{@value{src::default-visualize-template}}.

The image shows Enblend's view of the overlap region and how it
decided to route the seam line.  If you are experiencing artifacts or
unexpected output, it may be useful to include this visualization
image in your bug report.  @xref{Bug Reports}.

@var{VISUALIZE-TEMPLATE} defines a template that is expanded for each
input file.  In a template, a percent sign (@samp{%}) introduces a
variable part; all other characters are copied literally.  Lowercase
letters refer to the name of the respective input file, whereas
uppercase ones refer to the name of the output file (@pxref{Common
Options}).  @ref{Table:mask-template-characters} lists all variables.

@noindent
@strong{Visualization Image.}
@cindex visualization image
@cindex image, visualization
@need 150
The visualization image shows the symmetric difference of the pixels
in the rectangular region where two images overlap.  The larger the
difference the lighter shade of gray it appears in the visualization
image.  Enblend paints the non-overlapping parts of the image pair --
these are the regions where @emph{no} blending occurs -- in
@value{src::visualize-no-overlap-value-color}.
@ref{Table:visualization-colors} shows the meanings of all the colors
that are used in seam-line visualization images.

@float Table,Table:visualization-colors
@table @asis
@dbtitle{Visualization Colors}
@item @value{src::visualize-no-overlap-value-color}
Non-overlapping parts of image pair.

@item various shades of gray
Difference of the pixel values in the overlap region.

@item @value{src::visualize-state-space-color}
Location of an optimizer sample.

@item @value{src::visualize-first-vertex-value-color}
First sample of a line segment.

@item @value{src::visualize-next-vertex-value-color}
Any other but first sample of a line segment.

@item @value{src::visualize-state-space-inside-color}
@cindex @sc{Dijkstra} radius
@cindex radius, @sc{Dijkstra}
State space sample inside the @sc{Dijkstra} radius.

@item @value{src::visualize-state-space-unconverged-color}
Non-converged point.

@item @value{src::visualize-initial-path-color}
@cindex nearest-feature transform (@acronym{NFT}), Graph-Cut (@acronym{GC})
Initial seam line as generated by the primary seam generator.

@cindex frozen seam-line endpoint
@cindex seam-line endpoint, frozen
Enblend marks a non-movable (``frozen'') endpoint of a seam-line
segment with a @value{src::visualize-frozen-point}
@value{src::mark-frozen-point}, whereas it uses a
@value{src::visualize-movable-point} @value{src::mark-movable-point}
to denote an endpoint that the optimizer is allowed to move around.

@item @value{src::visualize-short-path-value-color}
Final seam line.
@end table

@caption{Colors used in seam-line visualization images.}

@shortcaption{Visualization colors}

@cindex visualization image colors
@cindex image colors, visualization
@cindex colors, visualization image
@end float

@ifnotinfo
@cindex seam-line visualization example
@cindex visualization example
@ref{Figure:seam-line-visualization} shows an example of a seam-line
visualization.  It was produced with an Enblend run at all defaults,
but @option{--fine-mask} and @option{--visualize} enabled.

The large @value{src::visualize-no-overlap-value-color} border is
``off-limits'' for Enblend, for the images do not overlap there.  The
dark wedge inside the @value{src::visualize-no-overlap-value-color}
frame is where the images share a common region.

The initial seam-line (@value{src::visualize-initial-path-color}) is
almost straight with the exception of a single bend on the left side
of the image and the final seam-line
(@value{src::visualize-short-path-value-color}) meanders around it.

@ifhtml
@float Figure,Figure:seam-line-visualization
@rimage{seam-line-visualization}

@caption{Seam-line visualization of a simple overlap.  The
853@classictimes{}238@dmn{pixel} image is shown at a magification of
100%.}

@shortcaption{Seam-line visualization}
@end float
@end ifhtml

@iftex
@float Figure,Figure:seam-line-visualization
@rimage{seam-line-visualization, 15cm}

@caption{Seam-line visualization of a simple overlap.  The
853@classictimes{}238@dmn{pixel} image has been rescaled to a width of
approximately 15@dmn{cm}.}

@shortcaption{Seam-line visualization}
@end float
@end iftex

@ifdocbook
@float Figure,Figure:seam-line-visualization
@rimage{seam-line-visualization, 15cm}

@caption{Seam-line visualization of a simple overlap.  The 853@classictimes{}238@dmn{pixel} image has been rescaled to a width of approximately 15@dmn{cm}.}

@shortcaption{Seam-line visualization}
@end float
@end ifdocbook
@end ifnotinfo
@end table

@page

@include mask-template-characters.texi

@node Primary Seam Generators
@chapter Primary Seam Generators
@cindex primary seam generator
@cindex seam generation

@include seam-generators.texi


@node Color Profiles
@chapter Color Profiles
@cindex profile, @acronym{ICC}
@cindex @acronym{ICC} profile
@cindex color profile

@include color-profiles.texi


@node Understanding Masks
@chapter Understanding Masks
@cindex understanding masks
@cindex masks, understanding

@include understanding-masks.texi


@node Tuning Memory Usage
@chapter Tuning Memory Usage
@cindex memory, tuning usage of
@opindex -b
@opindex -m

@include tuning-memory-usage.texi


@node Helpful Programs
@chapter Helpful Additional Programs
@cindex helpful programs
@cindex programs, helpful additional

@include helpful-programs.texi


@node Bug Reports
@appendix Bug Reports
@cindex bug reports

@include bug-reports.texi


@node Authors
@appendix Authors
@cindex authors, list of

@include authors.texi


@node FDL
@appendix @acronym{GNU} Free Documentation License
@cindex free documentation license (@acronym{FDL})
@cindex @acronym{GNU} free documentation license

@include fdl.texi


@c
@c End of Document
@c

@ifnotdocbook
@node Program Index
@unnumbered Program Index
@cindex program index
@cindex index, program

@printindex pg


@node Syntactic-Comment Index
@unnumbered Syntactic-Comment Index
@cindex syntactic-comment index
@cindex index, syntactic-comment

@printindex sc


@node Option Index
@unnumbered Option Index
@cindex option index
@cindex index, option

@printindex op


@node General Index
@unnumbered General Index
@cindex general index
@cindex index, general

@printindex cp
@end ifnotdocbook

@bye
