Lens/Geometry

Lens/Geometry

To keep the preview fast, RawTherapee uses the preview image of the current zoom level when applying these transformations. Because of this, the preview image can become soft. Lets assume you are editing a Nikon D700 image: 4256×2832px (that's 12.1 megapixels), and the preview image's size is 600x400px. Rotating it 5° will not be the same as rotating the full 12.1Mp image and then scaling it down to 600x400px. The former will be softer than the latter, though rotating the former will take less time than rotating the latter, which is why RawTherapee does that. But don't worry, when saving the image RawTherapee uses the full resolution image, so it will be sharp. If you zoom the preview in, then RawTherapee will use this higher resolution preview image when calculating the transformation, so to see what the saved file will look like, just zoom in to 100% Magnifier-1to1.png.

1 Introduction

This tool comprises of several sub-tools which share common adjustment parameters. They allow you to fix errors and distortions which derive from imperfections in your camera gear, such as lens distortion and vignetting, as well as to improve issues deriving from the placement and adjustment of your camera, such as an uneven horizon or perspective distortion.

1.1 Lens Hood

Do not confuse vignetting with a blurry lens hood being visible in the corners of your image. Some cameras, typically small ones - compacts, bridge-type and even mirrorless - will capture parts of the lens hood or lens mechanism in the corners of the frame. Typically the same cameras have lenses which suffer from strong distortion. The way these cameras deal with these two problems is by correcting the distortion, as a result of which the corners of the image get "pushed out" beyond the frame, thereby hiding the corners darkened by the lens or lens hood. When you view a JPEG image from these cameras the distortion has already been corrected in-camera, so owners are often unaware that the problem existed in the first place and are surprised to find that the raw image shows these dark corners.

It is not possible to fix the dark corner issue by using vignetting correction - there is no information about the scene in those corners, the scene is occluded by the lens mechanism/lens hood. Do as the camera does: correct the distortion, and the dark corners disappear

2 Automated Correction

Some of these sub-tools are capable of performing their function in an automated way with a single click by relying on data which describes the imperfections inherent to a given camera and lens. There are two sources for this data: Lensfun and Adobe LCP.

2.1 Lensfun

Lensfun is an open-source project which contains a database of lens parameters. You can find more information about it in the Lensfun FAQ.

The tools "Profiled Lens Correction" and "Perspective" rely on data from Lensfun to simplify and automate the work of specifying the right camera/lens information and finding the optimal correction parameters.

In order for RawTherapee to be able to automatically query the Lensfun database, RawTherapee needs to know which camera and lens was used to take a given photo. This information is decoded from the photo's metadata (currently using a home-made solution, and in the future using Exiv2). To check whether the camera and lens names are decoded correctly, open a photo and in the Editor tab hit the "Info.png Quick info" button. The info panel should show your camera and lens names. If it does not, then RawTherapee failed to decode this information correctly. For the time being, there is nothing you can do about this but wait for a new version of RawTherapee. This will hopefully change in RawTherapee 6.0 which will use Exiv2.

If your camera and lens cannot be decoded from the photo's metadata, you may still be able to specify them manually, depending on the tool.

2.1.1 How to check whether your Lensfun database is intact

To find out whether RawTherapee can query the Lensfun database at all, look at the "Camera" and "Lens" drop-downs in the Profiled Lens Correction tool. If you click on either drop-down, it should contain a long list of entries. If it does not, then your RawTherapee installation is buggy - try reinstalling, and if the problem persists then seek help via the forum.

2.1.2 How to check whether your Lensfun database contains information about your camera/lens

To find out whether your Lensfun database contains data for your camera and lens, open a raw file and look at the "Camera" and "Lens" drop-downs in the "Profiled Lens Correction" tool. They should both automatically show the correct camera and lens.

Common causes of failure to auto-detect a profile include:

  • RawTherapee could not decode the camera and lens make and model.
  • A profile for your camera/lens combination does not exist in your version of the Lensfun database.
  • A profile for your camera/lens combination does exist, but it uses names and parameters which differ enough to confuse the matching algorithm, for example "Pentax" vs "Ricoh Pentax", or "F4.0" vs "f/4".

You can try manually looking through each drop-down list to select the right camera and lens.

If you do not find your camera or lens in the drop-downs, then your version of the Lensfun database does not contain this data. Update your Lensfun database. If it still does not contain your camera or lens, then play your part in the open-source world and contribute this information - see the Lensfun documentation to find out how to measure the parameters and contribute them for everyone's benefit.

2.1.3 Updating your Lensfun database in Linux

Run the executable lensfun-update-data to download the latest version of the Lensfun database. Restart RawTherapee.

Alternatively, you could copy and paste the relevant section from the Lensfun database (which could be taken from one of the files in /usr/share/lensfun/) into a new file $HOME/.local/share/lensfun/myLensfun and modify the relevant parameter to match the metadata from your photos. You can find the camera and lens name and parameters contained in your photos by viewing the "Info.png Quick info" panel.

Note that while editing the Lensfun database in /usr/share/lensfun/ directly may be possible, this is not recommended because you could lose your changes during an update.

Should you need to use a Lensfun database in a custom location, you can point RawTherapee to it by editing the options file and setting the DBDirectory key's value to the absolute path of the custom Lensfun database file.

2.1.4 Updating your Lensfun database in Windows

  1. Close RawTherapee while doing this.
  2. Download the Lensfun database. Either get the appropriate XML file from https://github.com/lensfun/lensfun/tree/master/data/db or download the latest release zip from https://github.com/lensfun/lensfun/releases and find all XML files in the data\db folder.
  3. Move these XML files to the Lensfun database folder on your computer, which could be in C:\Program Files\darktable\share\lensfun\version_1.

2.2 LCP

Adobe provides Lens Correction Profiles (LCP) and the tools needed to create them. These are text files which describe the distortion, vignetting and chromatic aberrations (CA) of a lens, so that simply loading this file in LCP-capable software such as RawTherapee will correct these issues. Select an Adobe LCP file (read the guide on how to get LCP profiles) to automatically correct geometric distortion, vignetting and lateral chromatic aberrations.

The Profiled Lens Correction tool's "geometric distortion" feature can be used together with the manual Distortion Correction tool, and the vignetting correction feature can be used together with the manual Vignetting Correction tool. This lets you apply manual adjustments in addition to the LCP profile's automatic adjustments, either for artistic reasons or if the LCP fails to sufficiently correct a parameter. Be careful that you don't overdo the distortion and vignetting correction by forgetting to turn the manual tools off if you use the LCP equivalents. However, the Profiled Lens Correction tool's vignetting correction is mutually exclusive with the Flat Field tool - that is, when you select a flat-field image, then the LCP's vignetting correction will have no effect.

The following restrictions apply:

  • Geometric distortion, vignetting and chromatic aberration correction are all supported in raw files, but only geometric distortion correction is supported in non-raw files.
  • Chromatic aberration correction is only supported if the Exif information contains the focus distance (e.g. in DNGs from Nikon files).
  • To keep the preview fast and responsive, the preview image is used to show the effects of the LCP. As this preview image is small (exactly the size you see), fixing the distortions will make it appear a little blurry. This has no effect on your saved image, which will be sharp, and so will the zoomed-to-100% preview. Only the zoomed-out preview might look soft.

As with any other tool, you can apply an LCP to multiple images either by including it in the processing profile (see Creating processing profiles for general use), or by selecting multiple images where the same lens was used (you can use the Metadata Filter in the File Browser tab to make this easier) and applying the LCP from the File Browser tab.


3 Interface

3.1 Method

TODO Explain what "logarithmic" and "linear" do.

3.2 Auto-Fill

Barrel distortion correction leaves black empty space in image periphery.
"Auto-fill" enlarges the image to fill in the empty space.

This option will upscale or downscale the photo to the extent that the whole image fits within the image boundaries with no black borders visible.

When correcting images that suffer from barrel distortion, "Auto-fill" will perform downscaling to fit as much of the re-projected image as possible into the image boundaries, so that you don't unnecessarily lose any parts of the image. Conversely if the image suffers from pincushion distortion, "Auto-Fill" will upscale the corrected image to fill the frame without black borders around the periphery.


3.3 Auto-Crop

"Auto-Crop" applied after distortion correction.
"Auto-Crop" applied after image rotation.

"Crop-auto.png Auto-Crop" is available when "Auto-fill" is disabled. When activated, it will not cause image interpolation, but instead will crop away the empty space left by the distortion correction or image rotation.


3.4 Rotate

Example of image rotation.

Rotate the image between -45° and +45°. Use the "Rotate-straighten.png Select Straight Line" button to set either a vertical or a horizontal image alignment. Use the mouse to draw this line - click and hold mouse to start, move to draw a new vertical or horizontal axis and release to engage image rotation.


3.5 Perspective

The Perspective tool offers the "simple" manual mode, and a powerful "camera-based" guided/automated mode. Try the "camera-based" mode first, as when it works it's the easiest and most accurate. Click on the "automatic" buttons for correcting horizontal, vertical or both perspectives. Revert to manual adjustments if these automatic adjustments fail.

Example of horizontal perspective correction.
Example of vertical perspective correction.

3.5.1 Simple

Horizontal
When your picture was taken while you were slightly off-center of the object, you can correct this (within certain limits) with the horizontal slider.
Vertical
Very useful to correct 'falling lines', e.g. when photographing architecture. Higher values for both sliders produce heavy distortion, so use with care. Or don't care at all and have fun!

3.5.2 Camera-Based


3.6 Profiled Lens Correction

This tool group allows you to use either Lensfun or Adobe LCP to automatically correct:

  • Geometric distortion
  • Vignetting
  • Chromatic aberration

Some of these automatic corrections can work together with manual corrections, while others are mutually exclusive. See the notes in the Lensfun and LCP sections of this page.

3.7 Geometric Distortion

This button has been renamed to "Automatic" in RawTherapee 5.

Corrects lens distortion. A negative number corrects barrel distortion, a positive value will correct pincushion distortion. You can place a grid over the image by activating Crop (without cropping) and using "Guide Type > Grid". This may serve as a guide to correct lens distortion.

The "Automatic" button only works if your camera corrected the distortion of the JPEG image embedded in the raw file (most cameras embed a JPEG image in every raw file, and some cameras correct the distortion of that image too). What this feature does is it looks at the JPEG image and, if it was corrected, tries to fix distortion in the raw image by making it match the JPEG image. There are two limitations:

  • If the JPEG image was not distortion-corrected by your camera, this button will have no effect.
  • If the JPEG image is insufficiently corrected or over-corrected, so will the results be, but as the computed correction will be shown on the Amount slider, you can further refine it manually.


3.8 Chromatic Aberration Correction

400% zoom showing correction of CA.
CA easily visible even at 100% corrected.

This "Chromatic Aberration Correction" tool in the Transform tab works on the image after demosaicing. The Chromatic Aberration tool in the Raw tab works on the image before demosaicing.

Chromatic aberration can be corrected by using the "Red" and "Blue" sliders. Normally you won't see any chromatic aberration in the fit-to-screen preview, therefore it is highly recommended to open a detail window Window-add.png or to zoom the main preview in to 100% Magnifier-1to1.png or more when you attempt this kind of correction. As in other software tools, this algorithm eliminates moderate chromatic aberration quite well. Do not expect miracles with images having extremely high chromatic aberration - garbage in, garbage out.


3.9 Vignetting Correction

Vignetting means light fall-off around the periphery of an image as compared to the center. One of the differences between a cheap lens and an expensive one is that the former is likely to produce stronger vignetting than the latter. The "Vignetting Correction" tool is meant to correct vignetting caused by the lens. This tool is not intended for artistic vignetting; use the Vignetting Filter tool for that.

Amount
Setting the "Amount" slider to a positive value brightens the four edges of the images to correct the classical vignetting. Setting it to a negative value darkens them.
Radius
Influences how much of the image beginning from the edges will be brightened or darkened. Lower values: area of darkening is bigger; higher values: area of darkening is smaller.
Strength
Amplifies the settings of the "Amount" and "Radius" sliders. Set "Amount" to -100, "Radius" to 50 and move "Strength" from 1 to 100 to see how this works.