This is the README file for Luminance
-------------------------------------------------------------------
Copyright (C) 2006-2008 Giuseppe Rota, <grota@users.sourceforge.net>
Webpage:       http://luminance.sourceforge.net
Sourceforge:   http://sourceforge.net/projects/luminance


Contents
---------
1. What it is
2. Dependencies
3. Compiling the sources
4. Workflow in the gui
5. Changes
6. Contact and Links



1. What it is
---------------------------------------------------------------------
This is a graphical user interface (based on the Qt4 toolkit) that
provides a workflow for HDR imaging.

Supported HDR formats:
* OpenEXR (extension: exr, linux and Mac OS X only)
* Radiance RGBE (extension: hdr)
* Tiff formats: 16bit, 32bit (float) and LogLuv (extension: tiff)
* Raw image formats (extension: various)
* PFS native format (extension: pfs)

Supported LDR formats:
* JPEG, PNG, PPM, PBM, TIFF

Supported features:
* Create an HDR file from a set of images (JPEG, TIFF 8bit and 16bit, RAW)
of the same scene taken at different exposure setting.
* Save and load HDR files.
* Rotate and resize HDR files.
* Tonemap HDR images.
* Projective Transformations.
* Copy exif data between sets of images.
* Supports internationalization.

Raw image formats are supported -and treated as HDRs- thanks to dcraw's.

MAKE SURE YOU READ THE "Dependencies" CHAPTER IN THIS FILE.
Read section 5 (Changes) to read the changes for this version.
Read section 3 (Compiling the sources) if you intend to package Luminance for a GNU/Linux distribution.

The code is in part based on the existing opensource packages:
"pfstools", "pfstmo" and "pfscalibration" by Grzegorz Krawczyk and Rafal Mantiuk
"qpfstmo", by Nicholas Phillips.
Without their contribution all of this would have not been possible.


2. Dependencies
-------------------------------------------------------------------
Luminance has 5 dependencies:
1) Qt4 (www.trolltech.com)
2) exiv2 (www.exiv2.org)
3) fftw3 (www.fftw.org)
4) libtiff (http://www.remotesensing.org/libtiff)
5) OpenEXR (www.openexr.com, *Linux only*)
6) Gnu Gsl (http://www.gnu.org/software/gsl/)


On Windows you can satisfy all the runtime dependencies by downloading the ``Windows DLL Package V4'' available at http://downloads.sourceforge.net/luminance/luminance-windows-DLLs-V4.zip
On GNU/Linux you have to compile the code and you need the aforementioned packages (and the ``devel'' or ``dev'' ones, depending on the distribution's naming convention).

1) Qt4 is required because it's the framework the graphical interface is built on.

2) libexiv2 is a C/C++ library used to extract EXIF tags from LDR and RAW image files, and is required in order to extract the aperture, exposure-time and ISO tags from the input images (and for other exif-related functionalities).

3) fftw is required by the fast implementation of Durand tonemapping algorithm.
Luminance requires the "float" variety of fftw3.

4) libtiff is required because of the tiff load/save feature.

5) OpenEXR (www.openexr.com)
OpenEXR is a high dynamic-range (HDR) image file format developed by Industrial Light & Magic for use in computer imaging applications.
The package is also known as ``ilmbase'' in some GNU/Linux distributions.
As for the other dependencies, OpenEXR is required at runtime as well.

