3.4.4. Correction group

The correction group contains the modules that will correct typical problems in an photo such as hotpixels, spot removal, noise, lens correction among others. This group also includes the basic sharpening tools.

3.4.4.1. Sharpen

Overview
This is an standard UnSharp Mask (USM) tool for sharpening the details of an image.
Usage

This module works by enhancing the contrast around edges and thereby enhances the impression of sharpness of an image. In darktable this module is only applied to the L-channel in Lab color space.

radius

USM applies a gaussian blur to your image as part of its algorithm. This controls the blur radius which in turn defines the spatial extent of edge enhancement. Too high values will lead to ugly over-sharpening.

amount

This controls the strength of the sharpening.

threshold

Contrast differences below this threshold are excluded from sharpening. Use this to avoid amplification of noise.

3.4.4.2. Equalizer

Overview
This versatile module can be used to achieve a variety of effects, such as: bloom, denoising, clarity, and local contrast enhancement. It works in the wavelet domain and parameters can be tuned for each frequency band separately.
Usage

Each frequency band can be tweaked independently. In particular, you can adjust contrast boost and denoise threshold splines for both lightness and chromaticity (luma and chroma), as well as the acuteness (edges) of the wavelet basis on each frequency scale.

Each spline can be dragged with a proportional edit approach; use the mouse wheel to adjust the radius in which your changes will have an effect. The transparent area indicates where you would drag the spline with the current mouse position and radius. The small little triangles on the x-axis can be moved to alter the x-position of the spline nodes.
Drag the upper line (bright circles, here for the lightness channel) to affect local contrast. Pulling it up, as shown here, will result in a contrast boost for that frequency band. Higher frequencies, i.e. smaller details, are to the right of the grid. Pulling it down works, too.
The bottom spline (black circles) is used to perform denoising. It adjusts the wavelet shrinkage threshold for each frequency band. Pull it up to see the effect. In this example, the noise which has been amplified by local contrast enhancement is removed.
This screen shows the effect of the edge parameter. It is here pulled down to zero for all bands. This is effectively a regular à trous wavelet, without edge detection, and results in the characteristic halos around sharp edges in the image.
This image is the other extreme. The wavelet basis now oversharpens, which results in ugly gradient reversals near the ridge of the rock.

Note that the edge parameter only affects the wavelet basis, not the image directly. You will have to change some denoise/contrast boost parameters to see an effect following adjustments to the edge parameter.

This module additionally has a mix slider below the spline GUI. Adjusting the slider will upscale or downscale the splines on the y-axis. The slider was added as a convenience tool to help you modify the strength of the effect. It is not a module parameter in itself; when you leave darkroom mode all changes will be consolidated into the spline curves.

Have a look at the presets where there are a broad variety of examples that will provide a good starting point to gain an intuitive understanding of the controls. Among others there is preset to enhance an image's clarity.

3.4.4.3. Denoise – profiled

Overview
This module offers an easy to use and – at the same time – highly efficient denoise operation. Under the hood it applies (your choice of) a non-local means or edge-aware wavelet denoise algorithm with parameters specifically profiled for certain camera models and ISO settings.
Usage

The darktable team, with the help of many users, has measured noise profiles for various cameras. Differentiated by ISO settings we evaluated how the noise statistics develop with brightness for the three color channels. Our set of profiles covers well above 200 popular camera models from all major manufacturers.

darktable stores noise profiles in an external json file. This file can be found in $DARKTABLE/share/darktable/noiseprofile.json where $DARKTABLE represents the darktable installation directory. The json format is quite straightforward and explained in depth in json.org. You can replace the default noise profiles by your own ones and specify that file on the command line when starting darktable. For more details see Section 1.1.1, “darktable binary”. If you generate your own noise profiles don't forget to share your results with the darktable team!

profile

Based on Exif data of your raw file, darktable will automatically determine the camera model and ISO setting. If found in its database, the corresponding noise profile will be used. If your image has an intermediate ISO value, the statistical properties will be interpolated between the two closest datasets in the database, and this interpolated setting will show up as the first line in the combo box. You also have the option to manually overwrite this selection to suit your personal preferences better. The top-most entry in the combo box brings you back to the profile darktable deems most suited.

mode

This module can eliminate noise with two different core algorithms. non-local means is a bit better suited to tackle luma (lightness) noise; wavelet has its strength in eliminating chroma (color) noise. If needed you can apply two instances of this module (see Section 3.2.4, “Multiple instances”). The non-local means instance should be combined with blend mode lightness or HSV lightness; the wavelet instance with blend mode color or HSV color. For more information on blend modes have a look at Section 3.2.6, “Blending operators”.

patch size

This slider is only available if mode non-local means is selected. It controls the size of the patches being matched when deciding which pixels to average (see also Section 3.4.4.4, “Denoise – non local means”). Setting this to higher values can give more sharpness. Processing time will stay about the same.

strength

This parameter is here to fine-tune the strength of the denoise effect. The default value has been chosen to maximize the peak signal to noise ratio. It's mostly a matter of taste if you prefer a rather low noise level at the costs of a higher loss of detail, or if you accept more remaining noise in order to have finer structures better preserved within your image.

3.4.4.4. Denoise – non local means

Overview
This is a denoise algorithm, which will work on chroma and/or luma.
Usage

This module reduces noise in your image but preserves structures. This is accomplished by averaging each pixel with some surrounding pixels in the image. The weight of such a pixel in the averaging process depends on the similarity of its neighborhood with the neighborhood of the one pixel to be denoised. A patch with a certain size is used to measure that similarity. As denoising is a resource hungry process, it slows down pixelpipe processing significantly; consider activating this module late in your workflow.

patch size

The radius of the patch for similarity evaluation.

strength

The strength of the denoise. Higher values lead to a stronger effect.

luma

Amount of denoise to apply to luma. Select carefully in order not to lose too much structure.

chroma

Amount of denoise to apply to chroma. You can be much more aggressive with this parameter compared to luma.

3.4.4.5. Denoise – bilateral

Overview
This module is used to denoise high ISO pictures. It is flagged as a slow module due to its high resource consumption, both in terms of CPU cycles and in terms of memory usage. Quite counter-intuitively, the greater the values for sliders, the lesser resources.
Usage

This module reduces noise in your image but preserves sharp edges. This is accomplished by averaging pixels with their neighbors, taking into account not only the geometric distance but also the distance on the range scale, i.e. differences in the RGB values. As denoising is a resource hungry process, it slows down pixelpipe processing significantly; consider to activate this module late in your workflow.

radius

Set the spatial extent of the gaussian blur.

red

Blur intensity for red channel.

green

Blur intensity for green channel.

blue

Blur intensity for blue channel.

3.4.4.6. Liquify

Overview
The liquify module offers a versatile way of moving pixels around by applying free style distortions to parts of the image. There are three tools to help doing that: points, lines, and curves.

Each of liquify's tools is based on nodes. A point is given by a single node, a line or a curve consist of a set of nodes defining the path.

There is a limit of 100 nodes in a single liquify instance. For more distortions one can use multiple instances of the liquify module. However, take into account that the liquify module requires a lot of computing resources.

Usage
The basic elements of all tools in liquify are nodes.

You can drag the central point of a node to move the node around. The radius describes the area of the applied effect: the distortion occurs only inside this radius. To change the radius drag the handle at the circumference. A strength vector starting from the center describes the direction of the distortion, and its strength is depicted by the length of the vector. You change the vector by dragging its arrowhead.

warps and nodes count

This information field displays the the number of warps (individual distortion object) and nodes currently used.

point tool

Click the icon to activate the point tool and left-click on the image to place it.

A point is formed by a single node. In a point the strength vector has three different modes which are toggled using ctrl-click over the arrowhead of the strength vector:

linear The linear mode produces a linear distortion inside the circle. Starting from the opposite side of the strength vector and following the strength vector's direction. This is the default mode.
radial growing In this mode the strength vector's effect is radial, starting with a strength of 0% in the center and growing when going away from the center. This mode is depicted by an additional circle with the arrow pointing outwards.
radial shrinking In this mode the strength vector's effect is radial, starting with a strength of 100% in the center and shrinking when going away from the center. This mode is depicted by an additional circle with the arrow pointing inwards.

Note that the strength by default varies linearly from 0% to 100% between the center and the radius of the control point. It is possible to modify the feathering effect by clicking on the center of the circle:

default Linear from the center to the radius.
feathered Two control circles are displayed and can be modified independently to feather the strength of the effect.

A point can be removed by right-clicking on the center.

line tool

Click the icon to activate the line tool and left-click on the image to place the first point, move and left-click to place another point and start forming the path. To end the line just right-click anywhere.

A line is a set of points. The points are linked together, the effect is interpolated by a set of strength vectors.

It is possible to add a control point on a line by ctrl-click on a segment. You may remove a control point from a line by ctrl-right- click on the node center.

A right-click on a segment will remove the shape completely.

A ctrl-alt-click on a segment will change it to a curve segment.

curve tool

Click the icon to activate the curve tool and left-click on the image to place the first point, move and left-click to place another point and start forming the path. To end the line just right-click anywhere.

A curve is a set of points. The points are linked together, the effect is interpolated as a bezier curve by a set of strength vectors.

It is possible to add a control point on a curve by ctrl-click on a segment. You may remove a control point from a curve by ctrl-right- click on the node center.

A right-click on a segment will remove the shape completely.

A ctrl-alt-click on a segment will change it to a line segment.

It is possible to change the way the points of the curve are linked together by using ctrl-click on the center. There are four modes which correspond to different ways of handling the steepness of the bezier curve by control handles:

autosmooth This is the default mode in which the control handles are not displayed as they are automatically computed to always give a smooth curve.  
cups Control handles can be moved independently. This mode is depicted by a triangle symbol in the node center.  
smooth Control handles are always giving a smooth curve. This mode is depicted by a diamond symbol in the node center.  
symmetrical Control handles are always moved together. This mode is depicted by a square symbol in the node center.  

node edit tool

Clicking the icon activates or deactivates the node edit tool displaying all defined distortion objects and their controls. Alternatively you can at any time right-click on the image for the same effect.

3.4.4.7. Perspective correction

Overview
This module is designed to automatically correct for converging lines, a form of perspective distortions frequently seen in architectural photographs. The underlying mechanism is inspired by Markus Hebel's ShiftN program.

Perspective distortions are a natural effect when projecting a three dimensional scene onto a two dimensional plane and cause objects close to the viewer to appear larger than objects further away. Converging lines are a special case of perspective distortions frequently seen in architectural photographs. Parallel lines when photographed at an angle get transformed into converging lines that meet at some vantage point within or outside the image frame.

This module is able to correct converging lines by warping the image in such a way that the lines in question become parallel to the image frame. Corrections can be applied in vertical and horizontal direction, either separately or in combination. In order to perform an automatic correction the module analyzes the image for suitable structural features consisting of line segments. Based on these line segments a fitting procedure is started that determines the best values of the module parameters.

Usage

Clicking the get structure icon ( ) causes darktable to analyze the image for structural elements. Line segments are detected and evaluated. Only lines that form a set of either vertical or horizontal lines are used for further processing steps. The line segments are displayed as overlays on the image base. A color code describes what type of line darktable has found:

green lines that are selected as relevant vertical converging lines
red lines that are vertical but are not part of the set of converging lines
blue lines that are selected as relevant horizontal converging lines
yellow lines that are horizontal but are not part of the set of converging lines
grey other lines identified but not of interest to this module

Lines marked in red or yellow are regarded as outliers and are not taken into account for the automatic fitting step. This outlier elimination involves a statistical process with random sampling so that each time you press the get structure button the color pattern of the lines will look a bit different. You can manually change the status of line segments: left-clicking on a line selects it (turns the color to green or blue) while right-clicking deselects it (turns the color to red or yellow). Keeping the mouse button pressed allows for a sweeping action to select/deselect multiple lines in a row. Holding down the shift key and keeping the left or right mouse button pressed while dragging selects or deselects all lines in the chosen rectangular area.

Clicking one of the automatic fit icons (see below) starts an optimization process which finds the best suited parameters. The image and the overlayed lines are then displayed with perspective corrections applied.

rotation

This parameter controls a rotation of the image around its center and can correct for a skewed horizon.

lens shift (horizontal)

This parameter corrects converging lines horizontally.

lens shift (vertical)

This parameter corrects converging lines vertically. In some cases you get a more naturally looking image if you correct vertical distortions not to their full extent but rather at an 80 to 90% level. If desired just reduce the value after having performed the automatic correction.

shear

This parameter shears the image along one of its diagonals and is needed when correcting vertical and horizontal perspective distortions simultaneously.

guides

If activated a number of guide lines is laid over the image to help you judge the quality of the correction.

automatic cropping

When activated the automatic cropping feature clips the image to get rid of any black corners. At your choice you can either clip to the largest area or to the largest rectangle maintaining the original aspect ratio (original format).

lens model

This parameter controls how lens and camera specifics are taken into account. If set to generic a focal length of 28mm on a full-format camera is assumed. If set to specific, focal length and crop factor can be set manually.

focal length

The focal length of the lens used. The default value is taken from the Exif data of your image. This parameter is only effective and visible if the specific lens model has been selected.

crop factor

The crop factor of the camera used. You will typically need to set this value manually. This parameter is only effective and visible if the specific lens model has been selected.

aspect adjust

If the specific lens model has been selected this parameter allows for a free manual adjustment of the image's aspect ratio.

automatic fit

Clicking on one of the icons starts an automatic fitting of the module parameters based on the selected vertical and/or horizontal lines. You can choose to correct only vertical distortions ( ), only horizontal distortions ( ), or both types of distortions simultaneously ( ). Ctrl-clicking on either icon only fits rotation. Shift-clicking on either icon only fits vertical and/or horizontal lens shift.

get structure

Clicking on the icon causes the image to be (re-)analyzed for suitable line segments. Shift-clicking applies a prior contrast enhancement step, ctrl-clicking applies an edge enhancement step. Both variations can be used alone or in combination if the default is not able to detect a sufficient number of lines. Clicking on the icon discards all collected structural data. By clicking on the icon you can switch the overlay display of line segments on and off.

Examples

An input image with a skewed horizon and converging lines caused by directing the camera upwards.
The image after having corrected for vertical and horizontal perspective distortions. Note the framing by the automatic cropping feature and the still visible overlay of structural lines.

3.4.4.8. Lens correction

Overview
This module is able to correct certain lens flaws, namely distortions, transversal chromatic aberrations (TCA) and vignetting. It relies on the external library lensfun, which comes with correction profiles for many (but not all) common cameras and lenses.
Usage

In order to perform lens corrections the module uses Exif data of your image to identify the specific camera/lens combination and collects the needed correction parameters from a profile in lensfun's database.

camera

The camera make and model as determined by Exif data. You can override this manually and select your camera from a hierarchical menu.

lens

The lens make and model as determined by Exif data. You can override this manually and select your lens from a hierarchical menu. This is mainly needed for pure mechanical lenses, but may also be needed for off-brand / third party lenses.

photometric parameters: focal length, aperture, focal distance

Corrections additionally depend on certain photometric parameters that are read from Exif data: focal length (needed for distortion, TCA, vignetting), aperture (needed for TCA, vignetting) and focal distance (needed for vignetting). Many cameras do not record focal distance in their Exif data; most likely you need to set this manually.

You can manually override all automatically selected parameters. Either take one of the predefined values from the pull-down menu; or – with the pull-down menu still open – just type in your own value.

If your system's lensfun library has no correction profile for the automatically identified camera/lens combination the controls for the three photometric parameters are not displayed, and you get a warning message instead. You may try to find the right profile yourself by searching for it in the menu. If there is no matching profile for your lens, please visit this lens calibration service offered by Torsten Bronger, one of darktable's users. Alternatively you may go to lensfun's home page and learn how to generate your own set of correction parameters. Don't forget to share your profile with the lensfun team!

corrections

This combobox gives you a choice about which corrections (out of distortion, TCA and vignetting) darktable shall apply. Change this from its default all, if your camera has already done some internal corrections (e.g. of vignetting), or if you plan to do certain corrections with a separate program.

geometry

In addition to the correction of lens flaws, this module can change the projection type of your image. Set this combobox to the aimed projection type, like rectilinear, fish-eye, panoramic, equirectangular, orthographic, stereographic, equisolid angle, thoby fish-eye.

scale

This slider allows you to adjust the scaling factor of your image. Pressing the auto scale button (right to the slider) will let darktable find the best fit to avoid black corners.

mode

The default behavior of this module is to correct lens flaws. Switch this combobox to distort in order to simulate the behavior of a specific lens (inverted effect).

TCA red

This slider allows to override the correction parameter for TCA. You can also use this slider to manually set the parameter in case the lens profile does not contain TCA correction. Look out for colored seams at features with high contrast edges and adjust this parameter and the following one to minimize those seams.

TCA blue

This slider allows to override the correction parameter for TCA. You can also use this slider to manually set the parameter in case the lens profile does not contain TCA correction.

corrections done

You will sometimes observe that for a given camera/lens combination only part of the possible corrections (distortion, TCA, vignetting) are supported by lensfun's profiles. This message box will tell you what corrections have actually been applied.

3.4.4.9. Scale pixels

Overview
Some cameras like the Nikon D1X have rectangular instead of the usual square sensor cells. Without correction this would lead to distorted images. This module applies the needed scaling.
Usage

darktable detects images that need correction by their Exif data and automatically activates this module. For other images the module always remains disabled. The modules has no parameters.

3.4.4.10. Rotate pixels

Overview
The sensors of some cameras like the Fujifilm FinePix S2Pro, F700, and E550 have a diagonally oriented Bayer pattern instead of the usual orthogonal layout. Without correction this would lead to a tilted image with black corners. This module applies the needed rotation.
Usage

darktable detects images that need correction by their Exif data and automatically activates this module. For other images the module always remains disabled. The modules has no parameters.

3.4.4.11. Spot removal

Overview
Spot removal allows you to correct an area in your image by using another area as model.
Usage

This module uses some of the shapes that are offered in drawn masks, namely circles, ellipses and path shapes. The user interface and the controls are the same as in drawn mask and explained in more detail in Section 3.2.7, “Drawn mask”.

Select the desired shape by clicking the corresponding icon, then click on the canvas to choose the area to be healed, i.e. the target area.

The source area is preliminary positioned at a location with a default distance to the target. Source area and target area can then be shifted independently until the result matches your expectations. An arrow helps to tell source from target area.

Use the shape specific controls to adjust its size, its border width, and other attributes.

Right-click on a shape to delete it.

Collapse the module to complete the changes.

Examples

Let's use this portrait as example; we want to remove some dirt and unwanted catchlight from camera popup strobe.
I have marked all the spots that I want to remove from the image with circle shapes and appropriately selected source areas.
And here is the result image of the spotremoval.

3.4.4.12. Raw denoise

Overview
Raw denoise allows you to perform denoising on pre-demosaic data. It is ported from dcraw.
Usage
noise threshold

Set the threshold for noise detection. Higher values lead to stronger noise removal and higher loss of image detail.

3.4.4.13. Dithering

Overview
This module eliminates some of the typical banding artifacts which can occur, when darktable's internal 32-bit floating point data are transferred into a discrete 8-bit or 16-bit integer output format for display or file export.

Banding is a problem which can arise, when an image is downsampled into a lower bit-depth. Downsampling happens regularly, when darktable displays or exports the results of a pixelpipe. In order to avoid banding, you may activate this module. As dithering consumes significant resources this module is disabled by default.

Although banding is not an inherent problem of any of darktable's modules, some operations may provoke it as they produce a lightness gradient in the image. To mitigate possible artifacts you should consider to activate dithering when using the vignette and the graduated density module, respectively (see Section 3.4.5.4, “Vignetting” and Section 3.4.5.13, “Graduated Density”). This is especially relevant for images with extended homogeneous areas like cloudless sky. Also when using a gradient mask (see the section called “gradient”) you should watch out for possible banding artifacts.

