processing modules

This module has always been in the pixel pipeline but was hidden in darktable GUI. Ansel 0.0 exposes it to allow users to fix a mistake in the default pipeline order of darktable.

Remove image noise while preserving structure.

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 pixel being denoised. A patch with a defined size is used to measure that similarity.

As denoising is a resource-intensive process, it slows down pixelpipe processing significantly. Consider activating this module late in your workflow.

Simulate physically-accurate blurs in scene-referred RGB space.

Degrade parts of the image in an aesthetically pleasing way, in order to anonymize people/objects or hide body parts.

Censorize works in linear RGB color space to apply a physically-accurate gaussian blur and gaussian luminance noise.

Aside from anonymization, this module can also be used for a wide range of creative purposes, for example:

• Combine a simple blur with a multiply blend mode to create a realistic bloom (Orton effect).
• Combine a simple blur with a subtract blending mode and low opacity to create an unsharp mask , similar to the sharpen module but in an RGB scene-referred space.
• Add noise to create artificial grain.

Note: The anonymizing methods provided by this module are not forensically safe in order to favor aesthetics. Some forensic techniques may still be able to reconstruct the censorized content based on its structure, especially for simple shapes and text (e.g. license plates, street numbers).

Correct chromatic aberrations.

In contrast to the raw chromatic aberrations module, this module does not require raw data as input.

An advanced module which brings color-grading tools from cinematography into the photographic scene-referred pipeline.

This module is not suitable for beginners with no prior knowledge of color theory, who might want to stick to the global chroma and global vibrance settings until they have a good understanding of the dimensions of color.

A fully-featured color-space correction, white balance adjustment and channel mixer module.

This simple yet powerful module can be used in the following ways:

• To adjust the white balance (chromatic adaptation), working in tandem with the white balance module. Here, the white balance module makes some initial adjustments (required for the demosaic module to work effectively), and the color calibration module then calculates a more perceptually-accurate white balance after the input color profile has been applied.

A generic color look up table implemented in Lab space.

The input to this module is a list of source and target points and the complete mapping is interpolated using splines. The resulting look up tables (LUTs) are editable by hand and can be created using the darktable-chart utility to match given input (such as hald-cluts and RAW/JPEG with in-camera processing pairs).

Recover color information in blown-out highlights.

Due to the nature of digital sensors, overexposed highlights lack valid color information. Most frequently they appear neutral white or exhibit some color cast, depending on what other image processing steps are involved. This module can be used to “heal” overexposed highlights by replacing their colors with better fitting ones. The module acts on pixels whose luminance exceeds a user-defined threshold. Replacement colors are taken from neighboring pixels. Both the spatial distance and the luminance distance (range) are taken into account for color selection.

Selectively adjust the lightness, saturation and hue of pixels based on their current lightness, saturation and hue.

This module works in CIE LCh color space, which separates pixels into lightness, chroma (saturation) and hue components. It allows you to manipulate the lightness, saturation and hue of targeted groups of pixels through the use of curves.

You first need to choose whether you wish to adjust (select) pixels based on their lightness, saturation or hue. You can then use three curves, on their respective tabs, to adjust the lightness, saturation and hue of ranges of pixels selected via this method.

Adjust luminance and chroma contrast in the wavelet domain.

This versatile module can be used to achieve a variety of effects, including bloom, denoise, clarity, and local contrast enhancement.

It works in the wavelet domain and its parameters can be tuned independently for each wavelet detail scale. The module operates in CIE LCh color space and so is able to treat luminosity and chromaticity independently.

A number of presets are provided, which should help you to understand the capabilities of the module.

Crop an image using on-screen guides.

This module appears late in the pipeline, meaning that the full image can remain available for source spots in the retouch module. For best results, you are advised to use the rotate and perspective module to perform rotation and perspective correction (if required), and then perform final creative cropping with this module.

Whenever this module is in focus, the full uncropped image will be shown, overlaid with crop handles and optional guiding lines.

Control how raw files are demosaiced.

An easy to use and highly efficient denoise module, adapted to the individual noise profiles of a wide range of camera sensors.

One issue with a lot of denoising algorithms is that they assume that the variance of the noise is independent of the luminosity of the signal. By profiling the noise characteristics of a camera’s sensor at different ISO settings, the variance at different luminosities can be assessed, and the denoising algorithm can be adjusted to more evenly smooth out the noise.

