Menu
▾
▴
Tree [80b879] default tip / History
tmodes
Lukas Wirz
Read Me
Copyright (C) 2004-2009 Andrew Mihal.
Copyright (C) 2009-2019 Christoph Spiel.
This file is part of Enblend.
* Programs
This packages contains the programs Enblend and Enfuse. The source
code and further information about Enblend are available at:
http://enblend.sf.net
** Enblend
Enblend is a tool for compositing images using a Burt&Adelson
multiresolution spline. This technique tries to make the seams
between the input images invisible. The basic idea is that image
features should be blended across a transition zone proportional in
size to the spatial frequency of the features. For example, objects
like trees and windowpanes have rapid changes in color. By blending
these features in a narrow zone, you will not be able to see the seam
because the eye already expects to see color changes at the edge of
these features. Clouds and sky are the opposite. These features have
to be blended across a wide transition zone because any sudden change
in color will be immediately noticeable.
Enblend expects each input file to have an alpha channel. The alpha
channel should indicate the region of the file that has valid image
data. Enblend compares the alpha regions in the input files to find
the areas where images overlap. Alpha channels can be used to
indicate to Enblend that certain portions of an input image should not
contribute to the final image.
Enblend does not align images for you. Use a tool like Hugin or
PanoTools to do this. The files produced by these programs are
exactly what Enblend is designed to work with.
** Enfuse
Enfuse is a tool for automatic exposure blending, contrast blending
and much more. It can be used to fuse an exposure bracketed step
automatically into a nicely looking image.
* Installation
GNU Make is required to build the project, because some of the
Makefiles contain pattern rules.
** Hints for the migration to C++17
*** Compiler
Some C++ compilers already default to the C++17 Standard, others may
have to be put into a conforming mode of operation with, for example,
-std=gnu++17
or
-std=c++17
in CXXFLAGS.
*** Little CMS2
Depending on the specific C++ compiler and the particular version of
the lcms2 library it may or may not be necessary to add
-DCMS_NO_REGISTER_KEYWORD
to CPPFLAGS because in C++17 `register' is a deprecated and reserved
keyword.
Library lcms2 is a mandatory prerequisite for both Enblend and Enfuse.
*** Exiv2
A sufficiently recent Exiv2 library is required because C++17 has
abandoned std::auto_ptr<>, which older versions of the library heavily
rely on; newer versions use std::unique_ptr<>.
Library exiv2 is optional (see `--with-exiv2').
** Tarball
./configure YOUR-OPTIONS-IF-ANY-GO-HERE
make
make install
** Mercurial Repository
*** AutoConf/AutoMake
In the root directory of the project issue:
make --makefile=Makefile.scm
./configure YOUR-OPTIONS-IF-ANY-GO-HERE
make
make install
The package fully supports VPATH builds. Thus the following command
sequence builds in a separate directory.
cd ROOT-DIRECTORY
make --makefile=Makefile.scm
mkdir BUILD-DIR
cd BUILD-DIR
ROOT-DIRECTORY/configure YOUR-OPTIONS-IF-ANY-GO-HERE
make
make install
If a less verbose output of the Make-process is desired, pass
`--enable-silent-rules' to configure(1), or `V=0' to make(1). As out
build uses recursion make(1) reports "Entering directory" and "Leaving
directory" which can only be suppressed with passing option
`--no-print-directory' to make(1).
*** CMake
The canonical way to build Enblend and Enfuse is with Autotools, this
is, autoconf(1) and automake(1). An alternative CMake build has been
added since version 4.0.
The CMake build strives to replicate the Autotools build. It may or
may not work for you. It is currently maintained but not supported,
meaning that it could break anywhere anytime in the future.
cmake .
make
make install
Analogously to Autotools, CMake allows for VPATH builds:
mkdir BUILD-DIR
cd BUILD-DIR
cmake ROOT-DIRECTORY
make
make install
* Specific Configuration Options
Among the usual configuration options of the GNU autoconf system, the
configure(1) script offers the following options to tailor Enblend and
Enfuse. Remember that configure(1) creates a file called "config.h"
that can serve for fine-tuning the configuration.
We write the default values of all configuration options in capital
letters.
** --enable-on-demand-dynlink=CHECK/yes/no
Link Enblend and Enfuse binaries with flags that instruct the dynamic
linker to delay loading dynamic libraries until they are actually
needed. This feature slightly decreases the load-time of the
binaries.
** --enable-partially-static-linking=NO/yes
Link against static libraries if they are performance critical for
Enblend or Enfuse. Currently, these are the GSL libraries and
LittleCMS2. The performance gain is some five percent at the cost of
only slightly larger binaries. The configuration option may also be
interesting if the target system should not require GSL libraries.
If partial static linking is on, configure(1) looks for "libatlas.a"
and "libcblas.a" to replace "libgslcblas.a" and use an optimized BLAS.
** --enable-openmp=yes/NO
-DENABLE_OPENMP=ON/off (CMake)
Parallelize parts of Enblend and Enfuse with OpenMP. See
http://www.openmp.org/
If auto-detection of OpenMP misfires, set appropriate OPENMP_CXXFLAGS
during configuration. For example, CLang++ may need the argument-form
of option `-fopenmp':
-fopenmp=libiomp5
In addition OpenMP support libraries may live in non-standard places.
These too can be specified in OPENMP_CXXFLAGS, because the flags will
be used for compilation and linking.
When OpenMP support has been enabled, the utilization of special
features of the actual, underlying OpenMP implementation can be
controlled as usual with the environment variables OMP_NUM_THREADS,
OMP_NESTED and OMP_DYNAMIC. See the OpenMP specification for details
on the usage of these variables.
** --enable-opencl=YES/no
Enable parallel execution of parts of Enblend and Enfuse with OpenCL
on machines providing the proper hardware. See
http://www.khronos.org/opencl/
As Enblend and Enfuse are written in C++ we prefer the C++-header of
OpenCL, namely "cl.hpp". This file does not always come
(pre-)installed, but can be downloaded from the canonical site,
Khronos OpenCL API Registry
http://www.khronos.org/registry/cl/
Currently, we compile and test against OpenCL API version 1.2. The
header files associated with the older versions 1.0 and 1.1 are
flawed; They do not compile with some compilers (e.g. CLang++).
It is advisable to match the API versions of C-headers and the
C++-header file. On systems with multiple header hierarchies
(e.g. /usr/include and /usr/local/include) particular care must be
taken that the correct headers are used at configuration time and at
compile time.
** --enable-debug=yes/NO
Compile without optimizations and enable all debug-checking code. The
default is "no", build an optimized version without debugging symbols.
** --with-dl=CHECK/yes/no/dl/gmodule
Enable user-defined exposure weight functions in Enblend. With
argument "check", test for POSIX-compatible dynamic-loader (dl) and if
unsuccessful for GLib implementation (gmodule).
** --with-exiv2=CHECK/yes/no
Use Exiv2 library for meta-data transfer of the input images to the
result. Without this library Enblend or Enfuse will not copy any EXIF
meta data.
** --with-tcmalloc=CHECK/yes/no
-DENABLE_TCMALLOC=OFF/on (CMake)
Compile with Google's TCMalloc. This library generally improves
memory allocation performance. Enblend and Enfuse prefer TCMalloc's
functions inside OpenMP parallel regions and thereby reduce the load
of the operating system's memory allocator.
Find more information on TCMalloc at
http://goog-perftools.sourceforge.net/doc/tcmalloc.html
** --with-dmalloc=yes/NO
Compile with the debug-malloc library. The library is available at
http://www.dmalloc.com/.
** --with-openexr=CHECK/yes/no
Build with support for reading and writing OpenEXR images. See
http://www.openexr.com/ for the required libraries.
* CMake Specifics
** Configuration Options
These options only apply to CMake.
*** -DCPACK_BINARY_<SYSTEM>:BOOL=OFF/on
Create a package for the specified <SYSTEM>, where <SYSTEM> is "DEB",
"RPM", or "NSIS".
*** -DCPACK_BINARY_<SYSTEM>:BOOL=ON/off
Create other packages for the specified <SYSTEM>, where <SYSTEM> is
"TBZ2", "TGZ", "STGZ", or "TZ".
*** -DPACK_SOURCE_<SYSTEM>:BOOL=OFF/on
Create a source package for the specified <SYSTEM>, where <SYSTEM> is
"TBZ2", "TGZ", "TZ", or "ZIP".
** Configuration Example
Creating a RedHat package on OpenSuSE
cmake . \
-DDOC=ON \
-DENABLE_OPENMP=ON \
-DCPACK_BINARY_RPM:BOOL=ON
make package
This will create a package enblend-4.0.595-Linux.rpm, which you may
install with
sudo rpm -U enblend-4.0.595-Linux.rpm
** Important Configured Make(1) Targets
help List all available targets.
edit_cache If cmake-gui(1) is installed, start the GUI
to edit the "CMakeCache.txt" file.
enblend Create an Enblend executable.
enfuse Create an Enfuse executable.
man Create the manual pages for Enblend and
Enfuse.
install Install everything in the proper places.
package Create package(s) specified with the
CPACK_BINARY_<SYSTEM>:BOOL parameter of
CMake. It is preferred to create a package
and use the package manager to install it
rather than using the "install" target.
rebuild_cache In a changed environment (e.g. newly
installed packages) this is the way to
discard cached values, so that CMake again
starts searching for everything.
package_source Build a source package like autotools
"make dist".
* Extra Make(1) Variables
** Compilation
You can override Makefile variables the usual way. In addition the
build process supplies several variables, all starting with "EXTRA",
that add their value to the "usual suspects". These are
CPPFLAGS -- EXTRACPPFLAGS
CFLAGS -- EXTRACFLAGS
CXXFLAGS -- EXTRACXXFLAGS
LDFLAGS -- EXTRALDFLAGS
All these "EXTRA" are intentionally unaffected by the
Automake/Autoconf generation of the Makefiles proper. That way
developers can override configured settings in any make(1) run or
quickly build the project with new combinations of flags.
For example, to quickly add an additional define, use
make EXTRACPPFLAGS=-DDEBUG_8BIT_ONLY
To compile for coverage analysis, say
make EXTRACXXFLAGS="-O0 --coverage" EXTRALDFLAGS="--coverage"
analogously for profiling analysis
make EXTRACXXFLAGS=-pg EXTRALDFLAGS=-pg
** Documentation Generation
We have introduced the variable
DYNAMIC_TEX_PREAMBLE
to give the maintainers and packagers better control over the
generation of the documentation. The contents of the variable goes
_before_ `\documentclass' so that even the document class can be
selected dynamically.
DYNAMIC_TEX_PREAMBLE can define the argument-less macros
`\documentclassoptions' which defines LaTeX \documentclass options
(thingies within square brackets) and `\finishdynamicpreamble' which
is expanded right before `\begin{document}' and thus _after_ all
packages have been loaded.
Some possibilities for `DYNAMIC_TEX_PREAMBLE' are
\hyperreftrue
\referencemanualtrue
\usepackage[showframe]{geometry}
\def\documentclassoptions{11pt,twoside}
\def\finishdynamicpreamble{\overfullrule=2pt\relax}
* Documentation
The distribution includes the manual pages in
src/enblend.1
src/enfuse.1
After the configuration you can build documentation in PostScript,
HTML, and possibly PDF formats.
make ps
make pdf
make html
The default paper size for all non-HTML formats is DIN A4. Override
make(1) variable `PAPERSIZE' to get e.g. Letter format. The default
resolution is 600 dpi; override it with `PRINT_RESOLUTION'. The
_printed_ versions can be formatted in two different styles: the usual
LaTeX `report' and `refman' style that borrows from old reference
manuals. Pass
DYNAMIC_TEX_PREAMBLE=\referencemanualtrue
to make(1) when generating a non-HTML format to get the `refman'
style. The reference manual style does _not_ work with HTML, in other
words, hevea(1) will barf. By default only PDFLaTeX turns on
HyperRef, for all other translators (in particular if PDF is
indirectly generated) it must be enabled with
DYNAMIC_TEX_PREAMBLE=\hyperreftrue
** HTML Generation
The default target `html' builds the HTML documentation as monolithic
files, which means the single HTML file "enblend.html" for Enblend and
"enfuse.html" for Enfuse. To build split versions with one chapter
per file of each of them use the target `split-html', where the root
files will be `enblend-index.html' and `enfuse-index.html' . Install
the broken-down version with `install-split-html'.
** PDF Generation
The canonical way to reach at PDF files i.e.
make pdf
is directly, via PDFLaTeX: LaTeX -> PDF. If for some reason this path
does not work, we provide two alternatives.
*** Alternative 1: LaTeX -> DVI -> PDF
Use dvipdfmx(1) to convert the final DVI files to PDF. It is
recommended to issue a
make clean
before starting to construct the PDF files this way! Add the
following commands to DYNAMIC_TEX_PREAMBLE:
- To get correctly positioned graphics
\PassOptionsToPackage{dvipdfmx}{graphicx}
- For all the hyperref goodies (e.g. clickable cross refferences)
\PassOptionsToPackage{dvipdfmx}{hyperref}\hyperreftrue
- To get the right color associations
\PassOptionsToPackage{dvipdfmx}{color}
Sometimes
EXTRA_LATEX_FLAGS='-shell-escape'
may be required. The targets are called "enblend.dvi.pdf" and
"enfuse.dvi.pdf", rename the products if necessary. See
doc/Makefile.am for details.
*** Alternative 2: LaTeX -> DVI -> PostScript -> PDF
Use GhostScript (gs(1)) in the incarnation of ps2pdf(1) to convert the
final PostScript files to PDF. None of the hyperref goodies makes it
through dvips(1). The targets are called "enblend.ps.pdf" and
"enfuse.ps.pdf"; rename if necessary; see doc/Makefile.am for details.
** Required Tools For Building the Documentation
Note that some additional packages are required to build these
formats:
convert - ImageMagick's swiss army knife of graphics
format conversion found at
http://www.imagemagick.org/.
dvips - Convert TeX's DVI format to PostScript.
gnuplot - Render plots (.gp) in text, PNG, EPS, and PDF
formats. Check out http://www.gnuplot.info/.
hevea - Convert LaTeX to HTML. Find more information
at http://hevea.inria.fr/.
latex, pdflatex - Typeset the LaTeX documents in DVI or PDF.
makeindex - Index generation for several typesetters.
dot - Graph generation. Part of the `GraphViz' suite.
See http://www.graphviz.org/.
rsvg-convert - Convert SVG to a variety of other formats, not
only raster images, but also EPS.
Check out http://librsvg.sourceforge.net/.
The tool texloganalyser(1) is optional. Its sole use is to beautify
LaTeX output in non-verbose (V=0) mode.
* Operating System Specific Instructions and Hints
** GNU/Linux
*** High-Performance Binaries
To configure and compile high-performance versions of Enblend and
Enfuse configure SMP boxes with
--enable-openmp
and pass
EXTRACXXFLAGS="-march=native -O2"
to make(1). The resulting binaries are pretty fast, although other
configuration options or compiler flags might improve their
performance even more.
*** Xmi and Xi
To avoid direct linkage to the two X11 libraries Xmi and Xi add
"--without-x" to the parameters of configure(1).
** MacOSX
*** Compiling on MacOSX
On MacOSX you can build Enblend/Enfuse with Fink and with MacPorts.
This README only describes the MacPorts way.
**** Prerequisites
- XCode: Install the XCode version for your MacOSX version. Download it
from
http://developer.apple.com/tools/download/
- MacPorts: Install MacPorts for your MacOSX version. Download it
from
http://www.macports.org/
**** Provide necessary dependencies
From the command line:
$ sudo port install make lcms jpeg tiff libpng OpenEXR mercurial
Note that Enblend/Enfuse can be build via AutoConf/AutoMake and via
CMake. The latter is experimental. If you want to build via CMake,
add "cmake" to the previous command line after "mercurial" like this:
$ sudo port install make lcms jpeg tiff libpng OpenEXR mercurial cmake
**** Compile
As MacPorts resides in /opt/local, which is not a standard
library/binary/include path for most source packages, you need to
specify that during the configure step.
Via AutoConf/AutoMake:
cd enblend
make --makefile=Makefile.scm
mkdir build
cd build
CPPFLAGS=-I/opt/local/include LDFLAGS=-L/opt/local/lib ../configure
make
sudo make install
Via CMake:
cd enblend
make --makefile=Makefile.scm
mkdir build
cd build
CPPFLAGS=-I/opt/local/include LDFLAGS=-L/opt/local/lib cmake ..
make
sudo make install
This will install Enblend/Enfuse in /usr/local.
**** Other compilation options
Please also check the AutoConf/AutoMake and CMake variables for more
build options.
** Win
*** General
There are two different archives: one with 32-bit executables, the
other one with 64-bit executables. Both variants are compiled with
multi-threaded support (via OpenMP).
*** Compiling on Windows
**** Prerequisites
You will need to following tools for compiling:
- MS Visual C++ 2015, works also with Community Edition
(older compiler may work, but have not been tested)
- CMake, at least version 2.8
- Perl, e.g. ActiveState Perl
CMake expects all sources and libraries in one folder. So, create a
folder, e.g., "d:\src", extract Enblend/Enfuse into this folder, and
also put all libraries into this folder.
You need the following libraries for reading and writing different
image formats. We state the version and the folder name of the
libraries used as of March 2016 in square brackets.
- libtiff [libtiff-4.0.6 in tiff]
- zlib, required by libtiff [1.2.8 in zlib]
- libjpeg (optional) [jpeg-9b]
- libpng (optional) [libpng-1.6.21 in libpng]
- OpenEXR and IlmBase (optional), compiled libraries are
expected in folder "Deploy" [OpenEXR-2.2.0 and IlmBase-2.2.0]
- vigra, required, should be compiled against same
libtifff, libjpeg, libpng and OpenEXR as used for Enblend/Enfuse
[1.10.0 in vigra]
Enblend/Enfuse also depend on the following libraries:
- Little-CMS2 [2.4 in lcm2-2.4]
**** Compile
1. Start cmake-gui or cmake-setup.
2. Enter path to Enblend/Enfuse source in "Where is the source code".
3. Enter path where to build the executable,
e.g. "d:\src\build-enblend". In following, it will be denoted as
<BUILDDIR>.
4. Select "Configure" when asked for a generator select the
appropriate generator.
5. Activate the appropriate options.
***** ENABLE_OPENMP=on/OFF
Parallelize parts of Enblend and Enfuse with OpenMP. See
http://www.openmp.org/
If OpenMP support has been enabled, the utilization of special
features of the actual, underlying OpenMP implementation can be
controlled as usual with the environment variables OMP_NUM_THREADS,
OMP_NESTED and OMP_DYNAMIC. See the OpenMP specification for details
on the usage of these variables.
***** ENABLE_SSE2=on/OFF
Creates executable which make use of the advanced features (SSE2) of
modern processors.
***** DOC=on/OFF
Building the documentation works also on Windows. It requires more
tools (see above). Some tools have several different variants for
Windows available, but not all work with Enblend/Enfuse documentation.
If you experience errors try another variant or version.
**** Compile (cont.)
6. Select "Configure". Maybe you need start the configuration step
several times until all dependencies are resolved.
7. Select "Generate".
8. Close CMake.
9. Open solution file <BUILDDIR>\enblend.sln.
10. Select "Release" in Solution Configuration pull-down menu, and
then choose Build > Build Solution. This step takes some time.
11. Select project "INSTALL" in Solution Explorer, and then choose
Build > Project Only > Build Only INSTALL.
12. Close Visual C++ 2008 Express Edition
13. Find the generated executables in <BUILDDIR>\INSTALLDIR\FILES.
* License
Enblend is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
Enblend is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with Enblend; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Local Variables:
mode: outline
End:
