RawPedia Book

General Information

Getting Started

Scope

RawTherapee is a powerful cross-platform raw image processing program, released under the GNU General Public License Version 3. Started in 2005 by Gábor Horváth, it was released as open-source software in 2010 and has been under development by an international team ever since. RawTherapee has an extensive set of tools specifically aimed at processing photographs. It works very well in conjunction with raster graphics editors, such as Photoshop or GIMP, and a digital asset manager, such as digiKam.

Get RawTherapee

Head over to the Download page to get stable builds for production use or unstable development builds for testing.

Start RawTherapee

RawTherapee in Single Editor Tab Mode - Vertical Tabs, showing: 1- Main sections: File Browser (currently opened), Queue, Editor and Preferences. 2- Panels used for navigating to files and folders. 3- Thumbnails of the currently opened folder. 4- Filters to limit the thumbnails shown to only those which match some metadata or state. 5- Thumbnail zooming and info. 6- Quick image operations. 7- Sub-tabs of the File Browser: Filter (currently opened), Inspect (to see a full-sized embedded JPEG preview), Batch Edit (to apply some setting to all selected images) and Fast Export (low quality and bypasses some tools but fast saving - don't use this for typical saving!). 8- Right-click context menu (you will typically use this to apply some processing profile to all selected files).

When you start RawTherapee you will land in the File Browser tab, and it might be empty. You need to point RawTherapee to where your raw photos are stored. Use the folder tree browser on the left of the File Browser tab to navigate to your raw photo repository and double-click on the folder to open it. Then double-click on a raw photo to start editing it.

Edit your first image

First, a little background. A raw photo contains a dump of sensor data, which makes up the bulk of the raw file. This sensor data does not look like a pretty image, in fact it does not look like anything - it is "raw" data, ergo the name. It must be "cooked" to look like the image you saw through the viewfinder. Your camera cooks the raw data into a pretty image, which it stores as a JPEG file inside the raw file (yes, even when you're shooting in only "RAW" mode as opposed to "RAW+JPEG" mode). Due to this fundamental fact of the data being "raw", there is no one correct way for a raw photo to look - the way your camera makes it look is not "the right way", nor is it the only way. However, many photographers would like to use the "camera look" as a starting point for further adjustments, and RawTherapee makes this possible.

When displaying a raw photo in the File Browser which has never been edited in RawTherapee before, the photo's thumbnail is based on the JPEG image embedded inside that raw file -- the exact same image you see when viewing that photo on your camera or in most other software. Once you open that photo in the Editor, RawTherapee creates a new thumbnail based on the actual raw data. Since creating an image from raw data requires "cooking" it, and since you have not manually edited that image yet, RawTherapee uses parameters from the default processing profile for raw photos to process it. From that moment on, the photo's thumbnail is no longer based on the embedded JPEG but on the actual raw data. When you make adjustments to the image in the Editor, the thumbnail is updated to reflect your changes.

Editing is done in the Editor. This is where you work with RawTherapee to create stunning works of art - or perhaps just apply first aid to your snapshots. When you open a raw photo in the Editor for the first time, the default processing profile for raw photos is applied, which as of RawTherapee 5.4 is set to "Auto-Matched Curve - ISO Low" (unless you changed it in Preferences), and it automatically adjusts your raw photo to look like the out-of-camera JPEG. It does so by analyzing the JPEG image which was created by your camera and is stored within the raw file, and adjusting the tone curve so as to match it. In most cases this match is very close to the "camera look". In rare cases it may fail. See the Auto-Matched Curve article for more information.

The Editor.

Take a moment to look around this Editor tab. Notice that there are tabs within this tab - on the right of screen towards the top. These tabs and the controls under them are the Toolbox. You probably have the first tab open and, if you hover your mouse over it, you'll find that it's called the Exposure tab. Below the choice of tabs are the tools the chosen tab contains – Exposure, Shadows/Highlights, Tone Mapping etc. If you click on one of them it will expand so that you can see its contents. Click again and it will collapse. Right-click on one and that one will expand while all others will collapse - a time-saving shortcut. To the left of each tool's label is a power button ( on / off) which lets you turn it on or off, or in some cases instead of a power button there is a triangular expander . Read the Tools section of the General Comments About Some Toolbox Widgets article for a detailed explanation. Browse through the tabs and panels until you feel totally overwhelmed by all that's available.

Before you start working on an image, here is some important advice – Don't Panic! You are in no danger of destroying any of your prized images if you make a mistake. RawTherapee has some features which help you protect your images:

• RawTherapee does non-destructive editing of your raw files. This means that RawTherapee will never, ever change the raw file itself. All changes are stored in sidecar files. You can find out more about them in the Sidecar Files - Processing Profiles article.
• When using the Editor, you'll see the History panel on the left. This panel shows a history stack of every change you have made to your image. To go back to any step (including when the image was first loaded), just click on the relevant line in the History panel.
• Under the History panel you'll see a Snapshots panel. You can skip it for now, but you'll find it handy when you gain experience with RawTherapee. This panel stores the state of all the tools as a "snapshot". This allows you to easily, for example, tweak your photo to a nice and colorful look and take a snapshot, then tweak it again to a lovely black-and-white look and take a snapshot, and then compare the two just by clicking on either snapshot. (Note: RawTherapee does not save snapshots to the PP3 file yet, it will do so in the future. If you have three snapshots which you want to retain, you will need to click through them and save a PP3 file each time under a unique name).
• As you might expect, Control-z will undo the previous change.

Basics

1. Open the raw photo. RawTherapee automatically makes it look like your camera's output. If you're happy with the result, you're done. Else read on.
2. Click on the Color tab and expanding the White Balance tool by right-clicking on it (or use the w keyboard shortcut). RawTherapee will start with the white balance used by your camera. Most white balance adjustments involve moving the Temperature and Tint sliders, or using the Spot White-Balance Picker on a colorless (neutral gray) patch. Adjust to taste.
3. Next, fix the exposure by going to the Exposure tab, expanding the Exposure tool and adjusting it to taste. For now, just use the Exposure Compensation and Saturation sliders.
4. If your image is noisy, switch to the Detail tab, zoom to 100% either using the button or using the z keyboard shortcut, because the effects of the tools in this tab are only visible in the zoomed-to-100% preview (and of course in the saved image), and enable the Noise Reduction tool by clicking on the power button leaving the settings at their default values for now. RawTherapee has automatically removed color (chrominance) noise. Luminance noise is removed manually, though leave it for now as luminance noise generally lends a pleasing, grainy, film-like look. As a general rule, when using noise reduction don't use sharpening. Zoom back out to see the whole image either using the button or using the f keyboard shortcut key.
5. Now you decided you want to fix the geometry and composition of your photo.
   • First make the horizon level, or correct the things which should be vertical such as street lamps or building edges. To easily do this, press the "s" key on your keyboard (the same as clicking the button), and click-and-drag a line along the horizon or along the edge of a building over the preview. Your image will rotate accordingly and you will automatically be taken into the Transform tab.
   • To crop the photo, press the c shortcut key on your keyboard (or use the button) and click-and-drag a crop over the preview; you will notice that the Crop tool becomes automatically enabled. There is no need to "apply" a crop - it takes effect the moment you draw it. You can zoom to fit the crop area by using the f keyboard shortcut, or ⎇ Alt+f if you want to fit the whole image. You may want to set the Crop "Guide type" to "none" if it's a problem.
   • Finally, you want to downscale the photo, because who wants to upload a 10MB JPEG to your social network. Enable the Resize tool and the Post-Resize Sharpening sub-tool, and leave them at the default settings. The resizing effect is only applied to the saved image, not to the preview, so you won't see any change in the preview as you enable these tools.
6. You're all set, let's save it straight away. Click the Save Current Image button (located below the lower left corner of the preview area), or use the ^ Ctrl+s keyboard shortcut. Save it as a JPG file using default settings (quality at "92", subsampling at "balanced"). These are good all-round settings. Choose a folder where you want it saved to, and after a few seconds your file will be ready in the folder you selected. If you close RawTherapee, the settings you used will be stored in a PP3 sidecar file next to the raw file, so that you can re-open the raw photo in the future and retain the tool settings you used.

Now that you went through basic photo adjustment and are familiar with the steps, let's recap the steps but with more advanced details.

Advanced

Always read each tool's article here on RawPedia before using it, to get a firm understanding of what it does. The articles explain how the tools work in RawTherapee, while the general concepts unspecific to RawTherapee are left to the user to find on Wikipedia or elsewhere.

Be sure to see the Keyboard Shortcuts.

The order of the tools inside RawTherapee's engine pipeline is hard-coded, so from that point of view it does not matter when you enable or disable a tool. However some tools can make a large impact on other tools, e.g. changing exposure may require you to re-adjust color toning, and some tools may require plenty of CPU power to calculate the preview making updates of the preview from then on slow, so it is for this reason we suggest you stick to this general order of operations:

1. Start off by making sure that RawTherapee's environment is set up correctly, meaning:
   • Make sure that RawTherapee is using your monitor's color profile if you use a color-managed workflow. Check Preferences > Color Management. You may also need to load the appropriate calibration curves into your graphics card if you built your monitor color profile on top of them, though how you do that is outside the scope of RawTherapee.
   • Make sure that the Color Management tool is configured correctly. Usually the defaults are best. Read the Color Management and Color Management addon articles. If instead of using the color matrix or DCP or ICC profiles shipped with RawTherapee you decide to use an external one, for example a self-made DCP or one from Adobe, load it as the first thing you do, otherwise you may need to re-adjust some of the color tools. Always use an output profile - in most cases the default one, RT_sRGB. If you think you're being smart by selecting "No ICM: sRGB Output", you're mistaken.
2. If you want to use a Flat-Field and/or Dark-Frame image, do so now, to avoid re-adjustment.
3. Now set the correct White Balance. You may fix the exposure first if the image is too dark (or too bright) to see white balance changes.
4. Next, adjust the Exposure, using the Exposure Compensation and Black sliders to get the image into the right ballpark. Once in the right ballpark, continue with using both tone curves. Be sure to read the Tone Curve section in the Exposure article to learn why there are two of them and how best to use them - they are a very powerful tool!
5. In the Basics section above we suggested that you use the Saturation slider (in the Exposure tool). Now that you've learned the basics and are exploring more advanced techniques, we suggest you not use the Saturation slider anymore, and instead use the more powerful CC curve in the Lab Adjustments tool, as it gives you finer control.
6. The order of the rest gets fuzzy. Some tools will unavoidably influence others. Carry on with the Lab Adjustments tool and then the rest of the tools in the Exposure tab.
7. Then use the tools in the Color tab.
8. Then zoom to 100% and use the tools in the Detail tab. Generally, don't sharpen if you're using noise reduction.
9. Finally, zoom out again and use the tools in the Transform tab. The reason you left these for last is that they may make the preview image appear a bit blurry, because in order for the preview to be responsive, RawTherapee uses that very preview image you see at the very resolution you see - small - to show what the tools do, and when you rotate or otherwise change the geometry of a small image, there is a clear softening. This is not a problem when saving as by that point RawTherapee does its processing on the full-sized image, which is slow but of high quality.
10. You can edit metadata in the Meta tab at any time before saving.
11. Save, either directly when you want to save a single photo, or via the Batch Queue when you want to process many photos. See the Saving Images article.

Features

• Open-source, cross-platform.
• Easy camera-like starting point. By default, RawTherapee matches your raw photo to look like the out-of-camera JPEG photo. You can export as-is, or make further tweaks.
• RawTherapee uses SSE optimizations for better performance on modern CPUs, and performs calculations in floating point precision.
• Color management using the LittleCMS color management system.
• Supports DCP and ICC color profiles.
• Supports most raw formats, as well as floating-point HDR images in the DNG format. Also supports JPEG, TIFF and PNG.
• Support for film negatives and monochrome cameras.
• Queue your photos for later exporting, freeing up your CPU for working with the preview in a responsive way.
• Rate photos using a 0-5 star system (ratings are read from embedded Exif and XMP), tag them by color, filter by filename and metadata.
• Scroll the tool panels using your mouse scroll wheel without worrying about accidentally misadjusting any tools, or hold the Shift key while using the mouse scroll wheel to manipulate the adjuster the cursor is hovering over.
• Efficient use of vertical screen space by right-clicking on a tool to expand it while automatically collapsing all other tools.
• A Before|After view to compare your latest change to any previous one.
• Lossless editing - all adjustments are stored in PP3 sidecar files.
• Dedicated command line support to automate RawTherapee using scripts or call it from other programs.
• Preserve, edit or strip metadata from exported images.
• Localized in over 15 languages.
• Adaptation of the CIECAM02 color appearance model ratified by the International Commission on Illumination (CIE) to maintain accurate colors and to, given a set of initial viewing condition parameters, convert the image so that it will look the same under the target viewing conditions.
• Profiled lens correction (vignetting, distortion, chromatic aberration) using Lensfun or Adobe Lens Correction Profiles (LCP).
• Dark frame subtraction and flat field correction to eliminate some forms of noise and sensor dust and correct vignetting and lens color casts.

The Floating-Point Engine

RawTherapee performs all calculations in 32-bit floating point precision (in contrast to 16-bit integer as used in many other converters such as dcraw and also in RawTherapee up to version 3.0).

Classical converters work with 16-bit integer numbers. A pixel channel has values ranging from 0-65535 in 16-bit precision (to increase precision, converters usually multiply the 12- or 14-bit camera values to fill the 16-bit range). The numbers have no fractions, so for example there is no value between 102 and 103. In contrast, floating point numbers store a value at a far wider range with a precision of 6-7 significant digits. This helps especially in the highlights, where higher ranges can be recovered. It allows intermediate results in the processing chain to over- or undershoot temporarily without losing information. The fraction values possible also help to smooth color transitions to prevent color banding.

The downside is the amount of RAM that floating point numbers require, which is exactly twice that of 16-bit integer. Together with the ever-increasing megapixel count of digital cameras, a 32-bit operating system can quite easily run out of memory and cause RawTherapee to crash. Therefore a 64-bit operating system is highly recommended for stability.

We officially ended support for 32-bit versions of RawTherapee with release 5.0-r1 in February 2017. Do not file bug reports regarding issues on 32-bit systems.

If you nevertheless need to use RawTherapee on a 32-bit system, the following will help make the most of it:

• Use 4-Gigabyte Tuning in Windows. See "4-Gigabyte Tuning: BCDEdit and Boot.ini" for an explanation of what it is, and find out how to do it by reading the guide "How to set the /3GB Startup Switch in Windows XP and Vista".
• Close other programs while working in RawTherapee.
• Use a single Editor tab.
• Turn off "auto-start" in the Queue. Add photos to the Queue as usual. When ready to start processing them, restart RawTherapee to free up RAM (no image open in the Editor), and start the queue.
• Ensure that RawTherapee does not load dark-frame or flat-field images if you do not use them.
• Avoid having more than a few hundred photos per folder, as each photo requires a little RAM (thumbnail, embedded ICC profile, etc.).

Memory Requirements

To open an image in the Editor, RawTherapee 5.6 needs very roughly this much RAM, in bytes:

• Non-raw
  • 8-bit: (width * height * 3) + (width * height * 4) + (previewWidth * previewHeight * 28)
  • 16-bit: (width * height * 3 * 2) + (width * height * 4) + (previewWidth * previewHeight * 28)
  • 32-bit: (width * height * 3 * 4) + (width * height * 4) + (previewWidth * previewHeight * 28)
• Raw
  • (width * height * 4) + (width * height * 4) + (width * height * 12) + (previewWidth * previewHeight * 28)

Some overhead memory is additionally required, for example for generating thumbnails of other images which reside in the opened image's folder.

The memory requirement for processing and saving an image depends on what tools you use and can vary significantly from the above - the above pertains only to opening an image.

Bit Depth

Introduction

You will hear terms such as "8-bit", "16-bit", "24-bit", "32-bit", "64-bit" and "96-bit" with reference to digital images. This article will clarify what those things mean.

Digital images consist of millions of pixels, and each pixel describes one or more color channels. Grayscale images need only one channel (a value of 0 could represent pure black, 255 could represent pure white, and the values in-between would then represent shades between black and white), while RGB color images need three channels - one describes red, one green and one blue. Each channel describes only an intensity, so there is nothing inherently green about a number which describes a pixel from the green channel; colors derive from the interaction between all three channels in the RGB color model.

A single pixel could represent more than three channels, for example it could contain information about an alpha channel (which describes transparency) or an infra-red channel (which some scanners support).

The higher the bit depth, the more precisely a color can be described, at a cost of requiring longer computation, more RAM and more storage space.

Bits Per What?

Bit depth is expressed as a value which describes either the number of bits per pixel (BPP), or bits per channel (BPC). The very popular JPEG format typically saves images with a precision of 8 bits per channel, using three channels, for a total of 24 bits per pixel. The TIFF format supports various bit depths, for example 32 bits per channel for a total of 96 bits per pixel.

When describing bit depth, state what you're describing to leave no room for ambiguity. For example, if someone says they have a "32-bit" image, does that mean the image has 32 bits per channel, or does it have 4 channels at 8 bits per channel?

Precision

What difference does bit depth make? The more bits are available to describe a color, the more precisely you can describe that color.

• A precision of 1 bit per channel means that there is only 1 bit to describe the value. A bit can only be 0 or 1, so you can only represent two values, which typically would mean black or white.
• A precision of 2 bits per channel means there are two bits available to describe a color. Since each bit can be 0 or 1, and there are two of them, they can represent 4 possible values:

  [00] = 0
  [01] = 1
  [10] = 2
  [11] = 3

  If we use 0 to represent black and 3 to represent white, there are two additional shades of gray which can be described.

• A precision of 8 bits per channel means there are 8 bits which can represent 256 values:

  [0000 0000] = 0
  [0000 0001] = 1
  (...)
  [1111 1110] = 254
  [1111 1111] = 255

  If we use 0 to represent black and 255 to represent white, 254 shades of gray can also be described. This is what JPEG files use - 8 bits per channel, with 3 channels. It is sufficient to be used for most ready-to-view photographs in the sRGB color space without visible posterization, so you can use it when saving photographs ready to be viewed over the internet. It is not suitable as an intermediate format nor as a final format if there is a chance you might need to tweak the photograph later on, as you run the risk of introducing posterization artifacts, depending on the strength of adjustments. 8-bit precision is not enough to represent a high dynamic range scene in a linear way without posterization, i.e. you theoretically could use 8 bits of precision to describe a high dynamic range scene linearly, but the numbers would be so far apart that heavy posterization would occur. For instance, if a photograph captures a sunny day in the park, and if we assume that black should be 0 and white should be 1 000 000, we could map 0 to 0 and 255 to 1 000 000, but then there would only be 254 values left for describing all the remaining 999 999 shades of the original scene.

• A precision of 16 bits per channel (16-bit integer) means there are 16 bits which can represent 65536 values:

  [0000 0000 0000 0000] = 0
  [0000 0000 0000 0001] = 1
  (...)
  [1111 1111 1111 1110] = 65534
  [1111 1111 1111 1111] = 65535

  Digital cameras typically capture light in 12-bit or 14-bit precision (and due to noise and imprecise electronics the lowest bits are of dubious quality). 16 bits per channel are enough for most photography needs, including for use in intermediate files (if you want to pass an image from one program to another without data loss).

• The values of a 16-bit floating point image, also known as half-precision floating point, are spread in a way more suitable to sampling light than in 16-bit integer. This is so for various reasons: human vision is more sensitive to small changes in dark tones than to small changes in bright ones; our eyes respond to light in a logarithmic way (light must be 10 times more intense in order for us to see it as twice as bright); and specular highlights which can be the the brightest elements in a scene (the sun reflecting off a door knob) need not be described as accurately as all the other tones. In 16-bit floating-point notation, values are distributed more closely in the (lower) darker tones than in the (higher) lighter ones, thus allowing for a more accurate description of the tones more significant to us.
• A 32-bit floating point image can represent 4.3 billion values per channel, and requires roughly twice the disk space as a 16-bit image. Few programs support 32-bit images.

One of the reasons bit depth affects mostly shadows is due to the way colors are stored. Each color is defined by a mixture of red, green and blue. Using an 8-bit image and the color orange as an example, many values are possible when describing bright orange, but the number of samples available to describe dark orange drops to very few, i.e. only the lowest 3-4 bits from each channel can be used to describe dark orange, which means only 16 possibilities exist. The higher the bit-depth, the more colors can be described, and posterization avoided.

Gamma Encoding

Gamma encoding can be used when saving image files, meaning that values are modified in such a way that more can be allocated in the shadow range than in the highlight range, which better matches the human eye's sensitivity. This means that an 8 bit JPEG can display as much as log2((1/2^8)^2.2) = 17.6 stops of dynamic range, which indeed exceeds the 14 stops of the current best cameras, which explains why you sometimes can see a camera's shadow noise even in an 8-bit JPEG. However, due to the non-linear distribution, we lose precision compared to the raw file recorded in a linear way by the digital camera. Practically this is not a problem when the output file is the definitive one and will not be processed anymore, however a photo can be vastly improved when saved as raw data and processed using a state of the art raw processing program, such as yours truly - RawTherapee.

After RawTherapee

Once you have adjusted a photo in RawTherapee and are ready to save, you are faced with a choice of output format, per-channel bit depth, color space and gamma encoding. If you plan to post-process your photos after RawTherapee in a 16-bit-capable image editing program, it is better to save them in a lossless 16-bit format. RawTherapee can save images in 16-bit integer precision (denoted as "TIFF (16-bit)" in the Save dialog) as well as 16-bit floating-point precision (denoted as "TIFF (16-bit float)"). Uncompressed TIFF at 16-bit integer precision is suggested as an intermediate format as it is the fastest to save and is widely compatible with other software. 32-bit files are roughly twice the size and not well supported by other programs.

RGB and L*a*b*

RGB cube.

Lab color space.

RGB and CIE L*a*b* (or just "Lab") are two different color spaces, or ways of describing colors.

Many people wonder what the differences are between adjusting lightness, contrast and saturation in the RGB color space, or lightness, contrast and chromaticity in the Lab color space. RGB operates on three channels: red, green and blue. Lab is a conversion of the same information to a lightness component L*, and two color components - a* and b*. Lightness is kept separate from color, so that you can adjust one without affecting the other. "Lightness" is designed to approximate human vision, which is very sensitive to green but less to blue. If you brighten in Lab space, the result will often look more correct to the eye, color-wise. In general we can say that when using positive values for the saturation slider in Lab space, the colors come out more 'fresh', while using the same amount of saturation in RGB makes colors look 'warmer'.

• Comparison of RGB and Lab adjustments
• 

  Neutral

• 

  RGB Lightness +30

• 

  Lab Lightness +30

• 

  RGB Contrast +45

• 

  Lab Contrast +45

• 

  RGB Saturation +25

• 

  Lab Chromaticity +25

• 

  Vibrance +25

The difference between the Lightness slider in the Exposure section (in RGB space) and the Lightness slider in the Lab section is subtle. A RGB Lightness setting of +30 produces an image that is overall a bit brighter than when using a Lab Lightness setting of +30. The colors in Lab Lightness are somewhat more saturated. The contrary is true for the Contrast sliders; when using a RGB Contrast of +45 the colors will be clearly warmer than when using a Lab Contrast of +45. The contrast itself is about the same with the two settings. Do not hesitate to use both sliders to adjust saturation and/or contrast. As for the Saturation/Chromaticity sliders, setting the RGB Saturation slider to -100 renders a black and white image which appears to have a red filter applied, while the Lab Chromaticity slider renders a more neutral black and white image. Positive RGB Saturation values will lead to hue shifts (the larger the value, the more visible the shift), while positive Lab Chromaticity values will boost colors while keeping their hues correct, rendering a crisp and clean result. Lab chromaticity (via the "Chromaticity" slider or "CC" curve) is the recommended method for boosting colors.

Making a Portable Installation

RawTherapee and the cache folder can be stored "self-contained" on a USB flash drive or any other mass-storage device.

For Windows

Get the latest build of RawTherapee. Since we want it portable, we don't want the installer, just the bare, zipped program. If the latest version on our website is in simple zipped form without an installer, you can skip this step. However, if it is an installer, you need to first extract the RawTherapee files.

• If it is an Inno Setup installer (.exe extension, all recent Windows installers are Inno Setup ones at the time of writing, summer 2014), get innounp or innoextract to unpack it.
• If it is an MSI installer (no recent Windows builds use this at the time of writing), fire up a command prompt and type:

  msiexec /a RawTherapee.msi TARGETDIR="C:\TargetDir" /qb

  Replace the name of the MSI installer and the target directory as appropriate. Spaces in the TargetDir path are allowed, as the path is enclosed in quotes.

Let's assume that you've unzipped your archive into E:\RawTherapee, where E:\ is the drive letter of your USB flash drive. Open the E:\RawTherapee\options file, and set the MultiUser option to false. Now when you run RawTherapee, it will store the cache and your settings in subfolders relative to the executable, named mycache and mysettings, respectively, so in E:\RawTherapee\mycache and E:\RawTherapee\mysettings.

See also the File paths page on how to set a different location for these two folders.

When updating RawTherapee, it is recommended to unzip the new version to a new folder and simply move mycache and mysettings into it.

For Linux

Getting RawTherapee to run off a portable medium such as a USB flash drive on various Linux systems is not straightforward due to the nature of Linux systems. While the Windows version of RawTherapee comes bundled with all required libraries to run on any Windows version, Linux distributions differ significantly from each other and as a result a version of RawTherapee built for one distribution is unlikely to run under a different distribution. One way around this is by using an AppImage.

A RawTherapee AppImage is a single file which contains a RawTherapee executable along with all the required files needed for it to run on any Linux distribution. Download it, make it executable, and run it. We are currently in the testing phase regarding AppImages. They are not yet available from our Downloads page, but you can find them on our "development builds" page in the forum.

Regardless whether you use the AppImage or a "proper" RawTherapee build from the distribution's package manager, you will want to be able to hang on to your RawTherapee configuration and processing profiles.

In order to backup your configuration you will want to copy RawTherapee's config folder onto your USB stick. Specifically, you want the "options" file, your custom "camconst.json" if you made one, and any custom PP3, ICC, DCP and LCP profiles. The File Paths article describes where to find these.

The File Browser

The File Browser tab is where you review your photos, select photos for editing, or perform batch-editing operations. It consists of the following parts:

RawTherapee in Single Editor Tab Mode - Vertical Tabs, showing: 1- Main sections: File Browser (currently opened), Queue, Editor and Preferences. 2- Panels used for navigating to files and folders. 3- Thumbnails of the currently opened folder. 4- Filters to limit the thumbnails shown to only those which match some metadata or state. 5- Thumbnail zooming and info. 6- Quick image operations. 7- Sub-tabs of the File Browser: Filter (currently opened), Inspect (to see a full-sized embedded JPEG preview), Batch Edit (to apply some setting to all selected images) and Fast Export (low quality and bypasses some tools but fast saving - don't use this for typical saving!). 8- Right-click context menu (you will typically use this to apply some processing profile to all selected files).

• The left panel
  • The "Places" panel on the top links to your home folder, USB card readers, the system's default "photos" folder, or custom folders.
  • Below this is a standard tree-type file browser that you can use to navigate to folders containing your photos. RawTherapee does not complicate things by requiring you to import photos into databases as some other software do.
• The right panel
  • The "Filter" tab lets you show only photos which match the parameters you specify.
  • The "Inspect" tab shows a preview at a fixed scale of 100% of the image your mouse cursor is hovering over, which is either the largest JPEG image embedded in the raw file, or the image itself when hovering over non-raw images.
  • The "Batch Edit" tab allows you to apply tool settings to the selected image or images. This allows you to quickly enable some tool in many photos at once.
  • The "Fast Export" tab lets you quickly process the selected images by bypassing certain tools even if they are enabled in the processing profiles of those images, so that you can get a quick preview of the raw files for example to delete the shots which are blurry or out of focus.
• The central panel shows thumbnails of the folder currently selected.

You can hide the individual panels using the "Show/Hide the left panel " and "Show/Hide the right panel " buttons - see the Keyboard Shortcuts page.

When you open a folder, RawTherapee will generate thumbnails of the photos in that folder in the central panel. The first time you open a folder full of raw photo files, RawTherapee will read each file and create a thumbnail based on the embedded JPEG image (every raw photo has an embedded JPEG image, sometimes even a few of various sizes). This can take some time on folders with hundreds of photos, but it only happens the first time you open that folder. All subsequent times you go to a previously opened folder, RawTherapee will read the thumbnails from its cache if they exist, and this will be much faster than the first time you opened that folder.

The JPEG image embedded in each raw photo is identical to the out-of-camera JPEG image you would get if you shot in JPEG mode (or in "RAW+JPEG" mode). This JPEG is not representative of the actual raw data in that photo, because your camera applies all kinds of tweaks to the JPEG image, such as increasing the exposure a bit, increasing saturation, contrast, sharpening, etc.

After you start editing a photo, its thumbnail in the File Browser tab is replaced with what you see in the preview in the Editor tab, and every tweak you make is reflected in the thumbnail. The thumbnails are stored in the cache for quick future access. If you want to revert to the embedded JPEG image as the thumbnail, then right-click on the thumbnail (or selection of thumbnails) and select "Processing Profile Operations > Clear".

Use the zoom icons in the File Browser's top toolbar to make the thumbnails smaller or larger. Each thumbnail uses some memory (RAM), so it is advisable not to set the thumbnail size too high ("Preferences > File Browser > Maximal Thumbnail Height").

You can filter the visible photos by using the buttons in the File Browser's or Filmstrip's top toolbar, as well as by using the "Find" box or the "Filter" tab. Possible uses:

• Show only unedited photos,
• Show only photos bracketed +2EV,
• Show only photos ranked as 5 star,
• Show only photos with a specific ISO range,
• Show only photos with a NEF extension.

If your screen's resolution is too low to fit the whole toolbar, some of the toolbar's contents (buttons, drop-downs, etc.) may become hidden. To see them, simply hover the cursor over the toolbar and use the mouse scroll-wheel to scroll the contents left and right.

Rating

RawTherapee allows you to rank images between 0 and 5 stars. RawTherapee 5.7 introduced support for reading the rating information stored within the image's metadata, e.g. as set by your camera or by other software, and showing it through its star rank system.

Metadata tags used for conveying the rating have evolved over the years, and RawTherapee prioritizes them in the following ascending order:

1. Exif rating
2. XMP rating
3. PP3 rank

That is, if an image has an Exif rating tag with value 1 and an embedded XMP rating tag with value 2, then RawTherapee will show 2 stars. If you then rank it 3 stars in RawTherapee, the 3-star rating is shown in RawTherapee's File Browser and Filmstrip.

Note that RawTherapee's star ranking does not get exported to saved images. That is, if you saved the image from the above example, the saved file would contain Exif:rating=1 and XMP:rating=2 if you set "metadata copy mode" to "copy unchanged" - it would not reflect the 3-star rank anywhere. Furthermore, if you set "metadata copy mode" to "apply modifications", the saved file would only contain Exif:rating=1, as editing XMP is unsupported so it gets stripped.

Batch Adjustments - Sync

Batch Adjustments / Sync

RawTherapee lets you batch-adjust, or sync, the processing settings in many photos at the same time in generally two ways. It lets you copy and paste a processing profile (a collection of tool settings), in parts or in full, to any number of images. It also lets you select any number of images and adjust any tool in all of them at once (sync), and it lets you do this in two ways. Let's take a closer look.

Both ways involve making a selection of photos you want the processing profile or adjustments applied to. Selections are made using standard key combinations: Shift+click to select a range, Ctrl+click to select individual images, or Ctrl+A to select everything. Both ways are performed from the File Browser tab. The "copy & paste" method can also be done via the Filmstrip.

Copy & Paste

Copying and pasting a processing profile to a selection of images is a very common task. Assume you took a series of photos - for example studio shots, wedding portraits or focus-bracketed macro photos. All images in each series are going to be very similar; they will probably use the same lens, the same ISO, the same white balance, and end up being used for the same purpose. This means that they will all probably require the same processing settings - the same noise reduction, the same sharpening and lens distortion correction, and so forth.

To process the lot, what you would usually do is open any one image from the whole series in the Editor tab and tweak it to your liking. Once you have finished tweaking it, you will apply this image's processing profile to all other images in the same series. To do that, go to the File Browser tab, right-click on this photo and select "Processing Profile Operations > Copy", then select the images you want to apply this profile to, right-click on any one of them (it doesn't matter which) and select "Processing Profile Operations > Paste". In one quick operation you have replicated the same tool settings in the whole series of images.

Additionally, RawTherapee lets you apply only a part of the copied processing profile, for example only the "Resizing" tool. To do this, use the "Processing Profile Operations > Paste Partial" option instead of the "Paste" option.

Sync

RawTherapee lets you instantly apply tool adjustments to a selection of images. Similar functionality in other software is called "sync". This method is useful for when you don't need to see an accurate preview of your changes, for example when you only want to enable the "Resizing" tool in a selection of photos, because when working in the File Browser tab your only preview are the small and inaccurate thumbnails. This method can only be performed from the File Browser tab because you need access to that tab's batch tools (the panel on the right).

When you're in the File Browser tab, select the images you want to batch-adjust (sync), then use the tool panel on the right to make adjustments. Your tweaks can either replace the existing ones ("Set" mode), or be added to them ("Add" mode). For example if you select two photos, one of which has previously been tweaked with +1EV Exposure Compensation and one which has not, and you set Exposure Compensation to +0.6EV, then the previously-tweaked photo would end up having +1.6EV Exposure Compensation in "Add" mode and just +0.6EV in "Set" mode. The photo which was not previously tweaked would have +0.6EV in both modes. You can decide which tools should work in which mode from the Batch Processing tab in Preferences.

Deleting Files

As RawTherapee is a cross-platform program, it has its own trash bin, independent from your system one if you have a system one.

Using the Trash Bin

To move files to the trash bin, either use the "Move to trash" button in the top-right corner of each thumbnail, or right-click on a selection of files and choose "File operations > Move to trash". These files are then marked as being in the trash bin, but they are not deleted from your hard drive.

• To hide all files which are marked as being in the trash bin, click the "Show only non-deleted images" button in the top toolbar.
• To see the contents of the trash bin, click the "Show contents of trash" button .
• While you are viewing the contents of the trash bin a new "Permanently delete the files from trash" button appears to the left of the thumbnails - use it to delete all trashed files from your hard drive.
• Click on the "Clear all filters" button to return to the default view.

Deleting From the Hard Drive

To delete files from your hard drive without using the trash bin, just right-click on a file or on a selection of files and choose "File operations > Delete" or "Delete with output from queue". Both options delete the selected photo and its sidecar file from your hard drive, but "Delete with output from queue" also deletes the saved image whose filename matches the template which you currently have set in the Queue tab, in the "Use template:" field.

The Editor

The Image Editor tab in RawTherapee 5.5.

Introduction

The Image Editor tab is where you tweak your photos. By default RawTherapee is in "Single Editor Tab Mode, Vertical Tabs" (SETM/VT) which is more memory-efficient and lets you use the Filmstrip (described below). You can switch to "Multiple Editor Tabs Mode" (METM) by going to "Preferences > General > Layout", however each Editor tab will require a specific amount of RAM relative to the image size and the tools you use, and also the Filmstrip is hidden in this mode, so we recommend you first give SETM a try.

The Preview Panel

The central panel shows a preview of the image being edited. This preview is generated from raw data if such is available. It reflects the adjustments made by the tools in the Toolbox. Note that the effects of some tools are only accurately visible when you are zoomed in to 1:1 (100%) or more; these tools are marked in the interface with a "1:1" icon alongside the tool's name.

When opening an image, RawTherapee loads the tool settings from the sidecar file if one exists, else it applies a default sidecar file as specified in "Preferences > Image Processing > Default Processing Profile". When you close the image (which happens automatically if you open a different image or if you close RawTherapee) the current tool settings are automatically saved to a sidecar file as specified in "Preferences > Image Processing > Processing Profile Handling".

Eek! My Raw Photo Looks Different than the Camera JPEG

When opening a raw photo you may notice that it looks different from your camera's JPEG, or from what other software show when viewing the same raw photo. In some cases this difference is minute, but in other cases it could be significant - the image could be darker, lack contrast, be less sharp and more noisy. What gives?

There are three things you must know first to understand what is happening here:

1. Your camera does not show you the real raw data when you shoot raw photos. It processes the raw image in many ways before presenting you with the histogram and the preview on your camera's display. Even if you set all the processing features which your camera's firmware allows you to tweak to their neutral, "0" positions, what you see is still not an unprocessed image. Exactly what gets applied depends on the choices made by your camera's engineers and company management, but usually this includes a custom tone curve, saturation boost, sharpening and noise reduction. Some cameras, particularly low-end ones and Micro Four-Thirds system, may also apply lens distortion correction to not only fix barrel and pincushion distortion but also to hide dark corners caused by severe vignetting or by the lens hood. Most cameras also underexpose every photo you take by anywhere from -0.3EV to -1.3EV or more, in order to gain headroom in the highlights. When your camera (or other raw editing software) processes the raw file it compensates for this by increasing exposure compensation by the same amount.
2. When shooting a raw photo, most cameras embed within the raw file a full-resolution JPEG image with tone curves and other adjustments applied. Some raw files contain as many as three JPEG images differing only in resolution. Most cameras offer storing photos in one of three modes: "RAW", "JPEG", or "RAW+JPEG". The embedded JPEG image discussed here is stored within the raw file even in just "RAW" mode! When you open raw files in other software, what you are usually seeing is not the raw data, but the embedded, processed JPEG image! Examples of software which are either incapable of or which in their default settings do not show you the real raw data: IrfanView, XnView, Gwenview, Geeqie, Eye of GNOME, F-Spot, Shotwell, gThumb, etc. It is worth mentioning at this point that if you shoot in "RAW+JPEG" mode then you could in fact be wasting space on your memory card and gaining nothing for it, as your raw files most likely already contain an embedded JPEG identical to the external one saved in "RAW+JPEG" mode.
3. Most raw development programs (programs which do read the real raw data instead of just reading the embedded JPEG) apply some processing to it, such as a base tone curve, even at their most neutral settings, thereby making it impossible for users to see the real, untouched contents of their raw photos. Adobe Lightroom is an example. Comparing RawTherapee's real neutral image to a pseudo-neutral one from these other programs will expose the differences.

RawTherapee, on the other hand, is capable of showing you the real raw image in the main preview, leaving the way you want this data processed up to you. When you use the "Neutral" processing profile you will see the demosaiced image with camera white balance in your working color space with no other modifications. You can even see the non-demosaiced image by setting the demosaicing method to "None".

To provide you with a more aesthetically pleasing starting point, RawTherapee by default uses the Auto-Matched Curve processing profile, which automatically generates a tone curve to make the tones of the raw image match those of the embedded JPEG, if one exists. If one does not exist, you can use the Standard Film Curve processing profile, which applies a curve which looks good in most cases. Choose the sub-type (ISO Low/Medium/High) depending on how noisy your image is.

Scrollable Toolbars

The toolbars above and below the main preview hold a certain number of buttons and other widgets which might not fit on lower resolution screens. If your screen's resolution is too low to fit the whole toolbar, some of the toolbar's contents (buttons, drop-downs, etc.) may become hidden. To see them, simply hover the cursor over the toolbar and use the mouse scroll-wheel to scroll the contents left and right.

Preview Background Color

The background color of the preview panel may be changed to allow you to better judge how the image tones will appear when the saved image is viewed on a website (or image viewer, or print) of a similar background color.

This choice also applies to the cropped-off area, if the image is cropped. See "Preferences > General > Appearance > Crop mask color".

Available options:

• theme-based (see Preferences > General > Appearance),
• black,
• L* middle grey,
• white.

Preview Channel

The preview can be toggled to show one of the following channels:

• red,
• green,
• blue,
• luminosity, which is calculated as 0.299*R + 0.587*G + 0.114*B.

Preview of individual channels may be helpful when editing RGB curves, planning black/white conversion using the channel mixer, evaluating image noise, etc. Luminosity preview is helpful to instantly view the image in black and white without altering development parameters, to see which channel might be clipping or for aesthetic reasons.

Preview Mask

Available options:

• Focus mask, which shows which areas are in focus (based on how sharp they appear),
• Sharpening contrast mask, which visualizes the mask which decides which areas are affected by sharpening. See Sharpening > Contrast Mask.
• Clipped shadow indication.
• Clipped highlight indication.

The clipped shadow and highlight indicators in the Editor allow you to easily see which areas of the image are too dark or too bright. Highlighted areas are shaded according to the much they transgress the thresholds.

The thresholds for these indicators are defined in Preferences > General.

The clipped shadow indicator will highlight areas where all three channels fall at or below the specified shadow threshold.

The clipped highlight indicator will highlight areas where at least one channel lies at or above the specified highlight threshold. If you want to see only where all channels are clipped, then enable the luminosity preview mode in addition to the clipped highlight indicator.

Clipping is calculated using data which depends on the state of the gamut button which you can toggle above the main preview in the Editor tab. When the gamut button is enabled the working profile is used, otherwise the gamma-corrected output profile is used.

Focus mask indicating the focusing plane

The focus mask is designed to highlight areas of the image which are in focus. Naturally, focused areas are sharper, so the sharp areas are highlighted. The focus mask is more accurate on images with a shallow depth of field, low noise and at higher zoom levels. To improve detection accuracy for noisy images, evaluate at smaller zoom, around the 10-30% range. The current implementation analyzes the preview image, which is rescaled from the original captured size down to what you see on screen. When zoomed less than 100%, the preview image is downscaled, a side-effect of which is the apparent reduction of noise. You can take advantage of this to help identify truly sharp details, rather than noise itself which may introduce a false micro texture. At the same time, downscaling compresses larger scale details into a smaller size, and it may introduce aliasing artifacts, both of which could lead to false positives. You can increase your confidence by viewing the mask at various zoom levels. It is not always fault proof, but can be helpful in many cases. Due to these caveats, be sure to double-check your images if you decide to delete them based on the focus mask.

Detail Window

The "New detail window" button , situated below the main preview next to the zoom buttons, opens a new viewport over the main preview of an adjustable size and of adjustable zoom. This lets you work on the photo zoomed-to-fit while examining several areas of interest at a 100% zoom (or even more). The benefit of using this feature is particularly important to users with slower machines, though not only them, as the zoomed-out main preview takes a shorter amount of time to update than if you were to zoom it to 100% because working at a zoom level less than 100% excludes certain slow tools, such as Noise Reduction, while the little detail windows zoomed to 100% do include all tools and are fast to update because of their small size. This allows you can use the main preview for your general exposure tweaks where it is necessary to see the whole image, and one or more detail windows to get sharpening and/or noise reduction just right.

Preview Refresh Delay

Changing any tool's parameters sends a signal for the preview image to be updated accordingly. Imagine what would happen if there was no "delay period", and you dragged, for example, the exposure compensation slider from 0.00 to +0.60. A signal would be sent to update the preview for every single change of that value - for +0.01, +0.02, ... +0.59, +0.60. Updating the preview 60 times would be completely unnecessary and actually take longer than it takes you to move the slider. This is especially true for more complicated tools, such as noise reduction, where a preview update can take even a second (depending on your CPU and preview size). The solution is for RawTherapee to wait for a very short period from the moment you stop moving a slider (you don't have to let go of it, pausing movement is enough) until the moment it sends a signal for the preview to be refreshed.

We have introduced two parameters which control the length of this waiting period:

AdjusterMinDelay

Default value = 100ms.

This is used for tools with a very fast response time, for example the exposure compensation slider.

AdjusterMaxDelay

Default value = 200ms.

This is used for tools with a slow response time, for example the CIECAM02 sliders.

You can adjust both of these values in the options file in the config folder.

The Left Panel

To the left is a panel which optionally shows the main histogram ("Preferences > General > Layout > Histogram in left panel"), and always shows the Navigator, History and Snapshots. You can hide this panel using the hide icon, or its keyboard shortcut.

Main Histogram

Histogram showing all 3 channels and luminosity.

The histogram in RawTherapee 5.7, showing a histogram of the raw data in all three modes - linear-linear, linear-log and log-log. We can see that the raw file is not clipped.

The RGB indicator shows the position in the histogram of the R, G, B and L values of the pixel your cursor is hovering over.

A histogram in photography is a graphical representation of the number of pixels of a given value. Typically the horizontal axis represents the range of possible values while the vertical axis represents the count of pixels with that value. The axes need not be linear - RawTherapee can also scale the histogram logarithmically.

Regardless of the photo's bit depth, the histogram itself has a precision of 256 sampling bins. To understand this, let us look at the example of a 16-bit image using integer precision. Its range of possible values spans from 0 to 65535 (2^16 = 65536 possible values, and since 0 is a possible minimum value then the maximum value is 65535). Drawing a histogram using 16-bit precision would mean that it would need to be 65535 pixels wide to faithfully represent the data, and no screen today is anywhere near that wide. Instead, all pixels with values from 0 to 255 (65535/256*1) are grouped into the first "bin". The second bin consists of a count of all pixels with values from 256 to 511 (65535/256*2). The third bin represents values 512 to 767 (65535/256*3). And so on until bin 256. This happens regardless of the input image's bit depth - and RawTherapee's engine uses 32-bit floating-point precision anyway.

The main histogram can simultaneously show one or more of the following:

• the red channel,
• the green channel,
• the blue channel,
• CIELab luminance,
• chromaticity.
• red, green and blue channels of the source raw image before demosaicing.

The histogram shows the channels listed above using the gamma-corrected output profile when the gamut button is disabled (default), or using the working profile when the button is enabled. The status of this button also affects the values shown in the Navigator panel, as well as the clipped shadow and highlight indicators. It does not affect the raw histogram.

Like water in a pipeline, image data flows through RawTherapee from the input file through various stages, most of which the user can control, to the output. The output could be the image saved in a file, or the image displayed on your screen. Each stage affects the color data. The histogram allows you to visualize this data at several stages. By default, the histogram shows color data as it will appear if you save the output image, including processing done at all intermediate stages. By enabling the gamut button you can peak at the data at the early stage where it gets converted into the working space. You can even look at the raw data before any transformations or demosaicing are applied.

Let's examine the large histogram example above. Though it actually shows four histograms (red, green, blue and luminance), focus on one histogram at a time. The horizontal axis represents the possible values of the histogram, where "A" are the darkest values possible, "C" the mid-tones, and "E" the brightest possible values. The position of the histogram line on the vertical axis represents how many pixels have that value. We can see that there are zero pixels in the red channel with values around "A" (from zero to very dark), because the histogram line lies right along the bottom. There is a significant number of pixels where the red channel is dark (between A and B), and a significant number where it is light (around D). Then, importantly, there is a spike at the right end of the histogram, at E - it tells us that a large number of pixels have maximal red values - they are clipped.

Generally speaking, you should care when clipping occurs on skin, and not care when it's due to specular highlights. If a histogram shows clipping, and if you care about the clipped regions, you should start by establishing where the clipping occurs. Check the raw histogram - are any channels clipped? If yes, then maybe highlight reconstruction can help. If the raw histograms are not clipped, then all the required information is intact, and it is some stage downstream in the pipeline which causes clipping. Ensure your working profile's gamut is large enough by enabling the gamut button to see histograms at the working profile stage of the pipeline. You might want to temporarily apply the Neutral profile to disable all the tools while checking, then revert. If your working space is not causing clipping (the default working space is ProPhoto and it's huge), then it's likely your adjustments which are causing clipping. Reduce exposure, go easy on the curves, use dynamic range compression if necessary.

Knowing how to read a histogram is a basic and very useful skill, as it can point out issues with your image regardless of how dim or miscalibrated your monitor may be.

To help you visualize the data, the histogram (as of RawTherapee 5.5) has three modes which scale the data in the x and y axes differently:

• Linear-linear mode. You find gridlines at halves, quarters, eighths and sixteenths, depending on the size of the histogram.
• Linear-log mode. The x-axis is linear, the y-axis and the horizontal gridlines are scaled logarithmically. The position of the gridlines still corresponds to the halves, quarters, etc.
• Log-log mode. Both the x- and y-axes are scaled logarithmically. The gridlines are not scaled logarithmically, but correspond to stops - with every gridline the value doubles, so there are lines for the values 1, 3, 7, 15, 31, 63, and 127 (pow(2.0,i) - 1)).

When there is a disproportionately bright area relative to the rest of the image, it will show up as a spike in the histogram. If you want to show this on a histogram with a linear y axis, the spike may push the lesser values down the y-axis, making them difficult to see. Switch to one of the log modes to scale the data and help you get a better overview of all values.

The histogram can be moved to the left/right panel from "Preferences > General > Layout > Histogram in left panel".

Raw Histograms

Raw files contain a dump of data captured by the sensor and quantified by the analog-to-digital converter. The raw file as a container has a bit depth of its own, typically 16-bit, while the data it contains could have a lower bit depth - typically it is 12-bit (0-4096) or 14-bit (0-16384). To display the data from a raw file as an image, one of the several key bits of information required to process the data correctly are the black and white levels. The black level is not necessarily 0, as the sensor and camera electronics produce digital noise, so the noise floor may lie for instance at 512. The white level is also not necessarily 16384; it depends on various things, and may lie for instance at 16300. For more information, see the articles Demosaicing and Adding Support for New Raw Formats (especially the header of the camconst.json file). The black and white level values used by RawTherapee are hierarchically set by looking in several places: in dcraw.c, inside the raw file's metadata, and in camconst.json (latter takes precedence). Furthermore, the user can tweak the raw black and white levels from within RawTherapee.

The raw histograms show data after black level subtraction. The right end of the histogram is anchored on the white level. The raw histograms are affected by the detected black and white levels as well as by the black and white level adjustments made by the user in RawTherapee.

When examining the raw histogram, you may also want to set the demosaicing method to "none". This will reveal the sensor pattern in the preview, and also cause the Navigator panel to show the raw RGB values of the pixel currently being hovered over. These values are affected by the detected black and white levels as well as by the black level adjustments made by the user in RawTherapee, but they are not affected by the white level adjustments ("white-point correction") made by the user in RawTherapee.

Waveform

In RawTherapee, the waveform is a special representation of the RGB channels which shows the position of the image pixels horizontally and the value of each pixel vertically. The number of pixels having the same position and value is indicated by the intensity.

In greater detail:

• each column represents a group of columns in the image. For example, if the waveform has 256 columns and the image is 5376 pixels wide, each column of the waveform represents 21 columns of the image. From left to right, the columns show the analysis of the corresponding groups of 21 columns in the image
• the analysis of the pixel values is performed on the final image, that is, taking into account the output profile
• for each column, the R, G, and B values of the pixels are placed vertically. The greater the channel value of the pixel, the higher it is placed in the column. Each channel of a pixel is placed according to its value (the three values do not have to be together)
• when several channels coincide at the same point on the waveform, their colors blend. For example, yellow points come from additive blending of the red and green channels
• the more pixels of a group that have the same channel value (therefore they all represent the same point in the waveform), the brighter or more intense the color of that channel will be. Suppose, in the previous example in a group of 21 columns of the image, there is a set of 300 pixels with a red channel value of 180 and another set of 40 pixels with a value of 57. When showing them in the waveform, the first set will have a red point brighter than the second. They will be located in the same column, but the first point will be higher and brighter than the other one. Additionally, you have a small slider to the left of the waveform to change the brightness of the points (if you do not see it, you should toggle the button to show the display options …). Increasing the brightness of the points, you will be able to better see when there are overexposed or underexposed pixels (at the top or bottom of the waveform)

Waveform of the displayed image. The shape of the wave in the padlock area is especially detailed in contrast to the right half, which corresponds to gray wood.

If you look carefully at the waveform you will see some dashed horizontal lines. They represent the position of the values 1, 3, 7, 15, 31, 63, and 127 (same as the vertical dashed lines in the histogram) and also the values 0 (although this line is obscured by the line for 1) and 255 (the uppermost dashed line). The waves never reach the lower or upper limits of the graph. This way the clipped values can be seen better.

Just like the histogram, you can independently activate or disable the three RGB channels and the luminosity, and also the bar that indicates the channel values of the image pixel currently under the mouse pointer.

In the example photo, you can see there are two distinct areas. To the left, a padlock with contrasty areas and different shades of color. To the right, we have gray wood that darkens towards the image border. Most of the waves are located in the lower part of the graph because the image has low luminosity (the average luminosity tends to a middle gray or a little darker).

In the case of the gray wood, you can see in the waveform that on the right side (corresponding with the location of the door) there is one thick descending white line. It is white because the wood has a neutral gray tone and the three channels of the pixels have similar values which create white when mixed. It is thick because there are different shades of gray (different values) in the wood texture. The line has a clear tendency to go down to the right where the wood is darker.

The peak that is on the left side comes from the padlock, with green and red channels more or less equal (generating a yellow area) and the blue channel is lower, coinciding with the brass tone of the padlock. The small cyan streak above the peak and at the top of the waveform comes from the overexposed reflection of the padlock shackle. Finally, the abrupt change in the white line at the left part of the waveform represents the large contrast between the edge of the door frame and the deep shade between the frame and door.

RGB Parade

RGB parade for the image shown. You can see the red and green peaks that correspond to the yellow padlock.

This is the same as the waveform, but with the color channels separated in to three adjacent graphs.

In this form, you can better see what happens with each channel, without the blending of colors or some channels blocking others. The disadvantage is that it is somewhat more difficult to identify a column of a channel in the corresponding area of the image because the graphs are narrower.

In the example, you can see the overexposed areas of the padlock correspond to the green and blue channels.

Vectorscopes

The vectorscopes are graphical representations of the image pixel colors. Every pixel is represented as a white point located at the position of the graph corresponding with the hue and saturation.

In the same way as with the waveform, the vectorscopes are calculated with the colors in the exported image, that is, based on the [output profile].

In RawTherapee, there are two types of vectorscopes:

• the H-S Vectorscope: shows pixel colors based on the [HSL color model]. The more saturated colors are located closer to the edges of the graph, which represent the limits of the output color space and is useful to estimate the number of pixels that are outside the color gamut, or about to go outside.
• the H-C Vectorscope: shows the colors based on the [Lch color space]. It is useful to estimate the saturation of colors as we perceive it with our eyes, that is, how “intense” or “washed-out” we perceive the colors. The closer to the edges the white points are, the more saturated the colors are.

The saturation can be understood as the amount of color there is in a hue, relative to the maximum for that hue (the “purest” hue), that is, the percentage of the pure color that the observed color has. The “average” person usually understands the “colors” as the hue with 100% saturation. In the color spaces used in the vectorscopes, these “colors” are found along the edges of their color ranges (similar to the CIExy diagram). The difference between HSL and Lch is that the latter represents the colors in a way that is closer to how we see them.

In the H-S Vectorscope the saturated colors at 100% (or almost) are located near the edges of the circle as white spots, indicating colors that are completely saturated or are already clipped. The concentric circles in the graph indicate a saturation of 25%, 50%, 75%, or 100% (in the outermost circle). This vectorscope is a good way to see how many pixels are outside (or almost outside) the color space of the output profile.

In this vectorscope you will see that there are three axes that point to the colors red, yellow, green, cyan, blue, and magenta.

In the image analysis, the saturated pixels are shown near the larger circle, between the colors yellow and red (top right).

The rest of the pixels are distributed and with different “amounts of color” (saturation), represented as white areas of a more or less intense color, depending on the number of pixels in that area.

By activating the “show out-of-gamut colors” button you will see a cyan mask that highlights the out-of-gamut pixels.

In the H-C Vectorscope the concentric circles represent the chroma values 32, 64, 96, and 128. The further towards the edges a color is located, the more saturated it is.

The chroma values are calculated with the values a* and b* from the L*a*b* coordinates that you can see in the Navigator panel using the formula:

In this example you see the more saturated colors reaching approximately the value 85. Specifically, they are the red and yellow tones.

However, keep in mind that the three-dimensional color space is not regular (they are not spheres or cubes) and therefore to correctly estimate the clipped colors you should combine more than one analysis method.

Additionally, you can see a diagonal line at the top right. This line indicates the average Caucasian skin hue. In a portrait, hovering the mouse pointer over a medium skin tone, the graph should mark the pixel around this line. Otherwise, there is a color cast on the skin that you would be interested in removing.

Navigator

The Navigator panel shows a thumbnail of the currently opened image, and RGB, HSV and Lab values of the pixel your cursor is currently hovering over.

The values shown in the main histogram and Navigator panel are either those of the working profile or of the gamma-corrected output profile, depending on the state of the gamut button located in the toolbar above the main preview. When the gamut button is enabled the working profile is used, otherwise the gamma-corrected output profile is used.

By clicking on the values in the Navigator you can cycle between these three formats:

• [0-255]
• [0-1]
• [%]

RawTherapee 5.1 onward can show the real raw photosite values. To see them, set the Navigator to use the [0-255] range, apply the Neutral processing profile, then set the Demosaicing method to "None". The Navigator will show the real raw photosite values after black level subtraction within the range of the original raw data.

History

The History panel contains a stack of entries which reflect each of your image editing actions. By clicking on the entries you can step back and forth through the different stages of your work.

An entry is added each time you adjust a different widget - multiple edits to the same widget are stored as one entry. For example, adjusting the exposure compensation slider from "0" to "0.3" and then to "0.6" will result in one entry being stored with a final value of "0.6". Likewise, when adjusting a curve, all individual control point adjustments are grouped into one history entry. Should you wish to store the adjustments as two (or more) history entries, you will have to split them by adjusting some other widget. For example, assuming a curve is in "Film-like" mode and you want to keep to that way: adjust several control points on the curve, then toggle the curve mode from "Film-like" to "Standard" and then back to "Film-like" to create a new history entry, and then continue adjusting the curve.

The history stack is not saved - it is lost as soon as you close the Editor tab. None of your adjustments are lost though, as the final state of all tools is saved in the sidecar file, ready to be used the next time you open that image.

Snapshots

Under the History panel is a panel called Snapshots. Its use is in that you can save a snapshot of the photo with all the adjustments up to that point in time, and then proceed to further modify your photo to give it a different appearance, saving new snapshots at every moment you feel you might have reached a version of your photo worth saving. Once you have two or more snapshots, you can just click on them to flip through the different versions and stick with whichever one you like best. In the future, the snapshots will be saved to the PP3 sidecar file. For now, the history and snapshots are lost when you load a new photo in the Image Editor or close RawTherapee.

The Right Panel

To the right is a panel which optionally shows the main histogram and Processing Profiles selector ("Preferences > General > Layout > Histogram in left panel"), and always shows the Toolbox. You can hide this panel using the hide icon, or its keyboard shortcut.

Processing Profile Selector

The Processing Profiles panel allows you to apply, save, load, copy and paste processing profiles, partially or in full.

Read the Sidecar Files / Processing Profiles page for more information.

Toolbox

The Toolbox, in the right panel, contains all the tools you use to tweak your photos. Each tool has its own RawPedia article.

Editor Tab Modes

RawTherapee allows you to work on photos in two modes:

• Single Editor Tab Mode (SETM), where you work only on one photo at a time, and each photo is opened in the same Editor tab. There is a horizontal panel called the Filmstrip at the top of the Editor tab showing the rest of the photos in that folder for easy access. There are Previous Image and Next Image buttons in the bottom toolbar (and keyboard shortcuts for them) to switch to the previous/next image.
• Multiple Editor Tabs Mode (METM), where each photo is opened in its own Editor tab. The Filmstrip is hidden in this mode and there are no previous/next buttons. Having multiple photos opened at the same time requires more RAM.

Try both modes and see which one suits you best. To do that, click on the Preferences icon in the bottom-left or top-right corner of the RT window, choose "General > Layout" and set Editor Layout to your preferred choice.

Use this Preferences window to select a different language for the user interface, to choose a different color theme, change the font size, etc.

It is also possible to start RawTherapee in no-File-Browser-mode (without the File Browser tab) by specifying RawTherapee to open an image from your operating system's file browser (in other words, right-click on a photo and select "Open With > RawTherapee"), or by using the image filename as an argument when starting RawTherapee from the command line (rawtherapee /path/to/some/photo.raw). This mode was introduced for people with little RAM as not having a File Browser tab means RawTherapee uses a little less memory, however in practice the amount of memory saved is little and the usability cost outweighs the little benefit, so it is likely to be removed in the future (see issue 2254).

The Filmstrip

RawTherapee-4.2 showing the Filmstrip with the toolbar visible, which takes up more screen space but lets you easily label, rate and filter the visible thumbnails.

RawTherapee-4.2 showing the Filmstrip with the toolbar hidden, which makes it less high and provides more screen space for the main preview (partially visible at the bottom).

If you use Single Editor Tab Mode ("Preferences > General > Layout") you can display a horizontal panel above the preview, this is called the Filmstrip. It contains thumbnails of all images in the currently opened album, and is synchronized with the currently opened image so that you can use keyboard shortcuts or the previous and next image buttons to open the previous/next image without needing to go back to the File Browser tab.

As of RawTherapee version 4.2.10, you can hide the Filmstrip's toolbar to save screen space. There are two ways of doing this: one way just toggles the toolbar on/off without resizing the filmstrip to the new height, and the other way does the same but also automatically resizes the filmstrip's height. Both are invoked via keyboard shortcuts only. As resizing the filmstrip's height will trigger a refresh of the image preview and this might take a while if using CPU-hungry tools like noise reduction while zoomed in at 100%, the mode that doesn't resize has been implemented for users with slow machines. Users with fast machines will find the auto-resizing mode more helpful.

Monitor Profile and Soft-Proofing

The widgets under the main preview in RawTherapee 5 allow you to apply a monitor color profile to the preview image. This enables users who have calibrated and profiled their monitors to get an instant and accurate preview of their work, whether you're staying in sRGB or working in a wide gamut. Note: OS X users are limited to sRGB and will not get an accurate preview otherwise (see discussion), while users of Linux and Windows will get a correct wide-gamut preview.

Go to Preferences > Color Management and point the "Directory containing color profiles" to the folder into which you saved your monitor and printer ICC profile. Restart RawTherapee for the changes to take effect. Now you will be able to select your monitor's color profile in the combo-box under the preview. Use the "Relative Colorimetric" rendering intent unless you have a good reason otherwise.

One can also enable soft-proofing of the preview. This will show you what your image will look like once it gets transformed by the printer profile set in Preferences > Color Management. If you want to adjust an image for printing and you have an ICC profile for your printer-paper combination you could set that as your output profile, enable "Black point compensation" in Preferences so that the blackest black in your image will match the blackest black your printer-paper combination is capable of reproducing, then enable soft-proofing. You will see what your image will look like if you print it. This allows you to make adjustments and get an instant preview of the result, saving you time and ink on test prints.

The icon with exclamation mark next to the soft-proofing button will gray out areas that cannot be reproduced by your printer, i.e. areas where you will loose details.

You should have a calibrated and profiled monitor in order for the soft-proofing preview to be accurate.

The items you see in the monitor profile combo-box (under the main preview) and in the printer profile combobox (in Preferences > Color Management) are ICC files located in a folder which you can point RawTherapee to by going to "Preferences > Color Management > Directory containing color profiles".

Batch Adjustments / Sync

RawTherapee lets you batch-adjust, or sync, the processing settings in many photos at the same time in generally two ways. It lets you copy and paste a processing profile (a collection of tool settings), in parts or in full, to any number of images. It also lets you select any number of images and adjust any tool in all of them at once (sync), and it lets you do this in two ways. Let's take a closer look.

Both ways involve making a selection of photos you want the processing profile or adjustments applied to. Selections are made using standard key combinations: Shift+click to select a range, Ctrl+click to select individual images, or Ctrl+A to select everything. Both ways are performed from the File Browser tab. The "copy & paste" method can also be done via the Filmstrip.

Copy & Paste

Copying and pasting a processing profile to a selection of images is a very common task. Assume you took a series of photos - for example studio shots, wedding portraits or focus-bracketed macro photos. All images in each series are going to be very similar; they will probably use the same lens, the same ISO, the same white balance, and end up being used for the same purpose. This means that they will all probably require the same processing settings - the same noise reduction, the same sharpening and lens distortion correction, and so forth.

To process the lot, what you would usually do is open any one image from the whole series in the Editor tab and tweak it to your liking. Once you have finished tweaking it, you will apply this image's processing profile to all other images in the same series. To do that, go to the File Browser tab, right-click on this photo and select "Processing Profile Operations > Copy", then select the images you want to apply this profile to, right-click on any one of them (it doesn't matter which) and select "Processing Profile Operations > Paste". In one quick operation you have replicated the same tool settings in the whole series of images.

Additionally, RawTherapee lets you apply only a part of the copied processing profile, for example only the "Resizing" tool. To do this, use the "Processing Profile Operations > Paste Partial" option instead of the "Paste" option.

Sync

RawTherapee lets you instantly apply tool adjustments to a selection of images. Similar functionality in other software is called "sync". This method is useful for when you don't need to see an accurate preview of your changes, for example when you only want to enable the "Resizing" tool in a selection of photos, because when working in the File Browser tab your only preview are the small and inaccurate thumbnails. This method can only be performed from the File Browser tab because you need access to that tab's batch tools (the panel on the right).

When you're in the File Browser tab, select the images you want to batch-adjust (sync), then use the tool panel on the right to make adjustments. Your tweaks can either replace the existing ones ("Set" mode), or be added to them ("Add" mode). For example if you select two photos, one of which has previously been tweaked with +1EV Exposure Compensation and one which has not, and you set Exposure Compensation to +0.6EV, then the previously-tweaked photo would end up having +1.6EV Exposure Compensation in "Add" mode and just +0.6EV in "Set" mode. The photo which was not previously tweaked would have +0.6EV in both modes. You can decide which tools should work in which mode from the Batch Processing tab in Preferences.

Saving Images

Your original raw file will never be altered by RawTherapee.

