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 le 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. Following is a sample screen shot of the UFRaw dialog. You can click on the image to switch between (white balance), (base curve), (crop and rotate) and (color management), (EXIF) settings.

(correct luminosity and saturation),

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 nd 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 nal 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 lm. 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 dened 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 ne 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 ddling 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 le 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.

Base curve
Base curve imitates the functionality of Nikon's tone curves. For Nikon NEF les you can choose Custom curve if you want to use the curve that is embedded in the raw le. 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 proles 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 x it. The auto curve button on the right tries to set a curve that attens the histogram. It can add lots of contrast to your photo but sometimes the results look very articial.

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 nish much faster.

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 eld 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 rst page you can delete proles and curves that you loaded before.

Conguration
In the options dialog you can also see the conguration data that will be written to UFRaw's ID les and the resource le .ufrawrc, which is created in your home directory. Here you can also tell UFRaw to save the current conguration now. Otherwise, the data is saved only after you convert the image. Notice that if you press Cancel, the conguration data is not saved. The Save image defaults is explained in the Taming UFRaw's conguration section.

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

Delete
Pressing delete will pop-up a window with the raw le and all other les with the same name but different ending. You can decide which les 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 with a single click or open the Save As dialog that let you choose the save settings. 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 conguration

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 nd a few useful tips in this place. UFRaw's conguration 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 As dialog. 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 le .ufrawrc located in the user's home directory. This le is created every time you save an image. Notice that this le is not saved if you exit the preview window with Cancel. ufraw-batch also reads this le but does not write to this le. If you open an image using an ID le: ufraw image-name.ufraw, the information in the ID le is used at this point. ID les are created by setting the Create ID le in the Save As dialog to Also or only. These ID les can also be used as conguration les using the command line option --conf. You can use these le to hold different sets of congurations for different situations. Next, all the options specied in the command line are applied. If you are using ufraw-batch then these options will be the decisive options. For example, ufrawbatch --temperature=5000, will always create output with the color temperature set to 5000K, no matter what the other congurations 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 le. 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 x 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 le 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 le .ufrawrc do not affect your batch conversion, you can create an ID le with your default congurations and batch convert using: ufraw-batch -conf=default.ufraw [...]. The ID le is in XML format. This means that you can read and write to this le with any text editor. Writing to this le is not recommended, even if you know what you are doing, since UFRaw assumes that this le was written using UFRaw and therefore there are very few consistency checks on it. The resource le uses the same format, but you should not go around switching between these les, since different data is saved to each of them. Examining these les could be instructive. They only contain settings which are different from the default ones. Therefore, all the information in the ID les has at least some relevance to the image conversion, and all lines in the resource les are related to a change you made in UFRaw at some point. It is safe to delete the resource le if you want to return UFRaw to its default behavior. The ID le 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 conguration les. 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 workow

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 rst scenario, you need to prepare an ID le 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 le .ufrawrc might affect your output. For the second scenario, use UFRaw's interactive interface and in the Save As dialog set the option Create ID le to only. With this setting UFRaw nishes the save procedure immediately since it does not need to convert the raw le. Later you should use the command ufraw-batch *.ufraw to do the actual conversion.

Color management
Original JPEG / No color prole added / color proled image I'm not going to go into the full details of color management here. Basically, color management is needed because different devices conceive colors differently. For example, if you display a pure red on your computer screen, and photograph it, your camera won't necessarily translate this color to pure red. This is why you need to apply color proles. The effect of color proling is demonstrated with three copies of the same image. The rst copy does not use color proling, I only played with the saturation to get the best possible results. In the second copy I apply Nikon's ICC prole in UFRaw. The difference is most apparent in extreme colors, like in the purple balloon. The third copy is the camera's generated JPG. Three ICC color proles are involved in the color management process: Input prole should be set to the prole of your camera. See the Camera proles section below for information on where such proles can be found together with explanation on the related controls. Output prole should be set to your working space prole. Depending on your workow this can be some large gamut prole, your printer prole or simply sRGB. This prole will be attached to the output image (TIFF, PNG or JPEG). Leave this setting to the default sRGB unless you know that the software that will handle this image is color management aware. Specically, Gimp 2.2 is not color management aware, while Gimp 2.4 is. Display prole should be set to the prole of your display. The System default option will check if there is a system dened ICC prole for your display and use it if found. For information on how to embed an ICC prole for your X display see this. The choice of display prole affects only the preview image you see in UFRaw and has no effect on the nal output image.

If you set both input and output proles to the default sRGB, no color transformation will be applied. The Output intent and Display intent options are explained in the Rendering intents section bellow.

Camera proles
The tricky part is nding a color prole for your camera. Here is a short list of proles you can download from this site. If you have other proles that you are willing to share, then I'm willing to host them here. Nikon D70 - the input prole for the Nikon D70. This prole comes with D70's software, it is copyrighted by Nikon, but I don't think they will mind me posting it here since any D70 owner has this prole anyway. I'm only posting it here to save Unix users the trouble of nding a Windows or Mac machine for extracting the prole from their D70 CD. Windows users can nd the Nikon proles under C:/Program Files/ Common/Nikon/Proles/. Nikon D80 - the input prole for the Nikon D80. Same copyright story as the D70 prole. Nikon D50 - the input prole for the Nikon D50. Same copyright story as the D70 prole. Nikon D100 - the input prole for the Nikon D100. Same copyright story as the D70 prole. Nikon D1/D1H/D1X - the input prole for the Nikon D1 series. Same copyright story as the D70 prole. Canon 10D - non linear - an input prole for the Canon 10D. Copyrighted by Timo Autiokari, the author of the XLProler freeware. Canon 10D - linear - another input prole for the Canon 10D. This is a linear prole, so Gamma should be set to 1. It is a public domain prole copied from Ture Plsson's EOS 10D page . Canon PowerShot S60 - For this prole you need to set Gamma to 0.45 and Linearity to 0.04. It is a free prole made by Artis Rozentals using lprof 1.11.4. It would best match direct sun light conditions.

Canon DSLR users can nd information on how to get and use the ICC proles that come with the camera software here and here. Adobe RGB - a possible wide gamut output prole. Prole taken from the Little CMS package. More prole can be downloaded here. The proles on this page require Gamma to be set to 0.45 and Linearity to be set to some small value, maybe 0.02. It also seems that one should enable the Use color matrix option with these proles. I think that it a bit oversaturates the colors, but it seems to be the author's intent. One can get many other proles by installing the trial version of Phase One. (Even Unix users can install it using Wine.) Another option is to create your own prole, for that you will need an appropriate IT8 target. To create the prole you can use LProf. LProf was developed by the author of Little CMS, but it is no longer maintained by him. Recently it was adopted by a new maintainer so there is still hope for it. Another free option for Windows users is the XLProler. For the input prole you need to dene the parameters of the gamma curve. For standard RGB prole the defaults are 0.45 (approximately 1/2.2) for the Gamma and 0.10 for the Linearity. For camera proles you need to use the setting the prole was created with. If you created the prole, this is not a problem, but if you are using someone else's prole you will probably have to guess these setting since they are usually not published. The Nikon D50, D70, D80 proles above, for example, seems to requires Gamma 0.45 and Linearity 0.00. It seems that the Phase One curves also require Gamma 0.45 but with Linearity 0.05. Also enabling the use of color matrix with these proles gives interesting results. For each prole you can choose if you want to use the Color Matrix. The color matrix is used to make a linear transformation from the sensor's color lters to standard RGB. UFRaw gets these matrices from DCRaw, which in turn got most of them from Adobe. Usually you will want to use the Color Matrix with RGB proles and not use it with camera proles. Notice that the Color Matrix and the gamma curve are applied before the ICC prole transformation. The reason that they appear after the Input Prole is to emphasize that these settings are dened per prole.

Rendering intents
The different intents options specify how out of gamut colors will be handled. Display intent has an extra option - Disable soft proong. When using this option, the output prole is ignored for the rendering of the preview image. The preview image is rendered in the display prole color space using the output intent. The following explaination of the various transformation intents is copied from the Little CMS documentation: It's out of scope of this document to define the exact meaning of rendering intents. I will try to make a quick explanation here, but often the meaning of intents depends on the profile manufacturer.

INTENT_PERCEPTUAL: Hue hopefully maintained (but not required), lightness and saturation sacrificed to maintain the perceived color. White point changed to result in neutral grays. Intended for images. In lcms: Default intent of profiles is used. INTENT_RELATIVE_COLORIMETRIC: Within and outside gamut; same as Absolute Colorimetric. White point changed to result in neutral grays. In lcms: If adequate table is present in profile, then, it is used. Else reverts to perceptual intent. INTENT_SATURATION: Hue and saturation maintained with lightness sacrificed to maintain saturation. White point changed to result in neutral grays. Intended for business graphics (make it colorful charts, graphs, overheads, ...) In lcms: If adequate table is present in profile, then, it is used. Else reverts to perceptual intent. INTENT_ABSOLUTE_COLORIMETRIC: Within the destination device gamut; hue, lightness and saturation are maintained. Outside the gamut; hue and lightness are maintained, saturation is sacrificed. White point for source and destination; unchanged. Intended for spot colors (Pantone, TruMatch, logo colors, ...) In lcms: relative colorimetric intent is used with undoing of chromatic adaptation. Not all profiles support all intents, there is a function for inquiring which intents are really supported, but if you specify an intent that the profile doesn't handle, lcms will select default intent instead. Usually perceptual one. This will force things to "look nice", even if the intent is not the one really desired.