~ubuntu-branches/ubuntu/trusty/enblend-enfuse/trusty

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

* Color Profiles::              How Enblend handles @acronym{ICC} color profiles

@ifnotdocbook

@end ifnotdocbook

* Standard Workflow::           The usual, all-in-one thing

* External Mask Manipulation::  Fiddling around with the masks yourself

 

 

Color Profiles

 

@dbtitle{Weighting Criteria}

@caption{Enfuse's four weighting criteria.  (Also see @ref{Table:default-weights} for the default weights of these criteria.)}

Enfuse is a part of a chain of tools to assemble images.  It merges

photos of the same subject at the same location and same direction,

but taken with varying exposure parameters.

 

@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

 

@node External Mask Manipulation

@section External Mask Manipulation

@cindex workflow, external mask manipulation

 

@include external-masks.texi

 

 

* Image Requirements::          Input image requirements

@node Image Requirements

@section Image Requirements

@cindex input image requirements

 

All input images must comply with the following requirements.

 

@itemize

@item

The images overlap.

 

@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

Enfuse understands the images' filename extensions as well as their

file formats.

 

You can check the supported extensions and formats by calling Enfuse

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

 

 

Enfuse 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 Enfuse to use the @sc{Deflate}

compression scheme.  This manual denotes all arguments in lowercase

for consistency.

 

@item @acronym{JPEG} format.

 

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

@item deflate

@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

@item packbits

@item Any other format.

@item --layer-selector=@var{ALGORITHM}

@opindex --layer-selector

@cindex layer selection

@cindex layer selection

Override the standard layer selector algorithm, which is

@samp{@value{srcCOLONCOLONlayerDASHselector}}.

 

This version of Enfuse 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

 

Print information on the available options and exit.

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.

level contains image data at 

@power{2, n}

-pixel scale.  This is the

@/@math{height}@dmn{pixels} cannot be

<mathinline xmlns="http://www.w3.org/1998/Math/MathML" display="inline">

    <mrowinline>

        <mrowinline>

            <msubinline>

            </msubinline>

            <mrowinline>

                <mfencedinline>

                </mfencedinline>

            </mrowinline>

        </mrowinline>

    </mrowinline>

</mathinline>

$\lfloor \log_2(\min(\mathit{width}, \mathit{height})) \rfloor$

@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

pyramids.  Use @samp{auto} or @samp{automatic} as @var{LEVELS} to

restore the automatic calculation of the maximum number of levels.

@item --parameter=@var{KEY}[=@var{VALUE}]:@dots{}

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 Enfuse without the need to recompile.

 

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!

 

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

@sc{Born}-@sc{von@tie{}K@'arm@'an} boundary condition}.}.

<math xmlns="http://www.w3.org/1998/Math/MathML" display="separate">

@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

<math xmlns="http://www.w3.org/1998/Math/MathML" display="separate">

<math xmlns="http://www.w3.org/1998/Math/MathML" display="separate">

@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

@itemx --ciecam

@opindex --ciecam

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

All input files should have identical @acronym{ICC} profiles when this

assumes that all images use the @acronym{sRGB} color space.

@xref{Color Profiles}.

 

Please keep in mind that using @acronym{CIECAM02} blending may change

the colors in the output image.

 

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

below.

uppercase letters.  For integer format, use

For floating-point format, use

Minimum normalized value: 

Maximum finite value: 

Minimum normalized value: 

Maximum finite value: 

@itemx -f @var{WIDTH}x@var{HEIGHT}+x@var{XOFFSET}+y@var{YOFFSET}

@cindex canvas size

@cindex size, canvas

Ensure that the minimum ``canvas'' size of the output image is at

least @var{WIDTH}@c

@/@var{HEIGHT}.  Optionally specify

the @var{XOFFSET} and @var{YOFFSET}, too.

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.

this problem.  With this flag Enfuse will create the output image

with the associated alpha tag set, even though the image is really

 

@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}.

 

Valid range: @value{srcCOLONCOLONminimumDASHweightDASHcontrast} @leq{} @var{WEIGHT}

@leq{} @value{srcCOLONCOLONmaximumDASHweightDASHcontrast}.

 

Default: @value{srcCOLONCOLONdefaultDASHweightDASHcontrast}.

 

Sets the relative @var{WEIGHT} of high local entropy pixels.

 

Valid range: @value{srcCOLONCOLONminimumDASHweightDASHentropy} @leq{} @var{WEIGHT}

@leq{} @value{srcCOLONCOLONmaximumDASHweightDASHentropy}.

 

Default: @value{srcCOLONCOLONdefaultDASHweightDASHentropy}.

pixels contribute more to the final output.

 

Valid range: @value{srcCOLONCOLONminimumDASHweightDASHexposure} @leq{} @var{WEIGHT}

@leq{} @value{srcCOLONCOLONmaximumDASHweightDASHexposure}.

 

Default: @value{srcCOLONCOLONdefaultDASHweightDASHexposure}.

weight curve.

 

Valid range: @value{srcCOLONCOLONminimumDASHexposureDASHmu} @leq{} @var{MEAN}

@leq{} @value{srcCOLONCOLONmaximumDASHexposureDASHmu}.

 

Default: @value{srcCOLONCOLONdefaultDASHexposureDASHmu}.

curve.  Low numbers give less weight to pixels that are far from

@option{--wMu} and vice versa.

 

Valid range: @var{STD-DEV} @geq{} @value{srcCOLONCOLONminimumDASHexposureDASHsigma}.

 

Default: @value{srcCOLONCOLONdefaultDASHexposureDASHsigma}.

final output.

 

Valid range: @value{srcCOLONCOLONminimumDASHweightDASHsaturation}