There are several ways of saving an image from the Image Editor tab:

• Save immediately from the Editor tab,
• Save via the Queue,
• Edit Current Image in External Editor (described in its own article).

Save Immediately

In the Editor tab, if you click on the little hard disk icon at the bottom-left of the preview image, or hit the ^ Ctrl + s shortcut, you can "Save immediately". This works as a standard "Save As" dialog. You can select the name and location for the output file (RawTherapee will automatically add the extension based on the chosen format), choose the output file format and bit depth, set the compression level, choose whether you want the processing profile saved alongside the output image, etc. The last option lets you choose whether you want to "Save immediately" or "Put to the head/tail of the processing queue". If you choose to "Save immediately", RawTherapee will be busy saving your photo as soon as you click "OK", so it will be less responsive to any adjustments you might try doing while it's busy saving, and it will also take longer to open other images as long as it's busy saving this one. For this reason it is recommended that you use the queue if you want to tweak other photos right away.

The Save window will by default open the location you saved to the last time you used this window. For your convenience, a shortcut to the folder containing the source image is automatically added to the bookmarks panel on the left side of the Save window. If you want to save the image to the source folder, clicking on this bookmark will save you having to manually click through to navigate to that location.

A shortcut for the OK button is ^ Ctrl + ⌅ Enter.

