10
@setfilename enblend.info
11
@settitle Combining Multiple Images with Enblend @value{VERSION}
13
@include versenblend.texi
14
@include varsenblend.texi
15
@include config-h.texi
17
@set default-image-cache-cachesize 1024@dmn{MB}
18
@set default-image-cache-blocksize 2048@dmn{KB}
20
@c Define a new index for syntactic comments.
22
@c Define a new index for options.
28
@c Categorization for the GNU Info System
31
@dircategory Individual utilities
34
* enblend: (enblend). Blend images using a multiresolution spline.
39
@c Summary Description and Copyright
43
This manual is for Enblend (version @value{VERSION}, @value{UPDATED}),
44
a tool for compositing images in such a way that the seam between the
45
images is invisible, or at least very difficult to see.
47
Copyright @copyright{} 2004--2009 @sc{Andrew Mihal}.
50
Permission is granted to copy, distribute and/or modify this document
51
under the terms of the @acronym{GNU} Free Documentation License,
52
Version 1.2 or any later version published by the Free Software
53
Foundation; with no Invariant Sections, no Front-Cover Texts and no
54
Back-Cover Texts. A copy of the license is included in the section
55
entitled ``@acronym{GNU} Free Documentation License''.
61
@c Title Page and Copyright
66
@subtitle Combining Multiple Images
67
@subtitle with Enblend version @value{VERSION}, @value{UPDATED}
83
@c For the TeX output the List-of-Tables and List-of-Figures appear
84
@c right after the Table-of-Contents. In all other formats they go
85
@c right before the indices.
87
@c Adjust page number so that we get roman numerals for the
88
@c List-of-Tables and List-of-Figures. This screws up Texinfo's page
89
@c count so that we must undo it later.
94
@unnumbered List of Tables
98
@unnumbered List of Figures
104
@c ``Top'' Node and Master Menu
111
This manual is for Enblend (version@tie{}@value{VERSION},
112
@value{UPDATED}), a tool for compositing images in such a way that the
113
seam between the images is invisible, or at least very difficult to
118
* Overview:: Overview of Enblend's features
119
* Workflow:: Enblend's role in making panoramas
120
* Invocation:: Command line options and arguments
121
* Understanding Masks:: How to interpret masks and mask files
122
* Tuning Memory Usage:: Balancing @acronym{RAM} and swap
123
* Helpful Programs:: Useful other programs
124
* Bug Reports:: How to write bug reports
125
* Authors:: Major Contributors
126
* FDL:: @acronym{GNU} Free Documentation License
127
* Program Index:: Names of programs referenced
128
* Syntactic-Comment Index:: Keys of syntactic comments
129
* Option Index:: Index of all options
130
* General Index:: Topic index
141
@c Undo the roman page numbering we used for the Table-of-Contents,
142
@c the List-of-Tables, and the List-of-Figures.
149
@cindex Burt-Adelson multiresolution spline
150
Enblend overlays multiple @acronym{TIFF} images using the
151
@sc{Burt}-@sc{Adelson} multiresolution spline
152
algorithm.@footnote{@sc{Peter J. Burt} and @sc{Edward H. Adelson}, ``A
153
Multiresolution Spline With Application to Image Mosaics'',
154
@acronym{ACM} Transactions on Graphics, @abbr{Vol@.} 2, @abbr{No@.} 4,
155
October 1983, pages 217--236.} This technique tries to make the seams
156
between the input images invisible. The basic idea is that image
157
features should be blended across a transition zone proportional in
158
size to the spatial frequency of the features. For example, objects
159
like trees and windowpanes have rapid changes in color. By blending
160
these features in a narrow zone, you will not be able to see the seam
161
because the eye already expects to see color changes at the edge of
162
these features. Clouds and sky are the opposite. These features have
163
to be blended across a wide transition zone because any sudden change
164
in color will be immediately noticeable.
166
@cindex alpha channel
167
@cindex channel, alpha
168
Enblend expects each input file to have an alpha channel. The alpha
169
channel should indicate the region of the file that has valid image
170
data. Enblend compares the alpha regions in the input files to find
171
the areas where images overlap. Alpha channels can be used to
172
indicate to Enblend that certain portions of an input image should not
173
contribute to the final image.
177
@cindex feathering, detrimental effect of
178
Enblend does @emph{not} align images. Use a tool such as
179
@command{hugin} or PanoTools to do this. The
180
@acronym{TIFF}@tie{}files produced by these programs are exactly what
181
Enblend is designed to work with. Sometimes these @acronym{GUI}s
182
allow you to select feathering for the edges of your images. This
183
treatment is detrimental to Enblend. Turn off feathering by
184
deselecting it or setting the feather width to zero.
186
Enblend blends the images in the order they are specified on the
187
command line. You should order your images according to the way that
188
they overlap, for example from left-to-right across the panorama. If
189
you are making a multi-row panorama, we recommend blending each
190
horizontal row individually, and then running Enblend a last time to
191
blend all of the rows together vertically.
193
@cindex multi-layer image
194
@cindex image, multi-layer
195
@cindex multi-directory @acronym{TIFF}
196
@cindex @acronym{TIFF}, multi-directory
197
@cindex @command{tiffcopy}
198
@cindex @command{tiffsplit}
199
Enblend reads all layers of multi-layer images, like, for example,
200
multi-directory @acronym{TIFF} images@footnote{Use utilities like,
201
e.g., @command{tiffcopy} and @command{tiffsplit} of LibTIFF to
202
manipulate multi-directory @acronym{TIFF} images. @xref{Helpful
203
Programs}.}. The input images are processed in the order they appear
204
on the command line. Multi-layer images are processed from the first
205
layer to the last before Enblend considers the next image on the
209
Find out more about Enblend on its @uref{http://@/sourceforge.net/,
210
SourceForge} @uref{http://@/enblend.sourceforge.net/, web page}.
217
@include workflow.texi
224
@command{enblend} [@var{OPTIONS}] [@code{--output=}@var{IMAGE}]
225
@var{INPUT}@enddots{}
228
Assemble the sequence of images @var{INPUT}@dots{} into a single
231
@cindex literal filename
232
@cindex filename, literal
233
@cindex response file
234
Input images are either specified literally or via so-called response
235
files (see below). The latter are an alternative to specifying image
236
filenames on the command line.
240
* Response Files:: Files listing the images' names
241
* Common Options:: General options
242
* Extended Options:: Memory and @acronym{GPU} control
243
* Mask Generation Options:: Mask generation control
248
@section Response Files
249
@cindex response file
251
@include filespec.texi
255
@section Common Options
256
@cindex options, common
258
Common options control some overall features of Enblend.
263
Pre-assemble non-overlapping images before each blending iteration.
265
This overrides the default behavior which is to blend the images
266
sequentially in the order given on the command line. Enblend will use
267
fewer blending iterations, but it will do more work in each iteration.
269
@item --compression=@var{COMPRESSION}
270
@opindex --compression
271
@cindex output file compression
273
Write a compressed output file.
275
Depending on the output file format Enblend accepts different values
276
for @var{COMPRESSION}.
280
@cindex @acronym{JPEG} compression
281
@cindex compression, @acronym{JPEG}
282
@var{COMPRESSION} is a @acronym{JPEG} quality level ranging from
286
@var{COMPRESSION} is one of the keywords:
290
Do not compress. This is the default.
293
@cindex deflate compression
294
@cindex compression, deflate
295
Use the @sc{Deflate} compression scheme also called
296
@acronym{ZIP}-in-@acronym{TIFF}. @sc{Deflate} is a lossless data
297
compression algorithm that uses a combination of the @acronym{LZ77}
298
algorithm and @sc{Huffman} coding.
301
@cindex @acronym{LZW} compression
302
@cindex compression, @acronym{LZW}
303
Use @sc{Lempel}-@sc{Ziv}-@sc{Welch} (@acronym{LZW}) adaptive
304
compression scheme. @acronym{LZW} compression is lossless.
307
@cindex packbits compression
308
@cindex compression, packbits
309
Use @sc{PackBits} compression scheme. @sc{PackBits} is particular
310
variant of run-length compression. It is lossless.
313
@item Any other format
314
Other formats do not accept a @var{COMPRESSION} setting.
316
However, @uref{http://@/hci.iwr.uni-@/heidelberg.de/@/vigra/,
317
@acronym{VIGRA}} automatically compresses @file{png}-files with the
325
Print information on the available options and exit.
327
@item -l @var{LEVELS}
328
@itemx --levels=@var{LEVELS}
331
@cindex pyramid levels
332
@cindex levels, pyramid
333
Use at most this many @var{LEVELS} for pyramid @footnote{As
334
Dr.@tie{}Daniel Jackson correctly
335
@uref{http://stargate.wikia.com/@/wiki/@/The_@/Tomb, noted}, actually,
336
it is not a pyramid: ``Ziggaurat, it's a
337
@uref{http://en.wikipedia.org/@/wiki/@/Ziggaurat, Ziggaurat}.''}
338
blending if @var{LEVELS} is positive, or reduce the maximum number of
339
levels used by @minus{}@var{LEVELS} if @var{LEVELS} is negative.
341
The number of levels used in a pyramid controls the balance between
342
local and global image features (contrast, saturation, @dots{}) in the
343
blended region. Fewer levels emphasize local features and suppress
344
global ones. The more levels a pyramid has, the more global features
345
will be taken into account.
347
As a guideline, remember that each new level works on a linear scale
348
twice as large as the previous one. So, the zeroth layer, the
349
original image, obviously defines the image at single-pixel scale, the
350
first level works at two-pixel scale, and generally, the @math{n}-th
351
level contains image data at @math{2^n}-pixel scale. This is the
352
reason why an image of
353
@math{width}@classictimes{}@math{height}@tie{}pixels cannot be
354
deconstructed into a pyramid of more than
357
@math{floor(log_2(min(width, height)))}
361
<math xmlns="http://www.w3.org/1998/Math/MathML">
369
<mo>⁡</mo>
373
<mo>⁡</mo>
375
<mi mathvariant="italic">width</mi>
376
<mi mathvariant="italic">height</mi>
381
<mo>⌋</mo>
387
\lfloor \log_2(\min(\mathit{width}, \mathit{height})) \rfloor
392
If too few levels are used, ``halos'' around regions of strong local
393
feature variation can show up. On the other hand, if too many levels
394
are used, the image might contain too much global features. Usually,
395
the latter is not a problem, but is highly desired. This is the
396
reason, why the default is to use as many levels as is possible given
397
the size of the overlap regions. Enblend may still use a smaller
398
number of levels if the geometry of the overlap region demands.
400
Positive values of @var{LEVELS} limit the maximum number of pyramid
401
levels. Depending on the size and geometry of the overlap regions
402
this may or may not influence any pyramid. Negative values of
403
@var{LEVELS} reduce the number of pyramid levels below the maximum no
404
matter what the actual maximum is and thus always influence all
407
The valid range of the absolute value of @var{LEVELS} is
408
@value{src::minimum-pyramid-levels} to
409
@value{src::maximum-pyramid-levels}.
412
@itemx --output=@var{FILE}
415
Place output in @var{FILE}.
417
@cindex @file{@value{src::default-output-filename}}
418
@cindex default output filename
419
@cindex output filename, default
420
If @option{--output} is not specified, the default is to put the
421
resulting image in @file{@value{src::default-output-filename}}.
424
@itemx --verbose[=@var{LEVEL}]
427
Without an argument, increase the verbosity of progress reporting.
428
Giving more @option{--verbose}@tie{}options will make Enblend more
429
verbose. Directly set a verbosity level with a non-negative integral
432
Each level includes all messages of the lower levels.
439
only warnings and errors
442
reading and writing of images
445
mask generation, pyramid, and blending
448
reading of response files, color conversions
451
image sizes, bounding boxes and intersection sizes
454
detailed information on the optimizer runs (Enblend only)
457
estimations of required memory in selected processing steps
460
The default verbosity level of Enblend is
461
@value{src::default-verbosity-level}.
467
Output information on the Enblend version.
469
Team this option with @option{--verbose} to inquire about
470
configuration details, like the extra features that have been compiled
474
@itemx --wrap=@var{MODE}
477
@cindex 360@textdegree{} panoramas
479
Blend around the boundaries of the panorama.
481
With this option Enblend treats the panorama of width@tie{}@math{w}
482
and height@tie{}@math{h} as an infinite data structure, where each
483
pixel@tie{}@math{P(x, y)} of the input images represents the set of
484
pixels@tie{}@math{S_P(x, y)}@footnote{Solid-state physicists will be
486
@uref{http://@/en.wikipedia.org/@/wiki/@/Born-@/von_@/Karman_@/boundary_@/condition,
487
@sc{Born}-@sc{von@tie{}K@'arm@'an} boundary condition}.}.
489
@var{MODE} takes the following values:
494
This is a ``no-op''; it has the same effect as not giving
495
@option{--wrap} at all. The set of input images is considered open at
499
Wrap around horizontally:
502
@math{S_P(x, y) = @{P(x + m * w, y): m in Z@}.}
506
<math xmlns="http://www.w3.org/1998/Math/MathML">
526
<mo>⁢</mo>
535
<mtext>  in  </mtext>
546
S_P(x, y) = \{P(x + m w, y): m \in Z\}.
549
This is useful for 360@textdegree{} horizontal panoramas as it
550
eliminates the left and right borders.
553
Wrap around vertically:
556
@math{S_P(x, y) = @{P(x, y + n * h): m in Z@}.}
560
<math xmlns="http://www.w3.org/1998/Math/MathML">
581
<mo>⁢</mo>
589
<mtext>  in  </mtext>
600
S_P(x, y) = \{P(x, y + n h): n \in Z\}.
603
This is useful for 360@textdegree{} vertical panoramas as it
604
eliminates the top and bottom borders.
607
@itemx horizontal+vertical
608
@itemx vertical+horizontal
609
Wrap around both horizontally and vertically:
612
@math{S_P(x, y) = @{P(x + m * w, y + n * h): m, n in Z@}.}
616
<math xmlns="http://www.w3.org/1998/Math/MathML">
636
<mo>⁢</mo>
643
<mo>⁢</mo>
655
<mtext>  in  </mtext>
666
S_P(x, y) = \{P(x + m w, y + n h): m, n \in Z\}.
669
In this mode, both left and right borders, as well as top and bottom
670
borders, are eliminated.
673
Specifying @option{--wrap} without @var{MODE} selects horizontal
678
Checkpoint partial results to the output file after each blending
683
@node Extended Options
684
@section Extended Options
685
@cindex options, extended
687
Extended options control the image cache, the color model, and the
688
cropping of the output image.
691
@item -b @var{BLOCKSIZE}
693
@cindex image cache, block size
694
Set the @var{BLOCKSIZE} in kilobytes (@acronym{KB}) of Enblend's image
697
This is the amount of data that Enblend will move to and from the disk
698
at one time. The default is @value{default-image-cache-blocksize},
699
which should be ok for most systems. See @ref{Tuning Memory Usage}
702
Note that Enblend must have been compiled with the image-cache feature
703
for this option to be effective. Find out about extra features with
704
@code{enblend --version --verbose}.
708
@cindex color appearance model
709
@cindex @acronym{CIECAM02}
710
Use the @acronym{CIECAM02} color appearance model for blending colors.
712
@cindex @acronym{ICC} profile
713
@cindex profile, @acronym{ICC}
714
@cindex @acronym{sRGB} color space
715
@cindex color space, @acronym{sRGB}
716
The input files should have embedded @acronym{ICC} profiles if this
717
option is specified. If no @acronym{ICC} profile is present, Enblend
718
will assume that the image uses the @acronym{sRGB} color space. The
719
difference between this option and Enblend's default color blending
720
algorithm is very slight and will only be noticeable when areas of
721
different primary colors are blended together.
724
@itemx --depth=@var{DEPTH}
727
@cindex bits per channel
728
@cindex channel width
729
Force the number of bits per channel and the numeric format of the
732
Enblend always uses a smart way to change the channel depth to assure
733
highest image quality (at the expense of memory), whether
734
requantization is implicit because of the output format or explicit
735
with option@tie{}@option{--depth}.
739
If the output-channel width is larger than the input-channel width of
740
the input images, the input images' channels are widened to the output
741
channel width immediately after loading, that is, as soon as possible.
742
Enblend then performs all blending operations at the output-channel
743
width, thereby preserving minute color details which can appear in the
747
If the output-channel width is smaller than the input-channel width of
748
the input images, the output image's channels are narrowed only right
749
before it is written to disk, that is, as late as possible. Thus the
750
data benefits from the wider input channels for the longest time.
753
All @var{DEPTH} specifications are valid in lowercase as well as
754
uppercase letters. For integer format, use
757
@item @code{8}, @code{uint8}
758
Unsigned 8@dmn{bit}; range: 0..255
760
Signed 16@dmn{bit}; range: @minus{}32768..32767
761
@item @code{16}, @code{uint16}
762
Unsigned 16@dmn{bit}; range: 0..65535
764
Signed 32@dmn{bit}; range: @minus{}2147483648..2147483647
765
@item @code{32}, @code{uint32}
766
Unsigned 32@dmn{bit}; range: 0..4294967295
769
For floating-point format, use
771
@c Minimum positive normalized value: 2^(2 - 2^k)
772
@c Epsilon: 2^(1 - n)
773
@c Maximum finite value: (1 - 2^(-n)) * 2^(2^k)
776
@c IEEE single: 32 bits, n = 24, k = 32 - n - 1 = 7
777
@item @code{r32}, @code{real32}, @code{float}
778
@cindex @acronym{IEEE754} single precision float
779
@cindex single precision float, @acronym{IEEE754}
780
@acronym{IEEE754} single precision floating-point, 32@dmn{bit} wide,
781
24@dmn{bit} significant
785
Minimum normalized value: @semilog{1.2, -38}
787
Epsilon: @semilog{1.2, -7}
789
Maximum finite value: @semilog{3.4, 38}
792
@c IEEE double: 64 bits, n = 53, k = 64 - n - 1 = 10
793
@item @code{r64}, @code{real64}, @code{double}
794
@cindex @acronym{IEEE754} double precision float
795
@cindex double precision float, @acronym{IEEE754}
796
@acronym{IEEE754} double precision floating-point, 64@dmn{bit} wide,
797
53@dmn{bit} significant
801
Minimum normalized value: @semilog{2.2, -308}
803
Epsilon: @semilog{2.2, -16}
805
Maximum finite value: @semilog{1.8, 308}
809
If the requested @var{DEPTH} is not supported by the output file
810
format, Enblend warns and chooses the @var{DEPTH} that matches best.
812
@cindex @acronym{OpenEXR}, data format
813
The @acronym{OpenEXR} data format is treated as
814
@acronym{IEEE754}@tie{}float internally. Externally, on disk,
815
@acronym{OpenEXR} data is represented by ``half'' precision
816
floating-point numbers.
818
@c ILM half: 16 bits, n = 10, k = 16 - n - 1 = 5
819
@cindex @acronym{OpenEXR}, half precision float
820
@cindex half precision float, @acronym{OpenEXR}
821
@uref{http://@/www.openexr.com/@/about.html#@/features,
822
@acronym{OpenEXR}} half precision floating-point, 16@dmn{bit} wide,
823
10@dmn{bit} significant
827
Minimum normalized value: @semilog{9.3, -10}
829
Epsilon: @semilog{2.0, -3}
831
Maximum finite value: @semilog{4.3, 9}
834
@item -f @var{WIDTH}x@var{HEIGHT}
835
@itemx -f @var{WIDTH}x@var{HEIGHT}+x@var{XOFFSET}+y@var{YOFFSET}
837
@cindex output image, set size of
838
Set the size of the output image manually to
839
@var{WIDTH}@classictimes{}@var{HEIGHT}. Optionally specify the
840
@var{X-OFFSET} and @var{Y-OFFSET}, too.
842
@pindex nona @r{(Hugin)}
844
This option is useful when the input images are cropped @acronym{TIFF}
845
files, such as those produced by @command{nona}. The stitcher
846
@command{nona} is part of Hugin. @xref{Helpful Programs}.
850
@cindex alpha channel, associated
851
Save alpha channel as ``associated''. See the
852
@uref{http://@/www.awaresystems.be/@/imaging/@/tiff/@/tifftags/@/extrasamples.html,
853
@acronym{TIFF} documentation} for an explanation.
857
Gimp (before version@tie{}2.0) and Cinepaint (@pxref{Helpful
858
Programs}) exhibit unusual behavior when loading images with
859
unassociated alpha channels. Use option @option{-g} to work around
860
this problem. With this flag Enblend creates the output image with
861
the associated alpha tag set, even though the image is really
866
@cindex graphics processing unit
867
@cindex @acronym{GPU} (Graphics Processing Unit)
868
Use the graphics card -- in fact the graphics processing unit
869
(@acronym{GPU}) -- to accelerate some computations.
871
This is an experimental feature that may not work on all systems. In
872
this version of Enblend, @value{VERSION}, only mask optimization
873
strategy@tie{}1 benefits from this option.
875
Note that @acronym{GPU}-support must have been compiled into Enblend
876
for this option to be available. Find out about this feature with
877
@code{enblend --version --verbose}.
879
@item -m @var{CACHESIZE}
881
@cindex image cache, cache size
882
Set the @var{CACHESIZE} in megabytes (@acronym{MB}) of Enblend's image
885
This is the amount of memory Enblend will use for storing image data
886
before swapping to disk. The default is
887
@value{default-image-cache-cachesize} which is good for systems with
888
3--4@dmn{gigabytes} (@acronym{GB}) of @acronym{RAM}. See @ref{Tuning
889
Memory Usage} for details.
891
Note that Enblend must have been compiled with the image-cache feature
892
for this option to be effective. Find out about extra features with
893
@code{enblend --version --verbose}.
897
@node Mask Generation Options
898
@section Mask Generation Options
899
@cindex options, mask generation
901
These options control the generation and the usage of masks.
904
@item --anneal=@var{TAU}[:@var{DELTA-E-MAX}[:@var{DELTA-E-MIN}[:@var{K-MAX}]]]
906
@cindex optimize, anneal parameters
907
@cindex anneal parameters
908
@cindex simulated annealing optimizer
909
@cindex optimizer, simulated annealing
910
Set the parameters of the Simulated Annealing optimizer used in
911
Optimizer Strategy@tie{}1 (see @ref{Table:optimizer-strategies}).
915
@var{TAU} is the temperature reduction factor in the Simulated
916
Annealing; it also can be thought of as ``cooling factor''. The
917
closer @var{TAU} is to one, the more accurate the annealing run will
918
be, and the longer it will take.
920
Append a percent sign (@samp{%}) to specify @var{TAU} as a percentage.
924
@value{src::minimum-anneal-tau} < @var{TAU} <
925
@value{src::maximum-anneal-tau}.
928
<math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
930
<mn>@value{src::minimum-anneal-tau}</mn>
932
<mi mathvariant="italic">TAU</mi>
934
<mn>@value{src::maximum-anneal-tau}</mn>
940
$@value{src::minimum-anneal-tau} < \mathit{TAU} <
941
@value{src::maximum-anneal-tau}$.
944
The default is @value{src::default-anneal-tau}; values around 0.95 are
945
reasonable. Usually, slower cooling results in more converged points.
949
@var{DELTA-E-MAX} and @var{DELTA-E-MIN} are the maximum and minimum
950
cost change possible by any single annealing move.
954
@value{src::minimum-anneal-deltae-min} < DELTA-E-MIN < DELTA-E-MAX.
957
<math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
959
<mn>@value{src::minimum-anneal-deltae-min}</mn>
961
<mi mathvariant="italic">DELTA-E-MIN</mi>
963
<mi mathvariant="italic">DELTA-E-MAX</mi>
969
$@value{src::minimum-anneal-deltae-min} < \mathit{DELTA-E-MIN} <
970
\mathit{DELTA-E-MAX}$.
973
In particular they determine the initial and final annealing
974
temperatures according to:
978
T_initial = ------------------------
979
log(K-MAX / (K-MAX - 2))
982
T_final = ------------------------
983
log(K-MAX^2 - K-MAX - 1)
987
<math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
993
<mi mathvariant="italic">T</mi>
994
<mi mathvariant="roman">initial</mi>
998
<mi mathvariant="italic">DELTA-E-MAX</mi>
1001
<mo>⁡</mo>
1004
<mi mathvariant="italic">K-MAX</mi>
1008
<mi mathvariant="italic">K-MAX</mi>
1025
<mi mathvariant="italic">T</mi>
1026
<mi mathvariant="roman">final</mi>
1030
<mi mathvariant="italic">DELTA-E-MIN</mi>
1033
<mo>⁡</mo>
1037
<mi mathvariant="italic">K-MAX</mi>
1041
<mi mathvariant="italic">K-MAX</mi>
1056
T_{\mathrm{initial}} & =
1057
{\mathit{DELTA-E-MAX} \over {\log(\mathit{K-MAX} / (\mathit{K-MAX} - 2))}} \cr
1058
T_{\mathrm{final}} & =
1059
{\mathit{DELTA-E-MIN} \over {\log(\mathit{K-MAX\/}^2 - \mathit{K-MAX} - 1)}} \cr
1063
The defaults are: @var{DELTA-E-MAX}:
1064
@value{src::default-anneal-deltae-max} and @var{DELTA-E-MIN}:
1065
@value{src::default-anneal-deltae-min}.
1068
@var{K-MAX} is the maximum number of ``moves'' the optimizer will make
1069
for each line segment. Higher values more accurately sample the state
1070
space, at the expense of a higher computation cost.
1074
@var{K-MAX} @geq{} @value{src::minimum-anneal-kmax}.
1077
<math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
1079
<mi mathvariant="italic">K-MAX</mi>
1082
<mtext>@value{src::minimum-anneal-kmax}.</mtext>
1087
$\mathit{K-MAX} \ge @value{src::minimum-anneal-kmax}$.
1090
The default is @value{src::default-anneal-kmax}. Values around 100
1094
@item --coarse-mask[=@var{FACTOR}]
1095
@opindex --coarse-mask
1096
@cindex mask, coarse
1098
Use a scaled-down version of the input images to create the seam line.
1099
This option reduces the number of computations necessary to compute
1100
the seam line and the amount of memory necessary to do so. It is the
1103
If omitted @var{FACTOR} defaults to
1104
@value{src::default-coarseness-factor}, this means,
1105
option@tie{}@option{--coarse-mask} shrinks the overlapping
1106
@emph{areas} by a factor of
1107
@math{@value{src::default-coarseness-factor} @classictimes{}
1108
@value{src::default-coarseness-factor}}. With
1109
@var{FACTOR}@tie{}=@tie{}8 the total memory allocated during a run of
1110
Enblend shrinks approximately by 80% and the maximum amount of memory
1111
in use at a time is decreased to 60% (Enblend compiled with image
1112
cache) or 40% (Enblend compiled without image cache).
1114
Valid range: @var{FACTOR} = 1, 2, 3,@dots{}.
1116
Also see @ref{Table:mask-generation}.
1118
@float Table,Table:mask-generation
1119
@multitable @columnfractions 0.2 0.35 0.35
1120
@headitem @tab @code{--no-optimize} @tab @code{--optimize}
1122
@item @code{--fine-mask}
1125
Use @acronym{NFT} mask.
1129
Vectorize @acronym{NFT} mask, optimize vertices with simulated
1130
annealing and @sc{Dijkstra's} shortest path algorithm, fill vector
1133
@item @code{--coarse-mask}
1136
Scale down overlap region, compute @acronym{NFT} mask and vectorize
1137
it, fill vector contours.
1141
Scale down overlap region, vectorize @acronym{NFT} mask, optimize
1142
vertices with simulated annealing and @sc{Dijkstra's} shortest path
1143
algorithm, fill vector contours.
1146
@caption{Various options that control the generation of masks. All
1147
mask computations are based on the Nearest-Feature Transformation
1148
(@acronym{NFT}) of the overlap region.}
1150
@shortcaption{Mask generation options}
1152
@cindex nearest-feature transform (@acronym{NFT})
1153
@cindex mask, generation
1156
@item --dijkstra=@var{RADIUS}
1158
@cindex @sc{Dijkstra} radius
1159
@cindex radius, @sc{Dijkstra}
1160
Set the search @var{RADIUS} of the @sc{Dijkstra} Shortest Path
1161
algorithm used in Optimizer Strategy@tie{}2 (see
1162
@ref{Table:optimizer-strategies}).
1164
A small value prefers straight line segments and thus shorter seam
1165
lines. Larger values instruct the optimizer to let the seam line take
1166
more detours when searching for the best seam line.
1170
@var{RADIUS} @geq{} @value{src::minimum-dijkstra-radius}.
1173
<math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
1175
<mi mathvariant="italic">RADIUS</mi>
1177
<mn>@value{src::minimum-dijkstra-radius}</mn>
1183
$\mathit{RADIUS} \ge @value{src::minimum-dijkstra-radius}$.
1186
Default: @value{src::default-dijkstra-radius}@dmn{pixels}.
1189
@opindex --fine-mask
1192
Instruct Enblend to employ the full-size images to create the seam
1193
line, which can be slow. Use this option, for example, if you have
1194
very narrow overlap regions.
1196
Also see @ref{Table:mask-generation}.
1198
@item --load-masks[=@var{IMAGE-TEMPLATE}]
1199
@opindex --load-masks
1202
Instead of generating masks, use those in @var{IMAGE-TEMPLATE}. The
1203
default is @file{@value{src::default-mask-template}}.
1205
See @option{--save-masks} below for details.
1207
@item --mask-vectorize=@var{DISTANCE}
1208
@opindex --mask-vectorize
1209
@cindex mask, vectorization distance
1210
Set the mask vectorization @var{DISTANCE} Enblend uses to partition
1211
each seam. Thus, break down the seam to segments of length
1212
@var{DISTANCE} each.
1214
If Enblend uses a coarse mask (@option{--coarse-mask}) or Enblend
1215
optimizes (@option{--optimize}) a mask it vectorizes the initial seam
1216
line before performing further operations. See
1217
@ref{Table:mask-generation} for the precise conditions.
1218
@var{DISTANCE} tells Enblend how long to make each of the line
1219
segments called vectors here.
1221
The unit of @var{DISTANCE} is pixels unless it is a percentage as
1222
explained in the next paragraph. In fine masks one mask pixel
1223
corresponds to one pixel in the input image, whereas in coarse masks
1224
one pixel represents for example
1225
@value{src::default-coarseness-factor}@dmn{pixels} in the input image.
1227
Append a percentage sign (@samp{%}) to @var{DISTANCE} to specify the
1228
segment length as a fraction of the diagonal of the rectangle
1229
including the overlap region. Relative measures do not depend on
1230
coarse or fine masks, they are recomputed for each mask. Values
1231
around 5%--10% are a good starting point.
1233
This option massively influences the mask generation process! Large
1234
@var{DISTANCE} values lead to shorter, straighter, less wiggly, less
1235
baroque seams that are on the other hand less optimal, because they
1236
run through regions of larger image mismatch instead of avoiding them.
1237
Small @var{DISTANCE} values give the optimizers more possibilities to
1238
run the seam around high mismatch areas.
1240
@cindex seam line, loops
1241
@cindex loops in seam line
1242
What should @emph{never} happen though, are loops in the seam line.
1243
Counter loops with higher weights of @var{DISTANCE-WEIGHT} (in
1244
option@tie{}@option{--optimizer-weights}), larger vectorization
1245
@var{DISTANCE}s, @var{TAU}s (in option@tie{}@option{--anneal}) that
1246
are closer to one, and blurring of the difference image with
1247
option@tie{}@option{--smooth-difference}. Use
1248
option@tie{}@option{--visualize} to check the results.
1252
@var{DISTANCE} @geq{} @value{src::minimum-vectorize-distance}.
1255
<math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
1257
<mi mathvariant="italic">DISTANCE</mi>
1265
$\mathit{DISTANCE} \ge @value{src::minimum-vectorize-distance}$.
1267
Enblend limits @var{DISTANCE} so that it never gets below
1268
@value{src::minimum-vectorize-distance} even if it has been given as a
1269
percentage. The user will be warned in such cases.
1271
Default: @value{src::coarse-mask-vectorize-distance}@dmn{pixels} for
1272
coarse masks and @value{src::fine-mask-vectorize-distance}@dmn{pixels}
1276
@opindex --no-optimize
1277
@cindex optimize seam
1278
@cindex seam optimization
1279
Turn off seam line optimization. Combined with
1280
option@tie{}@option{--fine-mask} this will produce the same type of
1281
mask as Enblend version@tie{}2.5, namely the result of a
1282
@cindex nearest-feature transform (@acronym{NFT})
1283
Nearest-Feature Transform (@acronym{NFT}).@footnote{@sc{Muhammad
1284
H. Alsuwaiyel} and @sc{Marina Gavrilova}, ``On the Distance Transform
1285
of Binary Images'', Proceedings of the International Conference on
1286
Imaging Science, Systems, and Technology, June 2000, @abbr{Vols@.} I
1287
and II, pages 83--86.}
1289
Also see @ref{Table:mask-generation}.
1293
@cindex optimize seam
1294
@cindex seam optimization
1295
Use a two-strategy approach to route the seam line around mismatches
1296
in the overlap region. This is the default.
1297
@ref{Table:optimizer-strategies} explains these strategies; also see
1298
@ref{Table:mask-generation}.
1300
@float Table,Table:optimizer-strategies
1301
@cindex optimize strategy
1304
@item Stragegy 1: Simulated Annealing
1305
Tune with option@tie{}@code{--anneal} = @var{TAU} : @var{DELTA-E-MAX}
1306
: @var{DELTA-E-MIN} : @var{K-MAX}.
1308
@uref{http://@/en.wikipedia.org/@/wiki/@/Simulated_@/annealing,
1309
Simulated-Annealing}
1312
@item Stragegy 2: @sc{Dijkstra} Shortest Path
1313
Tune with option@tie{}@code{--dijkstra} = @var{RADIUS}.
1315
@uref{http://@/en.wikipedia.org/@/wiki/@/Dijkstra_@/algorithm,
1316
@sc{Dijkstra} algorithm}
1319
@caption{Enblend's two strategies to optimize the seam lines between
1322
@shortcaption{Optimizer strategies}
1325
@item --optimizer-weights=@var{DISTANCE-WEIGHT}[:@var{MISMATCH-WEIGHT}]
1326
@opindex --optimizer-weights
1327
@cindex optimizer weights
1328
@cindex weights, optimizer
1329
@cindex seam optimization
1331
Set the weights of the seam-line optimizer. If omitted,
1332
@var{MISMATCH-WEIGHT} defaults to 1.
1334
The seam-line optimizer considers two qualities of the seam line:
1338
The distance of the seam line from its initial position, which has
1339
been determined by @acronym{NFT} (see
1340
option@tie{}@option{--no-optimize}).
1343
The total ``mismatch'' accumulated along it.
1346
The optimizer weights@tie{}@var{DISTANCE-WEIGHT} and
1347
@var{MISMATCH-WEIGHT} define how to weight these two criteria.
1348
Enblend up to version@tie{}3.2 used 1:1. This version of Enblend
1349
(@value{VERSION}) uses
1350
@value{src::default-optimizer-weight-distance}:@value{src::default-optimizer-weight-mismatch}.
1352
A large @var{DISTANCE-WEIGHT} pulls the optimized seam line closer to
1353
the initial postion. A large @var{MISMATCH-WEIGHT} makes the seam
1354
line go on detours to find a path along which the mismatch between the
1355
images is small. If the optimized seam line shows cusps or loops (see
1356
option@tie{}@option{--visualize}), reduce @var{MISMATCH-WEIGHT} or
1357
increase @var{DISTANCE-WEIGHT}.
1359
Both weights must be non-negative. They cannot be both zero at the
1360
same time. Otherwise, their absolute values are not important as
1361
Enblend normalizes their sum.
1363
@item --save-masks[=@var{IMAGE-TEMPLATE}]
1364
@opindex --save-masks
1367
Save the generated masks to @var{IMAGE-TEMPLATE}. The default is
1368
@file{@value{src::default-mask-template}}. Enblend saves masks as
1369
8@dmn{bit} grayscale (single channel) images. For accuracy we
1370
recommend to choose a lossless format.
1372
Use this option if you wish to edit the location of the seam line by
1373
hand. This will give you images of the right sizes that you can edit
1374
to make your changes. Later, use @option{--load-masks} to blend the
1375
project with your custom seam lines.
1377
@var{IMAGE-TEMPLATE} defines a template that is expanded for each
1378
input file. In a template a percent sign (@samp{%}) introduces a
1379
variable part. All other characters are copied literally. Lowercase
1380
letters refer to the name of the respective input file, whereas
1381
uppercase ones refer to the name of the output file (@pxref{Common
1382
Options}). @ref{Table:mask-template-characters} lists all variables.
1384
A fancy mask filename template could look like this:
1390
It puts the mask files into the same directory as the output file
1391
(@samp{%D}), generates a two-digit index (@samp{%02n}) to keep the
1392
mask files nicely sorted, and decorates the mask filename with the
1393
name of the associated input file (@samp{%f}) for easy recognition.
1395
@item --smooth-difference=@var{RADIUS}
1396
@opindex --smooth-difference
1397
@cindex smooth difference image
1398
@cindex blur difference image
1399
Smooth the difference image prior to seam-line optimization to get a
1400
shorter and -- on the length scale of @var{RADIUS} -- also a
1401
straighter seam-line. The default is not to smooth.
1403
If @var{RADIUS} is larger than zero Enblend blurs the difference
1404
images of the overlap regions with a @sc{Gaussian} filter having a
1405
radius of @var{RADIUS}@dmn{pixels}. Values of 0.5 to 1.5@dmn{pixels}
1406
for @var{RADIUS} are good starting points; use
1407
option@tie{}@option{--visualize} to directly judge the effect.
1409
When using this option in conjunction with
1410
@tie{}@option{--coarse-mask}=@var{FACTOR}, keep in mind that the
1411
smoothing occurs @emph{after} the overlap regions have been shrunken.
1412
Thus, blurring affects a @var{FACTOR}@classictimes{}@var{FACTOR} times
1413
larger area in the original images.
1417
@value{src::minimum-smooth-difference} @leq{} @var{RADIUS}.
1420
<math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
1422
<mn>@value{src::minimum-smooth-difference}</mn>
1424
<mi mathvariant="italic">RADIUS</mi>
1430
$@value{src::minimum-smooth-difference} \le \mathit{RADIUS}$.
1433
@item --visualize[=@var{VISUALIZE-TEMPLATE}]
1434
@opindex --visualize
1435
@cindex mask, optimization visualization
1436
@cindex visualization of mask optimization
1437
Create an image according to @var{VISUALIZE-TEMPLATE} that visualizes
1438
the mask optimization process. The default is
1439
@file{@value{src::default-visualize-template}}.
1441
The image shows Enblend's view of the overlap region and how it
1442
decided to route the seam line. If you are experiencing artifacts or
1443
unexpected output, it may be useful to include this visualization
1444
image in your bug report. @xref{Bug Reports}.
1446
@var{VISUALIZE-TEMPLATE} defines a template that is expanded for each
1447
input file. In a template, a percent sign (@samp{%}) introduces a
1448
variable part; all other characters are copied literally. Lowercase
1449
letters refer to the name of the respective input file, whereas
1450
uppercase ones refer to the name of the output file (@pxref{Common
1451
Options}). @ref{Table:mask-template-characters} lists all variables.
1454
@strong{Visualization Image}
1455
@cindex visualization image
1456
@cindex image, visualization
1458
The visualization image shows the symmetric difference of the pixels
1459
in the rectangular region where two images overlap. The larger the
1460
difference the lighter shade of gray it appears in the visualization
1461
image. Enblend paints the non-overlapping parts of the image pair --
1462
these are the regions where @emph{no} blending occurs -- in
1463
@value{src::visualize-no-overlap-value-color}.
1464
@ref{Table:visualization-colors} shows the meanings of all the colors
1465
that are used in seam-line visualization images.
1467
@float Table,Table:visualization-colors
1469
@item @value{src::visualize-no-overlap-value-color}
1470
Non-overlapping parts of image pair.
1472
@item various shades of gray
1473
Difference of the pixel values in the overlap region.
1475
@item @value{src::visualize-state-space-color}
1476
Location of an optimizer sample.
1478
@item @value{src::visualize-first-vertex-value-color}
1479
First sample of a line segment.
1481
@item @value{src::visualize-next-vertex-value-color}
1482
Any other but first sample of a line segment.
1484
@item @value{src::visualize-state-space-inside-color}
1485
@cindex @sc{Dijkstra} radius
1486
@cindex radius, @sc{Dijkstra}
1487
State space sample inside the @sc{Dijkstra} radius.
1489
@item @value{src::visualize-state-space-unconverged-color}
1490
Non-converged point.
1492
@item @value{src::visualize-initial-path-color}
1493
@cindex nearest-feature transform (@acronym{NFT})
1494
Initial seam line as generated by the @acronym{NFT}.
1496
@cindex frozen seam-line endpoint
1497
@cindex seam-line endpoint, frozen
1498
Enblend marks a non-movable (``frozen'') endpoint of a seam-line
1499
segment with a @value{src::visualize-frozen-point}
1500
@value{src::mark-frozen-point}, whereas it uses a
1501
@value{src::visualize-movable-point} @value{src::mark-movable-point}
1502
to denote an endpoint that the optimizer may move around.
1504
@item @value{src::visualize-short-path-value-color}
1508
@shortcaption{Visualization colors}
1509
@caption{Colors used in seam-line visualization images.}
1511
@cindex visualization image colors
1512
@cindex image colors, visualization
1513
@cindex colors, visualization image
1519
@include mask-template-characters.texi
1522
@node Understanding Masks
1523
@chapter Understanding Masks
1524
@cindex understanding masks
1525
@cindex masks, understanding
1527
@include understanding-masks.texi
1530
@node Tuning Memory Usage
1531
@chapter Tuning Memory Usage
1532
@cindex memory, tuning usage of
1536
@include tuning-memory-usage.texi
1539
@node Helpful Programs
1540
@chapter Helpful Additional Programs
1541
@cindex helpful programs
1542
@cindex programs, helpful additional
1544
@include helpful-programs.texi
1548
@appendix Bug Reports
1551
@include bug-reports.texi
1556
@cindex authors, list of
1558
@include authors.texi
1562
@appendix @acronym{GNU} Free Documentation License
1563
@cindex free documentation license (@acronym{FDL})
1564
@cindex @acronym{GNU} free documentation license
1574
@unnumbered Program Index
1575
@cindex program index
1576
@cindex index, program
1581
@node Syntactic-Comment Index
1582
@unnumbered Syntactic-Comment Index
1583
@cindex syntactic-comment index
1584
@cindex index, syntactic-comment
1590
@unnumbered Option Index
1591
@cindex option index
1592
@cindex index, option
1598
@unnumbered General Index
1599
@cindex general index
1600
@cindex index, general
added
removed
.pc/15_texi_ids.diff/doc/enblend.texi
