## 3.4. Modules

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.

### 3.4.1. Basic 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.

#### 3.4.1.1. Crop and rotate

##### Overview
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”).

##### Usage

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.

###### flip

This tool is used to flip the image on the horizontal,vertical or both axis.

###### angle

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.

###### keystone

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.

###### automatic cropping

Use this options to avoid black edges on the image borders. Useful when you rotate the image.

###### aspect

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

plugins/darkroom/clipping/extra_aspect_ratios/foo=x:y


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.

###### guides flip

In case the chosen guidelines are not symmetrical relative to the image frame, you can flip them on the horizontal,vertical or both axis.

##### Examples

A cropped image in center view when module crop and rotate is in focus. The cropped area is visible as well as some guiding lines.

#### 3.4.1.2. Orientation

##### Overview
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.
##### Usage
###### rotate

Clicking on one of the buttons causes a counter-clockwise or clockwise rotation in steps of 90 degrees.

##### Overview
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.
##### Usage

This slider controls the effect on shadows; positive values will lighten up shadows while negative values will darken them.

###### highlights

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.

###### soften with

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.

###### compress

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.

##### Examples

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%.
Resulting image.

#### 3.4.1.4. Base curve

##### Overview
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.
##### Usage

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 3.4.2.3, “Tone curve” and Section 3.4.2.4, “Zone system”) it may be easier to leave the image in linear RGB. Disable the base curve module in this case.

###### scale

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.

###### fusion

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 3.4.1.5, “Exposure”) to apply a suitable adjustment for correctly exposed highlights.

###### exposure shift

This slider is only visible if the exposure fusion feature is activated. It allows you to set the exposure difference between the merged images in ev units (default 3).

#### 3.4.1.5. Exposure

##### Overview
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.

##### Usage

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 3.4.1.9, “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 3.4.2.3, “Tone curve”) and the levels module (see Section 3.4.2.2, “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.

###### mode

Defines the mode of operation. Defaults to manual.

###### black

Adjust the black level in both manual and automatic mode.

###### exposure

Adjust the exposure correction [EV] (only available in manual mode).

###### clipping threshold

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.

###### percentile

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.

###### target level

Defines the target level for automatic exposure correction in terms of [EV] relative to the white point of the camera. The white point is camera specific and defines the highest lightness value that the camera sensor can detect. Only available in automatic mode.

#### 3.4.1.6. Contrast Brightness Saturation

##### Overview
This module offers a very basic tool for adjusting an image's contrast, brightness and saturation.
##### Usage

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 3.4.2.3, “Tone curve”, Section 3.4.2.2, “Levels”, and Section 3.4.2.4, “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 3.4.2.3, “Tone curve”, Section 3.4.3.4, “Color contrast”, and Section 3.4.3.8, “Color zones”).

###### contrast

This slider adjusts the image's contrast.

###### brightness

This slider adjusts the image's brightness.

###### saturation

This slider adjusts the color saturation.

#### 3.4.1.7. Color reconstruction

##### Overview
The color reconstruction module is able to bring back color into blown out highlights.
##### Usage

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 3.4.1.9, “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.

###### threshold

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.

###### spatial extent

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.

###### range extent

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.

###### preference

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.

###### 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.

##### Examples

Original image with overexposed highlights on head, arm and shoulder of the statue.
Color reconstruction with default settings of all module parameters.

#### 3.4.1.8. Demosaic

##### Overview
This module allows you to control how the demosaic is processed.
##### Usage

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.

###### method

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.

###### edge threshold

Set the threshold for an additional median pass. Defaults to 0 which disables median filtering. This option is not shown for X-Trans sensors.

###### color smoothing

Activates a number of additional color smoothing passes. Defaults to off.

###### match greens

In some cameras the green filters have slightly varying properties. This parameter adds an additional equalization step to suppress artifacts. Available options are disabled, local average, full average and full and local average. This option is not shown for X-Trans sensors.

#### 3.4.1.9. Highlight reconstruction

##### Overview
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.
##### Usage

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 3.4.1.5, “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”).

###### method

Choose the method for highlight reconstruction.

###### clipping threshold

Manually adjust the clipping threshold against magenta highlights. The default is usually satisfactory without any need for additional adjustments.

#### 3.4.1.10. White balance

##### Overview
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.
##### Usage
###### tint

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.

###### temperature

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.

###### red, green and blue channels

Set the channel values on a scale from 0 to 8.

###### preset

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.

###### finetune

Some cameras offer additional finetuning parameters if one of the camera presets is selected. Depending on camera white balance, can be adjusted in steps within a certain range. The adjustments are usually towards yellow (value < 1) or blue (value > 1).

#### 3.4.1.11. Invert

##### Overview
The main purpose of this module is to invert scanned negatives.
##### Usage
###### color of film material

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.

#### 3.4.1.12. Raw black/white point

##### Overview
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.
##### Usage
###### black level 0 to 3

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.

###### white point

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 3.4.1.9, “Highlight reconstruction”). Pixels with values equal to the white level are considered to be white.