Put to the Head / Tail of the Processing Queue

If you click on the gears icon or in the "Save" window choose "Put to head or tail of the processing queue", your image will be kept in a queue of files to be processed, so RawTherapee can make the most of your CPU and be responsive while you tweak your photos. Once you're done tweaking and adding them to the queue, you can have RawTherapee start processing the queue while you go and enjoy some tea. The benefit of putting it to the queue using the "Save" window is that you can individually change the file format, name and destination of each image, whereas putting images to the queue without using the "Save" window will use the settings from the "Queue" tab.

Naming

If your original raw file was called photo_1000.raw, the default processed file name will be photo_1000.jpg (or .tif or .png). There is an option in the "Save current image" window: "Automatically add a suffix if the file already exists". When checked, you can make different versions of one raw, which will be saved as photo_1000.jpg, photo_1000-1.jpg, photo_1000-2.jpg, etc. The same applies when you send different versions of the same image to the Queue.

The Queue

Introduction

Saving images from RawTherapee can be done in several ways, the two most common of which are either saving the image immediately from the Editor tab, or adding it to the batch processing queue which resides in the Queue tab.

Using the "Save immediately" feature will put your CPU immediately to work, and as a result, opening and tweaking other images in the Editor will be somewhat slow while the image is being saved. The queue mechanism allows you to put edited images which are ready to be saved to a virtual queue which you can start processing at a later time. Adding them to the queue is instant, so you can continue editing other images and making the most of your CPU for editing. Once you are done editing and putting images to the queue, you can flip the large "On" switch and go off to brew yourself a coffee while RawTherapee grinds away at all the images in the queue.