Diffusion is a family of physical processes by which particles move and spread gradually with time, from a source that generates them. In image processing, diffusion mostly occurs in two places:

• diffusion of photons through lens glass (blur) or humid air (hazing),
• diffusion of pigments in wet inks or watercolors.

In both cases, diffusion makes the image less sharp by “leaking” particles and smoothing local variations.

The diffuse or sharpen module uses a generalized physical model to describe several kinds of diffusion, and can be used by image makers to either simulate or revert diffusion processes.

This module eliminates some of the banding artifacts that can result when Ansel’s internal 32-bit floating point data is transferred into discrete 8-bit or 16-bit integer output format for display or export.

Although not an inherent problem in any of Ansel’s modules, some operations may provoke banding if they produce a lightness gradient in the image. To mitigate possible artifacts you should consider activating dithering when using the vignetting or graduated density modules. This is especially relevant for images with extended homogeneous areas such as cloudless sky. Also watch out for banding artifacts when using a gradient drawn mask.

Increase or decrease the overall brightness of an image.

This module has two modes of operation:

manual

Set the exposure, black level and clipping threshold manually

automatic (RAW images only)

Use an analysis of the image’s histogram to automatically set the exposure. Ansel automatically selects the exposure compensation that is required to shift the selected percentile to the selected target level (see definitions below). This mode is particularly useful for automatically altering a large number of images to have the same exposure. A typical use case of automatic mode is deflickering of time-lapse photographs.

Remap the tonal range of an image by reproducing the tone and color response of classic film.

This module can be used either to expand or to contract the dynamic range of the scene to fit the dynamic range of the display. It protects colors and contrast in the mid-tones, recovers the shadows, and compresses bright highlights and dark shadows. Highlights will need extra care when details need to be preserved (e.g. clouds).

Generate a frame around the image.

The frame consists of a border (with a user-defined color) and a frame line within that border (with a second user-defined color). Various options are available to control the geometry and color of the frame.

Simulate a graduated density filter in order to correct exposure and color in a progressive manner.

A line is shown on screen allowing the position and rotation of the gradient to be modified with the mouse.

This module is known to provoke banding artifacts under certain conditions. You should consider activating the dithering module to alleviate these issues.

Simulate the grain of analog film. The grain is processed on the L channel of Lab color space.

Automatically reduce the effect of dust and haze in the atmosphere. This module may also be employed more generally to give pictures a color boost specifically in low-contrast regions of the image.

Haze absorbs light from objects in the scene but it is also a source of diffuse background light. The haze removal module first estimates, for each image region, the amount of haze in the scene. It then removes the diffuse background light according to its local strength and recovers the original object light.

Attempt to reconstruct color information for pixels that are clipped in one or more RGB channel.

If these pixels are left partially clipped it can result in unrealistic colors appearing in the image. For example pixels with both green and blue channels clipped will appear to be red without any highlight reconstruction.

Three methods of reconstruction are available:

clip highlights

Clamp all pixels to the white level (i.e. clip the remaining color channels). This method is most useful in cases where clipped highlights occur in naturally desaturated objects (e.g. clouds).

reconstruct in LCh

Analyse each pixel with at least one clipped channel and attempt to correct the clipped pixel (in LCh color space) using the values of the other (3 for Bayer or 8 for X-Trans) pixels in the affected sensor block. The reconstructed highlights will still be monochrome, but brighter and with more detail than with “clip highlights”. This method works fairly well with a high-contrast base curve, which renders highlights desaturated. As with clip highlights this method is a good option for naturally desaturated objects.

reconstruct color

Use an algorithm that transfers color information from 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. Please note that this method can produce maze-like artifacts on highlights behind high-contrast edges, for example well-exposed fine structures in front of an overexposed background.

guided laplacians

Use an algorithm (derived from the diffuse or sharpen module) to replicate details from valid channels into clipped channels and to propagate color gradients from valid surrounding regions into clipped regions. This is a slow and computationally-intensive method designed for maximum smoothness and seamless blending of the reconstructed regions into their neighborhood, and is designed primarily to reconstruct spotlights and specular reflections. This mode is available for Bayer sensors only.

