Qtpfsgui Manual

this page has been migrated to our new wiki site


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


Stands for “High Dynamic Range”, see wikipedia's article: High dynamic range imaging. 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".
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 (also written as “tonemap”)
Tonemapping 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 tonemapping dialog as a “tab”.
Shorthand for “Tone Mapping Operator”.
another umbrella definition for several (mininally processed) image formats. See wikipedia's article: Raw_image_format. 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. Tonemap 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). The newly created HDR will be available in the workspace as soon as the HDR creation wizard has ended.
To tonemap 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 currently 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 tonemapping 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 is 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 lauch (because it doesn't make sense) that particular function at this time. For example you cannot tonemap 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 execute (because it doesn't make sense) that particular function at this 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 never 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: (View->Fit to window, Normal size, Zoom in, Zoom out).
  2. histogram options: (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.
When an HDR has a “wide” histogram, (a high gamut of dynamic range) its not possible, even with this (simple) compression algorithm, to show correctly at the same time all the regions of different luminosity in the image (this indeed would be the tonemapping's job).
So, 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.
  • Tonemap it (Image->Tonemap the Hdr…): Tonemapping an HDR involves showing another dialog, called “Tonemapping 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 and very CPU demanding (even buggy), 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 Tonemapping dialog

Via the Tonemapping Dialog the user is able to get an LDR from an HDR.
At the top right side of the dialog the user 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.
The tonemapping step works like this (as a pipe, some people would say):
pre-gamma -> tonemapping operator -> post-gamma

  • Pregamma changes the gamma in the HDR before the tonemapping: depending on the chosen tonemapping operator this can yield unexpected effects, like color saturation.
  • The tonemapping operator transforms an HDR into a LDR.
  • Postgamma is the usual run-of-the-mill gamma effect, it roughly changes brightness.

The tonemapping operators and their parameters

This section aims to be a reference for all the tonemapping operators and related options.
TODO, see http://osp.wikidot.com/parameters-for-photographers in the meanwhile.

The tonemapping settings file

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

  • the currently selected tonemapping operator and its related settings.
  • the values of the pregamma and postgamma settings.

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 tonemapping settings filename that you want to load.
The “Apply settings” button applies the settings contained in the tonemapping 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 Options Dialog

This dialog lets you configure the global behavior of qtpfsgui. You can access this dialog via the “Tools -> Configure Qtpfsgui…” 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, see http://cybercom.net/~dcoffin/dcraw/dcraw.1.html.

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.


Choose whether you want to keep the current size of the output when switching operator (tab), or to default to the smallest size.

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, see the author's page.
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

You can access this dialog via the “Tools -> Copy Exif Data…” menu item.
With this dialog you will be able to transplant (i.e. 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 tonemap 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 Exposure
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 -> Configure Qtpfsgui…
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 -> About…
Launches a short help dialog.
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-Share Alike 2.5 License.