1Copyright (C) 2004-2009 Andrew Mihal.
2Copyright (C) 2009-2016 Christoph Spiel.
3
4This file is part of Enblend.
5
6
7* Programs
8
9This packages contains the programs Enblend and Enfuse. The source
10code and further information about Enblend are available at:
11 http://enblend.sf.net
12
13
14** Enblend
15
16Enblend is a tool for compositing images using a Burt&Adelson
17multiresolution spline. This technique tries to make the seams
18between the input images invisible. The basic idea is that image
19features should be blended across a transition zone proportional in
20size to the spatial frequency of the features. For example, objects
21like trees and windowpanes have rapid changes in color. By blending
22these features in a narrow zone, you will not be able to see the seam
23because the eye already expects to see color changes at the edge of
24these features. Clouds and sky are the opposite. These features have
25to be blended across a wide transition zone because any sudden change
26in color will be immediately noticeable.
27
28Enblend expects each input file to have an alpha channel. The alpha
29channel should indicate the region of the file that has valid image
30data. Enblend compares the alpha regions in the input files to find
31the areas where images overlap. Alpha channels can be used to
32indicate to Enblend that certain portions of an input image should not
33contribute to the final image.
34
35Enblend does not align images for you. Use a tool like Hugin or
36PanoTools to do this. The files produced by these programs are
37exactly what Enblend is designed to work with.
38
39
40** Enfuse
41
42Enfuse is a tool for automatic exposure blending, contrast blending
43and much more. It can be used to fuse an exposure bracketed step
44automatically into a nicely looking image.
45
46
47* Installation
48
49GNU Make is required to build the project, because some of the
50Makefiles contain pattern rules.
51
52
53** Tarball
54
55 ./configure YOUR-OPTIONS-IF-ANY-GO-HERE
56 make
57 make install
58
59
60** Mercurial Repository
61
62*** AutoConf/AutoMake
63
64In the root directory of the project issue:
65
66 make --makefile=Makefile.scm
67 ./configure YOUR-OPTIONS-IF-ANY-GO-HERE
68 make
69 make install
70
71The package fully supports VPATH builds. Thus the following command
72sequence builds in a separate directory.
73
74 cd ROOT-DIRECTORY
75 make --makefile=Makefile.scm
76 mkdir BUILD-DIR
77 cd BUILD-DIR
78 ROOT-DIRECTORY/configure YOUR-OPTIONS-IF-ANY-GO-HERE
79 make
80 make install
81
82If a less verbose output of the Make-process is desired, pass
83`--enable-silent-rules' to configure(1), or `V=0' to make(1). As out
84build uses recursion make(1) reports "Entering directory" and "Leaving
85directory" which can only be suppressed with passing option
86`--no-print-directory' to make(1).
87
88
89*** CMake
90
91The canonical way to build Enblend and Enfuse is with Autotools, this
92is, autoconf(1) and automake(1). An alternative CMake build has been
93added since version 4.0.
94
95The CMake build strives to replicate the Autotools build. It may or
96may not work for you. It is currently maintained but not supported,
97meaning that it could break anywhere anytime in the future.
98
99 cmake .
100 make
101 make install
102
103Analogously to Autotools, CMake allows for VPATH builds:
104
105 mkdir BUILD-DIR
106 cd BUILD-DIR
107 cmake ROOT-DIRECTORY
108 make
109 make install
110
111
112* Specific Configuration Options
113
114Among the usual configuration options of the GNU autoconf system, the
115configure(1) script offers the following options to tailor Enblend and
116Enfuse. Remember that configure(1) creates a file called "config.h"
117that can serve for fine-tuning the configuration.
118
119We write the default values of all configuration options in capital
120letters.
121
122
123** --enable-on-demand-dynlink=CHECK/yes/no
124
125Link Enblend and Enfuse binaries with flags that instruct the dynamic
126linker to delay loading dynamic libraries until they are actually
127needed. This feature slightly decreases the load-time of the
128binaries.
129
130
131** --enable-openmp=yes/NO
132 -DENABLE_OPENMP=ON/off (CMake)
133
134Parallelize parts of Enblend and Enfuse with OpenMP. See
135 http://www.openmp.org/
136
137If auto-detection of OpenMP misfires, set appropriate OPENMP_CXXFLAGS
138during configuration. For example, CLang++ may need the argument-form
139of option `-fopenmp':
140 -fopenmp=libiomp5
141In addition OpenMP support libraries may live in non-standard places.
142These too can be specified in OPENMP_CXXFLAGS, because the flags will
143be used for compilation and linking.
144
145When OpenMP support has been enabled, the utilization of special
146features of the actual, underlying OpenMP implementation can be
147controlled as usual with the environment variables OMP_NUM_THREADS,
148OMP_NESTED and OMP_DYNAMIC. See the OpenMP specification for details
149on the usage of these variables.
150
151
152** --enable-debug=yes/NO
153
154Compile without optimizations and enable all debug-checking code. The
155default is "no", build an optimized version without debugging symbols.
156
157
158** --with-dl=CHECK/yes/no/dl/gmodule
159
160Enable user-defined exposure weight functions in Enblend. With
161argument "check", test for POSIX-compatible dynamic-loader (dl) and if
162unsuccessful for GLib implementation (gmodule).
163
164
165** --with-tcmalloc=CHECK/yes/no
166 -DENABLE_TCMALLOC=OFF/on (CMake)
167
168Compile with Google's TCMalloc. This library generally improves
169memory allocation performance. Enblend and Enfuse prefer TCMalloc's
170functions inside OpenMP parallel regions and thereby reduce the load
171of the operating system's memory allocator.
172
173Find more information on TCMalloc at
174 http://goog-perftools.sourceforge.net/doc/tcmalloc.html
175
176
177** --with-dmalloc=yes/NO
178
179Compile with the debug-malloc library. The library is available at
180http://www.dmalloc.com/.
181
182
183** --with-openexr=CHECK/yes/no
184
185Build with support for reading and writing OpenEXR images. See
186http://www.openexr.com/ for the required libraries.
187
188
189* CMake Specifics
190
191** Configuration Options
192
193These options only apply to CMake.
194
195
196*** -DCPACK_BINARY_<SYSTEM>:BOOL=OFF/on
197
198Create a package for the specified <SYSTEM>, where <SYSTEM> is "DEB",
199"RPM", or "NSIS".
200
201
202*** -DCPACK_BINARY_<SYSTEM>:BOOL=ON/off
203
204Create other packages for the specified <SYSTEM>, where <SYSTEM> is
205"TBZ2", "TGZ", "STGZ", or "TZ".
206
207
208*** -DPACK_SOURCE_<SYSTEM>:BOOL=OFF/on
209
210Create a source package for the specified <SYSTEM>, where <SYSTEM> is
211"TBZ2", "TGZ", "TZ", or "ZIP".
212
213
214** Configuration Example
215
216Creating a RedHat package on OpenSuSE
217
218 cmake . \
219 -DDOC=ON \
220 -DENABLE_OPENMP=ON \
221 -DCPACK_BINARY_RPM:BOOL=ON
222 make package
223
224This will create a package enblend-4.0.595-Linux.rpm, which you may
225install with
226
227 sudo rpm -U enblend-4.0.595-Linux.rpm
228
229
230** Important Configured Make(1) Targets
231
232help List all available targets.
233
234edit_cache If cmake-gui(1) is installed, start the GUI
235 to edit the "CMakeCache.txt" file.
236
237enblend Create an Enblend executable.
238
239enfuse Create an Enfuse executable.
240
241man Create the manual pages for Enblend and
242 Enfuse.
243
244install Install everything in the proper places.
245
246package Create package(s) specified with the
247 CPACK_BINARY_<SYSTEM>:BOOL parameter of
248 CMake. It is preferred to create a package
249 and use the package manager to install it
250 rather than using the "install" target.
251
252rebuild_cache In a changed environment (e.g. newly
253 installed packages) this is the way to
254 discard cached values, so that CMake again
255 starts searching for everything.
256
257package_source Build a source package like autotools
258 "make dist".
259
260
261* Extra Make(1) Variables
262
263** Compilation
264
265You can override Makefile variables the usual way. In addition the
266build process supplies several variables, all starting with "EXTRA",
267that add their value to the "usual suspects". These are
268
269 CPPFLAGS -- EXTRACPPFLAGS
270 CFLAGS -- EXTRACFLAGS
271 CXXFLAGS -- EXTRACXXFLAGS
272 LDFLAGS -- EXTRALDFLAGS
273
274All these "EXTRA" are intentionally unaffected by the
275Automake/Autoconf generation of the Makefiles proper. That way
276developers can override configured settings in any make(1) run or
277quickly build the project with new combinations of flags.
278
279For example, to quickly add an additional define, use
280 make EXTRACPPFLAGS=-DDEBUG_8BIT_ONLY
281To compile for coverage analysis, say
282 make EXTRACXXFLAGS="-O0 --coverage" EXTRALDFLAGS="--coverage"
283analogously for profiling analysis
284 make EXTRACXXFLAGS=-pg EXTRALDFLAGS=-pg
285
286
287** Documentation Generation
288
289We have introduced the variable
290 DYNAMIC_TEX_PREAMBLE
291to give the maintainers and packagers better control over the
292generation of the documentation. The contents of the variable goes
293_before_ `\documentclass' so that even the document class can be
294selected dynamically.
295
296DYNAMIC_TEX_PREAMBLE can define the argument-less macros
297`\documentclassoptions' which defines LaTeX \documentclass options
298(thingies within square brackets) and `\finishdynamicpreamble' which
299is expanded right before `\begin{document}' and thus _after_ all
300packages have been loaded.
301
302Some possibilities for `DYNAMIC_TEX_PREAMBLE' are
303 \hyperreftrue
304 \referencemanualtrue
305 \usepackage[showframe]{geometry}
306 \def\documentclassoptions{11pt,twoside}
307 \def\finishdynamicpreamble{\overfullrule=2pt\relax}
308
309
310* Documentation
311
312The distribution includes the manual pages in
313 src/enblend.1
314 src/enfuse.1
315
316After the configuration you can build documentation in PostScript,
317HTML, and possibly PDF formats.
318 make ps
319 make pdf
320 make html
321
322The default paper size for all non-HTML formats is DIN A4. Override
323make(1) variable `PAPERSIZE' to get e.g. Letter format. The default
324resolution is 600 dpi; override it with `PRINT_RESOLUTION'. The
325_printed_ versions can be formatted in two different styles: the usual
326LaTeX `report' and `refman' style that borrows from old reference
327manuals. Pass
328 DYNAMIC_TEX_PREAMBLE=\referencemanualtrue
329to make(1) when generating a non-HTML format to get the `refman'
330style. The reference manual style does _not_ work with HTML, in other
331words, hevea(1) will barf. By default only PDFLaTeX turns on
332HyperRef, for all other translators (in particular if PDF is
333indirectly generated) it must be enabled with
334 DYNAMIC_TEX_PREAMBLE=\hyperreftrue
335
336
337** HTML Generation
338
339The default target `html' builds the HTML documentation as monolithic
340files, which means the single HTML file "enblend.html" for Enblend and
341"enfuse.html" for Enfuse. To build split versions with one chapter
342per file of each of them use the target `split-html', where the root
343files will be `enblend-index.html' and `enfuse-index.html' . Install
344the broken-down version with `install-split-html'.
345
346
347** PDF Generation
348
349The canonical way to reach at PDF files i.e.
350 make pdf
351is directly, via PDFLaTeX: LaTeX -> PDF. If for some reason this path
352does not work, we provide two alternatives.
353
354
355*** Alternative 1: LaTeX -> DVI -> PDF
356
357Use dvipdfmx(1) to convert the final DVI files to PDF. It is
358recommended to issue a
359 make clean
360before starting to construct the PDF files this way! Add the
361following commands to DYNAMIC_TEX_PREAMBLE:
362 - To get correctly positioned graphics
363 \PassOptionsToPackage{dvipdfmx}{graphicx}
364 - For all the hyperref goodies (e.g. clickable cross refferences)
365 \PassOptionsToPackage{dvipdfmx}{hyperref}\hyperreftrue
366 - To get the right color associations
367 \PassOptionsToPackage{dvipdfmx}{color}
368Sometimes
369 EXTRA_LATEX_FLAGS='-shell-escape'
370may be required. The targets are called "enblend.dvi.pdf" and
371"enfuse.dvi.pdf", rename the products if necessary. See
372doc/Makefile.am for details.
373
374
375*** Alternative 2: LaTeX -> DVI -> PostScript -> PDF
376
377Use GhostScript (gs(1)) in the incarnation of ps2pdf(1) to convert the
378final PostScript files to PDF. None of the hyperref goodies makes it
379through dvips(1). The targets are called "enblend.ps.pdf" and
380"enfuse.ps.pdf"; rename if necessary; see doc/Makefile.am for details.
381
382
383** Required Tools For Building the Documentation
384
385Note that some additional packages are required to build these
386formats:
387 convert - ImageMagick's swiss army knife of graphics
388 format conversion found at
389 http://www.imagemagick.org/.
390 dvips - Convert TeX's DVI format to PostScript.
391 gnuplot - Render plots (.gp) in text, PNG, EPS, and PDF
392 formats. Check out http://www.gnuplot.info/.
393 hevea - Convert LaTeX to HTML. Find more information
394 at http://hevea.inria.fr/.
395 latex, pdflatex - Typeset the LaTeX documents in DVI or PDF.
396 makeindex - Index generation for several typesetters.
397 dot - Graph generation. Part of the `GraphViz' suite.
398 See http://www.graphviz.org/.
399 rsvg-convert - Convert SVG to a variety of other formats, not
400 only raster images, but also EPS.
401 Check out http://librsvg.sourceforge.net/.
402
403The tool texloganalyser(1) is optional. Its sole use is to beautify
404LaTeX output in non-verbose (V=0) mode.
405
406
407* Operating System Specific Instructions and Hints
408
409** GNU/Linux
410
411*** High-Performance Binaries
412
413To configure and compile high-performance versions of Enblend and
414Enfuse configure SMP boxes with
415 --enable-openmp
416and pass
417 EXTRACXXFLAGS="-march=native -O2"
418to make(1). The resulting binaries are pretty fast, although other
419configuration options or compiler flags might improve their
420performance even more.
421
422
423*** Xmi and Xi
424
425To avoid direct linkage to the two X11 libraries Xmi and Xi add
426"--without-x" to the parameters of configure(1).
427
428
429** MacOSX
430
431*** Compiling on MacOSX
432
433On MacOSX you can build Enblend/Enfuse with Fink and with MacPorts.
434This README only describes the MacPorts way.
435
436
437**** Prerequisites
438
439- XCode: Install the XCode version for your MacOSX version. Download it
440 from
441 http://developer.apple.com/tools/download/
442
443- MacPorts: Install MacPorts for your MacOSX version. Download it
444 from
445 http://www.macports.org/
446
447
448**** Provide necessary dependencies
449
450From the command line:
451
452 $ sudo port install make lcms boost jpeg tiff libpng OpenEXR mercurial
453
454Note that Enblend/Enfuse can be build via AutoConf/AutoMake and via
455CMake. The latter is experimental. If you want to build via CMake,
456add "cmake" to the previous command line after "mercurial" like this:
457
458 $ sudo port install make lcms boost jpeg tiff libpng OpenEXR mercurial cmake
459
460
461**** Compile
462
463As MacPorts resides in /opt/local, which is not a standard
464library/binary/include path for most source packages, you need to
465specify that during the configure step.
466
467Via AutoConf/AutoMake:
468
469 cd enblend
470 make --makefile=Makefile.scm
471 mkdir build
472 cd build
473 CPPFLAGS=-I/opt/local/include LDFLAGS=-L/opt/local/lib ../configure
474 make
475 sudo make install
476
477
478Via CMake:
479
480 cd enblend
481 make --makefile=Makefile.scm
482 mkdir build
483 cd build
484 CPPFLAGS=-I/opt/local/include LDFLAGS=-L/opt/local/lib cmake ..
485 make
486 sudo make install
487
488This will install Enblend/Enfuse in /usr/local.
489
490
491**** Other compilation options
492
493Please also check the AutoConf/AutoMake and CMake variables for more
494build options.
495
496
497** Win
498
499*** General
500
501There are two different archives: one with 32-bit executables, the
502other one with 64-bit executables. Both variants are compiled with
503multi-threaded support (via OpenMP).
504
505
506*** Compiling on Windows
507
508**** Prerequisites
509
510You will need to following tools for compiling:
511
512- MS Visual C++ 2015, works also with Community Edition
513 (older compiler may work, but have not been tested)
514- CMake, at least version 2.8
515- Perl, e.g. ActiveState Perl
516
517CMake expects all sources and libraries in one folder. So, create a
518folder, e.g., "d:\src", extract Enblend/Enfuse into this folder, and
519also put all libraries into this folder.
520
521You need the following libraries for reading and writing different
522image formats. We state the version and the folder name of the
523libraries used as of March 2016 in square brackets.
524
525- libtiff [libtiff-4.0.6 in tiff]
526- zlib, required by libtiff [1.2.8 in zlib]
527- libjpeg (optional) [jpeg-9b]
528- libpng (optional) [libpng-1.6.21 in libpng]
529- OpenEXR and IlmBase (optional), compiled libraries are
530 expected in folder "Deploy" [OpenEXR-2.2.0 and IlmBase-2.2.0]
531- vigra, required, should be compiled against same
532 libtifff, libjpeg, libpng and OpenEXR as used for Enblend/Enfuse
533 [1.10.0 in vigra]
534
535Enblend/Enfuse also depend on the following libraries:
536
537- Boost [1.60 in boost_1_60_0]
538 - Only header files are used by default.
539 - Optionally, Enblend/Enfuse can use the Filesystem Library.
540 However, this library needs to compiled against STLport.
541- Little-CMS2 [2.4 in lcm2-2.4]
542
543
544**** Compile
545
5461. Start cmake-gui or cmake-setup.
5472. Enter path to Enblend/Enfuse source in "Where is the source code".
5483. Enter path where to build the executable,
549 e.g. "d:\src\build-enblend". In following, it will be denoted as
550 <BUILDDIR>.
5514. Select "Configure" when asked for a generator select the
552 appropriate generator.
5535. Activate the appropriate options.
554
555
556***** ENABLE_OPENMP=on/OFF
557
558Parallelize parts of Enblend and Enfuse with OpenMP. See
559 http://www.openmp.org/
560
561If OpenMP support has been enabled, the utilization of special
562features of the actual, underlying OpenMP implementation can be
563controlled as usual with the environment variables OMP_NUM_THREADS,
564OMP_NESTED and OMP_DYNAMIC. See the OpenMP specification for details
565on the usage of these variables.
566
567
568***** ENABLE_SSE2=on/OFF
569
570Creates executable which make use of the advanced features (SSE2) of
571modern processors.
572
573
574***** DOC=on/OFF
575
576Building the documentation works also on Windows. It requires more
577tools (see above). Some tools have several different variants for
578Windows available, but not all work with Enblend/Enfuse documentation.
579If you experience errors try another variant or version.
580
581
582**** Compile (cont.)
583
584 6. Select "Configure". Maybe you need start the configuration step
585 several times until all dependencies are resolved.
586 7. Select "Generate".
587 8. Close CMake.
588 9. Open solution file <BUILDDIR>\enblend.sln.
58910. Select "Release" in Solution Configuration pull-down menu, and
590 then choose Build > Build Solution. This step takes some time.
59111. Select project "INSTALL" in Solution Explorer, and then choose
592 Build > Project Only > Build Only INSTALL.
59312. Close Visual C++ 2008 Express Edition
59413. Find the generated executables in <BUILDDIR>\INSTALLDIR\FILES.
595
596
597* License
598
599Enblend is free software; you can redistribute it and/or modify
600it under the terms of the GNU General Public License as published by
601the Free Software Foundation; either version 2 of the License, or
602(at your option) any later version.
603
604Enblend is distributed in the hope that it will be useful,
605but WITHOUT ANY WARRANTY; without even the implied warranty of
606MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
607GNU General Public License for more details.
608
609You should have received a copy of the GNU General Public License
610along with Enblend; if not, write to the Free Software
611Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
612
613
614
615Local Variables:
616mode: outline
617End:
618