# Qtpfsgui Manual

1. Introduction

1. Terminology
2. Summary of features

2. Using Qtpfsgui

1. The main Window

1. The menubar
2. The toolbar
3. The workspace
4. Visualization of an HDR
5. Operations on an HDR

2. The Creation of an HDR
3. The Resize dialog
4. The Tone mapping dialog

1. The tone mapping operators and their parameters
2. The tone mapping settings file

5. The Batch Tone Mapping dialog
6. The Options dialog

1. RAW Import
2. HDR Visualization
3. Tone mapping
4. Tiff Options

7. The Copy Exif Data dialog

3. The menu reference

## Introduction

Qtpfsgui is an open source graphical user interface application that provides a workflow for HDR imaging.

### Terminology

HDR
  Stands for "High Dynamic Range". An HDR image is an image which presents more than 8 bit per color channel. Most CRTs, LCDs and printers only have a limited dynamic range, and can display only LDR images (see below). Thus various methods of "converting" HDR images into a viewable format have been developed, generally called "tone mapping".
LDR
  Stands for "Low Dynamic Range". The most common image formats, such as JPEG,PNG,GIF,... have 8 bits per color channel, LDR is just another umbrella definition.
Tone map
  Tone mapping is the method of converting an HDR into a LDR. Various algorithms exist, and in this context they are also known as "tone mapping operators", or (in this manual) simply as "operator". Each operator is represented in the tone mapping dialog as a "tab".
TMO
  Shorthand for "Tone Mapping Operator".
RAW
  Another umbrella definition for several (mininally processed) image formats. Raw files can have 12 or 14 bits per color channel, but noise usually cuts down the available dynamic range to something like 1000:1, roughly 10 bits. For all intents and purposes they are HDR files.

### Summary of features

Current supported features include:

1. Create an HDR from a set of files: either JPEG or RAW or TIFF.
2. Tone map a HDR image to get a LDR image.
3. Save and load HDR images.
4. Rotate and resize HDR images.
5. Copy exif data between sets of images.

The first feature is accessible via the "File -> New Hdr..." wizard: in order to create an HDR the user can load either a set of JPEG files, or a set of RAW files, or a set of TIFF files (8bit or 16bit).
The pictures must have been taken at the same scene, with different exposure settings (change the exposure time and/or aperture, and use a tripod if you have one). The newly created HDR will be available in the workspace as soon as the HDR creation wizard has ended.
To tone map an HDR file to get an LDR image (second feature) you can press the "Tonemap the HDR" button.
Via the "File -> Open Hdr..." dialog you can choose to load in the workspace an HDR image image file, and the "File->Save Hdr as..." item lets you save the currently selected hdr image to a HDR image file format (third feature).
Users can also rotate and resize (fourth feature) the currently selected hdr image via the "Image" menu item, see below. In order to create an HDR image Qtpfsgui requires to have a set of images with exif data in it. Qtpfsgui requires this information to get the exposure settings for an image in the set. When Qtpfsgui doesn't find this information in an image it warns the user and aborts the hdr creation process. To cope with this requirement Qtpfsgui provides a panel that performs a one-to-one copy of the exif data between two sets of files (fifth feature).

## Using Qtpfsgui

This chapter describes the most important elements of Qtpfsgui: the Main window, the Resize dialog, the Tone Mapping dialog, the Copy Exif data dialog and the Options dialog.

### The main Window

Here's the main window that you can see once the program has launched.

#### The menubar

