User Guide

UFRaw has three modes of operation. As a Gimp (or Cinepaint) plug-in, you simply open the raw image with the Gimp and the UFRaw preview window pops up. You can also use the stand-alone tool ufraw to convert images interactively. For batch processing of images use ufraw-batch. Type man ufraw or ufraw --help for more information. (In MS-Windows you just click on the UFRaw icon or drag a raw image onto it.)

UFRaw has a graphical user interface, so you can simply open a raw file and experiment with the controls to see how they affect the image. Color management is a bit more complicated and is explained here. The purpose of this guide is to explain some of the more delicate issues of the raw conversion process. It is also useful if you want to have full control over UFRaw's default behavior. This is especially important in batch mode where you don't see your mistakes immediately.

The screenshot and guide below are for UFRaw 0.15.

Following is a sample screen shot of the UFRaw dialog. You can click on the image to switch between (white balance), (Grayscale), (base curve), (color management), (correct luminosity and saturation), (crop and rotate), (Save) and (EXIF) settings.

The image controls appear almost exactly in the order in which they are applied to the image.

Raw histogram

First appears the raw data histogram. I find this histogram very instructive as it shows that even in well exposed photos, most of the pixels have very small luminosity. On this histogram you can also see the red, green and blue curves that show how the raw data will be converted to the final image. These curves can be thick, since a single raw value can be translated to a range of values, depending on the value of the other RGB channels in the same pixel.

Right clicking on the raw histogram pops up a menu that gives you control over the scaling and size of the histogram.

Spot values

If you select a spot area in the preview image (this can only be done when you are on the white balance page), its average RGB values are shown in the display color space. The next value is the luminosity - the Y of the linear XYZ space (between 0 and 1). The last number is the Adams' zone. Adams' zone is the log of the luminosity (base 2) normalized so that middle gray (18% gray) is mapped to zone 5.

Exposure

You can digitally change the original photo exposure. Increasing the exposure is very simple, the only downside is that at the same time you are also increasing the noise in the image. Decreasing the exposure is more tricky, since it is impossible to recover clipped highlights.

When setting the exposure you can control the way highlight restoration is handled.

• restores highlights in LCH space. This means that luminosity is restored while chrominance and hue are preserved. This results in soft natural highlight details (symbolized by a bulb lighting the object directly). More information about this feature can be found here.
• restores highlights in HSV space. In this case value (which corresponds to luminosity) is taken as the average of the clipped and unclipped values, resulting in sharp details (symbolized by a bulb lighting the object from the side).
• clips the highlights completely, this guarantees that there will be no artifacts from the highlight restoration.

These options are only relevant when applying negative EV.

You can also control how positive exposure correction is applied.

• emulates the linear response of the digital sensor. This is mathematically correct, but can result in harsh cutoffs.
• adds a "shoulder" to the response curve, emulating the soft behavior of film.

Exposure is applied together with white balance, and before color management. Auto exposure is calculated according to the white balance and color management settings. Therefore, every time you change one of these settings the auto exposure gets recalculated.

The rest of the image conversion settings are separated into several groups. White balance are settings UFRaw must apply during the raw conversion. UFRaw uses the camera white balance if it can, still I think that this is the setting that would most probably require adjustment. The reset of the settings on the other hand can usually be simply set to no corrections, and this is the default.

White balance

The WB settings control the ratio between the three color channels. Here you can set the color Temperature, making your picture warmer or colder. Going into technical terms, we are using the correlated color temperature of CIE daylight illuminant, which is not exactly the same as black body radiation. CIE daylight illuminant are not defined below 4000K, therefore in the range 2000K to 4000K we use black body radiation. We also use the color matrices (discussed later) to convert to the camera color space. You can learn more about color science at the excellent homepage of Bruce Lindbloom.

Setting the ratio between the three color channels requires two adjustments. Since the Temperature adjustment mostly controls the ratio between the red and the blue channels, it is natural that the second adjustment will control the intensity of the Green channel.

In addition you can set the white balance to the Camera WB, Auto WB and a list of preset WB. The preset values are camera dependent, and there is also fine tuning for cameras that have this feature. If your camera is not supported, go to the Contribute page to read how to get it supported.

If you have a neutral gray color in your picture, then instead of fiddling around with the above controls, you can simply use spot white balance. Click anywhere on the image (and drag the mouse to change the spot size) to get the output color of that area, and press to make this area neutral gray.