6) Gnu GSL (http://www.gnu.org/software/gsl/)
Gnu GSL is required because Mantiuk08 TMO uses this library.




3. Compiling the sources
-------------------------------------------------------------------
The build system is based on Qt's qmake.
The build description is contained in the project.pro file.

If you want Luminance to use a language different from english you should run:
> lrelease project.pro
as a first step.
This steps creates a "qm" file for each one of the "ts" files in the i18n directory.
If you want to run Luminance without the internationalization feature
you can skip this step and continue with the steps described below.
Running
> qmake
from the directory where there is project.pro creates the Makefile.
Luminance should be able to detect if your system has all the required dependencies at the "qmake" step.
If something goes wrong drop me an email.
Then you can run
> make
to compile.
In Linux you can also run
# make install
as root to install the luminance executable in /usr/local/bin.
This last step also installs the icon, the desktop file, the html documentation and the "qm" translation files.
This last step is usually required in order for Luminance to locate the "qm" files used for internationalization.

WARNING:
In Linux you have to make sure to install qt4 and qt4-devel, since most distributions install only qt3. Once you have qt4 and qt4-devel installed you also have to make sure that you are using the tools from qt4 and not qt3. The tools are ``qmake'', ``uic'' and ``moc''. On Ubuntu and debian you can install the program ``galternatives'' that lets you switch from Qt3's to Qt4's executables (or you can use qmake-qt4 rather than qmake).

Some people have experienced some problems using gcc 3.X.X. Switching to gcc 4.X.X has solved the issue.
Some people have experienced some problems using shells different than bash/sh.

NOTE FOR PACKAGERS:
Luminance's default PREFIX is "/usr/local". You can execute:
qmake PREFIX=/usr
before running make in order to modify the default PREFIX.
Also, the icon luminance.png will be installed in $${PREFIX}/share/icons/hicolor/48x48/apps. This has been chosen in order to make the icon show up in the KDE/GNOME menu in both cases of PREFIX=/usr/local and PREFIX=/usr.
You may need to run update-desktop-database in case Luminance's entry doesn't show up in the graphical menus.
In case you need it you can also specify a path where the "translation messages" (qm files) will be installed to. You can do that specifying the I18NDIR variable like this:
qmake I18NDIR=/choose/your/path
The default is I18NDIR=$${PREFIX}/share/luminance/i18n
Running:
> qmake ENABLE_DEBUG="yes"
creates a Makefile that builds Luminance with debug statements enabled.
By default the debug statements are disabled.

The Windows EXE was obtained on Windows XP using MinGW and MSYS.
In GNU/Linux you have to compile the code and you need the packages mentioned in Chapter 2 (and the ``devel'' or ``dev'' ones, depending on the distribution's naming convention).
If you want to compile the sources in windows you need to have a compiled
version of libexiv2 and fftw3. You also need Qt4 Opensource Edition by Trolltech.
Also check the variables in the win32{} section in project.pro: they need
to be changed according to your setup.
Building Luminance from sources on Mac OS X can be performed by either issuing "qmake -spec macx-g++" or "qmake -spec macx-xcode", read the Qt Documentation (http://doc.trolltech.com/4.3/qmake-platform-notes.html) for more detail.

Optimization note: the default compiler flags include SSE2 and OpenMP. SSE2 is only available on recent CPUs (Pentium 4, Pentium-M or newer). OpenMP is only available if compiling with gcc 4.2 or newer. If your CPU is a Pentium III or older, or your compiler is gcc 4.1.x or older, you may need to customize the CXXFLAGS and LFLAGS before compiling.


4. Workflow in the gui
-------------------------------------------------------------------
See also the online help:
Help->Documentation...

Here I'll only describe the basic workflow in Luminance.

From the main window you can see the buttons that enable the user
to work on HDR images:

"New Hdr..." launches a wizard that asks you to select the set of images
(of the same scene, but taken at different exposures) that are going
to contribute to the final hdr (supported input: jpeg and raw).
The wizard will also ask you which kind of configuration you want to use
to create the hdr from the source images: usually the first choice leads
to good results, so feel free to accept the default "Config 1" option
by pressing next.
Only if you feel that the results can be improved you can try one of
the other predefined configurations.
If you want to fiddle with settings you can check the "custom" option and
another page of the wizard will show up with a complete set of configurations.
It is worth mentioning that you should use the custom option as a
last resort because the predefined configurations (which are a sub-set of the
all possible configurations you can have in the custom configuration panel)
are known to yield good results.
The anti-ghosting feature is still beta (even buggy), and very cpu demanding.

"Save Hdr as...", "Open Hdr..." and "Tonemap the Hdr...":
Once the hdr is loaded into the main workspace you can choose to rotate it,
resize it, save it (in one of the HDR supported formats) or to tonemap it.

Through "Open Hdr..." you can also choose to open an existing HDR image 
format and load it into the workspace. The user can now load also a raw image file.

Clicking on the tonemap button will pop up a dialog that will enable you
to tonemap your HDR image and save to one of the plain LDR formats,
like PNG or JPEG.

The tonemapping dialog consists in a series of tabs (and related settings).
Each tab pertains to a different tonemapping operator (TMO).
You can also choose a working size different from the original
one (the TMO will be faster: this is useful for getting
a quick peek at the results of the current settings).

After you're satisfied with the results you can press the save
button to save the results to one of the plain LDR formats,
like PNG or JPEG.

NOTE:
The tonemapping step works like this (as a pipeline, some people would say):
(pre)gamma -> tonemapping operator
The tonemapping operator transforms an HDR into a LDR.
The pregamma changes the gamma in the HDR before the tonemapping:
depending on the chosen tonemapping operator it can yield
unexpected effects like changing color saturation.



5. Changes
-------------------------------------------------------------------
v1.9.2
* Integrated pfstmo 1.2 changes (Ed Brambley's optimization to Mantiuk)
* Fixed other bugs with non-ascii characters in paths/filenames.
* Added support for align_image_stack commandline parameters and user language selection.
* Global: added 2 new fields in the singleton luminance class: QStringList for align_image_stack options and a 2-chars ISO 639 language code for Luminance's user interface.
* Improved comments with references for the algorithm that reads exif data to obtain average global luminance (and EV).
* Cleaned up the code a little bit.

***WARNING***
Starting Luminance 1.8.10, Windows users have to download the new
``Windows DLL Package V4'', make sure to get it at:
http://downloads.sourceforge.net/luminance/luminance-windows-DLLs-V4.zip
If you already have "V4" you don't need to download it again.

Read the Changelog file for previous versions' details.



6. Contact and Links
-------------------------------------------------------------------
All comments and suggestions concerning this package or implementation
of particular algorithm are welcome. Please report bugs and
comments to Giuseppe Rota <grota@users.sourceforge.net>.

See also:
PFStools:
http://www.mpii.mpg.de/resources/pfstools/

PFStmo (a tone mapping library):
http://www.mpii.mpg.de/resources/tmo/

PFScalibration:
http://www.mpii.mpg.de/resources/hdr/calibration/pfs.html

Dcraw: used for raw images support.
http://cybercom.net/~dcoffin/dcraw/