The queue is persistent - you can exit RawTherapee and restart it later; the queued images will still be there. The queue can even survive a crash.

Adding Images to the Queue

There are several ways of adding an image to the queue:

1. When you are done tweaking an image in the Editor, click the "Put current image to processing queue" button .
2. Also in the Editor tab, click the "Save current image" button and select "Put to the head/tail of the processing queue".
3. Right-click on a thumbnail in the File Browser or the Filmstrip and select "Put to queue".

Regardless which method you use, when you go to the Queue tab you will see your photos lined up, ready for processing (if you had the queue set to "Auto-start", it may have finished processing before you viewed it).

Queue Settings

The "Save current image" window. Notice the "Force saving options" checkbox, which is disabled in the screenshot because neither of the "Put to the head/tail of the processing queue" options are enabled.

The Queue has several settings, such as the output file format and destination. These settings take effect in all cases except when you use the "Save current image" button , select "Put to the head/tail of the processing queue" and enable the "Force saving options" checkbox. In this case, the settings seen in the "Save" window will be used, and the ones from the Queue tab ignored. In all other cases, the settings from the Queue tab will be used.

The settings speak for themselves. Two things worth pointing out:

1. "Save processing parameters with image" will save a sidecar file alongside the output file, with the same filename as the output image but with a ".pp3" extension. This is useful when you want to save multiple copies of the same photo, each one tweaked a bit differently.
2. The destination folder can be set by selecting "Save to folder", but if you need to dynamically customize the destination folder and filename then select "Use template" instead. Hover your mouse over the Use template input box and a tooltip with an explanation will pop up:

Specify the output location based on the source photo's location, rank, trash status or position in the queue.

Using the following pathname as an example:
/home/tom/photos/2010-10-31/photo1.raw
the meaning of the formatting strings follows:
%d4 = home
%d3 = tom
%d2 = photos
%d1 = 2010-10-31
%f = photo1
%p1 = /home/tom/photos/2010-10-31/
%p2 = /home/tom/photos/
%p3 = /home/tom/
%p4 = /home/

%r will be replaced by the photo's rank. If the photo is unranked, '0' is used. If the photo is in the trash, 'x' is used.

%s1, ..., %s9 will be replaced by the photo's initial position in the queue at the time the queue is started. The number specifies the padding, e.g. %s3 results in '001'.

If you want to save the output image alongside the source image, write:
%p1/%f

If you want to save the output image in a folder named 'converted' located in the source photo's folder, write:
%p1/converted/%f

If you want to save the output image in
'/home/tom/photos/converted/2010-10-31', write:
%p2/converted/%d1/%f

Running the Queue

In the top-left corner of the Queue tab you will find an "On/Off" switch, and an "Auto-start" checkbox.

1. If "Auto-start" is enabled, processing will start as soon as an image is sent to the queue. Usually you will not want this, as this will use your CPU for processing the photos in the queue leaving very little CPU time for allowing RawTherapee to be responsive while you tweak other photos.
2. If "Auto-start" is not checked, you will have to activate the queue manually by hitting the "On/Off" switch.

You can pause the queue by hitting the "On/Off" switch - RawTherapee will first finish processing the current photo.

Clearing the Queue

You can remove a specific image from the queue by clicking the small "Cancel job" button in the corner of each thumbnail.

You can clear the whole queue right-clicking on a thumbnail and clicking "Select all" and "Cancel job", or by using the ^ Ctrl + a keyboard shortcut to select all thumbnails and then hitting the ⌦ Delete key on the keyboard. The "Edit current image in external editor" feature allows you to have RawTherapee fully process the current image and immediately open it in any external application. You can use this feature to easily send the image to an image editor such as GIMP or Photoshop for further processing, or to preview the processed image in an image viewer.

The button to send the image to an external application is located at the bottom-left of the preview panel. When the button is clicked, the image will be processed and sent to the currently selected external application. The button's icon and tooltip reflect the current external application. To select a different application, click on the drop-down arrow and select an item from the list (this list can be configured via Preferences > External Editor). Note that the last entry in the list is "Other". If this option is selected, clicking the button will open a list of installed applications. RawTherapee will then send the processed image to the chosen application.

When using this feature, RawTherapee processes your image and saves it as a gamma-encoded 16-bit integer TIFF to the temporary folder as specified in Preferences > External Editor > Output Directory.

Command-Line Options

Explanation

<Chevrons> indicate parameters you can change.

[Square brackets] mean the parameter is not mandatory.

The pipe symbol | indicates a choice of one or the other.

The dash symbol - denotes a range of possible values from one to the other.

Since RawTherapee 5.1, two executables are provided.

RawTherapee GUI

Use this application to start the version with graphical user interface.

Usage:

rawtherapee <selected dir>

Start File Browser inside folder.

rawtherapee <file>

Start Image Editor with file.

-w

Do not open the Windows console. This option is available in Windows only. If you pass parameters to the RawTherapee executable it spawns a console window so that you can see the verbose output of your processing. Normally Windows closes this console directly after RawTherapee is terminated. To let you see the output we added a prompt which waits for you to hit a key before closing the console. By specifying -w no console will be opened and therefore no key press is needed. Useful if you want to invoke rawtherapee.exe in batch, e.g. from a PowerShell script. Please note that -w will have no effect for "Debug" builds where a console window will be opened unless you're starting RawTherapee from a console window already.

-v

Print the RawTherapee version number and exit.

-R

"Remote" mode, available since RawTherapee 5.2. When opening an image using "Open with" or by passing its filename as an argument, without using the -R option RawTherapee will open in "no-File-Browser" mode - that is a mode which lacks the File Browser and Queue tabs as well as the Preferences button. Using the new -R mode, RawTherapee will open in a full-fledged instance. Using -R also allows you to open an image in an already-running instance of RawTherapee, if that instance was also started using -R. The no-File-Browser mode exists for historical reasons when RAM requirements were higher and stability was worse. Now that RawTherapee's memory usage is optimized and it can quickly and reliably open folders with thousands of images, users may prefer using the -R mode by default.

-h -?

Display these commands.

RawTherapee CLI

Use this application to start the command line only version. You'll find all command line options to develop your photos without any graphical user interface.

Usage:

rawtherapee-cli <options> -c <dir>|<files>

Convert files in batch with default parameters if no <options> specified.

-w

Do not open the Windows console. This option is available in Windows only. If you pass parameters to the RawTherapee executable it spawns a console window so that you can see the verbose output of your processing. Normally Windows closes this console directly after RawTherapee is terminated. To let you see the output we added a prompt which waits for you to hit a key before closing the console. By specifying -w no console will be opened and therefore no key press is needed. Useful if you want to invoke rawtherapee-cli.exe in batch, e.g. from a PowerShell script.

Other options used with -c:

rawtherapee-cli [-o <output>|-O <output>] [-q] [-a] [-s|-S] [-p <files>] [-d] [-j[1-100] [-js<1-3>]|[-b<8|16>] <[-t[z] | [-n]]] [-Y] [-f] -c <input>

-c <files>

Specify one or more input files or folders.

When specifying folders, RawTherapee will look for image files which comply with the selected parsed extensions (see the -a option).

The -c option must always be the last one.

-o <file>|<dir>

Select output file or folder.

Saves output file alongside input file if -o is not specified.

-O <file>|<dir>

Select output file or folder and copy PP3 file into it.

Saves output file alongside input file if -O is not specified.

-q<file>|<dir>

Quick-start mode. Does not load cached files to speedup start time.

-a<file>|<dir>

Process all supported image file types when specifying a folder, even those not currently selected in Preferences > File Browser > Parsed Extensions.

-s

Use the existing sidecar file to build the processing parameters, e.g. for photo.raw there should be a photo.raw.pp3 file in the same folder. If the sidecar file does not exist, neutral values will be used.

-S

Like -s but skip if the sidecar file does not exist.

-p <file.pp3>

Specify processing profile to be used for all conversions. You can specify as many sets of "-p <file.pp3>" options as you like, each will be built on top of the previous one, as explained below.

-d

Use the default raw or non-raw PP3 file as set in " Preferences > Image Processing > Default Processing Profile"

-j[1-100]

Specify output to be JPEG (default, if -t and -n are not set).

Optionally, specify compression 1-100 (default value: 92).

-js<1-3>

Specify the JPEG chroma subsampling parameter, where:

1 = Best compression: 2x2, 1x1, 1x1 (4:2:0)

Chroma halved vertically and horizontally.

2 = Balanced: 2x1, 1x1, 1x1 (4:2:2)

Chroma halved horizontally.

3 = Best quality: 1x1, 1x1, 1x1 (4:4:4)

No chroma subsampling.

-b<8|16>

Specify bit depth per channel (16 by default).

Only applies to TIFF and PNG output, JPEG is always 8.