Note: When using the highlight reconstruction included with the filmic rgb module it may be useful to avoid using this module in clip highlights mode (so that filmic rgb has more information to work with).

Automatically detect and eliminate hot pixels.

Hot pixels are pixels which have failed to record a light level correctly. Detected hot pixels are replaced by an average of their neighbors.

Define how Ansel will interpret the colors of the image.

This module takes the color space used by the image source (e.g. camera, scanner) and converts the pixel encodings to a standardized working color space. This means that subsequent modules in the pipeline don’t need to be concerned with the specifics of the input device, and can work with and convert to/from a common working color space.

Where an image has been captured in a raw file, the input color profile module will normally apply either a standard or enhanced color matrix specific for that camera model, which will be used to map the colors into the working profile color space. If color space information is embedded in the image, the input color profile module will use this information when mapping the colors to the working profile color space. The user can also explicitly specify a color space for the incoming image, and can even supply a custom ICC color profile specifically made for the input device.

Automatically correct for (and simulate) lens distortion, transversal chromatic aberrations (TCA) and vignetting.

This module identifies the camera/lens combination from the image’s Exif data and uses the external lensfun library  to provide correction parameters.

If your system’s lensfun library has no correction profile for the automatically identified camera/lens combination, the controls for the three photometric parameters (below) are replaced with a warning message. You may try to find the right profile yourself by searching for it in the menu.

Move pixels around by applying freestyle distortions to parts of the image using points, lines and curves.

Enhance the image’s local contrast.

This is achieved using either a local laplacian (default) or unnormalized bilateral filter. Both modes work exclusively on the L channel from Lab. The local laplacian filter has been designed to be robust against unwanted halo effects and gradient reversals along edges.

Transform RGB values with a 3D LUT file.

A 3D LUT is a tridimensional table that is used to transform a given RGB value into another RGB value. It is normally used for film simulation and color grading.

This module accepts .cube, .3dl, .png (haldclut) and .gmz files. Uncompressed 3D LUT data is not saved in the database or the XMP file, but is instead saved to the 3D LUT file path inside the 3D LUT root folder. It is therefore important to back up your 3D LUT folder properly – sharing an image with its XMP is pointless if the recipient doesn’t also have the same 3D LUT file in their own 3D LUT folder.

Process scanned film negatives.

You can obtain an image of a negative using a film scanner, or by photographing it against a white light (e.g. a light table or computer monitor) or off-camera flash.

Rotate the image 90 degrees at a time or flip the image horizontally and/or vertically.

The module is enabled by default and the orientation (rotation) is automatically set based on the image’s Exif data.

The orientation can also be set using the selected images module in the lighttable view.

Manage the output profile for export and the rendering intent to be used when mapping between color spaces.

Ansel comes with pre-defined profiles sRGB, Adobe RGB, XYZ and linear RGB. You can provide additional profiles by placing them in $Ansel/share/Ansel/color/out and $HOME/.config/Ansel/color/out (where $Ansel is the Ansel installation directory and $HOME is your home directory).

The output color profile may also be defined within the export module.

Define camera-specific black and white points.

This module is activated automatically for all raw images. Default settings are applied for all supported cameras. Changes to the defaults are not normally required.

Correct chromatic aberrations of raw images.

As this module operates on non-demosaiced raw data, the underlying model assumes an uncropped photographic image as input. It is therefore likely to fail when you zoom in, as it is only able to operate on the visible portion of the image. The module will therefore be bypassed at high zoom levels, and a “bypassed” message will appear at the top of the module. This limitation only applies to interactive work and not to the final export.

Perform denoising on raw image data before it is demosaiced.

This module has been ported from dcraw .

Remove unwanted elements from your image by cloning, healing, blurring and filling using drawn shapes.

This module includes a “heal” tool (based on the heal tool from GIMP), as well as “fill” and “blur” modes. It can also take advantage of wavelet decomposition, allowing the image to be separated into layers of varying detail (from coarse to fine) which can be selectively retouched before being recombined to produce the output image.

A classic digital photography tool to alter an image’s tones using curves.

Activate the color picker on the left to show the picked values in the graph (Ctrl+click or right-click to use the picker in area mode). Numerical (Lab) values of the input and output (see below) at the selected spot or area are shown at the top left of the widget.

A second color picker to the right can be used to automtaically create new nodes based on the sampled area. Ctrl+click+drag to alter the created nodes to have a positive curve for the selected area; Shift+click+drag to create a negative curve.

Adjust black, white and mid-gray points in RGB color space.

The rgb levels tool shows a histogram of the image, and displays three bars with handles. Drag the handles to modify the black, middle-gray and white points in lightness (in “RGB, linked channels” mode) or independently for each of the R, G and B channels (in “RGB, independent channels” mode).

Moving the black and white bars to match the left and right borders of the histogram will make the output image span the full available tonal range. This will increase the image’s contrast.

Automatically correct for converging lines, a form of perspective distortion. The underlying mechanism is inspired by Markus Hebel’s ShiftN  program. This module also allows for the rotation of the image to be adjusted.

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, are transformed into converging lines that meet at some vantage point within or outside of the image frame.

The sensors of some cameras (such as 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 required rotation.

Ansel detects images that need correction using their Exif data and automatically activates this module where required. For other images the module always remains disabled.

The module has no controls.

Some cameras (such as the Nikon D1X) have rectangular instead of the usual square sensor cells. Without correction this would lead to distorted images. This module applies the required scaling.

Ansel detects images that need correction using their Exif data and automatically activates this module where required. For other images the module always remains disabled.

The module has no controls.

Sharpen the details in the image using a standard UnSharp Mask (USM).

This module works by increasing the contrast around edges and thereby enhancing the impression of sharpness of an image. This module is applied to the L channel in Lab color space.

Note: The USM algorithm used in this module performs blurs in Lab color space, which can produce undesirable effects, and is no longer recommended. Instead use the presets offered by the contrast equalizer module for deblurring or the local contrast module for general sharpness.

Smooth image surfaces while preserving sharp edges using a bilateral filter.

This module can be used to denoise images, however you should be aware that bilateral filters are susceptible to overshoots and Ansel offers much better alternatives. For example, the astrophoto denoise module uses a non-local means denoising algorithm, and the denoise (profiled) module provides a choice between non-local means and wavelet denoising algorithms.

The surface blur module blurs noise within the surfaces of an image by averaging pixels with their neighbors, taking into account not only their geometric distance but also their distance on the range scale (i.e. differences in their RGB values). It can be particularly useful if one RGB channel is more noisy/needs more smoothing than the others. In such a case, use the color calibration module to examine the channels one by one, in order to set the blur intensities accordingly.

Dodge and burn while preserving local contrast.

It works in linear RGB space and utilizes a user-defined mask to guide the dodging and burning adjustments, helping to preserve local contrast within the image.

The following diagram describes how the tone equalizer works:

Add a correction curve to image data. This is required if you have selected certain input profiles in the input color profile module.

If you decide to use an ICC profile from the camera manufacturer in the input color profile module, a correction curve frequently needs to be pre-applied to image data to prevent the final output from looking too dark. This extra processing is not required if you use Ansel’s standard or enhanced color matrices.

Apply a vignetting effect to the image.

Vignetting is a modification of the brightness and saturation at the borders of the image in a specified shape. Many of the parameters listed below can also be modified with a graphical control that overlays the image when the module has focus, showing the shape and extent of the effect.

Note: This module is known to provoke banding artifacts under certain conditions. You should consider activating the dithering module to alleviate this.

Render a vector-based overlay onto your image. Watermarks are standard SVG documents and can be designed using Inkscape .

You can also use bitmap (PNG) images.

The SVG processor in Ansel can also substitute strings within an SVG document, allowing image-dependent information to be included in the watermark.

User-designed watermarks should be placed into the directory $HOME/.config/Ansel/watermarks. Once in place, use the reload button update the list of available watermarks.

Adjust the white balance of the image by altering the temperature and tint, defining a coefficient for each RGB channel, or choosing from list of predefined white balance settings.

The default settings for this module are derived from the camera white balance stored in the image’s Exif data.

White balance is not intended as a “creative” module – its primary goal is to technically correct the white balance of the image ensuring that neutral colored objects in the scene are rendered with neutral colors in the image. For creative color operations, it is usually better to use other modules such as color calibration or color balance rgb.