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


Contents
---------

0. What it is
1. Dependencies
2. Compilation
3. Workflow in the gui
4. Contact and Links


0. What it is
---------------------------------------------------------------------
This is version 1.0 of qtpfsgui, a qt3 graphical user interface that 
enables users to work on hdr images.
Supported operations include: creations of a HDR file from a set of
images of a scene taken at different exposure setting, loading an
existing HDR image, saving an image in a HDR format, rotating HDRs,
and tonemapping an HDR image into a common LDR image format (e.g jpeg or png).

MAKE SURE YOU READ THE "Dependencies" CHAPTER IN THIS FILE.

The code is in part based on the existing opensource program "pfsview"
(belonging to the pfstools package) by Grzegorz Krawczyk 
and on "qpfstmo", by Nicholas Phillips.
Without their contribution all of this would have not been possible.

Since qtpfsgui relies heavily on the capabilites of pfstools, the
fileformats supported by qtpfsgui are the SAME as the ones supported by
pfstools (a summary of the supported fileformats of pfstools can be seen
after the initial ./configure step for pfstools).

Indeed, in order to accomplish its task, qtpfsgui v1.0 relies on calling 
the same external commandline tools belonging to pfstools/pfstmo, 
see below for more info.


1. Dependencies
-------------------------------------------------------------------
Qtpfsgui has 3 main dependencies:
1) pfstools
2) pfstmo
3) libexiv2

pfstools is an opensource library and a set of commandline tools
and can be obtained from:
http://www.mpi-sb.mpg.de/resources/pfstools/
or from:
http://sourceforge.net/projects/pfstools/

pfstmo is a set of executables implementing several tone mapping operators,
usually used in conjunction with pfstools.
pfstmo can be obtained from:
http://www.mpii.mpg.de/resources/tmo/

NOTE: starting with version 1.0 qtpfsgui does not need to have 
pfshdrcreate as an external executable anymore, since its code
has been integrated in qtpfsgui (see also NEWS and Changelog).

libexiv2 is a C/C++ library used to extract EXIF tags from LDR image files
(usually from JPEG files).
libexiv2 can be obtained from:
http://www.exiv2.org/

WARNING: the naive build system makes the assumption that the exiv2
headers are in /usr/include/exiv2/ and the libraries in /usr/lib.
If that is not true on your system, please change the related 
variables in qtpfsgui.pro before running qmake as explained below.
(On ubuntu run "apt-get install libexiv2-dev")

2. Compilation
---------------------------------------------------------------------
Provided pfstools+pfstmo have been installed, you can
unpack and compile qtpfsgui by doing:

> tar xzf qtpfsgui-X.X.tgz
then cd to the newly created source directory

> cd qtpfsgui-X.X

then create the Makefile by issuing the command:

> qmake

The procedure checks (naively) for the presence of the aforementioned
packages and refuses to create the Makefile in case it thinks the
dependencies are not met.
In case you see
Project MESSAGE: OK... pfstools found!
Project MESSAGE: OK... pfstmo found!
you can then compile:

> make

and install:

> make install



3. Workflow in the gui
-------------------------------------------------------------------

Here I'll describe the workflow in qtpfsgui: pretty much the same
information can be found in the Help->About dialog.

Documentation related to pfstools/pfstmo can be 
found in the respective packages.

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.
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.

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

You can also choose to open an existing HDR image format and load it
into the workspace.

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 big save
button to save the results to one of the plain LDR formats,
like PNG or JPEG.



4. Contact and Links
-------------------------------------------------------------------

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

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

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

pfshdrcreate, a commandline tool used to create an HDR from a set 
of LDR images (branch of pfscalibration), hosted on the same 
sourceforge page as qtpfsgui:
http://sourceforge.net/projects/qtpfsgui/

PFScalibration, the original software from which the backend pfshdrcreate
was obtained (not needed for qtpfsgui):
http://www.mpii.mpg.de/resources/hdr/calibration/pfs.html