At the very top you can see the menubar which, as its name implies, contains the various menus. When an item in a menu is "grayed out" it means that you cannot use (because it doesn't make sense) that particular function at that time. For example you cannot tone map an HDR unless you have at least one HDR image loaded in the workspace. In case the text describing an item in a menu is not clear enough, below you can find a complete reference of all the items contained in all the menus.

#### The toolbar

Below the menubar you can see the toolbar. It simply contains some of the most frequently used functions listed in the menus: "New HDR...", "Open HDR...", "Save HDR as...", "Tonemap the HDR" and "Exit". Again, if an item is "grayed out" it means that you cannot use (because it doesn't make sense) that particular function at that time.

#### The workspace

The main gray area is the workspace. Here you can see all the HDR images which you can work on. As soon as the program is launched the workspace is empty. To have an HDR in the workspace you can either load an existing one (File->Open Hdr...) or create a new one (File->New Hdr...).

#### Visualization of an HDR

All of the visualization options do not modify the current HDR, they are only a visualization tool.
In the picture above you can see what an HDR image looks like once it is loaded in the workspace. From left to right, in an HDR image titlebar you can see:

1. A gamma combobox, which changes the visualization brightness.
2. The green histogram with its blue "histogram selection" (you can use the mouse to drag it and/or move its boundaries).

In the View menu you can find the visualization options, which fall in 2 categories:

1. Zoom options: (These are: View->Fit to window, Normal size, Zoom in, Zoom out).
2. Histogram options: (all under: View->HDR Histogram->...)

The zoom options are self explanatory, they deal with the fitting of the HDR in its containing window.

The histogram options require more explanation: we somehow have to visualize an HDR image on a CRT or LCD, even if they can only show a normal LDR with 8 bit per color channel. So a simple "luminosity compression" algorithm is performed.
The problem is that when an HDR has a "wide" histogram, (a high gamut of dynamic range) its not possible, even with this (simple) "luminosity compression" algorithm, to show correctly at the same time all the regions of different luminosity in the image (this indeed would be the tone mapping's job).
So you may ask: "Why do we need this tool?"
The answer is that, for example, you may want to visualize correctly all the regions of luminosity of your HDR image by:

1. narrowing down the range of the visible histogram (View->HDR Histogram->Low Dynamic Range)
2. dragging repeatedly the blue rectangle over the different areas of the green histogram.

#### Operations on an HDR

As soon as at least one HDR image has been loaded in the workspace you can:

- Rotate it (Image->Rotate CounterClockWise or Image->Rotate ClockWise): Rotating an HDR modifies the HDR itself.
- Resize it, i.e. scale it (Image -> Resize the Hdr...): Resizing an HDR modifies the HDR itself.
- Save it (File->Save Hdr as...): This is useful when you have just created an HDR from a set of JPEGs (or RAWs or TIFFs) via the "File->New Hdr..." wizard.
- Tone map it (Image->Tonemap the Hdr...): Tone mapping an HDR involves showing another dialog, called "Tone mapping Dialog" which uses the HDR as a source to create an LDR.

### The Creation of an HDR

You can access the wizard that will guide you through the process of creating a new HDR image via the "File -> New Hdr..." menu item.
On the first page the wizard will 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, raw and tiff -8 and 16 bit-).
Even if Qtpfsgui doesn't find the required exif data (Shutter Speed & Aperture) in your image set you can still proceed creating an HDR. To do so you have to insert manually the EV (exposure values) or stop difference values for each one of your images in the set.
On the second page 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.
If you think 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, use it with few and small input exposures.

### The Resize dialog

You can access this dialog via the "Image -> Resize the Hdr..." menu item.

### The Tone mapping dialog

Via the Tone mapping Dialog the user is able to get an LDR from an HDR.
The most important item in the Tone mapping Dialog is the "Tone mapping Panel" (shown on the left). You can toggle its visibility via the first button in the toolbar. The "Tone mapping Panel" is actually a dockbar, so you can make it float or dock it in the left or right areas of the window.
At the top you can change (via a combobox) the size of the resulting image. It is usually a good idea to work on a smaller scale image while trying out the TMOs, because some of them can be very cpu-intensive.
Operators may behave differently depending on the chosen size.
The tone mapping step works like this (as a pipe, some people would say):
pre-gamma --> tone mapping operator

- Pregamma changes the gamma in the HDR before the tone mapping: depending on the chosen tone mapping operator this can yield unexpected effects, like color saturation.
- The tone mapping operator transforms an HDR into a LDR.

NOTE: the post-gamma operation (typical of previous versions of Qtpfsgui) can be performed via the "Correct Histogram" button.
With the "Correct Histogram" button you can tweak the histogram of the current LDR image, the tool has been designed to be similar to the one in GIMP: you can drag the triangular handles to set the new value.

#### The tone mapping operators and their parameters

This section aims to be a reference for all the tone mapping operators and related options.
Have a look at http://osp.wikidot.com/parameters-for-photographers in the meanwhile.

#### The tone mapping settings file

Via the "Save..." button it is also possible to save in a text file (the filename extension is "txt"):

- the currently selected tone mapping operator and its related settings.
- the values of the pregamma settings.

NOTE: Qtpfsgui 1.8.4 uses a new file format (the postgamma option has been removed).
This is useful if you find that are often using some specific operator (and pregamma and postgamma settings) and don't want to manually set the values each time.
The "Load..." button lets you specify the file tone mapping settings filename that you want to load.
The "Apply settings" button applies the settings contained in the tone mapping settings file that has been loaded. This is useful when, after playing around with the values, you want to get back to the file's values.

### The Batch Tone Mapping Dialog

This dialog lets you tone map a batch of M hdr files using N tone mapping setting files. After the process you'll get M*N LDR results.
The top-left list contains the input hdrs, the top-right list contains the input tone mapping setting files.
You have to specify an output directory where the output LDR files will be saved to.
You can also always see what's happening in the Log panel at the bottom. You can filter the visualization of the log messages using the drop-down menu on the bottom-left and the text-field at the bottom-right of the dialog.

### The Options Dialog

This dialog lets you configure the global behavior of Qtpfsgui. You can access this dialog via the "Tools -> Preferences..." menu item.

#### RAW Import

Qtpfsgui uses dcraw's code (internally, no external process is called) to import RAW files. This decision of embedding dcraw has been recently revised, and in the future we will call dcraw as an external process.
Highlights recovery mode: 0, Clip all highlights to solid white. 1, Leave highlights unclipped in various shades of pink. 2-9 Reconstruct highlights. Low numbers favor whites, high numbers favor colors. Try -H 5 as a compromise.
The rest of the options should be almost self explanatory, in case they are not, read the dcraw's manpage.

#### HDR Visualization

Click on the buttons to pop-up a dialog that lets you choose which color to use for the nan/inf and for the negative values.

#### Tone mapping

Qtpfsgui needs a directory path where it will save some intermediate temporary files. Here you can specify this path.
You can also specify how many threads you want to use for the Batch Tone Mapping feature (and the file format you want to save the images to). Each thread gets allocated to a different CPU.

#### Tiff Options

Here you can choose which TIFF-HDR format Qtpfsgui will use to save an HDR image.
LogLuv TIFF is the appropriate format for most cases because it stores the hdr data in a reasonable amount of space (i.e. file size). Even if it is a 16 bit format, it can store floating point data.
The Float TIFF format has to be used only if you want to load your tiff in another application that cannot open the LogLuv format.

### The Copy Exif Data dialog

WARNING: THIS IS AN EXPERIMENTAL TOOL, MAKE A BACKUP OF YOUR IMAGES BEFOREHAND AND CHECK THE RESULT.
You can access this dialog via the "Tools -> Copy Exif Data..." menu item.
With this dialog you will be able to copy the exif data contained in a set of files (the sources) into another set of files (the destinations).
This is a one-to-one data copy, i.e. the first file in the destination list gets the exif data from the first file in the sources list and so on.
This is useful if you lost your original exif data after processing your images.

## The Menu reference

In this section you can find a complete reference describing what all the items in the menu do.

File -> New Hdr...
  launches a wizard that enables you to create an HDR starting from either a set of JPEGs or a set of RAWs, or a set of 8 or 16 bit TIFF files.
File -> Open Hdr...
  launches a dialog that lets you load in the workspace either an existing HDR image file format (OpenEXR, Radiance RGBE, PFS stream) or a RAW file or also a TIFF file.
File -> Save Hdr as...
  launches a dialog that lets you save the HDR image currently selected in the workspace to a HDR image file format (OpenEXR, Radiance RGBE, PFS stream, or 32bit or LogLuv TIFF).
File -> Exit
  Exits the program

Image -> Rotate CounterClockWise
  modifies the HDR image currently selected in the workspace by rotating it counterclockwise.
Image -> Rotate ClockWise
  modifies the HDR image currently selected in the workspace by rotating it clockwise.
Image -> Resize the Hdr...
  launches a dialog that lets you resize the HDR image currently selected in the workspace.
Image -> Tonemap the Hdr...
  launches a dialog that lets you tone map the HDR image currently selected in the workspace.

View -> HDR Histogram -> Fit to dynamic range
  sets the boundaries of the blue "histogram selection" rectangle to the leftmost and rightmost values of the histogram.
View -> HDR Histogram -> Low dynamic range
  sets the boundaries of the blue "histogram selection" rectangle to values which enable a correct representation of the image on a LCD/CRT. The "histogram selection" rectangle can later be dragged.
View -> HDR Histogram -> Shrink dynamic range
  sets the boundaries of the blue "histogram selection" rectangle closer to each other.
View -> HDR Histogram -> Extend dynamic range
  sets the boundaries of the blue "histogram selection" rectangle away to each other.
View -> HDR Histogram -> Decrease Expos
  moves the boundaries of the blue "histogram selection" rectangle left
View -> HDR Histogram -> Increase Exposure
  moves the boundaries of the blue "histogram selection" rectangle right.

Tools -> Preferences...
  launches a dialog that lets you configure the global behaviour of Qtpfsgui.
Tools -> Copy Exif Data...
  launches a dialog that lets you copy (a one-to-one copy) the exif tags in a set of images into another set.

Help -> Documentation...
  Launches the help dialog containing this documentation.