The reset white balance button behaves a bit differently from all the other reset buttons. It resets the white balance to the initial value with which the image was loaded as opposed to the other reset buttons, which reset their controls to UFRaw's default values.

The channels multiplier show the actual numbers by which the different camera channels would be multiplied as a result of the other settings. You can change them directly, but usually this should not be needed. Notice that the lowest value is always normalized to 1.00.

Interpolation

After setting the white balance UFRaw interpolates the Bayer pattern.

• AHD interpolation is the Adaptive Homogeneity-Directed interpolation. It is the default interpolation.
• VNG interpolation uses threshold-based Variable Number of Gradients interpolation. This used to be the default interpolation and it is still very good.
• VNG four color interpolation should be used if you get Bayer pattern artifacts in your photo (see DCRaw's FAQ for more details).
• PPG interpolation stands for Patterned Pixel Grouping interpolation. It is almost as good as all of the above and much faster.
• Bilinear interpolation is a very basic interpolation but it is much faster.

After the interpolation you can apply color smoothing. Color smoothing can reduce color artifacts such as noise and chromatic aberration without loss of detail. (The EAHD interpolation option in previous version of UFRaw was just AHD interpolation with color smoothing enabled.)

Wavelet denoising

The Threshold controls the amount of noise reduction applied to the image. The default of 0 (zero) stands for no denoising at all.

Dark frame subtraction

Many cameras apply dark frame subtraction for long exposures to reduce noise and remove hot pixels. The downside of this procedure is that it makes the exposure twice as long, since the dark frame exposure time has to be the same as that of the real image. You can make your own dark frame by putting on the lens cover and load the created raw file in this entry. It is useful if your camera does not have the dark frame subtraction feature or if you decide to disable it to save time. For best results the dark frame should be taken in similar conditions to the original frame.

Grayscale

When a grayscale output is selected, only one channel per pixel is written to the output file instead of three. Therefore the output file should be much smaller. There are sevral modes for generating the grayscale image

• Lightness takes the average beween the maximum and minimun channels.
• Luminance sets the saturation of each pixel to 0, while preserving Luminance.
• Value uses the channel with the maximum value.
• Channel mixer mixes the channel according to the user choice in the channel mixer adjustments.

Base curve

Base curve imitates the functionality of Nikon's tone curves. For Nikon NEF files you can choose Custom curve if you want to use the curve that is embedded in the raw file. Choosing Camera curve will enable the embedded curve only if it was enabled in camera. All camera users can load curves to apply custom curves to their images. The famous white wedding curve (V3.5) from Fotogenetic was applied to the image on the right. Move the mouse over the image to see the original image with a linear curve. A +0.5EV was applied to the original image to equalize the luminosity of both images. The white wedding curve adds some details to the dress. UFRaw can directly apply The curve from Fotogenetic to your images.

The base curve is applied directly to every color channel. It is applied after the exposure and white balance setting so that it will effect each channel equally. It is applied before the gamma correction, meaning that it is applied on the linear data.

You can also create curves of your own using the curve editor. The curve editor can be fully controlled using either the mouse or the keyboard. When using the keyboard the relevant keys are INSERT, DELETE, HOME, END, PAGE-UP, PAGE-DOWN and the arrow keys. I'll let you discover yourself what each key does or how to use the mouse.

Color management

Color profiles and color management are explained on the Color management page.

Corrections

The Saturation adjustment changes the saturation in Lch(ab) space, meaning that hue and luminosity are preserved. Use a value larger than 1 to increase the saturation and a value less than 1 to desaturate the photo. A value of 0 will give a black and white photo.

The curve in the Corrections settings is applied to the luminosity channel in Lch(ab) space. The controls on the left of the curve editor are for controlling the black point. You will notice that they simply control the leftmost point of the curve. If your picture looks foggy, the auto black button might fix it. The auto curve button on the right tries to set a curve that flattens the histogram. It can add lots of contrast to your photo but sometimes the results look very artificial.

Crop and Rotate

On this page you can crop your image, shrink and rotate it. Notice that you can change the crop area by clicking the mouse on the edges of the crop area. For aspect ratio, you can choose any of the presets or enter you own value in decimal notation (1.273) or as a ratio of two numbers (14:11). Locking the aspect ratio allows you to change the image cropping without changing the aspect ratio.

When setting the shrink factor, you should take into account the fact that for values of 2 or heigher, no interpolation needs to be applied to the image. This means that the image conversion would finish much faster.

Save

The name of the output image is split to a path and a filename. By default, the output path is the same as the input path. If you want to save a batch of images to a non-default path, use the Remember output path option.

The JPEG compression level setting, also controls the sampling factor. For compression level 90 or less, 2x2 sampling is used. For compression level 91, 2x1 sampling is used. For compression level 92 or above, 1x1 sampling is used.

EXIF data can be written to JPEG or PNG images. EXIF data can also be written to TIFF file when using Exiv2-0.18 or newer.

UFRaw ID files have the same name as the output file on with a .ufraw ending. ID files contain all the settings for generating the output file. Choosing Create ID file Also is useful for keeping track of the setting used, or for making future changes on top of the saved settings. The only option is useful if one doesn't want to wait while the output file is being generated. The output file can be generated in the background using the command:

ufraw-batch ID-FILE.

EXIF

Here you cannot make any setting, you can only view some very basic EXIF information. UFRaw can save the EXIF data to JPEG output for a few supported formats. These formats include Canon (CRW, CR2), Nikon (NEF), Pentax (PEF), Samsung (PEF), Sony (SR2, ARW), Minolta (MRW), Fuji (RAF) and Adobe's DNG.

UFRaw relies on Exiv2 for the EXIF support, therefore if you want to add support for your camera you should help the Exiv2 developers in this respect. Meanwhile, for unsupported formats it is recommended to use ExifTool by Phil Harvey. To copy all the EXIF information, use the command:

exiftool -TagsFromFile RAWFILE -x Orientation OUTPUTFILE

This will copy all the EXIF data except for Orientation. UFRaw already rotates the image as needed, therefore copying this field could cause a double rotation.

Live histogram

This is the histogram of the preview image, it is updated as you change the settings. Below it you can get some statistics. Notice that the histogram bins for the extreme values (0 and 255) might be clipped, so if you have many over or under exposed pixels, this fact will not appear in the histogram but only in the statistics below it.

Right clicking on the raw histogram pops up a menu that gives you control over the type, scaling and size of the histogram.

The are two modes in which you can Indicate Overexposure and Indicate Underexposure on the preview. If you enable them in the appropriate check boxes, then pixels with at least one overexposed channel will be colored black while pixels with at least one underexposed channel will become white. Press the appropriate button to see which channel is over or under exposed. Like the histogram, this option adds up the colors, so if more than one channel in a pixel is overexposed, when you press the indicate Overexposure button, you will see the combined color, where white means that all three channels are overexposed. For underexposure this is a bit counter intuitive. When pressing the indicate Underexposure button, if all three channels are underexposed you will get black as expected, but if only one channel is underexposed you will get the complementary color (for example, if only the blue channel is underexposed it will show up as yellow which is red + green).

Controls under the preview image

Zoom

This option is obvious. Zooming is limited to 50%. Hopefully 100% zooming will be added in the near future.

Options

All settings which are not directly related to image editing are hidden in the Options dialog. In the first page you can delete profiles and curves that you loaded before.

Configuration

In the options dialog you can also see the configuration data that will be written to UFRaw's ID files and the resource file .ufrawrc, which is created in your home directory. Here you can also tell UFRaw to save the current configuration now. Otherwise, the data is saved only after you convert the image. Notice that if you press Cancel, the configuration data is not saved.

The Save image defaults is explained in the Taming UFRaw's configuration section.

Log

The log information is a bit technical and mostly not interesting.

Delete

Pressing delete will pop-up a window with the raw file and all other files with the same name but different ending. You can decide which files to delete, if any.

Send to Gimp

Hopefully, this option will work correctly out of the box. Otherwise you might have to go to the options window to set the gimp-remote command to match your environment.

Saving the image

In the plug-in version, you just press OK to send the image to the Gimp.

In the stand-alone version you can Save the image or send it to Gimp . Hovering with the mouse over the Save button, pops up a tool-tip with a summary of where and how the image will be saved.

Taming UFRaw's configuration

I believe that generally using UFRaw is straightforward and that its behavior is mostly predictable. Still, if you are converting lots of images and want to minimize the number of key strokes, or if you are using batch mode, then you might find a few useful tips in this place.

UFRaw's configuration options can be divided into three groups:

• Image manipulation options that control how the raw image will be converted. These are the options which are controlled from the preview window.
• Save options that control how the image will be saved. These are the options which are controlled from the (Save) page.
• GUI settings that control how the preview window looks.

There are several sources for these options. The possible sources are listed in the order in which they are applied.

• First, the options are set to UFRaw's default settings. All subsequent sources will override these settings. Still, it is very simple to return to these settings using the buttons. These buttons are grayed out when their appropriate settings are already set to default. This allows one to quickly see which options were changed. The one exception to this rule is the reset white balance button, whose behavior was explained earlier.
• Next, UFRaw reads the options from the resource file .ufrawrc located in the user's home directory. This file is created every time you save an image. Notice that this file is not saved if you exit the preview window with Cancel. ufraw-batch also reads this file but does not write to this file.
• If you open an image using an ID file: ufraw image-name.ufraw, the information in the ID file is used at this point. ID files are created by setting the Create ID file in the (Save) page to Also or only.
• These ID files can also be used as configuration files using the command line option --conf. You can use these file to hold different sets of configurations for different situations.
• Next, all the options specified in the command line are applied. If you are using ufraw-batch then these options will be the decisive options. For example, ufraw-batch --temperature=5000, will always create output with the color temperature set to 5000K, no matter what the other configurations contain.
• In interactive mode, the options you see in the user interface are naturally the options that will be used.

By default UFRaw saves all the settings to the resource file. This is the expected behavior by new users. If you start using UFRaw on a regular basis, you will probably discover that you have your preferred settings. At this point you would like to set Save image defaults to never again. This way you can fix your default settings, and if a certain image requires special settings it won't affect the defaults for subsequent images.

In batch mode the save options from the resource file are ignored. This is to prevent a scenario where you converted a big batch of images only to discover that JPEG compression, for example, was set to 20. If you want to be sure that other setting from the resource file .ufrawrc do not affect your batch conversion, you can create an ID file with your default configurations and batch convert using: ufraw-batch --conf=default.ufraw [...].

The ID file is in XML format. This means that you can read and write to this file with any text editor. Writing to this file is not recommended, even if you know what you are doing, since UFRaw assumes that this file was written using UFRaw and therefore there are very few consistency checks on it.

The resource file uses the same format, but you should not go around switching between these files, since different data is saved to each of them.

Examining these files could be instructive. They only contain settings which are different from the default ones. Therefore, all the information in the ID files has at least some relevance to the image conversion, and all lines in the resource files are related to a change you made in UFRaw at some point. It is safe to delete the resource file if you want to return UFRaw to its default behavior. The ID file also contains the log of the conversion.

UFRaw has three auto adjust buttons. When they are pressed in you can click on them to release them. This has no effect on the image you are converting, but the information of whether these keys are pressed or not is written to the configuration files. Therefore, if for example the auto exposure button is pressed, UFRaw will auto expose the next image also. Otherwise the next image will use the same exposure as the current one.

There are some subtle differences between the behavior of the three auto adjust keys. Auto exposure and auto black are active as long as their button is pressed in. This means that changing the white balance could simultaneously change the exposure and the black point. Auto curve is never kept pressed in. The reason is that auto curve behavior is unpredictable and can lead to very strange outputs. It therefore does not make sense to apply it blindfolded.

Batch processing workflow

There are two reasons to use batch processing. One reason is if you know exactly the parameters you want to apply to your images. The other reason is you don't have the patience to wait for UFRaw to process your images after you make your settings.

For the first scenario, you need to prepare an ID file with all the settings. Then you can convert the images using ufraw-batch --conf=IDFILE.ufraw. You can also use the command line options, but beware that settings from the resource file .ufrawrc might affect your output.

For the second scenario, use UFRaw's interactive interface and in the (Save) page set the option Create ID file to only. With this setting UFRaw finishes the save procedure immediately since it does not need to convert the raw file. Later you should use the command ufraw-batch *.ufraw to do the actual conversion.

Changing theme

UFRaw is a GTK+2.0 application and as such its theme can be changed by changing the GTK theme. Still, you might want to use a specific theme for UFRaw. This can be done by putting a GTK theme file in the home directory with the name .ufraw-gtkrc. A good starting point is this sample dark theme.

---

For comments on UFRaw you can contact me at UdiFuchs@ .com

You are also welcome to visit my photography homepage.