Usage

Viewing from some distance an image dithered into a very low bit depth (like floyd-steinberg 1-bit b&w) will give the impression of a homogeneous grayscale image. We try to mimic this impression in darktable when you look at zoomed-out images in the center view, in the navigation window and for thumbnails. This is accomplished by dithering those images into a higher number of grayscale levels. Note that as a consequence the histogram – which is derived from the navigation window – will show this increased number of levels and is no longer a full match of the output image.

method

This combobox sets the dithering method. Floyd-Steinberg error diffusion – with some typical output bit depths – and random noise dithering are both supported. Floyd-Steinberg systematically distributes quantization errors over neighboring pixels, whereas random dithering just adds some level of randomness to break sharp tonal value bands. The default setting is floyd-steinberg auto, which automatically adapts to the desired output format.

damping

This slider is only displayed if you choose method random. It controls the level of added random noise expressed as a damping factor in a 10*log 2 basis. A value of -80 is a good fit for 8-bit output formats and -160 for 16-bit ones.

Examples

The visibility of the following examples depends on the quality of your monitor or the print quality.

Banding artifact caused by vignetting (100% crop of a 8-bit PNG; effect heavily exaggerated by strong contrast enhancement).
The same image area, processed as above but with activated Floyd-Steinberg dithering.

3.4.4.14. Hotpixels

Overview
This module is able to automatically detect and eliminate hotpixels. Hotpixels are pixels which failed to record light level correctly. Detected hotpixels are replaced by an average value of their neighbors.
Usage

You control the detection sensitivity with the threshold parameter and the level of elimination with the strength parameter.

threshold

The threshold of the detection, i.e. how strong a pixel's value needs to deviate from its neighbors to be regarded as a hotpixel.

strength

The strength of blending hotpixels with their surrounding.

detect by 3 neighbours

This will extend the detection of hotpixels, it will even regard a pixel as hot if a minimum of only three (instead of four) neighbor pixels deviate by more than the threshold level.

mark fixed pixels

This options will mark the pixels that have been corrected. It also displays the count of detected and fixed pixels.

3.4.4.15. Chromatic aberrations

Overview
This module allows you to correct chromatic aberrations.
Usage

The module has no parameters. On activation it will automatically try to optimize away visible CA's.

The underlying model assumes as input an uncropped photographic image. The module is likely to fail when you zoom into the image, as in that case it will only receive parts of your photograph as input in darktable's pixelpipe. As a consequence, chromatic aberrations do not get corrected properly in the center view. This limitation only applies to interactive work, not to file export.

This module currently only works for images recorded with a Bayer sensor (which is the sensor used in the majority of cameras).

3.4.4.16. Defringe

Overview
This module is designed to remove purple or any other color of fringing which often results from Longitudinal Chromatic Aberrations (LCA), also known as Axial Chromatic Aberrations.
Usage

This module helps removing fringe via edge-detection. Where pixels are detected as a fringe, it rebuilds the color from lower-saturated neighboring pixels.

operation mode

Set the operation mode for detecting fringes. global average is usually the fastest but might show slightly incorrect previews in high magnification. It might also protect the wrong regions of color too much or too little by comparison with local averaging. local average is slower because it computes local color references for every pixel, which might protect color better than global average and allows for rebuilding color where actually required. The static method does not use a color reference but directly uses the threshold as given by the user.

edge detection radius

Set the spatial extent of the gaussian blur used for an edge detection. The algorithm uses the difference of gaussian-blurred and original image as an indicator for edges (a special case of the difference of gaussians edge detection). Try increasing this value if you either want a stronger detection of the fringes or the thickness of the fringe edges is too high.

threshold

Sets the threshold over which the edge of a pixel is counted as a fringe. The colors of the affected pixels will be rebuild from neighboring pixels. Try lowering this value if there is not enough fringe detected and try increasing this value if too many pixels are desaturated. You may additionally want to play around with the edge detection radius.