-t[z]

Specify output to be TIFF (16-bit if -b8 is not set).

Uncompressed by default, or ZIP compression with 'z'.

-n

Specify output to be compressed PNG (16-bit if -b8 is not set).

Compression is hard-coded to level 6.

-Y

Overwrite output if present.

-f

Use the custom fast-export processing pipeline.

Your PP3 files can be incomplete, RawTherapee will set the values as follows:

1. A new processing profile is created using neutral values,
2. If the -d option is set, the values are overridden by those found in the default raw or non-raw processing profile,
3. If one or more -p options are set, the values are overridden by those found in these processing profiles,
4. If the -s or -S options are set, the values are finally overridden by those found in the sidecar files.

The processing profiles are processed in the order specified on the command line.

Redirect Output

To redirect RawTherapee's output to a text file, you have to start it from a console and append the redirection code as follows:

Windows (cmd.exe)

rawtherapee.exe > rtlog.txt 2>&1

Linux

rawtherapee &> rtlog.txt

Examples

Example 1

In Linux, process a single raw which resides in /tmp and is called "photo.raw", use its sidecar file "photo.raw.pp3" during conversion, save it in the same folder as "foo.tif", and overwrite the file "foo.tif" if it exists:

rawtherapee-cli -o /tmp/foo.tif -s -t -Y -c /tmp/photo.raw

Example 2

In the next example, we'll assume that you want to quickly process all your raw photos from the /tmp/jane01 folder to a web sub-folder by using the default profile as a basis, using the sidecar profile if it exist, but with removing some Exif tags (e.g. the camera's serial number) and adding some IPTC tags (e.g. your usual copyright parameters), plus resize and sharpen the image for the web (spread over multiple lines for clarity):

rawtherapee-cli -o /tmp/Jane01/web -p ~/profiles/iptc.pp3 -s -p ~/profiles/exif.pp3 -p ~/profiles/web.pp3 -t -Y -d -c /tmp/Jane01/

The processing profile will be built as follows:

1. A new profile is created using internal default values (hard-coded into RawTherapee),
2. then overridden by those from the default raw profile (-d),
3. then overridden by those found in iptc.pp3,
4. then overridden by those found in the sidecar file (-s) if it exists, so you can force some IPTC tags even if already set by iptc.pp3,
5. then overridden by those found in exif.pp3, so you can force the profile to erase some tags,
6. then overridden by those found in web.pp3, to resize and sharpen the image, and make sure that the output colorspace is sRGB.

As you can see, the position of the -s switch tells when to load the sidecar profile relative to the other -p parameters. That is not the case for the -d switch.

Example 3

In the third example, we will see how long it takes to process every raw file in a folder, assuming that each raw photo has a corresponding processing profile, and discard each output file:

