README

Copyright (C) 2004-2009 Andrew Mihal.
Copyright (C) 2009-2017 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.


** 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 boost 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 boost 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:

- Boost  [1.60 in boost_1_60_0]
    - Only header files are used by default.
    - Optionally, Enblend/Enfuse can use the Filesystem Library.
      However, this library needs to compiled against STLport.
- 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: