Modules are organized into five functional groups: basic, tone, color, correction and effect. You either view all modules in one long list or instead click on a group to just display modules belonging to that group.
The basic group of modules contains the modules for basic development. These are ones you probably will use most often, such as exposure, white balance etc.
|This module is used to crop, rotate and correct perspective distortions of your image. You can overlay your image with various helpful guidelines that assist you using the tools.||
Some of the tools of this module, namely adjustment of angle and corrections of perspective distortion, will require the original image data to be interpolated. For best sharpness results set “lanczos3” as pixel interpolator in core options (see Section 8.2, “Core options”).
Whenever the user interface of this module is in focus, you will see the full uncropped image overlayed with handles and guiding lines.
First off, select what aspect ratio you want and size the crop boundaries by dragging border and corner handles. Use the button right of the aspect box, to swap between portrait and landscape mode. You can move around the crop rectangle by holding down left mouse button and move around. When you are done and want to execute the crop, just give focus to another module or double-click into the image base. You can at any time change your crop area by just revisiting this module.
This tool corrects the rotation angle helping you level an image. You can either set a numerical value or use your mouse directly on the image. To use your mouse, right-click, hold it down and draw a line along a suited horizontal or vertical feature; as soon as you release the mouse button the image is rotated so the line you drew matches the horizontal/vertical axis.
This tool is used to correct perspective distortions in your image. Useful for example when you shoot a high building from ground with a short focal length, aiming upwards with your camera. The combobox lets you select the type of correction you want to use :
|vertical||if you want to limit the correction to vertical lines|
|horizontal||limit the correction to horizontal lines|
|free||if you want to correct horizontal and vertical lines|
Depending on the selected correction type you will see two or four straight adjustment lines overlaid to your image. Two red circles on every line let you modify the line positions with your mouse. Each line additionally carries a “symmetry” button. If activated (and highlighted in red) all movements of the affected line will be mirrored by the opposite line.
In order to correct perspective distortions, you need to find suitable horizontal and/or vertical features in your image and align the adjustment lines with them. When done, press the “OK” button, which is located close to the center of your image. The image will be corrected immediately. You can at any time come back and refine your corrections by selecting “correction applied” in combobox keystone.
Use this options to avoid black edges on the image borders. Useful when you rotate the image.
Here you can change what aspect ratio you want to have on the result, thus constraining the proportion of width and height of the crop rectangle to the aspect ratio of your choice. Many common numerical ratios are pre-defined. A few special aspect ratios deserve explanation:
|free||free forming the rectangle without any ratio restrictions|
|image||this option constrains the ratio to be equal to image ratio|
|golden cut||this option constrains the ratio to be equal the golden number|
|square||this option constrains the ratio to be 1|
You can also select any other ratio after opening the combobox and typing it in the form of “x:y”. If you want a certain aspect ratio to be added to the pre-defined ones you can do so by including a line of the form
into darktable's configuration file
$HOME/.config/darktable/darktablerc. Here “foo”
defines the name of the new aspect ratio and “x” and “y” the
corresponding numerical values.
|This module allows the user to modify the orientation of an image. By default it is active for all images and receives its standard settings from the camera's orientation flag stored in the Exif data.||
|The shadows and highlights module allows adjustment to the tonal range of darker parts of an image (shadows) and lighter parts (highlights); it can bring back details in shadows and highlights by enhancing local contrast.||
This slider controls the effect on shadows; positive values will lighten up shadows while negative values will darken them.
This slider controls the effect on highlights; negative values will darken highlights while positive values will lighten them up.
By default the algorithm of this modules leaves black point and white point untouched. In some cases an image might contain tonal variations beyond the white point, i.e. above a luminance value of 100. A negative shift in the white point adjustment slider allows to bring these values down into the proper range so that further details in the highlights get visible.
This combobox chooses the underlying blurring filter, gaussian or bilateral. Try bilateral filter if you experience halos with gaussian blur.
This slider controls the radius of the involved blurring filter. Higher values give softer transitions between shadows and highlights but might introduce halos. Lower values will reduce the size of halos but may lead to an artificial look. As said, bilateral filter is much less prone to halo artifacts.
This slider controls how strong the effect extends to midtones; high values reduce the effect to the extreme shadows and highlights; low values cause strong adjustments also to midtones. You normally only need to touch this parameter if you want to limit the effects to the extreme shadows and highlights; increase the value in this case. At 100% this module has no visible effect any longer as only absolute black and absolute white are affected.
This slider controls the color saturation adjustment made to shadows; high values cause saturation enhancements on lightened shadows; low values cause desaturation on lightened shadows. It is normally safe to leave this at its default of 100%. This gives a natural saturation boost on shadows – similar to the one you would also expect in nature if shadows would receive more light.
This slider controls the color saturation adjustment made to highlights; high values cause saturation enhancements on darkened highlights; low values cause desaturation on darkened highlights. Often highlights do not contain enough color information to give convincing colors when darkened. You might need to play a bit with this parameter in order to find the best fitting value depending on your specific image; but be aware that sometimes results still might not be fully satisfying.
||Original image exposed for the outer sunlit wall to avoid clipped highlights. As a consequence the interior of the barn has pitch black shadows.|
||Shadows get lightened; highlights are untouched; overall effect toned down a bit by blend mode “normal” and an opacity of 65%.|
|Camera sensors provide data in linear RGB format, the original image appears flat and dull. That's the reason why camera manufacturers apply their characteristic base curves to the raw data when they generate in-camera JPEG images with better colors and contrast.||
darktable comes with base curve presets that mimic the curves of various manufacturers. These are automatically applied to raw images according to the manufacturer ID found in Exif data. For several camera models darktable comes with base curves adapted for that specific model. A configuration option in the core preferences dialog (see Section 8.2, “Core options”) defines whether darktable by default should apply the per-camera base curve or the manufacturer one.
You can adjust an existing base curve or create a new one. The base curve is defined by two or more nodes. You can move any node to modify the curve. You can also create additional nodes by clicking on a curve segment between two nodes. With ctrl-click you generate a new node at the x-location of the mouse pointer and the corresponding y-location of the current curve – this adds a node without risking to accidentally modify the curve. In order to remove a node move it outside of the widget area.
Tip: If you intend to take full manual control of the tonal values with the tone curve module or the zone system module (see Section 126.96.36.199, “Tone curve” and Section 188.8.131.52, “Zone system”) it may be easier to leave the image in linear RGB. Disable the base curve module in this case.
This combobox toggles between “linear” and “logarithmic” view. In the double logarithmic view more space is given to the lower values allowing a more fine-grained adjustment of the shadows.
This control triggers the exposure fusion feature. You can choose to merge the image with one or two copies of itself after applying the current base curve and boosting its exposure by a selectable number of ev units. The resulting image is thus a combination of two or three different exposures of the original image. Use this to compress dynamic range for extremely underexposed images or for true HDR input. For best results, use the exposure module (see Section 184.108.40.206, “Exposure”) to apply a suitable adjustment for correctly exposed highlights.
|This module is used to tweak the exposure. It is directly linked to the histogram panel. If you correct exposure graphically, using the histogram (see Section 3.3.6, “Histogram”), you automatically activate the exposure module. The histogram simply acts as a view for the exposure module.||
You can activate multiple instances of this module each with different parameters acting on different parts of the image which you select by a drawn mask (see Section 3.2.4, “Multiple instances” and Section 3.2.7, “Drawn mask”). The histogram is always linked to the last instance in pixelpipe.
This module is responsible for one of the most basic steps in each raw image development. An exposure adjustment value allows you – within certain limits – to correct for under- or overexposure. A shift by 1EV is equivalent to a change of exposure time by a factor of 2.
Positive exposure corrections will make the image brighter. As a side effect noise level gets higher. Depending on the basic noise level of your camera and the ISO value of your image, positive exposure compensations with up to 1EV or 2EV still give reasonable results.
Negative exposure corrections will make the image darker. Given the nature of digital images this can not correct for fully blown out highlights but allows to reconstruct data in case that only some of the RGB channels are clipped (see also Section 220.127.116.11, “Highlight reconstruction”).
A black level adjustment is a basic tool to increase contrast and pop of an image. The value defines at what threshold dark gray values are cut off to pure black. Use with care as the clipped values can not be recovered in other modules further down the pixelpipe. Please also have a look at the tone curve module (see Section 18.104.22.168, “Tone curve”) and the levels module (see Section 22.214.171.124, “Levels”) which can produce similar results with less side effects as they come later in pixelpipe.
The exposure module has two modes of operation.
In “manual” mode you directly define the value for exposure correction that you want to apply to your image.
In “automatic” mode darktable analyses the histogram of your image. You select a reference point within the histogram as a percentile and define a target level – darktable automatically calculates the exposure compensation that is needed to shift the selected position to that target value. The computed exposure compensation value is displayed in the module's GUI for your information.
The “automatic” mode has a black level adjustment that works as in manual mode.
Automatic adjustment is only available for raw images. A typical use case is deflickering of time-lapse photographs. You apply an automatic exposure correction with the same set of parameters to all images of the series – differences in lighting get compensated so that the final video sequence does not show any flickering.
darktable can calculate correct black level and exposure values for your image based on the content of a rectangular area. The adjustment slider lets you define what percentage of bright values are to be clipped out in the calculation. Pressing the icon starts the calculation and lets you draw a rectangular area of your choice using your mouse. This feature is only available in “manual” mode.
Defines a location in the histogram for automatic exposure correction. A percentile of 50% denotes a position in the histogram where 50% of pixel values are below and 50% of pixel values are above. For more details see percentile . Only available in “automatic” mode.
|This module offers a very basic tool for adjusting an image's contrast, brightness and saturation.||
The module has sliders for each of the three affected attributes. In their neutral position (zero) the image remains unchanged. Shifting sliders left to negative values reduces contrast, brightness and saturation, respectively. Shifting right to positive values leads to an increase.
Much more versatility for contrast and brightness adjustment is offered by the tone curve, levels, and zone system modules (see Section 126.96.36.199, “Tone curve”, Section 188.8.131.52, “Levels”, and Section 184.108.40.206, “Zone system”). Likewise you may adjust color saturation in a more detailed way with the tone curve, color contrast, and color zones modules (see Section 220.127.116.11, “Tone curve”, Section 18.104.22.168, “Color contrast”, and Section 22.214.171.124, “Color zones”).
Due to the nature of digital sensors, overexposed highlights are lacking valid color information. Most frequently they appear neutral white or exhibit some color cast – depending on which other image processing steps are involved. This module can “heal” overexposed highlights by replacing their colors with better fitting ones. The module acts on highlight pixels whose luminance values exceed a user defined threshold. Replacement colors are taken from the neighborhood. Both, the spatial distance and the luminance distance (range) are taken into account for color selection.
As a limitation of the underlying algorithm reconstructed colors may sometimes be displayed incorrectly if you zoom into the image in the darkroom view. If this happens you might observe a magenta shift in highlight areas close to high contrast edges, or you might see colorless highlight areas if you combine this module with the “reconstruct color” method of the “highlight reconstruction” module (see Section 126.96.36.199, “Highlight reconstruction”). These artifacts only influence image display – the final output remains unaffected. It is recommended that you finetune the parameters of this module while viewing the full, not zoomed-in image.
The color reconstruction module replaces the color of all target pixels characterized by luminance values above this threshold. Inversely, only pixels with luminance values below this threshold are taken as valid source pixels for replacement colors. Too high settings of this parameter will cause the module to have no effect on any pixels. Too low values will minimize the “pool” of replacement colors – if no suited ones are available the original colors are maintained. Therefore, this parameter exhibits a “sweet spot” characteristic with an optimum setting depending on the individual image.
Defines the spatial distance (x,y-coordinates) that source pixels may have from a target pixel in order for them to contribute to color replacement. Higher values cause ever more distant pixels to contribute; this increases the chance to find a replacement color but makes that color more undefined and less clear.
Defines the range distance (difference in luminance values) that source pixels may have from target pixels in order for them to contribute to color replacement. Higher values cause more pixels to contribute even if their luminance differs more strongly from the target pixels; this again increases the chance to find a replacement color but at the same time increases the risk of unfitting colors creeping in.
This combobox defines if certain replacement colors shall take precedence over others. In its default setting “off ” all pixels contribute equally. Setting it to “saturated colors” makes pixels contribute according to their chromaticity – the higher saturated a color the more it contributes. By selecting “hue” you get a choice of giving precedence to a specific hue.
This slider is visible if you set the preference combobox to “hue”. It allows you to select a preferred hue of replacement colors. This only has an effect if the preferred hue is actually present within the selected spatial and range distance of the target pixels (see above). A typical use case is repairing highlights on human skin in situations where diverging colors are in close proximity (e.g. textiles or hair with a luminance close to skin). Setting a hue preference on skin tones avoids these other colors from creeping in.
Demosaic is an essential step of any raw image development process.
A detailed description would be beyond the scope of this manual. In a nutshell, the sensor cells of a digital camera are only able to record different levels of lightness, not different color. In order to get a color image, each cell is covered by a color filter, either in red, green or blue. Due to the color sensitivity of the human vision, there are two times more green cells than red or blue. Filters are arranged in a certain mosaic, called Bayer pattern. Therefore each pixel of your image originally only has information about one color channel. Demosaic reconstructs the missing color channels by interpolation with data of the neighboring pixels. For further reading see the Wikipedia article on the Bayer filter.
As interpolation is prone to produce artifacts, various different demosaic algorithms have been developed in the past. Artifacts would typically be visible as moiré-like patterns when you strongly zoom into your image. Currently darktable supports PPG, AMAZE, and VNG4. All these algorithms produce high quality output with a low tendency to artifacts. AMAZE is reported to sometimes give slightly better results. However, as AMAZE is significantly slower, darktable uses PPG as a default. VNG4 produces the softest results of the three algorithms, but if you see "maze" artifacts, try VNG4 to eliminate them.
There are a few cameras whose sensors do not use a Bayer filter. Cameras with an "X-Trans" sensor have their own set of demosaicing algorithms. The default algorithm for X-Trans sensors is Markesteijn 1-pass, which produces fairly good results. For a bit better quality (at the cost of much slower processing), choose Markesteijn 3-pass. Though VNG demosaic is faster than Markesteijn 1-pass on certain computers, it is more prone to demosaicing artifacts.
Additionally, darktable supports a special demosaicing algorithm – passthrough (monochrome). It is not a general-purpose algorithm that is useful for all the images. It is only useful for cameras with the color filter array physically removed from the sensor, e.g. physically scratched off. Normally, demosaic reconstructs the missing color channels by interpolation with data of the neighboring pixels. But since the color filter array is not present, there is nothing to interpolate, so this algorithm simply sets all the color channels to the same value, which results in pixels being gray, thus producing a monochrome image. This method guarantees that there are no interpolation artifacts that would otherwise be present should one of the standard demosaicing algorithm be used.
Some further parameters of this module can activate additional averaging and smoothing steps. They might help to reduce remaining artifacts in special cases.
Demosaic is always applied when exporting images. Demosaic is done on monitor display only when zoom is greater than 50% or when the according preference setting “demosaicing for zoomed out darkroom mode” (see Section 8.2, “Core options”) is set accordingly. Else color channels are taken from neighboring pixels without an expensive interpolation.
Set the demosaic method. darktable currently supports PPG, AMAZE, and VNG4 for Bayer sensors. For X-Trans sensors darktable supports VNG, Markesteijn 1-pass, and Markesteijn 3-pass.
Set the threshold for an additional median pass. Defaults to “0” which disables median filtering. This option is not shown for X-Trans sensors.
|This module tries to reconstruct color information that is usually clipped because of incomplete information in some of the channels. If you do nothing, your clipped areas are often toned to the not clipped channel. For example, if your green and blue channels are clipped, then your image will appear red in the clipped areas.||
You can choose between three methods for highlight reconstruction.
“Clip highlights” just clamps all the pixels to the white level. Effectively this converts all clipped highlights to neutral grey tones. This method is most useful in cases where clipped highlights occur in non-colored areas like clouds in the sky.
“Reconstruct in LCh” analyses each pixel having at least one channel clipped and transforms the information in LCh color space in an attempt to correct the clipped pixel using the values of the other (3 for Bayer or 8 for X-Trans) pixels in the affected sensor block. This method usually does a better job than “Clip highlights” as some details in the clipped areas are preserved. However it is incapable to reconstruct any color information – the reconstructed highlights will all be monochrome, but brighter and with more detail than with “Clip highlights”. This method works fairly well with a high-contrast base curve (such as most manufacturers apply to their JPEG), which renders highlights desaturated. This method is a good option on naturally desaturated objects such as clouds.
“Reconstruct color” uses an algorithm that transfers color information from the unclipped surroundings into the clipped highlights. This method works very well on areas with homogeneous colors and is especially useful on skin tones with smoothly fading highlights. It fails in certain cases where it produces maze-like artifacts at highlights behind high-contrast edges, such as fine, well-exposed structures in front of overexposed background (for instance ship masts or flags in front of the blown-out sky).
Tip: for highlight reconstruction to be effective you need to apply a negative EV correction in the exposure module (see Section 188.8.131.52, “Exposure”). If you want to avoid a general darkening of your image you can use darktable's mask feature in that module to limit the EV correction to only the highlights (see Section 3.2.7, “Drawn mask” and Section 3.2.8, “Parametric mask”).
|This module is used to set the white balance. You have three ways to interact with it: (a) Set up tint and temperature, (b) define the value of each channel, or (c) choose from predefined white balances.||
Alter the color tint of the image, from magenta (value < 1) to green (value > 1). The channel sliders will be updated when you adjust this parameter.
Set the color temperature (in Kelvin). The channel sliders will be updated when you adjust this parameter. darktable derives the color temperature from the Exif data using some model assumptions. The value given is not meant to be authoritative. In the end only the updated channel values determine how the image is modified.
Select a preset white balance.
|camera white balance (default)||White balance reported by the camera.|
|camera neutral||Essentially sets temperature to 6502K. The actual math: it computes such white balance channel multipliers, so that pure white color in camera colorspace is converted into pure white color in sRGB D65. (pure white color here means having the same equal value for each channel = 1.0)|
|spot white balance||Select a square area in your image containing mostly grey pixels. The white balance is calculated based on the selected area.|
|camera presets||Camera specific white balance presets. Examples: direct sunlight, flash, cloudy, shade and a number of indoor lighting options.|
The only control element of this module is a color selector which allows to adjust for different colors of your film material. Clicking on the colored field will open a color selector dialog which offers you a choice of commonly used colors, or allows to define a color in RGB color space. You can also activate a color picker by pressing and take a color probe from your image – preferably from the unexposed border of your negative.
|This module is activated automatically for raw images and makes sure that the camera specific black and white points are taken into account. Default settings are applied for all supported cameras. Changes to the defaults are normally not required.||
The camera specific black level of the four pixels in the RGGB Bayer pattern. Pixels with values lower than that level are considered to contain no valid data.
The camera specific white level. All pixels with values above are likely to be clipped and handled accordingly in the highlight reconstruction module (see Section 184.108.40.206, “Highlight reconstruction”). Pixels with values equal to the white level are considered to be white.