time {
 for f in /home/user/photos/2011-11-11/*.raw; do
   rawtherapee-cli -o /dev/null -S -t -Y -c "$f";
 done
 }

Keyboard Shortcuts

For reference, this is the standard United States-NoAltGr QWERTY keyboard layout.

Note that some shortcuts, specifically ones that involve one or more modifier keys such as ^ Ctrl+⇧ Shift, are known to not work on some non-QWERTY keyboard layouts. This is not a fault of RawTherapee.

• SETM = Single Editor Tab Mode (required for Filmstrip panel visibility)
• METM = Multiple Editor Tabs Mode

Cross-Platform Shortcuts

Where	Shortcut	Action
Anywhere	^ Ctrl + F2	Switch to the File Browser tab.
Anywhere	^ Ctrl + F3	Switch to the Queue tab.
Anywhere	^ Ctrl + F4	Switch to the Editor tab.
Anywhere	^ Ctrl + c or ^ Ctrl + ⎀ Insert	Copy the processing profile.
Anywhere	^ Ctrl + v or ⇧ Shift + ⎀ Insert	Paste the processing profile.
Anywhere	^ Ctrl + ⇧ Shift + v	Partial-paste the processing profile. Pay attention to the processing profile fill mode!
Anywhere	^ Ctrl + f	Activates "Find" functionality, allows to search the focused widget for some text. Use it in e.g. File Browser > Folders, or in Editor > Meta > Exif. Press ⌅ Enter to execute search (comma-separated values list is supported), Press ⎋ Escape to clear the Find box.
Editor, File Browser	⎇ Alt + e	Switch to Exposure tab.
Editor, File Browser	⎇ Alt + d	Switch to Detail tab.
Editor, File Browser	⎇ Alt + c	Switch to Color tab.
Editor, File Browser	⎇ Alt + a	Switch to Advanced tab.
Editor, File Browser	⎇ Alt + t	Switch to Transform tab.
Editor, File Browser	⎇ Alt + r	Switch to Raw tab.
Editor	⎇ Alt + m	Switch to Metadata tab.
Anywhere	F11	Toggle fullscreen.
Anywhere	^ Ctrl + q	Quit.
Editor	z	Zoom to 100%.
Editor	f	Zoom to crop.
Editor	⎇ Alt + f	Zoom to fit whole image.
Editor	+ or =	Zoom in.
Editor	- or _	Zoom out.
Editor	9	Toggle background color of image preview: theme-based, black, middle grey, white.
Editor	<	Toggle clipped shadows indicator.
Editor	>	Toggle clipped highlights indicator.
Editor	⇧ Shift + b	Before/After view.
Editor	c	Crop tool.
Editor	⇧ Shift+left-click-drag	Pan the cropped area. Perform this inside the cropped area.
Editor	⇧ Shift+left-click-drag	Proportionally scale the crop when "lock ratio" is disabled, allows resizing crop by a custom ratio. Perform this on a crop corner or edge.
Editor	^ Ctrl + e	Edit current image in external editor.
Editor	^ Ctrl + s	Save current image.
Save Window	^ Ctrl + ⌅ Enter	"OK" to save.
Editor	^ Ctrl + ⇧ Shift + s	Force saving current settings to the processing profile. This happens automatically each time you close the image or RawTherapee, but you can also force it to happen immediately so you don't lose any work should the program crash.
Editor	^ Ctrl + z	Undo.
Editor	^ Ctrl + ⇧ Shift + z	Redo.
Editor	h	Hand/cross tool (standard); use this to navigate around a zoomed image or to move the frame that defines where the detail window is.
Editor	i	Toggle quick info (Exif info overlay).
Editor	Right-click in the preview area	Return to default cursor (after having used the pipette for white balance or the straightening tool). If the RGB indicator bar is enabled, this (un)freezes its indicators.
Editor	s	Select straight line (Rotate tool).
Editor	⎇ Alt + s	Add a snapshot.
Editor	w	Spot white balance pipette.
Editor	r	Toggle preview mode - red.
Editor	g	Toggle preview mode - green.
Editor	b	Toggle preview mode - blue.
Editor	v	Toggle preview mode - luminosity.
Editor	⇧ Shift + f	Toggle preview mode - focus mask.
Editor	[	Rotate open image left.
Editor	]	Rotate open image right.
Editor	-	Decrease preview size.
Editor	+	Increase preview size.
File Browser	[	Rotate selected thumbnail left.
File Browser	]	Rotate selected thumbnail right.
Filmstrip (SETM)	⎇ Alt + [	Rotate selected thumbnail left.
Filmstrip (SETM)	⎇ Alt + ]	Rotate selected thumbnail right.
Filmstrip (SETM)	⎇ Alt + -	Decrease thumbnail size.
Filmstrip (SETM)	⎇ Alt + +	Increase thumbnail size.
File Browser	-	Decrease thumbnail size.
File Browser	+	Increase thumbnail size.
File Browser	i	Toggle thumbnail information.
Filmstrip (SETM)	⎇ Alt + i	Toggle thumbnail information.
Editor (METM)	^ Ctrl + w	Close current image tab.
Editor (SETM)	F3	Navigate to the previous image relative to the thumbnail selected in the File Browser/Filmstrip.
Editor (SETM)	⇧ Shift + F3	Navigate to the previous image relative to the image open in the Editor.
Editor (SETM)	F4	Navigate to the next image relative to the thumbnail selected in the File Browser/Filmstrip.
Editor (SETM)	⇧ Shift + F4	Navigate to the next image relative to the image open in the Editor.
Filmstrip (SETM)	x	Synchronize the Filmstrip with the Editor to reveal and focus the thumbnail of the currently open image and clear active filters (rating, labels, metadata filters).
Filmstrip (SETM)	y	Synchronize the Filmstrip with the Editor to reveal and focus the thumbnail of the currently open image, but without clearing filters in File Browser/Filmstrip. (Note that the thumbnail of the open file will not be shown if filtered out).
File Browser/Filmstrip (SETM)	⎋ Esc	Resets Browse Path box to current directory. Clears Find box. Does not defocus.
File Browser/Filmstrip (SETM)	⇧ Shift + ⎋ Esc	Resets Browse Path box to current directory. Does not clear Find box. Defocuses.
File Browser/Filmstrip (SETM)	^ Ctrl + o	Sets focus to Browse Path box, selects contents. Browse Path shortcuts: Press ⌅ Enter to refresh, Press ^ Ctrl+⌅ Enter to reload.
File Browser/Filmstrip (SETM)	⇧ Shift + 1 through 5	Rank selected thumbnails with 1-5 stars:
File Browser/Filmstrip (SETM)	⇧ Shift + 0	Un-rank selected thumbnails.
File Browser/Filmstrip (SETM)	⇧ Shift + ^ Ctrl + 1 through 5	Apply a color label to the selected thumbnails: Red Yellow Green Blue Purple
File Browser/Filmstrip (SETM)	⇧ Shift + ^ Ctrl + 0	Remove color label from the selected thumbnails.
File Browser/Filmstrip (SETM)	0	Toggle filter for images without a rating. ^ Ctrl allows to apply an additive filter.
File Browser/Filmstrip (SETM)	1 through 5	Toggle filter for images with a specific rating. ^ Ctrl allows to apply an additive filter.
File Browser/Filmstrip (SETM)	6	Toggle filter for not edited images. ^ Ctrl allows to apply an additive filter.
File Browser/Filmstrip (SETM)	7	Toggle filter for edited images. ^ Ctrl allows to apply an additive filter.
File Browser/Filmstrip (SETM)	⎇ Alt + 0	Toggle filter for images without a color label. ^ Ctrl allows to apply an additive filter.
File Browser/Filmstrip (SETM)	⎇ Alt + 1 through 5	Toggle filter for images with a specific color label. ^ Ctrl allows to apply an additive filter.
File Browser/Filmstrip (SETM)	⎇ Alt + 6	Toggle filter for images that were not saved. ^ Ctrl allows to apply an additive filter.
File Browser/Filmstrip (SETM)	⎇ Alt + 7	Toggle filter for images that were saved. ^ Ctrl allows to apply an additive filter.
File Browser/Filmstrip (SETM)	d	Clear all filters: ratings, color labels, (not)edited, (not)saved, trash.
File Browser/Filmstrip (SETM)	F2	Rename file. If multiple thumbnails are selected, the rename dialog will be called for each.
File Browser/Filmstrip (SETM)	^ Ctrl + t	Show trash contents. Was just t prior version 4.2.10.
File Browser, Editor	l	Toggle left panel visibility.
File Browser, Editor	⎇ Alt + l	Toggle right panel visibility.
Filmstrip	Shit + l	Toggle Filmstrip visibility.
Filmstrip	t	Toggle the visiblity of the Filmstrip's toolbar and automatically resize the height of the filmstrip.
Filmstrip	⇧ Shift + t	Toggle the visiblity of the Filmstrip's toolbar but do not automatically resize the height of the filmstrip.
Editor (SETM)	^ Ctrl + ⇧ Shift + l	Toggle left panel and Filmstrip visibility.
Editor (SETM)	⎇ Alt + ⇧ Shift + l	Toggle right panel and Filmstrip visibility.
File Browser, Editor	^ Ctrl + ⎇ Alt + l	Toggle left and right panel visibility.
Editor	^ Ctrl + ⇧ Shift + ⎇ Alt + l	Toggle left panel, right panel and Filmstrip visibility.
File Browser, Editor	m	Toggle all panels' visibility (maximize preview area).
File Browser, Editor	^ Ctrl + b	Add current image to the Batch Queue.
File Browser	← ↑ → ↓	Navigate through displayed thumbnails.
File Browser	⇧ Shift + ← ↑ → ↓	Change the selected range of thumbnails.
Tool Panel	^ Ctrl + (Ctrl-click on slider's reset button)	The slider is reset to the value it had when the image was loaded in the Editor, or when the image was selected in the File Browser.
Tool Panel	^ Ctrl + drag a curve point	Makes the point move slower than the mouse cursor, allowing finer adjustments to the curve.
Tool Panel	⇧ Shift + drag a curve point	The point is snapped to key positions (highlighted in red).
Tool Panel	Right-click on a tool's name	Unfolds clicked section and folds all others.
Queue	^ Ctrl + s	Start/stop the queue.

Windows-Only Shortcuts

Where	Shortcut	Action
File Browser, Editor	F5	Open resulting image in the default image viewer (must have been processed before). Uses current queue settings to determine output file path.
File Browser, Editor	^ Ctrl + F5	Open Explorer in the raw's directory and select current image.
File Browser, Editor	⇧ Shift + F5	Open Explorer in the Batch Queue's output directory and selects the current image if already converted.
Editor	Right-Alt	Temporarily enables both shadow and highlight clipping indicators while the preview is being re-drawn (e.g. while adjusting exposure compensation).

Adding Support for New Raw Formats

Introduction

Supporting a raw format requires the following:

• Being able to decode the raw file, so that the program has access to the image data and metadata stored within each raw file. This is handled either by a program embedded inside RawTherapee called "dcraw", or by custom code.
• Being able to interpret the image data. This can be further broken down into:
  • Measuring the "white levels" (and sometimes the "black levels") of the decoded image data, as every camera's idea of what is the whitest white (and sometimes the blackest black) is different. White levels are measured using photos called "white frames".
  • Determining where the actual image lies on the raw canvas - the "raw crop".
  • Creating an "input profile" to accurately reproduce the colors.

You will have to shoot the photos, but you do not heave to understand or carry out the measurement - we can do that for you.

Storing and Reading This Information

RawTherapee looks for information regarding how to interpret the image data (the black and white levels, the color matrix, and some other details, but not the input profile) in three places:

• In the dcraw code which is embedded inside RawTherapee,
• In the raw file itself,
• In a text file on your system which is installed with RawTherapee called camconst.json

Information is gathered from all three places, and values from camconst.json are prioritized above those from other sources. There is an exception for the input color matrix, in that if the raw file is in the DNG format and the Software Exif tag (0x0131) does not begin with the string Adobe DNG Converter and the file does contain a ColorMatrix2 tag, then the value from this tag is prioritized.

If you made any changes to camconst.json while RawTherapee was running, restart it for the changes to take effect.

White Levels

What are black and white levels? A sensor is made of millions of tiny photo-sensitive elements called photosites or sensels. Each one measures the intensity of the light which falls upon it, and records that intensity as a number - the more light, the higher the number. The bulk of the raw file consists of these recorded measurements. Each photosite has a level below which it cannot sense any light - there might be some light falling upon it, but this light is too weak to register a signal. This is called the black level, and it is not always 0. There is also a level beyond which the photosite will not register a change in light intensity even if the light does keep getting brighter - this is the white level. A photosite which cannot record any brighter light is said to be fully saturated, and in post-processing this state is called clipping.

The white levels are measured based on completely overexposed photos called "white frames".

Some camera models use the same white and black levels regardless of other settings, while for other models these levels depend on other factors, such as ISO sensitivity. We need photos from across the whole range of ISO values to determine this.

Some cameras have built-in noise reduction, often called LENR - Long Exposure Noise Reduction. It could affect the white and black levels. If you enable it, typically it only kicks-in when the exposure time is over 1s. The steps explained further on will explain when to turn it on and off.

The white levels for some camera models change depending on the aperture, but generally this only happens for wide-open apertures. To avoid this being a problem, set the aperture to f/5.6 or higher unless instructed otherwise.

For more documentation detailing the required photos and instructions how to measure them, read the comments inside the camconst.json file: https://github.com/Beep6581/RawTherapee/blob/dev/rtengine/camconst.json

How to Shoot White Frames

Shoot raw photos in manual (M) mode. If your camera has several raw modes, use the full one, uncropped, lossless compression if possible.

Each photo must be completely overexposed all across the frame. As such, it does not matter what you shoot since everything will be white anyway, but its easiest to achieve this while pointing the camera at the sky or at a white light bulb. It does not matter whether the sky is sunny or overcast, but don't point it at the sun as you might damage the sensor.

It does not matter what lens you use, but it will be easier to make the whole image overexposed if you do not use a wide angle lens.

Needed Photo Sets

We have broken down the image requirements into three sets, where each subsequent set would improve the quality of support, but would also require more effort from you and from us. In most cases, you only need to photograph the first two sets. All sets involve photographing completely overexposed white frames.

The sets:

1. If your camera has LENR, turn it OFF. Set the aperture to f/5.6 or higher. Take a series of photos, one photo for every ISO value your camera supports, making sure not to exceed an exposure time of 1 second. As an example, you could end up with about 8 photos for ISO 100, 200, 400, 800, 1600, 3200, 6400 and 12800. Most cameras include intermediate ISO values, e.g. ISO160 or ISO320, so if you wanted to improve white level accuracy you would need to photograph these intermediate values as well.
2. If your camera has LENR, turn it ON. Take a second series of photos, as described above but this time making sure that the exposure time in all cases is at least 2 seconds, not less. That's another 8 or more photos. In most cases these two sets should be enough.
3. Some cameras scale raw values for larger apertures, particularly Canon and Nikon models. The only way to know whether your camera does this for sure is to take a photo and measure it. Take one photo as described above but using your lens's widest aperture, e.g. f/1.7, at ISO100 with LENR turned OFF, and send it to us along with the rest of the shots. If we detect that there is raw scaling (or if you detect it yourself if you do your own measurements) then we will ask you shoot a series of photos using an exposure time of less than 1 second, from the widest aperture your lens supports down every 1/3 of a stop until such an aperture where raw scaling is no longer performed. This could mean many photos. Handling raw scaling caused by large apertures is not very important so don't feel daunted by it, you don't need to do it even if your camera does do raw scaling, but if you have the time and bandwidth then it would be better to check for it.

At the very least, you should end up with a series of about 8 photos from point 1. It is recommended that you take photos for both points 1 and 2, leading to 16 or more photos, plus the one raw scaling test photo from point 3. If it is found that your camera performs raw scaling, you could additionally take the needed series described in point 3, but since this could potentially mean many photos (over 50) it is not expected.

Compress all these photos, upload them to filebin.net and send us the full link either through our GitHub page or in the Forum.

Completely clipped photos can have amazing compression, don't forget to compress them (7-Zip, ZIP, bzip2, whatever) before uploading! As an example, 10 completely clipped Sony 7M2 raw files with LENR disabled weigh 234MB but if you ZIP them you get a 1MB file.

Renaming

In order to simplify working with these white frame images, the filenames should segregate the photos by LENR, aperture and ISO. ExifTool can rename them automatically:

exiftool '-FileName<${make}_${model}_${LongExposureNoiseReduction}_${aperture}_${iso}%-c.%le' dir

Raw Crop

The raw crop can be determined from any photograph, no extra photos are needed.

Input Profile

An input profile is required in order to reproduce colors accurately. One is needed per camera model. Read the "How to Create DCP Color Profiles" article to learn about the types of input profiles and how to shoot photos of a color target so that we may create an input profile for your camera model.

File Paths

RawTherapee makes use of a "cache" folder to store temporary files which are safe to delete, and a "config" folder which stores your RawTherapee settings, custom processing profiles and other user-editable files. These folders reside in a special place, described below, and have a name that begins with the word "RawTherapee" optionally followed by a suffix. This suffix is set by the person who made the build of RawTherapee you're using. Some examples of what it can look like:

• RawTherapee
• RawTherapee4.2
• RawTherapee5
• RawTherapee5-dev
• RawTherapee_test
• And other possibilities always beginning with "RawTherapee"

The first part, "RawTherapee", is hard-coded. The second part, the suffix, is up to the person who made the build. It might be specific, like "5.0-gtk2-123-g87654321", it could be general, like "5", it could be anything else, like "_test", or it could be not set. We recommend that RawTherapee stable releases not use a suffix at all, while all development versions use "5-dev" - hopefully the person who made the build you're using took this into account.

Config

The RawTherapee config folder contains:

• the "options" file, which contains all of your settings from Preferences,
• the "batch" folder, which stores temporary processing profiles of the photos you sent to the Queue,
• the user-editable camconst.json file, where you can define details of how a specific raw format is to be treated (this overrides the values from the system camconst.json file),
• the dynamic profile rules,
• and the "profiles" folder where you can save your custom processing profiles to if you want them to appear in RawTherapee's drop-down list.

You could include this folder in your backups so that you can regain all of your settings and custom processing profiles if you install RawTherapee on a new system.

Default locations for the RawTherapee config folder (look for the "RawTherapee*" prefix as described above):

Windows XP

%USERPROFILE%\Local Settings\Application Data\

Windows 7, 8 and 10

%LOCALAPPDATA%

Linux

~/.config/

macOS

~/Library/Containers/RawTherapee/Data/Library/Application Support/RawTherapee/config/

Under the Finder's 'Go' menu click 'Go to Folder' (shortcut Command+Shift+g), you can then type/paste any path you want to navigate to, even if it's hidden.

Cache

The RawTherapee cache folder contains sets of cached items, where each set consists of:

• a thumbnail,
• metadata,
• a sidecar file,
• and optionally an embedded profile.

By default, RawTherapee keeps up to 20 000 cached sets. Keep an eye on the "cache" folder as over time it may grow considerably in size! This is mostly due to the cached thumbnails which are stored in the "images" sub-folder. Deleting the "images" sub-folder is safe, you will not lose any image settings, RawTherapee will just have to regenerate the thumbnails.

Default locations for the RawTherapee cache folder (look for the "RawTherapee*" prefix as described above):

Windows XP

%USERPROFILE%\Local Settings\Application Data\

Windows 7, 8 and 10

%LOCALAPPDATA%

Linux

~/.cache/

macOS

~/Library/Containers/RawTherapee/Data/Library/Application Support/RawTherapee/cache/

Under the Finder's 'Go' menu click 'Go to Folder' (shortcut Command+Shift+g), you can then type/paste any path you want to navigate to, even if it's hidden.

A cached set used to include a 32kB histogram file, but as of RawTherapee 5.5 the need for storing the histogram was eliminated.

Custom config and cache folders

You can have RawTherapee use a custom config folder by setting the RT_SETTINGS environment variable to an absolute path which you have read and write access to, and likewise you can use a custom cache folder by setting the RT_CACHE environment variable. How you do that depends on your operating system, so just search on the internet for "how to set environment variables in <your operating system>".

Some examples:

Windows

Variable name: RT_SETTINGS, value: %LOCALAPPDATA%\rawtherapee\5.7

Variable name: RT_CACHE, value: Z:\rawtherapee\cache

Linux and macOS

RT_SETTINGS=/home/bob/.config/rawtherapee/5.7

RT_CACHE=/home/bob/junk/rtcache

Processing Profiles

If you create your own processing profiles, to have them appear in RawTherapee's "Processing Profiles" list you should save them to the "profiles" folder which you will find inside the "config" folder as described above.

Temporary Folder

The "Edit Current Image in External Editor" tool stores intermediate image files in the folder specified in Preferences > External Editor > Output Directory. By default this is the operating system's default temp folder. RawTherapee will use a subdirectory with the name format rawtherapee-<username>, e.g. rawtherapee-Lawrence37, and permissions are set to user-only read/write access. If this subdirectory already exists but has the wrong permissions, a new directory will be created with the correct permissions and with the name format rawtherapee-<username>-xxxxxx where xxxxxx is a random sequence of 6 characters, e.g. rawtherapee-Lawrence37-abc123.

Windows

The operating system's default temp folder is the one stored in the $TEMP environment variable, which is usually %LOCALAPPDATA%/Temp

If you do not have the $TEMP environment variable set, C:\ is used.

Linux and macOS

The operating system's default temp folder is the one stored in the $TMPDIR environment variable, which is usually /tmp

If you do not have the $TMPDIR environment variable set, /tmp is used.

Preferences

You can access the Preferences window by clicking on the Preferences button which is either in the bottom-left corner of the RawTherapee window, or the top-right one, depending on your Editor tab mode layout.

About

The About button opens a window which contains a splash screen, technical details of the specific RawTherapee build you're running, credits, licence and release notes.

Please include these technical details when filing a bug report.

General Tab

Layout

• Editor Layout

The layout of RawTherapee's user interface can be adapted to suite your taste and needs, specifically pertaining to whether you would like to have more than one raw file open simultaneously, and whether you use one monitor or more. The following modes are available:

• Single Editor Tab Mode
• Single Editor Tab Mode, Vertical Tabs
• Multiple Editor Tabs Mode
• Multiple Editor Tabs Mode (if available on second monitor)

Remember that if you simultaneously open several images each in its own Editor tab, each tab and instance will require a significant amount of RAM. Only use multiple Editor tabs if you have quite a lot of RAM - exactly how much depends on what resolution your images are, which tools you use, how many other programs you run in the background, and so forth, however a rule of thumb could be to not use multiple Editor tabs unless you have more than 8GB of RAM.

A restart is required for these changes to take effect.

• Position of Curve Copy & Paste Buttons

Curves include adjacent buttons for copying, pasting, opening and saving the curve, and some include buttons for placing a node on the curve by picking a sample from the preview and for setting numeric in/out values. This option lets you decide where these buttons will be positioned relative to the curve widget.

A restart is required for these changes to take effect.

• Histogram in Left Panel

Position the main histogram in the left panel above "History", or in the right tool panel above the tools.

• Show Filmstrip Toolbar

The filter and ratings toolbar (4) can be shown in the Filmstrip.

The Filmstrip is a narrow panel which you can toggle to appear within the Editor tab. It contains thumbnails of the images in the currently opened folder, along with the filter and ratings toolbar. It can be useful to see the Filmstrip while working in the Editor tab, but you can hide it if you need the extra vertical screen space. Use this option to show or hide it. Note that you can also toggle its visibility from the Editor tab by using the "Toggle the visiblity of the Filmstrip's toolbar" keyboard shortcut.

• Compact Toolbars in File Browser

Disabled, great for low-resolution screens.

Enabled, requires that the screen has a high enough resolution to fit all the elements horizontally.

Enable this option if you have a high resolution screen to merge all the toolbars at the top of the File Browser tab into one.

If your screen's resolution is too low to fit the whole toolbar, some of the toolbar's contents (buttons, drop-downs, etc.) may become hidden. To see them, simply hover the cursor over the toolbar and use the mouse scroll-wheel to scroll the contents left and right.

• Hide Vertical Scrollbar

You can hide the vertical scrollbar from the toolbox to save a little horizontal screen space. Use the mouse scroll-wheel to scroll when the scrollbar is hidden.

• Tool Collapsed/Expanded State

If you have a few favorite tools which you would like to always see expanded, you can expand them now, hide the others, then return here to Preferences, disable "Automatically save tools' collapsed/expanded state before exiting", click "Save tools' collapsed/expanded state now", and click "OK" to close the Preferences window and commit your changes.

Alternatively, if you would instead like RawTherapee to remember which tools are collapsed and which are expanded at the end of every editing session, then enable "Automatically save tools' collapsed/expanded state before exiting".

Language

Select a language for the user interface. "Use system language" will try to auto-detect your language based on environment variables. You can override the auto-detected language by selecting one manually.

If you would like to help by updating one of the translations or creating a new one, see this post:

https://discuss.pixls.us/t/localization-how-to-translate-rawtherapee-and-rawpedia/2594

A restart is required for these changes to take effect.

Appearance

The Image Editor tab showing: (1) the preview background, (2) the crop mask, (3) lockable color pickers and (4) buttons which toggle the color of the preview background between black, white and theme-based.

• Theme

Choose a theme for the user interface. Although you will see theme-related changes as soon as you hit the "OK" button, you need to restart for the changes to take affect correctly.

The way human vision perceives colors depends on various factors, of particular importance to this paragraph are the properties of the area which surround the observed region. The way you perceive the colors of a photograph viewed on a screen depends in part on the colors of the area surrounding the photograph. You can read more about this in the CIECAM02 article. In order to mitigate the errors the user makes while adjusting a photo, RawTherapee ships themes which use neutral background colors. While all of the themes are based on shades of grey, the theme which is most suited to avoid affecting human perception is "TooWaGrey - Average Surround", available from version 5.2 onward.

• Main font, and color picker font

Choose a custom main font, and a font for the Lockable Color Picker in the Image Editor tab, marked "3" in the screenshot.

Some users will find the default font size too small or too large due to their screen resolution and DPI setting. You can fix that by changing the font size.

• Crop mask color

Adjust the color and transparency of the area outside of a cropped region, marked "2" in the screenshot. By clicking on the colored button, a new window appears where you can select a standard color or click on "Custom" to specify a new color. The vertical axis adjusts hue, while the horizontal axis adjusts transparency. Partial transparency is useful as it allows the cropped-off part of the photo to remain somewhat visible (2), so that you can move the crop around to find the best composition (hold the Shift key and move the crop with the mouse).

The Image Editor tab showing: (1) the Navigator panel, (2) the Navigator guide which marks the area currently visible in the main preview when zoomed-in.

• Navigator guide color

Adjust the color and transparency of the frame (marked "2" in the second screenshot) visible in the Navigator panel (marked "1") when the main preview is zoomed-in.

Normal interface and HiDPI scaled interface.

• Pseudo-HiDPI mode

Scales the user interface so that text and images remain sharp even on a HiDPI screen. Introduced in RawTherapee 5.6. Scaling in RawTherapee depends on font size, DPI and display scaling. While scaling has been tested to work well in Windows, Linux and macOS, there are some macOS display modes which are incompatible with it, specifically those modes suffixed by "(HiDPI)" in macOS Display settings. Some versions of macOS (10.14.*) seem to not list any modes, in which case the user must just give it a try.

Clipping Indication

The clipped shadow and highlight indicators in the Editor allow you to easily see which areas of the image are too dark or too bright. Highlighted areas are shaded according to the much they transgress the thresholds.

The thresholds for these indicators are defined in Preferences > General.

The clipped shadow indicator will highlight areas where all three channels fall at or below the specified shadow threshold.

The clipped highlight indicator will highlight areas where at least one channel lies at or above the specified highlight threshold. If you want to see only where all channels are clipped, then enable the luminosity preview mode in addition to the clipped highlight indicator.

Clipping is calculated using data which depends on the state of the gamut button which you can toggle above the main preview in the Editor tab. When the gamut button is enabled the working profile is used, otherwise the gamma-corrected output profile is used.

Pan Rate Amplification

Imagine you are viewing a high resolution images while zoomed-in to 100%. In order to pan the image around the screen you would have to make multiple mouse movements (or have a very large mouse pad). RawTherapee saves you from this by using "pan rate amplification" - when set to 5, RawTherapee multiplies every pixel you pan by 5. If you'd normally move the cursor 500 pixels in one comfortable mouse movement, you will have panned 2500 pixels with this option set to 5.

The effect is most visible when you are zoomed in, and least visible when zoomed out.

When "Remember zoom % and pan offset" is enabled, when you open the next image RawTherapee will try to show the same area at the same zoom level as the current image. This only works in "Single Editor Tab Mode" and when "Demosaicing method used for the preview at <100% zoom" is set to "As in PP3".

External Editor

Ability to specify multiple external editors was added in RawTherapee 5.10.

RawTherapee can send the processed image directly to an external program, e.g. an image editor, an image viewer or a script. This is done using the "Edit Current Image in External Editor" button in the Editor tab under the main preview - see the Saving article. It is here in Preferences where you can customize which program the processed image is to be sent to when you click the button.

To get started, click the plus button. This will add a new entry to the list. Then, click Change Application or Change Executable to select the external editor. The Change Application button opens a list of installed applications to choose from, while the Change Executable button opens an executable file selector. Multiple external editors can be added this way. To remove an editor, select the entry in the list and click the minus button.

The external editor names and commands can be edited directly by double clicking the text. You must confirm the edit by hitting enter, else your edit will be discarded.

Processed images are stored in the location specified by "Output directory", and are not deleted when RawTherapee is closed. However, the default location is the operating system's temp directory which is typically lost when the operating system shuts down.

Suggestions for external editor commands:

• geeqie --remote will open images in a single Geeqie window, preventing clutter caused by multiple Geeqie windows.
• macOS users may use the "open" command, open -a "External Program", for example open -a "/My stuff/Programs/Turbo Pixels". We have reports that it is not necessary to write the full path to the program even if it does not reside in the standard /Applications/ folder.

Image Processing Tab

Default Processing Profile

Specify which profile RawTherapee is to use when opening a raw or non-raw photo.

• The default processing profile for raw photos as of RawTherapee 5.4 is "Auto-Matched Curve - ISO Low".
• The default processing profile for non-raw photos (such as JPEG, TIFF or PNG) is "Neutral". The "Neutral" profile just loads the photo as it is, without applying any changes.

To have processing profiles you have made yourself appear in the list, save them to the "profiles" sub-folder within the "config" folder. You can find out where it is on the file paths page.

The special entry "Dynamic" activates the support for Dynamic Processing Profiles.

When you right-click on a thumbnail and select "Processing profile operations > Reset to default" RawTherapee will apply whichever processing profile is selected as default for that image type. If the default is set to "Dynamic", then RawTherapee will run through the dynamic profile rules to generate a profile dynamically.

Custom Processing Profile Builder

Executable (or script) file called when a new initial processing profile should be generated for an image. The path of the communication file (*.ini style, a.k.a. "Keyfile") is added as a command line parameter. It contains various parameters required for the executable or script to allow a rules-based processing profile generation.

This feature is very powerful; for example it allows you to set lens correction parameters or noise reduction based on image properties. It is called just once on the first edit of the picture, or called manually from the context menu when right-clicking on a thumbnail in the File Browser or Filmstrip

Note: You are responsible for using double quotes where necessary if you're using paths containing spaces.

Processing Profile Handling

• Processing profile saving location

  Choose whether you want RawTherapee to store the processing profiles next to the input file (the default behavior), to a central cache, or both.

  It is a good idea to save the processing profiles next to the input files, as that lets you easily backup and handle your photos and their associated processing profiles.

• Processing profile loading location

  RawTherapee will look for processing profiles alongside the images, and in the central cache. If a profile exists in both places and they are not identical, this setting allows you to choose which one should have the deciding say.

Directories

Specify the location of your Dark-Frame, Flat-Field and HaldCLUT Film Simulation folders.

Crop Editing

This section lets you decide which guides are shown when the crop is _not_ being manipulated. "Original" means the guide type currently selected, so for example if you would like to see the "Rule of Thirds" guide while dragging a crop, and to have the guide automatically disappear once you are done dragging the crop, then set this option to "Frame" or "None".

Once a crop is in place, RawTherapee can automatically zoom the cropped area to fit the screen if you enable this option.

Favorites Tab

This tab allows you to choose which tools appear in the Favorites tab of the editor toolbox.

Available Tools

Checkboxes indicate which tools and sub-tools are in the Favorites tab. Only tools that can be marked as a favorite will have a checkbox. Toggling a checkbox adds or removes the corresponding tool to/from the Favorites tab.

Favorites Panel

Favorite tools are listed here in the same order as they will appear in the Favorites tab. Selecting a tool from the list and clicking the up or down button located to the left of the list moves the tool up or down the list. It is also possible to rearrange tools by dragging them. Tools can be removed from favorites by selecting them and clicking the remove button. Use the Ctrl key to select multiple tools or the Shift key to perform a range selection.

Options

• Keep favorite tools in original locations: If set, favorite tools will appear in both the favorites tab and their original tabs. Enabling this option may result in a slight delay when switching tabs.

Dynamic Profile Rules Tab

Here you can define your custom rules for creating Dynamic Processing Profiles.

File Browser Tab

Image Directory at Startup

At the top you can define the image directory to use at startup. It could be the RawTherapee installation directory, the last-visited directory, the home directory, or a custom directory.

File Browser / Thumbnail Options

These options determine which information is visible in the thumbnails and how it should be displayed.

Context Menu Options

Adjust the grouping of the right-click context menu in the File Browser (and Filmstrip).

Parsed Extensions

Choose which files are recognized as images and displayed in the File Browser. All supported extensions are set by default, except for PNG which is disabled by default.

If a desired extension is missing you can easily add it by clicking the "Add" button.

Some users reported that their Parsed Extensions panel is empty. This could happen after updating from an unspecified older version of RawTherapee. If your parsed extensions panel is empty, we recommend you close RawTherapee, then find and delete the "options" file. The next time you run RawTherapee you will be using the latest defaults, and your list of parsed extensions will contain all supported formats.

Cache Options

To understand this section, first read the Cache article. The typical user should not need to change these defaults.

The maximum thumbnail height decides how large you can make the thumbnails. Each thumbnail is stored in RawTherapee's cache folder and requires disk space, so keep this in mind if you increase the default size.

The maximum number of cache entries decides how many of these cached files are kept before the oldest ones are deleted once the limit is reached.

You can manually clear elements of the cache using the "Clear" buttons.

You could "clear all cached files except for cached processing profiles" when updating RawTherapee to keep your disk clean and benefit from new cache-related improvements.

Color Management Tab

Use the "Directory containing color profiles" button to point RawTherapee to the folder which contains color profiles.

Standard locations where color profiles are stored:

Windows

C:\Windows\system32\spool\drivers\color

Linux

/usr/share/color/icc/

macOS

/library/ColorSync/Profiles/Displays/

Monitor

Set the "Default color profile" to the ICC file you generated when calibrating and profiling your monitor. You can have RawTherapee try to auto-detect the profile by using the "Use operating system's main monitor color profile" option.

• In Linux, the _ICC_PROFILE X11 atom is used to automatically find the monitor's ICC profile. Since there is only one such atom, and it is used by the "main" monitor, automatic detection is also limited to the main monitor, though you can copy multiple ICC profiles into the standard location and then you will be able to manually select them under the preview in the Editor.
  One very simple way of "installing" a monitor profile in Linux so that the atom gets set correctly is using DisplayCAL, via the menu "File > Install profile".
  To see if the X11 atom is set, run this in a console:

  xprop -len 8 -root _ICC_PROFILE

  If the result is "_ICC_PROFILE: no such atom on any window", then the atom is not set. If the result is a bunch of numbers, then it is set.
• In Windows, right-click an ICC (or ICM, they're identical) file and select "Install profile" in the context menu, or search for "colour management" in the Start menu.
• In macOS, monitor profiles on an application level are not supported. All displayed colors will be in the sRGB space, and then, if necessary, converted by the native macOS color pipeline to match the screen calibration, if any. This means that you cannot choose a monitor color profile in macOS. If you have a wide-gamut screen, RawTherapee's displayed colors will still be limited to sRGB. This will however not affect output, i.e. you can still produce images with colors outside the sRGB space. For more information, see: https://discuss.pixls.us/t/wide-gamut-preview-in-macos/2481

Rendering intents and black point compensation are explained below.

The monitor profile must be of the "device" class in the RGB colorspace.

Printer (Soft-Proofing)

You can select here the color profile of your own printer or your print service in order to simulate the rendering of the printed image.

The printer profile must be of the "output" class in either the RGB or CMYK colorspaces.

See below for Black Point Compensation.

Rendering Intents

The "Rendering intent" drop-down lets you choose how the ICC profiles are used for translation between gamuts or color spaces. When in the "Monitor" section, the "source" is the color space within which lies the image data at the end of the pipeline before being put into the monitor profile's color space, and the "destination" is the selected monitor profile's color space. When in the "Printer (Soft-Proofing)" section, the "source" is the image data at the end of the pipeline, and the "destination" is the selected printer profile's color space.

Relative Colorimetric

Colors from the source which lie outside the gamut of the destination color space will be shown using the nearest in-gamut color without affecting other in-gamut colors. The white point will be corrected. This is the default option and works with all profiles.

Perceptual

Colors from the source which lies outside the gamut of the destination color space will be compressed into the destination's gamut at the expense of also affecting in-gamut colors. How the compression is performed is up to the gamut mapping contained within the color profile - it usually involves desaturation, and sometimes even hue shifts. The perceptual intent only works with LUT profiles which contain the required gamut mapping tables - most ICC profiles do not, and in those cases "relative colorimetric" will be silently used instead (this is standard behavior across most software).

Absolute Colorimetric

Similar to relative colorimetric, but the white point will not be corrected. For this reason, it is used when you want to match paper whiteness to screen. You might want to use it when proofing, but not otherwise.

Black Point Compensation

When enabled, the Black Point level of the input image is moved to the Black Point level of the output image in a color transformation (e.g. from working profile to display profile). It means that the luminance channel alone is compressed or expanded to match the output capabilities. This feature will keep details in the shadows (avoid flat dark areas) at the expense of less color correctness.

Batch Edit Tab

Batch editing is making adjustments to more than one image at the same time. This is done through the Batch Edit tab in the File Browser.

The tool panel in the Batch Edit tab looks similar to the tool panel from the Image Editor tab, but it uses checkboxes to communicate which tool settings are consistent across the selected images and which are not. These checkboxes have three states:
[ ] Disabled
[✓] Enabled
[-] Values differ across selected images.

Batch editing is done by selecting multiple images in the File Browser (hold the ⇧ Shift or ^ Ctrl key, then click the images you want to select), then you can edit those images using the tools in the Batch Edit panel on the right.

The controls (sliders, spinboxes, etc.) in the Batch Edit panel show the values of the processing parameters for the selected images. These can be the values of the default processing profile or the values from your last edit session of those photos.

If an image is currently being edited in the Editor, the editor's values will be reflected in real time in the Batch Edit panel, and vice versa, so take care what you're doing.

What happens to the tool values as you manipulate them depends on the "Behavior" setting in this Batch Edit tab.

The "Add" Mode

This mode may also be understood as "relative". Modifying sliders which are set to the "Add" mode will result in the value of the modification being added to the existing value. For example, if you select two images by holding the Ctrl modifier key, one image which has an Exposure#Exposure_Compensation Exposure Compensation of -0.5 EV and the other which has +1.0 EV, moving the "Exposure Compensation" slider up to +0.3 will result in setting a value of -0.2 EV for the first image and +1.3 EV for the second one.

Using the "Reset" button will move the slider to its default (zero) position and will then bring back the initial value of that slider for each selected image.

The "Set" Mode

This mode may also be understood as "absolute". Modifying sliders which are set to the "Set" mode will result in the value of the modification being set, irrelevant of what the existing value was. If we use the same example as before, moving the slider up to +0.3 EV will result in setting a value of +0.3 EV for both images (one value for all images).

Using the 'Reset' button will move the slider to its default position (different for each slider), and will then reset this parameter for each image.

Performance Tab

The "Performance" tab is only for people who know what they're doing. It lets you poke under the hood and tweak some parameters depend on available RAM and CPU speed.

Preview Demosaicing Method

The "Demosaicing method used for the preview at <100% zoom" option sets which demosaicing method is used for the main preview in the Editor. By default, the same demosaicing method is used as specified in the Demosaicing section of the Raw tab, but if you are on a a very slow computer you can save a few hundred milliseconds by using the "Fast" demosaicing method. The trade-off is that the "Fast" method has the worst quality, though in most cases the difference is slight.

TIFF Read Settings

"Serialize read of TIFF files", enabled by default, can speed up thumbnail generation when opening for the first time a folder full of uncompressed TIFF files.

HaldCLUT Cache

The "Maximum number of cached CLUTs" setting lets you specify how many last-used HaldCLUT (Film Simulation) images are stored in RAM for faster access when switching back and forth between them in the Editor.

Inspect

Most raw files contain an embedded JPEG preview image. To show that image in the Inspect tab it needs to be extracted, which takes a fraction of a second. The "Maximum number of cached images" setting lets you specify how many of the last-viewed embedded images are kept in RAM, so that if you view the previous image in the Inspect tab, RawTherapee will not need to re-extract it, but just access it from RAM.

The "Image to show" option lets you decide whether to use the embedded JPEG image or to render one based on the real raw data using the "Neutral" processing profile. Using the embedded image is faster than rendering from the real raw data.

Threads

Splitting calculations and running them as concurrent threads allows them to complete faster, however doing so requires more RAM. By default, RawTherapee decides automatically how many threads to use. You can override this value here.

Most modern CPUs run two threads per physical core. Find out what CPU you have and how many cores it has, multiply that number by two, and you get the maximum number of threads it would make sense to run simultaneously. Let's call this number T_max. You would not benefit from running more threads than this - in fact you would likely suffer a small speed penalty.

Setting this parameter to "0" will let your CPU figure out what T_max is, and use that. If you experience crashes due to insufficient RAM, then you can calculate T_max yourself and use a number lower than that.

Sounds Tab

The "Sounds" tab lets you set an audible notification when a lengthy operation ends. It is currently only supported on Windows and Linux.

The "Queue processing done" sound is played after the last Queue image finishes processing. The "Editor processing done" sound is played after a lengthy in-editor operation that took longer than the specified number of seconds is complete.

Sounds can be muted either by disabling the "Enabled" checkbox or by setting fields with sound file references to blank values.

The "Queue" and "Editor processing done" text boxes can either point to wave (.wav) files, or can specify one of the following values:

Windows

• SystemAsterisk
• SystemDefault
• SystemExclamation
• SystemExit
• SystemHand
• SystemQuestion
• SystemStart
• SystemWelcome

Linux

• bell
• camera-shutter
• complete
• dialog-warning
• dialog-information
• message
• service-login
• service-logout
• suspend-error
• trash-empty
• possibly the name of any file in /usr/share/sounds/freedesktop/stereo/ without the path or extension.

RawTherapee relies on libcanberra to produce sounds. In case of issues in Linux, you can trigger a sound to play from a terminal by invoking the following command (replace "bell" with any of the above):

canberra-gtk-play -i bell

Negative

GIMP Plugin

You can open raw images in GIMP using RawTherapee as a plugin.

Requirements

• RawTherapee 5.3
• GIMP 2.9.6
• The RawTherapee executable must be found from the $PATH environment variable. This will be the case if you installed RawTherapee system-wide.

Usage

Just open a raw file from GIMP. A RawTherapee editor window should open automatically, which you can use to tweak your raw file. When you close the window, the image gets imported into GIMP.