A more up-to-date version of this manual can be found in the online help from within Qtpfsgui.
Qtpfsgui is an open source graphical user interface application that provides a workflow for HDR imaging.
- Stands for "High Dynamic Range", read wikipedia's article for more information. 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")
- 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".
- Shorthand for "Tone Mapping Operator".
- another umbrella definition for several (minimally processed) image formats. Here's the wikipedia's article. 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:
- Create an HDR from a set of files: either JPEG or RAW or TIFF. (icon: File:Http://qtpfsgui.sourceforge.net/img/newfile.png)
- Tone map a HDR image to get a LDR image. (icon: File:Http://qtpfsgui.sourceforge.net/img/tonemap.png)
- Save File:Http://qtpfsgui.sourceforge.net/img/filesave.png and load File:Http://qtpfsgui.sourceforge.net/img/fileopen.png HDR images.
- Rotate File:Http://qtpfsgui.sourceforge.net/img/rotate left.png,File:Http://qtpfsgui.sourceforge.net/img/rotate right.png and resize File:Http://qtpfsgui.sourceforge.net/img/scale.png HDR images.
- Copy exif data between sets of images (icon: File:Http://qtpfsgui.sourceforge.net/img/copyexif.png).
The first feature is accessible via the File->New Hdr...File:Http://qtpfsgui.sourceforge.net/img/newfile.png 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 tone map an HDR file to get an LDR image (second feature) you can press the "Tonemap the HDR" buttonFile:Http://qtpfsgui.sourceforge.net/img/tonemap.png.
Via the File->Open Hdr...File:Http://qtpfsgui.sourceforge.net/img/fileopen.png dialog you can choose to load in the workspace an HDR image image file, and the File->Save Hdr as...File:Http://qtpfsgui.sourceforge.net/img/filesave.png item lets you save the currently selected hdr image to a HDR image file format (third feature).
Users can also rotate File:Http://qtpfsgui.sourceforge.net/img/rotate left.png,File:Http://qtpfsgui.sourceforge.net/img/rotate right.png and resize File:Http://qtpfsgui.sourceforge.net/img/scale.png (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 tool that performs a one-to-one copy of the exif data between two sets of files (fifth feature, icon: File:Http://qtpfsgui.sourceforge.net/img/copyexif.png).
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.
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 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.
Below the menubar you can see the toolbar. It simply contains some of the most frequently used functions listed in the menus: "New HDR..."File:Http://qtpfsgui.sourceforge.net/img/newfile.png, "Open HDR..."File:Http://qtpfsgui.sourceforge.net/img/fileopen.png, "Save HDR as..."File:Http://qtpfsgui.sourceforge.net/img/filesave.png, "Tonemap the HDR"File:Http://qtpfsgui.sourceforge.net/img/tonemap.png 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 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...File:Http://qtpfsgui.sourceforge.net/img/fileopen.png) or create a new one (File->New Hdr...File:Http://qtpfsgui.sourceforge.net/img/newfile.png).
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:
- A gamma combobox, which changes the visualization brightness.
- 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:
- zoom options: (View->Fit to window, Normal size, Zoom in, Zoom out).
- 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 tone mapping's job).
So, for example, you may want to visualize correctly all the regions of luminosity of your HDR image by:
- narrowing down the range of the visible histogram (View->HDR Histogram->Low Dynamic Range)
- 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 CounterClockWiseFile:Http://qtpfsgui.sourceforge.net/img/rotate left.png or Image->Rotate ClockWiseFile:Http://qtpfsgui.sourceforge.net/img/rotate right.png): Rotating an HDR modifies the HDR itself.
- Resize it, i.e. scale it (Image->Resize the Hdr...File:Http://qtpfsgui.sourceforge.net/img/scale.png): Resizing an HDR modifies the HDR itself.
- Save it (File->Save Hdr as...File:Http://qtpfsgui.sourceforge.net/img/filesave.png): This is useful when you have just created an HDR from a set of JPEGs (or RAWs or TIFFs) via the File->New Hdr...File:Http://qtpfsgui.sourceforge.net/img/newfile.png wizard.
- Tone map it (Image->Tonemap the Hdr...File:Http://qtpfsgui.sourceforge.net/img/tonemap.png): 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...File:Http://qtpfsgui.sourceforge.net/img/newfile.png menu item.
On the first page the wizard will ask 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...File:Http://qtpfsgui.sourceforge.net/img/scale.png 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 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.
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 "Adjust Levels" button.
With the "Adjust Levels" 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.
TODO, see this page 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 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.
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.
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.
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.
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, read author's page|this page for more information.
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: Experimental tool, make a backup of your images 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...File:Http://qtpfsgui.sourceforge.net/img/newfile.png 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...File:Http://qtpfsgui.sourceforge.net/img/fileopen.png 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...File:Http://qtpfsgui.sourceforge.net/img/filesave.png 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 CounterClockWiseFile:Http://qtpfsgui.sourceforge.net/img/rotate left.png modifies the HDR image currently selected in the workspace by rotating it counterclockwise.
Image->Rotate ClockWiseFile:Http://qtpfsgui.sourceforge.net/img/rotate right.png modifies the HDR image currently selected in the workspace by rotating it clockwise.
Image->Resize the Hdr...File:Http://qtpfsgui.sourceforge.net/img/scale.png launches a dialog that lets you resize the HDR image currently selected in the workspace.
Image->Tonemap the Hdr...File:Http://qtpfsgui.sourceforge.net/img/tonemap.png 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 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->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->About... Launches the help dialog.