@leq{} @var{WEIGHT} @leq{} @value{srcCOLONCOLONmaximumDASHweightDASHsaturation}.

 

Default: @value{srcCOLONCOLONdefaultDASHweightDASHsaturation}.

@cindex Laplacian-of-Gaussian

 

@var{enhanced} = (1 + @var{LCE-FACTOR}) @c

@classictimes{}@c

 @var{original}

@minus{} @var{LCE-FACTOR} @c

@classictimes{}@c

 Gaussian@/Smooth(@var{original},

@var{LCE-SCALE}).

@item --contrast-min-curvature=@var{CURVATURE}

@opindex --contrast-min-curvature

 

Define the minimum @var{CURVATURE} for the @acronym{LoG} edge

detection.  Default: @value{srcCOLONCOLONdefaultDASHminimumDASHcurvature}.  Append a

@samp{%} to specify the minimum curvature relative to maximum pixel

value in the source image (for example 255 or 65535).

 

A positive value makes Enfuse use the local contrast data (controlled

with @option{--contrast-window-size}) for curvatures less than

@var{CURVATURE} and @acronym{LoG} data for values above it.

 

A negative value truncates all curvatures less than

@minus{}@var{CURVATURE} to zero.  Values above @var{CURVATURE} are

left unchanged.  This effectively suppresses weak edges.

 

@item --contrast-window-size=@var{SIZE}

@opindex --contrast-window-size

 

Set the window @var{SIZE} for local contrast analysis.  The window

will be a square of @var{SIZE}@c

@classictimes{}@c

@/@var{SIZE} pixels.  If

given an even @var{SIZE}, Enfuse will automatically use the next odd

number.

 

For contrast analysis @var{SIZE} values larger than 5 might result in

a blurry composite image.  Values of 3 and 5 have given good results

on focus stacks.

 

Valid range: @var{SIZE} @geq{} @value{srcCOLONCOLONminimumDASHcontrastDASHwindowDASHsize}.

 

Default: @value{srcCOLONCOLONdefaultDASHcontrastDASHwindowDASHsize}@dmn{pixels}.

 

See also @ref{Fusion Options, Option --contrast-weight} and

@option{--hard-mask} below.

 

@vimage{entropy-cutoff}

@caption{Linear lightness@tie{}@var{Y} in comparison with an entropy-cutoff function for @var{LOWER-CUTOFF} = 5% and @var{UPPER-CUTOFF} = 90%, which are rather extreme values.  Please note that we have shifted the original lightness curve up and the cut-off curve down by a very small @var{Offset} to emphasize that the proportional part of @var{Y} remains unaltered under the cut-off operation.}

@/@var{SIZE} pixels.

Valid range: @var{SIZE} @geq{} @value{srcCOLONCOLONminimumDASHentropyDASHwindowDASHsize}.

 

Default: @value{srcCOLONCOLONdefaultDASHentropyDASHwindowDASHsize}@dmn{pixels}.

@item --exposure-cutoff=@var{LOWER-CUTOFF}

@itemx --exposure-cutoff=@var{LOWER-CUTOFF}:@var{UPPER-CUTOFF}

@itemx --exposure-cutoff=@var{LOWER-CUTOFF}:@var{UPPER-CUTOFF}:@var{LOWER-PROJECTOR}:@var{UPPER-PROJECTOR}

@opindex --exposure-cutoff

 

The first form sets the weight for all pixels below the lower cutoff

to zero.  The second form sets the lower cutoff and the upper cutoff

at the same time.  For color images the values of @var{LOWER-CUTOFF}

and @var{UPPER-CUTOFF} refer to the gray-scale projection as selected

with the option @option{--gray-projector}.

 

The impact of this option is similar, but not identical to

transforming @emph{all} input images with

@uref{http://@/www.imagemagick.org/, ImageMagick's} @command{convert}

(@pxref{Helpful Programs}) prior to fusing with the following

commands.

 

@example

@group

# First form

convert IMAGE \

        \( +clone -threshold LOWER-CUTOFF \) \

        -compose copy_opacity -composite \

        MASKED-IMAGE

@end group

 

@group

# Second form

convert IMAGE \

        \( \

            \( IMAGE -threshold LOWER-CUTOFF \) \

            \( IMAGE -threshold UPPER-CUTOFF -negate \) \

            -compose multiply -composite \

        \) \

        -compose copy_opacity -composite \

        MASKED-IMAGE

@end group

@end example

 

(Transforming some or all input images as shown in the above examples

gives the user more flexibility because the thresholds can be chosen

for each image individually.)

 

The third form specifies projection operators as in

option@tie{}@option{--gray-projector} for the @var{LOWER-CUTOFF} and

@var{UPPER-CUTOFF} thresholds.

 

This option can be helpful if the user wants to exclude underexposed

or overexposed pixels from the fusing process in @emph{all} of the

input images.  The values of @var{LOWER-CUTOFF} and @var{UPPER-CUTOFF}

as well as the gray-scale projector determine which pixels are

considered ``underexposed'' or ``overexposed''.  As any change of the

exposure-weight curve this option changes the brightness of the

resulting image: increasing @var{LOWER-CUTOFF} lightens the final

image and lowering @var{UPPER-CUTOFF} darkens it.

 

Defaults: @value{srcCOLONCOLONdefaultDASHexposureDASHlowerDASHcutoff} for

@var{LOWER-CUTOFF} and @value{srcCOLONCOLONdefaultDASHexposureDASHupperDASHcutoff} for

@var{UPPER-CUTOFF}, that is, all pixels' values are weighted according

to the ``uncut'' exposure-weight curve.

 

Append a @samp{%} to specify the cutoff relative to the maximum pixel

value in the source image (for example 255 or 65535).