darktable on darktable 5.6 user manual

overview

Mon, 01 Jan 0001 00:00:00 +0000

This page defines the style guide for dtdocs and information about how to contribute to the project.

It is included in the user manual so that you can see how the page is rendered as well as how it is written. Please go to GitHub to see the source for this page.

The manual structure and content have been carefully considered based on the following criteria:

The manual should be comprehensive – it should describe all of the functionality available in darktable
It should have a consistent and logical structure and every piece of functionality should have its own logical place within that structure
It should be as long as necessary but as short as possible – brevity is a must
It should be objective
Functionality should be explained once and only once (with the exception of the basic workflow guidelines in the overview section)
Images should be included only where necessary to improve understanding of key principles and should not contain text unless it is unavoidable

We are generally not interested in:

development & deployment

Mon, 01 Jan 0001 00:00:00 +0000

darktable’s documentation is maintained in the dtdocs repository. Changes are introduced through pull requests (see workflow). Translations are maintained through weblate; see translations.

🔗Building

The full set of outputs (HTML site, EPUB, and per-language PDFs) is built by ./tools/build-all.sh <base_url>

This generates the translated content from the PO files, then builds the HTML site, the EPUB, and one PDF per enabled language. Outputs are written under public/, with PDFs at public/<lang>/darktable_user_manual.pdf.

Requirements: Hugo (extended), weasyprint, and po4a for the translation step.

invocation per OS

Mon, 01 Jan 0001 00:00:00 +0000

darktable and the other binaries (e.g. darktable-cltest) can be executed from the console as follows:

Linux

Installed as package or snap: darktable
Flatpak: flatpak run org.darktable.Darktable
- To run e.g. darktable-cltest: flatpak run --command=darktable-cltest org.darktable.Darktable --arguments-go-here.
AppImage: Navigate to containing folder, then ./darktable.Appimage (or however you named the file)
- To run e.g. darktable-cltest: ./darktable.Appimage darktable-cltest
- An additional option to run the various binaries included in darktable (e.g. darktable-cltest or darktable-cli) is through a symbolic link:
  - Create a symbolic link to your AppImage and call it e.g. darktable-cli.
  - Then, when calling the AppImage through the symbolic link with ./darktable-cli, the code inside the package checks if there is a binary file inside the AppImage with a name that matches the symlink name. If so, it will be run instead of the default one.

Windows

workflow

Mon, 01 Jan 0001 00:00:00 +0000

These instructions assume that you already have a github account and have installed Git as well. Make sure that git is in your PATH by executing the command git in any terminal or cmd and checking that it doesn’t output an error such as “command not found”. If you don’t have git installed, follow these instructions.

🔗Documenting undocumented features

We are particularly interested in documenting closed pull requests that require additions or changes to this manual. Pull requests that require documentation are cataloged with a GitHub label documentation: pending.

AgX

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: applies a tone mapping curve. inspired by Blender’s AgX tone mapper.
purpose: corrective and creative.
input: linear, RGB, scene-referred.
processing: non-linear, RGB.
output: linear, RGB, display-referred.

Transform the colors and tonal range of an image to fit a display.

The primary innovation of the AgX module is an advanced color handling method that ensures a natural and film-like appearance, preventing the oversaturation artifacts common with simpler tone mapping techniques. It is derived from the display transform of the same name, used in the Blender 3D modeler by T. J. Sobotka, Eary_Chow, Sakari Kapanen and others.

astrophoto denoise

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: apply a poisson noise removal best suited for astrophotography.
purpose: corrective.
input: non-linear, Lab, display-referred.
processing: non-linear, Lab.
output: non-linear, Lab, display-referred.

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.

base curve

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: apply a view transform based on personal or camera maker look, for corrective purposes, to prepare images for display.
purpose: corrective.
input: linear, RGB, display-referred.
processing: non-linear, RGB.
output: non-linear, RGB, display-referred.

Simulate the in-camera JPEG by applying a characteristic base curve to the image.

darktable comes with a number of base curve presets that attempt to mimic the curves of various camera manufacturers. These presets are automatically applied according to the “maker ID” found in the image’s Exif data. Camera-specific base curve presets are also available for some camera models.

bloom

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: apply Orton effect for a dreamy ethereal look.
purpose: creative.
input: non-linear, Lab, display-referred.
processing: non-linear, Lab.
output: non-linear, Lab, display-referred.

Create a soft bloom effect.

This module works by blurring the highlights and then blending the result with the original image.

Note: This module performs blurs in Lab color space, and is no longer recommended. Instead, use the tone equalizer module or the exposure module with a parametric mask.

blurs

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: simulate physically-accurate lens and motion blurs.
purpose: creative.
input: linear, RGB, scene-referred.
processing: linear, RGB.
output: linear, RGB, scene-referred.

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

🔗blur types

Three types of blur are provided:

lens blur: Simulates a lens diaphragm with a configurable number of blades and blade curvature to create synthetic bokeh.
motion blur: Simulates the effect of camera motion with a configurable path.
gaussian blur: This is not really an optical blur but can be used for denoising or for creative effects using blend modes

A diagram at the top of the module shows the shape of the blurring operator (known as the point spread function). The module will turn each luminous point from the scene into a blot shaped like the displayed blurring operator, with the size of the blot defined by the blur radius.

censorize

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: censorize license plates and body parts for privacy.
purpose: creative.
input: linear or non-linear, RGB, scene-referred.
processing: frequential, RGB.
output: special, RGB, scene-referred.

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:

chromatic aberrations

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: correct chromatic aberrations.
purpose: corrective.
input: linear, RGB, scene-referred.
processing: linear, RGB.
output: linear, RGB, scene-referred.

Correct chromatic aberrations.

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

🔗workflow

To obtain the best result, you are advised to proceed as follows:

Attenuate the chromatic aberrations as much as possible in the lens correction module using the TCA sliders.
Increase the strength slider in this module to better see its effect.
Increase the radius until the chromatic aberrations disappear. If this is insufficient, try enabling the “very large chromatic aberrations” setting.
Choose the guide that gives the best result in term of sharpness and artifacts.
Reduce the strength to avoid washing out the colors too much.

For more complicated cases you could also try the following:

color balance

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: shift colors selectively by luminance range.
purpose: corrective or creative.
input: linear, Lab, scene-referred.
processing: non-linear, RGB.
output: non-linear, Lab, scene-referred.

A versatile tool for adjusting the image’s color balance.

This module can be used to revert parasitic color casts or to enhance the visual atmosphere of an image using color grading, a popular technique in the cinema industry. For scene-referred workflow, you should consider using the improved color balance rgb module instead.

color balance rgb

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: color grading tools using alpha masks to separate shadows, mid-tones and highlights.
purpose: corrective or creative.
input: linear, RGB, scene-referred.
processing: non-linear, RGB.
output: non-linear, RGB, scene-referred.

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.

color calibration

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: perform color space corrections such as white balance, channels mixing and conversions to monochrome emulating film.
purpose: corrective or creative.
input: linear, RGB, scene-referred.
processing: linear, RGB or XYZ.
output: linear, RGB, scene-referred.

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.

color contrast

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: increase saturation and separation between opposite colors.
purpose: creative.
input: non-linear, Lab, display-referred.
processing: non-linear, Lab.
output: non-linear, Lab, display-referred.

A simplified control for changing the contrast or separation of colors between the green/magenta and blue/yellow axes in Lab color space. Higher values increase color contrast, lower values decrease it.

🔗module controls

green-magenta contrast: Change the green-magenta color contrast. This is equivalent to raising or lowering the steepness of the a* curve in Lab. Lower values desaturate greens and magenta, while higher values increase their saturation.
blue-yellow contrast: Change the blue-yellow color contrast. This is equivalent to raising or lowering the steepness of the b* curve in Lab. Lower values desaturate blues and yellows, while higher values increase their saturation.

color correction

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: correct white balance selectively for blacks and whites.
purpose: corrective or creative.
input: non-linear, Lab, display-referred.
processing: non-linear, Lab.
output: non-linear, Lab, display-referred.

Modify the global image saturation to give the image a tint or as an alternative method to split-tone the image.

Note: Use the color balance rgb module for color modifications.

🔗module controls

color board: For split toning move the white dot to the desired highlight tint and then select a tint for shadows with the dark spot. For a simple global tint set both spots to the same color.
saturation: Correct the global saturation.

color equalizer

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: change saturation, hue and brightness depending on local hue.
purpose: corrective and creative.
input: linear, RGB, scene-referred.
processing: quasi-linear, RGB.
output: quasi-linear, RGB, scene-referred.

Selectively adjust the hue, saturation, and/or brightness of pixels based on their current hue.

This module is an attempt to recreate some of the functionality of the color zones module in the scene-referred part of the pipeline whilst overcoming some of that module’s limitations. Specifically, the color zones module is prone to increase chroma/luma noise, and introduce artifacts or harsh transitions. These are somewhat mitigated within color equalizer with the following additions:

color harmonizer

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: harmonize colors toward a selected palette in perceptual space.
purpose: creative color grading.
input: linear, RGB, scene-referred.
processing: darktable UCS / JCH (perceptual).
output: linear, RGB, scene-referred.

The color harmonizer reduces chromatic dissonance by pushing hues toward a selected color palette. This palette is defined by a set of hue angles called harmony nodes. Colors that are “off-palette” are gently pulled toward the nearest node; colors already on a node are left unchanged. A per-node saturation multiplier can additionally boost or reduce the colorfulness of colors near each node.

color look up table

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: perform color space corrections and apply looks.
purpose: corrective or creative.
input: linear or non-linear, Lab, display-referred.
processing: defined by profile, Lab.
output: linear or non-linear, Lab, display-referred.

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). See using darktable-chart for details.

color mapping

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: transfer a color palette and tonal repartition from one image to another.
purpose: creative.
input: linear or non-linear, Lab, display-referred.
processing: non-linear, Lab.
output: non-linear, Lab, display-referred.

Transfer the look and feel of one image to another.

This module statistically analyses the color characteristics of a source and target image. The colors of the source image are then mapped to corresponding colors on the target image.

Two steps are required to use this module:

color reconstruction

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: recover clipped highlights by propagating surrounding colors.
purpose: corrective.
input: linear or non-linear, Lab, display-referred.
processing: non-linear, Lab.
output: non-linear, Lab, display-referred.

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.

color zones

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: selectively shift hues, chroma and lightness of pixels.
purpose: creative.
input: linear or non-linear, Lab, display-referred.
processing: non-linear, Lab.
output: non-linear, Lab, display-referred.

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

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

colorize

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: overlay a solid color on the image.
purpose: creative.
input: linear or non-linear, Lab, display-referred.
processing: non-linear, Lab.
output: non-linear, Lab, display-referred.

Add a solid layer of color to the image.

🔗module controls

hue: The hue of the color layer.
saturation: The saturation of shadow tones.
lightness: The lightness of the color layer.
source mix: Controls how the lightness of the input image is mixed with the color layer. Setting this to zero will result in a uniformly colored plane.

composite

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: combine the image with elements from another processed image (move this module to after output color profile if you see banding).
purpose: corrective and creative.
input: linear, RGB, scene-referred.
processing: linear, RGB.
output: linear, RGB, scene-referred.

Create a composite image by overlaying an already-processed image on top of the current image.

Drag and drop a processed image from the filmstrip onto the “drop image from filmstrip here” box to overlay the chosen image, and then alter the various placement and adjustment attributes of the image being overlaid.

contrast equalizer

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: add or remove local contrast, sharpness, acutance.
purpose: corrective and creative.
input: linear, Lab, scene-referred.
processing: frequential, RGB.
output: linear, Lab, scene-referred.

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.

crop

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: change the framing.
purpose: corrective or creative.
input: linear, RGB, scene-referred.
processing: geometric, RGB.
output: linear, RGB, scene-referred.

Crop an image using on-screen guides.

This module appears later in the pipeline than the deprecated crop and rotate module, 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.

darktable

Mon, 01 Jan 0001 00:00:00 +0000

The darktable binary starts darktable with its GUI and full functionality. This is the standard way to use darktable. The command to run the binary depends on your OS.

The following command line parameters are available:

darktable [-d {all,act_on,ai,cache,camctl,camsupport,common,control,
               dev,expose,fswatch,imageio,input,ioporder,lighttable,lua,
               masks,memory,nan,opencl,params,perf,pipe,print,pwstorage,
               signal,sql,tiling,undo,verbose}]
          [--d-signal <signal>]
          [--d-signal-act <all,raise,connect,disconnect,print-trace>]
          [--disable-pipecache]
          [<input file>|<image folder>]
          [--version]
          [--disable-opencl]
          [--configdir <user config directory>]
          [--library <library file>]
          [--datadir <data directory>]
          [--moduledir <module directory>]
          [--tmpdir <tmp directory>]
          [--cachedir <user cache directory>]
          [--localedir <locale directory>]
          [--luacmd <lua command>]
          [--noiseprofiles <noiseprofiles json file>]
          [--conf <key>=<value>]
          [-t <num openmp threads>]

All parameters are optional. In most cases darktable should be started without any additional parameters, in which case darktable uses suitable defaults.

demosaic

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: reconstruct full RGB pixels from a sensor color filter array reading.
purpose: mandatory.
input: linear, raw, scene-referred.
processing: linear, raw.
output: linear, RGB, scene-referred.

Control how raw files are demosaiced and optionally apply capture sharpening.

🔗bayer filters

The sensor cells of a digital camera (commonly named “photosites”) are not color-sensitive – they are only able to record different levels of lightness. In order to obtain a color image, each cell is covered by a colored filter (red, green or blue) that primarily passes light of that color. This means that each photosite (and therefore each “pixel” of the raw image) only contains information about a single color channel.

denoise (profiled)

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: denoise using noise statistics profiled on sensors.
purpose: corrective.
input: linear, RGB, scene-referred.
processing: linear, RGB.
output: linear, RGB, scene-referred.

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.

developing monochrome images

Mon, 01 Jan 0001 00:00:00 +0000

Photography has a long history of producing monochrome images, and many still enjoy this aspect of photography. While there are some specialized/modified cameras with a truly monochrome sensor, most still use a regular camera to capture a color image and transform it into a monochrome image during post-processing.

There are two main approaches to this conversion:

A physical approach, where we attempt to simulate how a silver-based photographic film emulsion would react to the light captured at the scene.

diffuse or sharpen

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: simulate directional diffusion of light with heat transfer model to apply an iterative edge-oriented blur, inpaint damaged parts of the image, or to remove blur with blind deconvolution.
purpose: corrective and creative.
input: linear, RGB, scene-referred.
processing: linear, RGB.
output: linear, RGB, scene-referred.

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:

dither or posterize

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: reduce banding and posterization effects in output JPEGs by adding random noise, or reduce bit depth.
purpose: corrective, artistic.
input: non-linear, RGB, display-referred.
processing: non-linear, RGB.
output: non-linear, RGB, display-referred.

This module eliminates some of the banding artifacts that can result when darktable’s internal 32-bit floating point data is transferred into discrete 8-bit or 16-bit integer output format for display or export. It can also be used for creative posterization effects.

enlarge canvas

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: add empty space to the left, top, right or bottom.
purpose: corrective and creative.
input: linear, RGB, scene-referred.
processing: linear, RGB.
output: linear, RGB, scene-referred.

Increase the size of the image canvas and fill the additional area with the selected color.

🔗module controls

percent left: The amount of enlargement to the left of the image.
percent right: The amount of enlargement to the right of the image.
percent top: The amount of enlargement to the top of the image.
percent bottom: The amount of enlargement to the bottom of the image.
color: The color with which to fill the additional area.

exposure

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: redo the exposure of the shot as if you were still in-camera using a color-safe brightening similar to increasing ISO setting.
purpose: corrective and creative.
input: linear, RGB, scene-referred.
processing: linear, RGB.
output: linear, RGB, scene-referred.

Increase or decrease the overall brightness of an image.

This module has two modes of operation:

manual: Set the exposure and black level manually
automatic (RAW images only): Use an analysis of the image’s histogram to automatically set the exposure. Darktable 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.

🔗module controls

mode: Choose the mode of operation (automatic/manual).
compensate camera exposure (manual mode): Automatically remove the camera exposure bias (taken from the image’s Exif data).
highlight preservation mode (manual mode): Some cameras underexpose the raw file in specific modes such as HDR, dynamic range expansion, HLG or AutoLightingOptimizer to protect the highlights. When enabled, it restores the withheld exposure (the amount, in EV, is shown on the button). This control appears only when such a mode is detected in the image’s Exif data.
exposure (manual mode): Increase (move to the right) or decrease (move to the left) the exposure value (EV). To adjust by more than the default limits shown on the slider, right click and enter the desired value up to +/-18 EV (see module controls).; The picker tool on the right sets the exposure such that the average of the selected region matches the target lightness defined in area exposure mapping options.
percentile (automatic mode): Define a location in the histogram to use for automatic exposure correction. A percentile of 50% denotes a position in the histogram where 50% of pixel values are above and 50% of pixel values are below that exposure.
target level (automatic mode): Define the target level for automatic exposure correction (EV) relative to the white point of the camera.
black level correction (manual and automatic modes): Adjust the black level point to unclip negative RGB values.

Note: Do not use the black level correction to add more density in blacks as this can clip near-black colors out of gamut by generating negative RGB values. This can cause problems with some modules later in the pixelpipe. Instead, use a tone mapping curve to add density to the blacks. For example, you can use the relative black exposure slider on the scene tab of the filmic rgb module, or establish a deeper toe in the base curve module.

external raster mask

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: read PFM/PNG files recorded for use as raster masks.
purpose: corrective or creative.
input: linear, raw, scene-referred.
processing: linear, raw.
output: linear, raw, scene-referred.

Generate a raster mask from a .pfm to be used by subsequent processing modules.

Note: .pfm files are not very common but darktable and GIMP can both generate such files. Both grayscale and RGB files are supported.

🔗usage

Raster masks are automatically created whenever you define a mask within a processing module, for subsequent re-use in modules further up the pixelpipe. In some cases you might want such a mask to be generated by other software, for example to make use of software that can isolate a subject from its background, or simply to add some background pattern.

filemanager

Mon, 01 Jan 0001 00:00:00 +0000

In the default mode images are displayed in a grid with an adjustable number of images per row.

🔗controls

zoom: The number of images in each row can be altered using the numeric input in the bottom panel, or by holding Ctrl while scrolling over the center view with your mouse.
navigate: You can navigate through the images using the arrow keys (←/→/↑/↓) or by scrolling with your mouse. Press the Home key to scroll to the top of the collection, the End key to scroll to the bottom, and PageUp/PageDown to scroll up/down by a page.
select: You can select the image under the pointer by clicking on its thumbnail or by pressing Enter. To select a range of images, click on the first image and then Shift+click on the last one. To add or remove images in a selection, Ctrl+click on a thumbnail or hover over a thumbnail and press Spacebar.
hover: When the pointer hovers over any image’s thumbnail, it is highlighted and its image implicitly selected for keyboard shortcuts. If that thumbnail is part of a currently-selected set, certain shortcuts will be applied to all images of the set (for example, a numeric digit star rating).
drag: You can drag a thumbnail (along with any selected set to which it may belong) to set its custom sort position just before or after the image it’s dropped upon.

filmic rgb

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: apply a view transform to prepare the scene-referred pipeline for display on SDR screens and paper prints while preventing clipping in non-destructive ways.
purpose: corrective and creative.
input: linear or non-linear, RGB, scene-referred.
processing: non-linear, RGB.
output: non-linear, RGB, display-referred.

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

framing

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: add solid borders or margins around the image.
purpose: creative.
input: linear or non-linear, RGB, display-referred.
processing: geometric, RGB.
output: linear or non-linear, RGB, display-referred.

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.

🔗module controls

border size: The size of the frame as a percentage of the underlying full image.
aspect: The aspect ratio of the final module output (i.e. the underlying image plus the frame). Right-click on the slider to enter a custom aspect as a ratio (e.g. “6:5”).
orientation: The orientation of the frame (portrait/landscape). Select ‘auto’ for darktable to choose the most reasonable orientation based on the underlying image.
horizontal/vertical position: Select from a set of pre-defined ratios to control where the underlying image will be positioned on the horizontal/vertical axis. You can also right click and enter your own ratio as “x/y”.
frame line size: The percentage of the frame line size, relative to the border size at its smallest part.
frame line offset: The position of the frame line, relative to the underlying image. Choose 0% for a frame line that touches the image. Choose 100% for a frame line that touches the outer border.
border color / frame line color: A pair of color selectors which allow the border and frame line colors to be defined. Clicking on the colored field will open a color selector dialog which offers a choice of commonly-used colors, or allows you to define a color in RGB color space. You can also activate a picker to take a color probe from the image.
show guides: Tick the box to show guide overlays whenever the module is activated. Click the icon on the right to control the properties of the guides. See guides & overlays for details.

graduated density

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: simulate an optical graduated neutral density filter.
purpose: corrective and creative.
input: linear or non-linear, RGB, scene-referred.
processing: non-linear, RGB.
output: non-linear, RGB, display-referred.

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 dither or posterize module to alleviate these issues.

grain

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: simulate silver grains from film.
purpose: creative.
input: non-linear, Lab, display-referred.
processing: non-linear, Lab.
output: non-linear, Lab, display-referred.

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

🔗module controls

coarseness: The grain size, scaled to simulate an ISO number.
strength: The strength of the effect.
mid-tone bias: The bias toward the mid-tones. As the bias increases, the grain becomes less visible in the shadows and highlights.

haze removal

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: remove fog and atmospheric hazing from images.
purpose: corrective.
input: linear, RGB, scene-referred.
processing: frequential, RGB.
output: linear, RGB, scene-referred.

Automatically reduce the effect of dust and haze in the atmosphere. This module may also be employed more generally to give images 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.

highlight reconstruction

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: avoid magenta highlights and try to recover highlights colors.
purpose: corrective.
input: linear, raw, scene-referred.
processing: reconstruction, raw.
output: linear, raw, scene-referred.

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

🔗clipping

Clipping occurs when the amount of captured light exceeds either the capacity of a camera’s sensor to record that light (photosite saturation) or the capacity of the Raw file to store it (digital clipping). Once a pixel is clipped we can no longer know the precise brightness of that pixel – only that it is equal to or greater than the maximum value that pixel can store.

highpass

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: isolate high frequencies in the image.
purpose: creative.
input: linear or non-linear, Lab, scene-referred.
processing: frequential, Lab.
output: special, Lab, scene-referred.

A high pass filter.

This module is primarily intended to be used in combination with a blend mode. For example, try using the module with a blend mode of “soft light” for high pass sharpening.

Note: This module performs blurs in Lab color space, which can result in undesirable effects, and is no longer recommended. Instead, use the contrast equalizer module for fine sharpness or the local contrast module for general sharpness.

hot pixels

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: remove abnormally bright pixels by dampening them with neighbors.
purpose: corrective.
input: linear, raw, scene-referred.
processing: reconstruction, raw.
output: linear, raw, scene-referred.

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.

🔗module controls

threshold: The minimum brightness for a pixel to be considered a hot pixel candidate.
strength: The sensitivity of detection; higher values will fix more pixels by requiring less deviation from their neighbors.
detect by 3 neighbours: Extend the detection of hot pixels – 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: Visually mark the corrected pixels on the image and display a count of hot pixels that have been fixed.

input color profile

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: convert any RGB input to pipeline reference RGB using color profiles to remap RGB values.
purpose: mandatory.
input: linear or non-linear, RGB, scene-referred.
processing: defined by profile.
output: linear, RGB, scene-referred.

Define how darktable 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.

introduction

Mon, 01 Jan 0001 00:00:00 +0000

This section is intended to provide you with a flavor of what darktable can do and offer a suggested end-to-end processing workflow. New users should start by working through this introduction and following the links provided for further details.

Please note that this is not an exhaustive guide and many useful topics are not covered. You are advised to read through the reference sections of this manual once you are familiar with the basics.

lens correction

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: correct lenses optical flaws.
purpose: corrective.
input: linear, RGB, scene-referred.
processing: geometric and reconstruction, RGB.
output: linear, RGB, scene-referred.

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

You can choose to either use lens correction data embedded in your RAW file (where present/supported) or correction data provided by the external Lensfun library.

Additional controls are also provided for manual vignetting correction, in case the profiles for your lens are insufficient or missing.

liquify

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: distort parts of the image.
purpose: creative.
input: linear, RGB, scene-referred.
processing: geometric, RGB.
output: linear, RGB, scene-referred.

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

As you might want to use source data from any part of the image you will be shown the uncropped image (possibly with the cropping rectangle overlaid as a guide) while the module is active.

local contrast

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: manipulate local and global contrast separately.
purpose: creative.
input: non-linear, Lab, display-referred.
processing: non-linear, Lab.
output: non-linear, Lab, display-referred.

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.

🔗module controls

mode: Choice of local laplacian filter or bilateral grid. The following sections define the controls available for each of these modes.

🔗bilateral grid

coarseness: Adjust the coarseness of the details to be adjusted.
contrast: Control how strongly the algorithm distinguishes between brightness levels. Increase this parameter for a more contrasty look.
detail: Add or remove detail. Higher values increase local contrast.

🔗local laplacian

To understand the parameters of the local laplacian filter, one can think of it as applying a curve to the image, similar to the following graph:

lowlight vision

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: simulate human night vision.
purpose: creative.
input: non-linear, Lab, display-referred.
processing: linear, XYZ.
output: non-linear, Lab, display-referred.

Simulate human lowlight vision. This module can also be used to perform a day-to-night conversion.

The idea is to calculate a scotopic vision image, which is perceived by the rods rather than the cones in the eyes under low light. Scotopic lightness is then mixed with photopic value (regular color image pixel) using some blending function. This module can also simulate the Purkinje effect by adding some blueness to the dark parts of the image.

lowpass

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: isolate low frequencies in the image.
purpose: creative.
input: linear or non-linear, Lab, scene-referred.
processing: frequential, Lab.
output: special, Lab, scene-referred.

Apply a low pass filter (for example, a Gaussian blur) to the image, while controlling the output contrast and saturation.

This module is primarily intended to be used in combination with a blend mode. For example, try using the local contrast mask preset with the overlay blend mode.

LUT 3D

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: perform color space corrections and apply look.
purpose: corrective or creative.
input: linear, RGB, display-referred.
processing: defined by profile, RGB.
output: linear or non-linear, RGB, display-referred.

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.

module header

Mon, 01 Jan 0001 00:00:00 +0000

At the top of each processing module is the module header.

Click on the module name to expand the module and display the parameters that control its operation.

By default darktable will only allow one processing module to be expanded at a time – if you click the header of another module, the previously-opened module’s controls are collapsed. If you want to expand more than one module, you may expand further modules by Shift+clicking on the header and all previously expanded modules will remain open. This behaviour can be reversed via a setting in preferences > darkroom.

monochrome

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: quickly convert an image to black & white using a variable color filter.
purpose: creative.
input: linear or non-linear, Lab, display-referred.
processing: non-linear, Lab.
output: non-linear, Lab, display-referred.

Quickly convert an image to black & white using a variable color filter.

To use this module, first reduce the filter size (to concentrate its effect) and move it across the hue palette to find the best filter value for your desired image rendition. Then gradually expand the filter to include more hues and achieve more natural tonality.

negadoctor

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: invert film negative scans and simulate printing on paper.
purpose: corrective and creative.
input: linear, RGB, display-referred.
processing: non-linear, RGB.
output: non-linear, RGB, display-referred.

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.

🔗preparation

If the image of the negative was obtained using a digital camera, then in order to obtain accurate colors in the final image, you will need to take the following points into consideration:

orientation

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: flip or rotate image by step of 90 degrees.
purpose: corrective.
input: linear, RGB, scene-referred.
processing: geometric, RGB.
output: linear, RGB, scene-referred.

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 actions on selection module in the lighttable view.

output color profile

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: convert pipeline reference RGB to any display RGB using color profiles to remap RGB values.
purpose: mandatory.
input: linear or non-linear, Lab, display-referred.
processing: defined by profile.
output: non-linear, RGB or Lab, display-referred.

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

darktable comes with pre-defined profiles sRGB, Adobe RGB, XYZ and linear RGB. You can provide additional profiles by placing them in $DARKTABLE/share/darktable/color/out (where $DARKTABLE is the darktable installation directory) or color/out in the darktable configuration directory. Note that these color/out directories are not created by the darktable install; if you need to use one, you must create it yourself.

overview

Mon, 01 Jan 0001 00:00:00 +0000

Masks allow you to limit the effect of a module so that it only applies to certain parts of the image.

A mask can be regarded as a grayscale image where each pixel has a value between 0 and 1.0 (or between 0% and 100%). This value is the opacity and is used to determine how much a module affects each pixel.

The following sections explain how to construct masks in darktable.

overview

Mon, 01 Jan 0001 00:00:00 +0000

Each processing module takes its input from the preceding module in the pixelpipe, performs its operation on the image data, and then hands the output to the next module in the pixelpipe.

A module’s output data can optionally be reprocessed (combined) with its input data before being handed to the next module. This additional processing step is called blending – input and output data is reprocessed using algorithms called blending operators or blend modes.

overview

Mon, 01 Jan 0001 00:00:00 +0000

Processing modules are organized and accessed via the right-hand panel in the darkroom:

Click on the icons at the top of this panel to reveal, from left to right,

quick access panel: A customizable panel allowing quick access to commonly-used module controls.
active modules: A group containing the modules that are currently active in the pixelpipe. Right-click to show all modules that are present in the history stack within the active group, regardless of whether or not they are actually active.
module groups: One or more groups of processing modules. These groups are user-defined but some default groupings are provided as presets.
presets menu: A menu that allows you to access stored module layout presets and create your own (via the “manage presets..” option). You can also directly access the “manage presets” dialog by Ctrl+clicking on the presets menu.

Click once on a module group icon (including the active group) to show only the modules in that group. Click a second time to show a list of all modules that are currently active or present in any group.

overview

Mon, 01 Jan 0001 00:00:00 +0000

The darkroom view is where you develop your images. The center panel contains the image currently being edited.

🔗zoom

Middle-click on the center panel cycle between “fit to screen”, 1:1 and 2:1 zoom.

Alternatively you can zoom by scrolling with your mouse or touchpad. When the constrain darkroom zoom between screen fit and 100% preference is enabled, scroll-wheel and pinch-to-zoom is constrained to the range between screen fit (zoom out) and 100% (zoom in). Hold Ctrl while zooming to temporarily lift the limit and zoom beyond 100%. When the preference is disabled, zoom is never constrained and the additional Ctrl key press is not needed to zoom beyond 100% .

overview

Mon, 01 Jan 0001 00:00:00 +0000

The lighttable view allows you to view and manage your image collection.

The centre view contains thumbnails of your images – how they are displayed depends on which mode you are working in.

While the mouse is over an image thumbnail or images are selected, there are a number of actions you can perform:

🔗keyboard shortcuts

The following keyboard shortcuts are enabled by default in the lighttable view:

F1, F2, F3, F4, F5 adds or removes a color label (red, yellow, green, blue, purple, respectively). A color label will be added if any selected image does not currently have the label; otherwise the label will be removed

overview

Mon, 01 Jan 0001 00:00:00 +0000

Lua scripts can be used to define actions for darktable to perform when an event is triggered. One example might be calling an external application during file export in order to apply additional processing steps outside of darktable.

Lua is an independent project founded in 1993, providing a powerful, fast, lightweight, embeddable scripting language. Lua is widely used by many open source applications, in commercial programs, and for games programming. darktable uses Lua version 5.4. Describing the principles and syntax of Lua is beyond the scope of this manual. For a detailed introduction see the Lua reference manual.

overview

Mon, 01 Jan 0001 00:00:00 +0000

The map view allows you to see where your geo-tagged images were taken, and to add location information to non-geo-tagged images.

The map view shows a world map with the images in the current collection pinned to their geo-tagged location (if available). This requires that images are tagged with location information. Some newer cameras, including smartphones, are already equipped with GPS receivers. Other cameras may need additional GPS hardware to do this.

overview

Mon, 01 Jan 0001 00:00:00 +0000

The modules in this reference section are broken down into two distinct types:

processing modules: Processing modules are used exclusively in the darkroom view. Each module performs a processing operation on the image before passing its output to the next module for further processing. Together this sequence of processing steps forms the pixelpipe.
Processing modules have a Technical information section which gives a brief summary of the module (the information can also be seen as a tooltip when hovering over the module name). The following information is shown:

overview

Mon, 01 Jan 0001 00:00:00 +0000

darktable comes with a number of user-configurable preferences. These can be adjusted in the preferences dialog, which can be reached by clicking the gear icon on the right of the top panel. Preferences are separated into tabs, each of which is described in more detail in the following sections.

When opened from within the lighttable or darkroom views, the appropriate tab will be loaded by default to allow you to modify that view’s settings.

overview

Mon, 01 Jan 0001 00:00:00 +0000

This view allows you to print your images. Because printing is not easy, there are many technical aspects to be taken into account.

After selecting an image in the lighttable view you can enter the print settings module to adjust printer settings and initiate printing.

This module supports the printer’s ICC profile, which is somewhat mandatory if you want to obtain a high quality print close to the image displayed on the screen.

overview

Mon, 01 Jan 0001 00:00:00 +0000

The slideshow view allows you to watch a slideshow of your current collection with the associated filtering rules and sort order applied.

To learn more about how to define the collection and filtering rules, see the section on collections. Select the sort criteria and sort order of the images in the top panel.

The next section provides more details on the usage of the slideshow view.

overview

Mon, 01 Jan 0001 00:00:00 +0000

darktable uses machine learning models for a handful of image-processing tasks: interactive object masking, denoising, upscaling, etc. This section explains how those features work end-to-end – what runs where, which models exist, how inference is accelerated, and what the user’s choices in the AI preferences actually control.

AI features are opt-in. They are off by default in a fresh install and can be toggled with a single preference at any time.

overview

Mon, 01 Jan 0001 00:00:00 +0000

darktable employs a fully color managed workflow:

Input color specifications are taken from embedded or user-supplied ICC profiles or (in the case of raw files) from a library of camera-specific color matrices.
darktable automatically reads the display profile of your monitor (if properly configured) for accurate on-screen color rendition. Multiple-screen setups are fully supported as long as a system service like colord is in place and properly configured to inform darktable of the correct monitor profile.

overview

Mon, 01 Jan 0001 00:00:00 +0000

darktable-chart is a tool for extracting luminance and color values from images of color reference cards such as IT8.7/1 charts. Its main purpose is to compare a source image (typically a largely unprocessed raw image) to a target image (typically a JPEG image created in-camera) and produce a darktable style that is able to use the luminance and color values of the source image to produce the target image. This style employs the tone curve module, the input color profile module, and the color look up table module for that purpose.

overview

Mon, 01 Jan 0001 00:00:00 +0000

The tethering view allows you to capture images directly into darktable from a connected camera.

To use the tethering feature you first need to connect your camera to your PC using a USB cable. Your computer might ask to mount or view the connected camera. Do not mount or view the camera. If your camera is mounted or viewed automatically, you will need to “unmount/eject” the camera before darktable can access it. This unlocks the camera so that darktable can take control of it – darktable will then re-lock the camera so that it cannot be used by other applications.

raw black/white point

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: sets technical specificities of the raw sensor touch with great care!.
purpose: mandatory.
input: linear, raw, scene-referred.
processing: linear, raw.
output: linear, raw, scene-referred.

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.

🔗module controls

black level 0-3: The camera-specific black level of the four pixels in the RGGB Bayer pattern. Pixels with values lower than this level are not considered to contain valid data.
white point: The camera-specific white level. All pixels with values above this are likely to be clipped and will be handled accordingly in the highlight reconstruction module.
flat field correction: Use flat field correction to compensate for lens shading. This field only appears for applicable Raw files and will automatically use any GainMap embedded in the Raw. You can choose to disable this correction if desired.

raw chromatic aberrations

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: correct chromatic aberrations for Bayer sensors.
purpose: corrective.
input: linear, raw, scene-referred.
processing: linear, raw.
output: linear, raw, scene-referred.

Correct chromatic aberrations of raw images.

This module currently only works for raw images recorded with a Bayer sensor (the sensor used in the majority of cameras) – for other types of image, you should use the chromatic aberrations module instead.

The module will also not apply any corrections to any photos that have been identified as monochrome (see developing monochrome images for more information).

raw denoise

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: denoise the raw image early in the pipeline.
purpose: corrective.
input: linear, raw, scene-referred.
processing: linear, raw.
output: linear, raw, scene-referred.

Perform denoising on raw image data before it is demosaiced.

This module has been ported from dcraw.

For an AI-based alternative that denoises the raw data as part of a combined denoise/demosaic inference pass, see neural restore and the AI features overview.

🔗module controls

noise threshold: The threshold for noise detection. Higher values lead to stronger noise removal and greater loss of image detail.
coarse/fine curves: The noise of an image is usually a combination of fine-grained and coarse-grained noise. These curves allow the image to be denoised more or less depending on the coarseness of the visible noise. The left of the curve will act on very coarse grain noise, while the right of the curve will act on very fine grain noise.; Raising the curve will result in more smoothing, while lowering it will result in less smoothing. As an example, you can preserve very fine-grained noise by pulling down the rightmost point of the curve to the minimum value.

retouch

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: remove and clone spots, perform split-frequency skin editing.
purpose: corrective.
input: linear, RGB, scene-referred.
processing: geometric and frequential, RGB.
output: linear, RGB, scene-referred.

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

This module extends the capabilities of the deprecated spot removal module (equivalent to this module’s “clone” tool) by including 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.

rgb curve

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: alter an image’s tones using curves in RGB color space.
purpose: corrective and creative.
input: linear, RGB, display-referred.
processing: non-linear, RGB.
output: linear, RGB, display-referred.

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

This module is very similar to the tone curve module but works in RGB color space.

Activate the 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.

rgb levels

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: adjust black, white and mid-gray points in RGB color space.
purpose: corrective and creative.
input: linear, RGB, display-referred.
processing: non-linear, RGB.
output: non-linear, RGB, display-referred.

Adjust black, white and mid-gray points in RGB color space. This module is similar to the levels module, which works in Lab 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).

rgb primaries

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: adjustment of the RGB color primaries for color grading.
purpose: corrective or creative.
input: linear, RGB, scene-referred.
processing: linear, RGB.
output: linear, RGB, scene-referred.

Adjust the hue and purity of the RGB primary colors (i.e. which red, green and blue they represent), while leaving uncolored (gray) pixels unchanged. In addition to preserving gray pixels, the opponency relationships between the colors are also preserved under this adjustment: If you increase the purity of the blue primary, the opponent yellow’s intensity increases to balance things out; If you twist the blue hue toward cyan, the opponent yellow is twisted toward orange.

rotate and perspective

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: rotate or distort perspective.
purpose: corrective or creative.
input: linear, RGB, scene-referred.
processing: geometric, RGB.
output: linear, RGB, scene-referred.

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.

rotate pixels

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: null.
purpose: null.
input: null.
processing: null.
output: null.

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.

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

scale pixels

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: module for setting pixel aspect ratio useful for certain sensor types and anamorphic desqueeze.
purpose: corrective.
input: linear, RGB, scene-referred.
processing: linear, RGB.
output: linear, RGB, scene-referred.

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.

darktable detects images that need correction using their Exif data and automatically activates this module where required.

shadows and highlights

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: modify the tonal range of the shadows and highlights of an image by enhancing local contrast.
purpose: corrective and creative.
input: linear or non-linear, Lab, display-referred.
processing: non-linear, Lab.
output: non-linear, Lab, display-referred.

Modify the tonal range of the shadows and highlights of an image by enhancing local contrast.

Note: This module performs blurs in Lab color space, which can result in a number of issues when the parameters are pushed hard, including halos, high local contrast in highlights, and hue shifts towards blue in the shadows. You are advised to use the tone equalizer module instead.

sharpen

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: sharpen the details in the image using a standard UnSharp Mask (USM).
purpose: corrective.
input: linear or non-linear, Lab, display or scene-referred.
processing: frequential, Lab.
output: quasi-linear, Lab, display or scene-referred.

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.

sidecar files

Mon, 01 Jan 0001 00:00:00 +0000

darktable is a non-destructive image editor and opens all images in read-only mode. Most data created within darktable (metadata, tags, and image processing steps) is stored in separate .XMP sidecar files. These files are stored alongside the original Raw files and allow darktable to store information about the images as well as the full editing history without touching the original raw files. When you import an image into darktable for the first time, an XMP file is automatically generated. The generation of XMP files can be disabled in preferences > storage > XMP sidecar files but this is not recommended in normal use.

sigmoid

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: apply a view transform to make an image displayable on a screen or print using a robust and smooth tone curve with optional color preservation methods.
purpose: corrective and creative.
input: linear, RGB, scene-referred.
processing: non-linear, RGB.
output: linear, RGB, display-referred.

Remap the tonal range of an image using a modified generalized log-logistic curve.

This module can be used to expand or contract the dynamic range of the scene to fit the dynamic range of the display.

soften

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: create a softened image using the Orton effect.
purpose: creative.
input: linear, RGB, display-referred.
processing: linear, RGB.
output: linear, RGB, display-referred.

Create a softened image using the Orton effect.

Michael Orton achieved his results on slide film by using two exposures of the same scene, one well exposed and one overexposed. He then used a darkroom technique to blend these two images into a final image where the overexposed image was blurred.

split-toning

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: use two specific colors for shadows and highlights and create a linear toning effect between them up to a pivot.
purpose: creative.
input: linear, RGB, scene-referred.
processing: linear, RGB.
output: linear, RGB, scene-referred.

Create a two color linear toning effect where the shadows and highlights are represented by two different colors.

The split-toning module does not convert images to black and white and has limited benefits on color images. In order to perform traditional split-toning, the input to this module should therefore be monochrome.

styles & conventions

Mon, 01 Jan 0001 00:00:00 +0000

The following details the writing style and documentation conventions used in this manual.

🔗format

This website is authored in pure markdown, using some extensions. It is initially designed to work with the Hugo SSG but intended to be portable enough that it can be easily rendered with another application if required.

Files should be rendered in UTF-8 and should not include any column wrapping.

🔗structure

The following shows the structure of an example main chapter with subsections in the dtdocs website.

surface blur

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: apply edge-aware surface blur to denoise or smoothen textures.
purpose: corrective and creative.
input: linear, RGB, scene-referred.
processing: linear, RGB.
output: linear, RGB, scene-referred.

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 darktable 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 anatomy of a processing module

Mon, 01 Jan 0001 00:00:00 +0000

The basic element of image processing in darktable is the processing module. In order to process a raw image a number of such modules act on the input image in sequence, each performing a different operation on the image data. For those familiar with Adobe Photoshop, the concept of a processing module in darktable is analogous to that of an adjustment layer in that both make an incremental adjustment to the image, building on top of the adjustments that came before.

the background

Mon, 01 Jan 0001 00:00:00 +0000

Processing high resolution images is a demanding task requiring a modern computer. In terms of both memory and CPU power, getting the best out of a typical 15, 20 or 25 megapixel image can quickly take your computer to its limits.

darktable’s requirements are no exception. All calculations are performed on 4 x 32bit floating point numbers. This is slower than “ordinary” 8 or 16 bit integer algebra, but eliminates all problems of tonal breaks or loss of information.

tone curve

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: alter an image’s tones using curves.
purpose: corrective and creative.
input: linear or non-linear, Lab, display-referred.
processing: non-linear, Lab.
output: non-linear, Lab, display-referred.

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

This module is very similar to the rgb curve module but works in Lab color space.

Activate the picker to show the picked values on the displayed histogram. Numerical (Lab) values of the input and output (see below) at the selected spot or area are shown at the top left of the graph.

tone equalizer

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: relight the scene as if the lighting was done directly on the scene.
purpose: corrective and creative.
input: linear, RGB, scene-referred.
processing: quasi-linear, RGB.
output: quasi-linear, RGB, scene-referred.

Dodge and burn while preserving local contrast.

The tone equalizer module replaces the need for other tone-mapping modules such as the shadows and highlights, tone curve, zone system (deprecated), and similar modules. 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.

unbreak input profile

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: correct input color profiles meant to be applied on non-linear RGB.
purpose: corrective.
input: linear, RGB, display-referred.
processing: non-linear, RGB.
output: non-linear, RGB, display-referred.

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 darktable’s standard or enhanced color matrices.

velvia

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: resaturate giving more weight to blacks, whites and low-saturation pixels.
purpose: creative.
input: linear, RGB, scene-referred.
processing: linear, RGB.
output: linear, RGB, scene-referred.

Resaturate pixels in a weighted manner that gives more weight to blacks, whites and less saturated pixels.

Note: This module causes hue and brightness shifts that can be difficult to manage. Instead, use the color balance rgb module for color modifications.

🔗module controls

strength: The strength of the effect
mid-tones bias: Reduce the effect on mid-tones in order to avoid unnatural skin tones. Reducing the mid-tone bias decreases mid-tone protection and makes the overall velvia effect stronger.

views

Mon, 01 Jan 0001 00:00:00 +0000

The functionality in darktable is separated into six different views:

lighttable: Manage images and collections.
darkroom: Develop a single image.
map: Show geo-tagged images on a map and manually geo-tag new images.
print: Send images to a printer.
slideshow: Display images as a slideshow, processing them on-the-fly.
tethering: Remotely capture and save images taken with a connected camera.

You can switch between views by clicking the view name at the top of the right-hand panel (the currently active view is highlighted) or by using one of the following keyboard shortcuts:

vignetting

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: simulate a lens fall-off close to edges.
purpose: creative.
input: non-linear, RGB, display-referred.
processing: non-linear, RGB.
output: non-linear, RGB, display-referred.

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.

watermark

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: overlay an SVG watermark like a signature on the image.
purpose: creative.
input: non-linear, RGB, display-referred.
processing: non-linear, RGB.
output: non-linear, RGB, display-referred.

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 darktable can also substitute strings within an SVG document, allowing image-dependent information to be included in the watermark.

white balance

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: scale raw RGB channels to balance white and help demosaicing.
purpose: corrective.
input: linear, raw, scene-referred.
processing: linear, raw.
output: linear, raw, scene-referred.

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.

backup settings & edits

Mon, 01 Jan 0001 00:00:00 +0000

If you want to back up darktable’s settings and edits you can save a copy of the contents of the configuration directory. See configuration directory for descriptions of what the individual files contain.

Transferring the contents of this directory also allows for migration between variants (e.g. between Flatpak and AppImage) of darktable.

Darktable also maintains a number of backups of data.db and library.db inside the configuration directory: 15 daily snapshots of each, plus a snapshot created when updating to a new version (e.g. data.db-pre-5.4.1).

darktable's scripts

Mon, 01 Jan 0001 00:00:00 +0000

🔗from 5.6 onward

A collection of scripts is included with darktable. They can be disabled in preferences > lua.

Starting with darktable 5.6, the lua-scripts are included with the release, so they no longer have to installed separately.

See basic principles for an explanation of how darktable loads Lua scripts.

Documentation for darktable’s scripts is available in the lua docs.

🔗pre 5.6

Pre 5.6 the scripts were not bundled and had to be installed using the following instructions.

(deprecated) basic adjustments

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: apply usual image adjustments.
purpose: creative.
input: linear, RGB, scene-referred.
processing: non-linear, RGB.
output: non-linear, RGB, scene-referred.

Please note that this module is deprecated from darktable 3.6 and should no longer be used for new edits. Please use the quick access panel instead.

A convenience module that combines controls from exposure, highlight reconstruction, color balance and vibrance into a single module.

While this module can provide a quick and convenient way to make simple adjustments to an image, it must be used with care. Normally exposure adjustments should come before input color profile in the pixelpipe, and color adjustments should come after. Because the basic adjustments module combines all of these functions into a single operation in the pixelpipe, it may not play nicely with other modules. Therefore, if you plan to use basic adjustments with other modules, please instead consider using the exposure + base curve / tone curve / filmic rgb + color balance modules so that these operations occur in the correct places in the pixelpipe.

(deprecated) channel mixer

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: perform color space corrections such as white balance, channels mixing and conversions to monochrome emulating film.
purpose: corrective or creative.
input: linear, RGB, display-referred.
processing: linear, RGB.
output: linear, RGB, display-referred.

Please note that this module is deprecated from darktable 3.4 and should no longer be used for new edits. Please use the color calibration module instead.

A simple yet powerful tool to manage color channels.

This module accepts red, green and blue channels as an input and provides red, green, blue, gray, hue, saturation and lightness channels as output. It allows you to independently control how much each input channel contributes to each output channel.

(deprecated) contrast brightness saturation

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: adjust the look of the image.
purpose: creative.
input: non-linear, Lab, display-referred.
processing: non-linear, Lab.
output: non-linear, Lab, display-referred.

Please note that this module is deprecated from darktable 4.4 and should no longer be used for new edits. Please use the color balance rgb module instead.

A very basic tool for adjusting the contrast, brightness and saturation of an image. Please note that a number of other modules provide much more versatile methods of adjusting these parameters.

(deprecated) crop and rotate

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: change the framing and correct the perspective.
purpose: corrective or creative.
input: linear, RGB, scene-referred.
processing: geometric, RGB.
output: linear, RGB, scene-referred.

Please note that this module is deprecated from darktable 3.8 and should no longer be used for new edits. Please use the crop module to crop the image, the rotate and perspective module to perform rotation and keystone correction, and the orientation module to flip the image on the horizontal/vertical axes.

(deprecated) defringe

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: attenuate chromatic aberration by desaturating edges.
purpose: corrective.
input: linear or non-linear, Lab, display-referred.
processing: non-linear, Lab.
output: non-linear, Lab, display-referred.

Please note that this module is deprecated from darktable 3.6 and should no longer be used for new edits. Please use the chromatic aberrations module instead.

Remove color fringing, which often results from Longitudinal Chromatic Aberrations (LCA), also known as Axial Chromatic Aberrations.

This module uses edge-detection. Where pixels are detected as a fringe, the color is rebuilt from less saturated neighboring pixels.

(deprecated) fill light

Mon, 01 Jan 0001 00:00:00 +0000

Please note that this module is deprecated from darktable 3.4 and should no longer be used for new edits. Please use the tone equalizer module or the exposure module with a drawn mask.

Locally modify exposure based on pixel lightness.

This module pushes exposure by increasing lightness with a Gaussian curve of a specified width, centered on a given lightness.

🔗module controls

exposure: The fill-light exposure (EV)
center: The median lightness impacted by the fill-light. The lightness must be set manually but a picker can be used to provide a guide based on a sample from the image. The lightness of the selected point/area is displayed in the gradient bar.
width: The width of the Gaussian curve. This number is expressed in zones, with the full range being 10 zones.

(deprecated) global tonemap

Mon, 01 Jan 0001 00:00:00 +0000

Please note that this module is deprecated from darktable 3.4 and should no longer be used for new edits. Please use the filmic rgb module instead.

Compress the tonal range of an HDR image into the limited tonal range of a typical LDR output file.

Global tonemap processes each pixel of an HDR image, without taking the local surrounding into account. This is generally faster than local tone mapping (deprecated), but might lead to less convincing results with very high-dynamic-range scenes.

(deprecated) invert

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: invert film negatives.
purpose: corrective.
input: linear, raw, display-referred.
processing: linear, raw.
output: linear, raw, display-referred.

Please note that this module is deprecated from darktable 3.4 and should no longer be used for new edits. Please use the negadoctor module instead.

Invert scanned negatives.

🔗module controls

color of film material: Clicking on the colored field will open a color selector dialog which offers you a choice of commonly used colors, or allows you to define an RGB color. You can also activate the picker to take a color probe from your image – preferably from the unexposed border of your negative.

(deprecated) levels

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: adjust black, white and mid-gray points.
purpose: creative.
input: linear or non-linear, Lab, display-referred.
processing: non-linear, Lab.
output: non-linear, Lab, display-referred.

Please note that this module is deprecated from darktable 4.4 and should no longer be used for new edits. Please use the rgb levels module instead.

Adjust black, white and mid-gray points.

The levels tool offers two modes of operation:

manual: The 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 absolute values of image lightness (the L value from Lab).; 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, increasing the image’s contrast.

(deprecated) spot removal

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: remove sensor dust spots.
purpose: corrective.
input: linear, RGB, scene-referred.
processing: geometric, raw.
output: linear, RGB, scene-referred.

Please note that this module is deprecated from darktable 3.6 and should no longer be used for new edits. Please use the “cloning” tool in the retouch module instead.

Correct areas of an image (the target) using details from another area of the image (the source).

This module uses some of the shapes that are available for drawn masks (circles, ellipses and paths), and the user interface is similar.

(deprecated) tone mapping

Mon, 01 Jan 0001 00:00:00 +0000

Please note that this module is deprecated from darktable 3.4 and should no longer be used for new edits. Please use the tone equalizer module instead.

Compress the tonal range of HDR images so that they fit into the limits of an LDR image, using Durand’s 2002 algorithm.

The underlying algorithm uses a bilateral filter to decompose an image into a coarse base layer and a detail layer. The contrast of the base layer is compressed, while the detail layer is preserved, then both layers are re-combined.

(deprecated) vibrance

Mon, 01 Jan 0001 00:00:00 +0000

Technical information

description: saturate and reduce the lightness of the most saturated pixels to make the colors more vivid.
purpose: creative.
input: linear or non-linear, Lab, display-referred.
processing: non-linear, Lab.
output: non-linear, Lab, display-referred.

Please note that this module is deprecated from darktable 3.6 and should no longer be used for new edits. Please use the vibrance control in the color balance rgb module instead.

Saturate and reduce the lightness of the most saturated pixels to make the colors more vivid.

(deprecated) zone system

Mon, 01 Jan 0001 00:00:00 +0000

Please note that this module is deprecated from darktable 3.4 and should no longer be used for new edits. Please use the tone equalizer or multiple instances of the exposure module with parametric masks to narrow down on a zone.

Adjust the lightness of an image using Ansel Adams’ zone system.

The lightness of the image (the L channel in Lab color space) is divided into a number of zones ranging from pure black to pure white. These zones are displayed in a zonebar beneath a preview image. The number of zones can be changed by mouse-scrolling on that bar (default 10 zones).

basic principles

Mon, 01 Jan 0001 00:00:00 +0000

Scripts can register callbacks to perform actions on various darktable events. This callback mechanism is the primary method of triggering lua actions.

The central orchestrator for lua scripts is the script manager, which spawns the utility module scripts in the lighttable and loads darktable’s bundled scripts.

Lua scripts can be disabled in preferences/lua options.

🔗how darktable loads scripts (and the script manager)

darktable treats two kinds of location differently: Files that are executed as Lua code, and directories that are scanned for scripts:

blend modes

Mon, 01 Jan 0001 00:00:00 +0000

Blend modes define how the input and output of a module are combined (blended) together before the module’s final output is passed to the next module in the pixelpipe.

Classic blending modes, designed for display-referred RGB (constrained to 0-100%), implicitly define a fulcrum at 50% (gray) or 100% (white) in their algorithms, depending on the blend mode. Because scene-referred is not subject to these restrictions, this fulcrum needs to be explicitly defined by the user when performing blending operations in the “RGB (scene)” color space. The additional blend fulcrum parameter will be presented to the user when using one of these blend modes in this color space. The effect depends on the operator used. For example, values above the fulcrum might be brightened and values below darkened, or vice versa.

collections & film rolls

Mon, 01 Jan 0001 00:00:00 +0000

A collection is a group of images matching a given set of selection criteria.

The most basic kind of collection is a film roll, which contains all of the images that have been imported from a specific folder on disk – whenever you import images from the filesystem, those images are organized in a film roll whose name is derived from that of their parent folder.

You can easily construct other kinds of collection in the collections module based on one or more image attributes (e.g. Exif data, filename, tags). The collection filters module allows you to refine a collection by setting additional selection and exclusion criteria.

darkroom view layout

Mon, 01 Jan 0001 00:00:00 +0000

🔗left panel

From top to bottom:

navigation: Navigate and zoom the center view.
snapshots: Take and view snapshots for comparison with the current edit.
duplicate manager: View and manage duplicates.
global color picker: Select and display color information taken from parts of the image.
tagging: Manage tags.
image information: Display information about the current image.
mask manager: View and edit drawn shapes.
export: Export selected images to local files or external services.
neural restore: Apply AI-powered raw denoise, RGB denoise, or upscaling to selected images.

🔗right panel

From top to bottom:

darktable-cli

Mon, 01 Jan 0001 00:00:00 +0000

The darktable-cli binary starts the command line interface variant of darktable which allows images to be exported.

This variant does not open any display – it works in pure console mode without launching a GUI. This mode is particularly useful for servers running background jobs.

darktable-cli can be called with the following command line parameters:

darktable-cli [<input file or folder>]
              [<xmp file>]
              <output file or folder>
              [--width <max width>]
              [--height <max height>]
              [--hq <0|1|true|false>]
              [--upscale <0|1|true|false>]
              [--style <style name>]
              [--style-overwrite]
              [--apply-custom-presets <0|1|false|true>]
              [--out-ext <extension>]
              [--import <file or dir>]
              [--library <path>]
              [--icc-type <type>]
              [--icc-file <file>]
              [--icc-intent <intent>]
              [--verbose]
              [--help [option]]
              [--core <darktable options>]

The user must supply an input filename and an output filename. All other parameters are optional.

display profile

Mon, 01 Jan 0001 00:00:00 +0000

For darktable to faithfully render colors on screen it needs to find the correct display profile for your monitor. In general this requires your monitor to be properly calibrated and profiled, and it needs the profile to be correctly installed on your system. darktable queries your X display server’s xatom as well as the system service colord (if available) for the right profile. If required you can enforce a specific method in preferences > miscellaneous.

drawn masks

Mon, 01 Jan 0001 00:00:00 +0000

With the drawn mask feature you can construct a mask by drawing shapes directly onto the image canvas. Shapes can be used alone or in combination. Once a shape has been drawn on an image it can be adjusted, removed, or reused in other modules.

Shapes are stored internally as vectors and are rendered with the required resolution during pixelpipe processing. Shapes are expressed in the coordinate system of the original image and are transformed along with the rest of the image by any active distorting modules in the pipe (lens correction, rotate and perspective for example). This means that a shape will always work on the same image area regardless of any modifications that may be subsequently applied.

general

Mon, 01 Jan 0001 00:00:00 +0000

Control the overall look and feel of darktable.

interface language: Set the language of the user interface. This includes the option to enable sentence case (en@truecase) for English. The system default is marked with an * (needs a restart)
theme: Set the theme for the user interface. Aside from any aesthetic considerations, the recommended interface color for color evaluation is middle gray. Visual perception is affected by ambient brightness, and a low user interface brightness causes all kinds of illusions. Using a dark interface to retouch photos can therefore lead to excessive retouching (abuse of contrast and saturation) and to a photo that is too dark when printed. It is therefore highly recommended that you use one of the “grey” themes for retouching work as these are designed so that the user interface approximates middle gray. For those who have difficulty reading text in the default theme, darktable includes two “highcontrast” themes with white text on a dark background, but the caveats mentioned previously apply if you select one of them (default “darktable-elegant-grey”).
use system font size: Select this option to use the font size defined by your system. If unchecked, you may enter a custom font size in the box below (default on).
font size in points: If the “use system font size” option is switched off, enter a font size (in points) for darktable to use. The font size will be changed immediately.
GUI controls and text DPI: Adjust the global GUI resolution to rescale controls, buttons, labels, etc. Increase for a magnified GUI, decrease to fit more content in the window. Set to -1 to use the system-defined global resolution. The default is 96 DPI on most systems. (needs a restart)
reset view panels: The order and visibility of utility modules can be manually changed by the user (see modules overview). Click this button to reset to default values.

🔗CSS theme modifications

In addition to selecting a pre-built theme you can also apply additional CSS customizations of your own to tweak the look-and-feel of darktable.

how AI features work

Mon, 01 Jan 0001 00:00:00 +0000

This page covers what goes on under the hood: the inference library darktable loads, the execution providers available to it, and how models are stored and activated.

🔗the inference runtime

darktable loads models through ONNX Runtime – a production-grade inference library originally developed at Microsoft and now governed by the Linux Foundation – that accepts models in the ONNX open format. ONNX is the de-facto standard for interchanging machine-learning models across frameworks (PyTorch, TensorFlow, etc.) so we can take a model trained in any of them, export it to ONNX, and run it from darktable without carrying its training framework along.

how OpenCL works

Mon, 01 Jan 0001 00:00:00 +0000

As you can imagine, the hardware architecture of GPUs can vary significantly. There are different manufacturers, and even different generations of GPUs from the same manufacturer may not be comparable. At the same time GPU manufacturers don’t normally disclose all the hardware details of their products to the public. One of the consequences of this is the need to use proprietary drivers under Linux, if you want to take full advantage of your graphics card.

import & review

Mon, 01 Jan 0001 00:00:00 +0000

Before you can do anything in darktable you must first add some images files to the library using the import module in the lighttable view. This will create entries for your images in darktable’s library database so that it can keep track of the changes you make. There are three ways to import images, each accessible through buttons in the import module:

add to library: This option adds images to the library without copying or moving – your original files will stay in their current location and will not be altered. On import, darktable will read the metadata from the image files and any accompanying XMP sidecar file. If an image has already been added to the database, any updates you have made to the sidecar file will be loaded.
copy & import: Copies the images to the storage location (following the file naming pattern defined in preferences > import), then adds the copied images to the library – the original images are not changed or moved. Only the images are copied and if an existing XMP sidecar file is available for the image, it will not be read, copied or used.
copy & import from camera: Connect the camera to your system with a USB cable (if your camera is auto-mounted by your system, you will need to un-mount it before it can be accessed by darktable). If you don’t see your camera listed in the import module, press the “scan for devices” button. Once your camera is detected the import module should offer the ability to copy & import images from the camera. Clicking the “copy & import” button physically copies the selected images from the camera into a specified directory (following the file naming pattern defined in preferences > import) and then adds the copied images to the library.

Once images have been imported, their thumbnails are displayed in the lighttable view, within which you can organize and catalog your imported images – please refer to the digital asset management section for more information.

importing sidecar files generated by other applications

Mon, 01 Jan 0001 00:00:00 +0000

When importing an image, darktable automatically checks if it is accompanied by a sidecar file. As well as looking for files named <basename>.<extension>.xmp and <basename>_<number>.<extension>.xmp (darktable’s XMP file naming formats) darktable also checks for the presence of a file in the form <basename>.xmp (the naming format for Lightroom’s XMP sidecar files). Files with the latter naming format will be read by darktable but will not be written to. Once the image has been imported, darktable will generate an additional XMP file using its own naming convention.

lighttable view layout

Mon, 01 Jan 0001 00:00:00 +0000

🔗left panel

From top to bottom:

import: Import images from the filesystem or a connected camera.
collections: Filter the images displayed in the lighttable center panel – also used to control the images displayed in the filmstrip and timeline modules.
recently used collections: View recently used collections of images.
image information: Display image information.
lua scripts installer (optional): Install lua scripts.

🔗right panel

From top to bottom:

selection: Select images in the lighttable using simple criteria.
actions on selection: Perform actions on selected images.
history stack: Manipulate the history stack of selected images.
styles: Store an image’s history stack as a named style and apply it to other images.
metadata editor: Edit metadata for selected images.
tagging: Tag selected images.
geotagging: Import and apply GPX track data to selected images.
export: Export selected images to local files or external services.
neural restore: Apply AI-powered raw denoise, RGB denoise, or upscaling to selected images.

🔗bottom panel

map view layout

Mon, 01 Jan 0001 00:00:00 +0000

🔗left panel

These modules are identical to the lighttable view. From top to bottom:

collections: Filter the list of images displayed in the map view.
recently used collections: View recently used collections of images.
image information: Display image information.

🔗right panel

Here you can find the modules specific to the map view. From top to bottom:

find location: Search for a place on map.
locations: Manage a hierarchical list of location tags and their corresponding regions on the map.
map settings: Choose the map provider and set up various map display parameters.
tagging: Tag selected images.
geotagging: Apply GPX track data to selected images.

🔗bottom panel

filmstrip: Drag images from the filmstrip onto the map as described in the map overview.

module groups

Mon, 01 Jan 0001 00:00:00 +0000

A number of pre-defined module groups are shipped with darktable and are selectable as presets. These are summarized below.

All of these presets (with the exception of modules: deprecated and search only) also include the quick access panel. All except the modules: deprecated group include the search bar.

🔗modules: all

This preset contains all modules, sorted according to the traditional module groupings used prior to darktable 3.4, as follows:

base modules: The minimal set of modules normally required to render a presentable image.
tone modules: Other modules related to tone levels and contrast.
color modules: Modules related to color grading and color profiles.
corrective modules: Modules related to correcting problems such as lens distortions, sensor noise, sharpening, etc.
(special) effects modules: “Special effect” modules such as bloom, diffuse or sharpen, etc.

🔗workflow: scene-referred & workflow: display-referred

These presets define groups of modules relevant to the scene-referred and display-referred workflows, sorted into groups as shown below:

multiple instances

Mon, 01 Jan 0001 00:00:00 +0000

Many of darktable’s modules can be applied more than once in the pixelpipe. Each instance of a module behaves independently, taking its input from the module below it in the pixelpipe and delivering its output to the next module.

As with the base instance of a module, all instances can be moved independently within the pixelpipe either by holding Ctrl+Shift while dragging & dropping or by choosing “move up” or “move down” in the multiple instances drop-down menu.

print view layout

Mon, 01 Jan 0001 00:00:00 +0000

The central area displays the image layout on the paper (the white area). Some gray borders may be displayed around the image to represent the printable area (the page minus the borders) not filled by the image.

The filmstrip below the image allows you to select more images.

🔗overlays

When the mouse is over the bounding box of an image, its width and height are shown along its top and left, respectively. Margins between the bounding box and the page edge are notated next to the dotted lines extending out from each side of the bounding box. All measurements are shown in the units as chosen in the print settings module.

screen layout

Mon, 01 Jan 0001 00:00:00 +0000

The layout of all darktable views is similar and consists of a center area with panels at the edges:

center area : Contains information and functionality specific to the current view.
left panel : Contains modules primarily used to provide information.
right panel : Contains modules primarily used for image processing.
top banner : Contains information about the current darktable version and allows you to switch between views. Also used by some modules to show additional hints and messages.

supported file formats

Mon, 01 Jan 0001 00:00:00 +0000

darktable supports a huge number of file formats from various camera manufacturers. In addition darktable can read a wide range of low- and high-dynamic-range images – mainly for data exchange between darktable and other software.

In order for darktable to consider a file for import, it must have one of the following extensions (case independent): 3FR, ARI, ARW, BAY, BMQ, CAP, CINE, CR2, CR3, CRW, CS1, DC2, DCR, DNG, GPR, ERF, FFF, EXR, IA, IIQ, JPEG, JPG, JXL, K25, KC2, KDC, MDC, MEF, MOS, MRW, NEF, NRW, ORF, PEF, PFM, PNG, PXN, QTK, RAF, RAW, RDC, RW1, RW2, SR2, SRF, SRW, STI, TIF, TIFF, X3F

tethering view layout

Mon, 01 Jan 0001 00:00:00 +0000

🔗left panel

image information: Display image information.

🔗right panel

From top to bottom:

scopes: A graphical depiction of the current image’s light levels and colors. This module can be moved to the left-hand panel if desired (see preferences > miscellaneous > position of the scopes module).
session: Session settings.
live view: Live view settings.
camera settings: Camera settings.
metadata editor: Edit metadata for selected images.
tagging: Tag selected images.

🔗bottom panel

From left to right:

the pixelpipe & module order

Mon, 01 Jan 0001 00:00:00 +0000

The ordered sequence of processing modules operating on an input file to generate an output image is known as the “pixelpipe”.

The order of the pixelpipe is represented graphically by the order in which modules are presented in the user interface – the pixelpipe starts with a RAW image at the bottom of the module list, and applies the processing modules one by one, piling up layer upon layer of processing from the bottom up, until it reaches the top of the list, where it outputs the fully processed image.

usage

Mon, 01 Jan 0001 00:00:00 +0000

The slideshow view is still in an early stage of development with only a basic set of features.

If you don’t need the auto-advance mode, you could even use the sticky preview feature instead.


spacebar             start and stop auto-advance mode which automatically switches
                     to the next images every five seconds by default.

ESC                  leave slideshow mode and return to lighttable view.


+ or                 increase delay between each image.
up arrow 

- or                 decrease delay between each image.
down arrow

left-click or        
right arrow or       switch to the next image of the collection.
right shift-key

right-click or       
left arrow or        switch to the previous image of the collection.
left shift-key

Hint: To take full advantage of your screen size, put darktable into fullscreen mode by pressing F11 and hide the border-controls by pressing the B key.

usage

Mon, 01 Jan 0001 00:00:00 +0000

The tool is organized into three tabs in the upper part and a text output frame in the lower part.

The first tab is used to define the source image, the second tab defines the reference (target) and the third tab contains the controls to generate the resulting darktable style.

zoomable lighttable

Mon, 01 Jan 0001 00:00:00 +0000

The zoomable lighttable mode provides an alternative way to navigate large collections of images, but with some similarities to the filemanager mode (described below).

🔗controls

zoom: Scroll with the mouse wheel to zoom in and out of the lighttable (compared to Ctrl+scroll in filemanager mode).; Zooming the thumbnails does not change the number of thumbnails per row, so the lighttable can exceed the visible area on all sides.
navigate: Hold down the left mouse button and drag to move the lighttable around and navigate through your collection.
select: As with the filemanager mode, you can select the image under the pointer by clicking on its thumbnail or by pressing Enter. To select a range of images, click on the first image and then Shift+click on the last one. To add or remove images in a selection, Ctrl+click on a thumbnail or hover over a thumbnail and press Spacebar.
hover: Hovering over a thumbnail highlights and impicitly selects it for keyboard shortcuts as in filemanager mode. However, dragging pans the entire thumbnail display, so you cannot change images’ custom sort order in this mode.

Hint: you may find that image thumbnails are slow to load when zooming quickly through a large collection. One way to speed up the navigation is to generate a cache containing all the thumbnails using the darktable-generate-cache command.

image sequence

Mon, 01 Jan 0001 00:00:00 +0000

A collection of images is always presented in a specific sort by sequence that determines the order of their display, processing, and export. It is often convenient to be able to control this sequence (e.g. for a slideshow or document).

You may choose to sort by an image attribute (filename, capture time, rating, title, etc.) using the sort by drop-down menu at the left-hand-side of darktable’s top panel or combine multiple sort criteria by clicking on new sort in the left panel at the bottom of the collection filters module.

a simple lua example

Mon, 01 Jan 0001 00:00:00 +0000

Let’s start with a simple example that will print some code on the console. Create a file called luarc in darktable’s configuration directory and add the following line to it:

print("Hello World !")

Start darktable from the console and you will see the sentence “Hello World !” printed on the console. Nothing fancy but it’s a start.

At this point, there is nothing darktable-specific in the script. We simply use Lua’s standard print function to print a string. That’s nice and all, but we can do better than that. To access the darktable API you first need to require it and save the returned object in a variable. Once this is done you can access the darktable API as subfields of the returned object. All of this is documented in darktable’s Lua API reference manual.

activating OpenCL in darktable

Mon, 01 Jan 0001 00:00:00 +0000

Using OpenCL in darktable requires that your PC is equipped with a suitable graphics card and that it has the required libraries in place. Most modern graphics cards from NVIDIA, Intel or AMD come with full OpenCL support. The OpenCL compiler is normally shipped as part of the proprietary graphics driver and is used as a dynamic library called libOpenCL.so. This library must be in a folder where it can be found by your system’s dynamic linker.

culling

Mon, 01 Jan 0001 00:00:00 +0000

Culling mode allows you to display images side by side for easy comparison.

Thumbnail overlays can be controlled by selecting the star icon in the top panel and changing the “culling overlays” setting. If “no overlays” is selected, then the overlay can be shown on-demand by pressing the “I” key.

🔗controls

zoom: In culling mode, you can zoom into images (up to 100%) by holding Ctrl while scrolling with the mouse wheel.; Pan within zoomed images with click+drag.; By default, zooming and panning are synchronized between all visible images. If you want to zoom or pan only a specific image, add the Shift modifier to the above actions.
navigate: Use the mouse wheel or arrow keys (←/→) to scroll through your collection.

🔗modes

There are two different culling modes, which define how many images are shown at the same time: “fixed” and “dynamic”. Switch between these while in culling mode by pressing the “<” key.

darktable-generate-cache

Mon, 01 Jan 0001 00:00:00 +0000

The darktable-generate-cache binary updates darktable’s thumbnail cache. Invoke this program to generate all missing thumbnails in the background when your computer is idle.

darktable-generate-cache can be called with the following command line parameters:

darktable-generate-cache
              [-h, --help]
              [--version]
              [--min-mip <0-8>] [-m, --max-mip <0-8>]
              [--min-imgid <N>] [--max-imgid <N>]
              [--core <darktable options>]

All parameters are optional. If started without parameters darktable-generate-cache uses reasonable defaults.

-h, --help: Display usage information and terminate.
--version: Display copyright and version information and terminate.
--min-mip <0-8>, -m, --max-mip <0-8>: darktable can store thumbnails with up to eight different resolution steps for each image. These parameters define the maximum resolution to be generated (defaults to a range of 0-2). There is normally no need to generate all possible resolutions here – missing ones will be automatically generated by darktable the moment they are needed. When asked to generate multiple resolutions at once, the lower-resolution images are quickly downsampled from the highest-resolution image.
--min-imgid <N>, --max-imgid <N>: Specifies the range of internal image IDs from the database to work on. If no range is given, darktable-generate-cache will process all images.
--core <darktable options>: All command line parameters following --core are passed to the darktable core and handled as standard parameters. See the darktable binary section for a detailed description.

examples

Mon, 01 Jan 0001 00:00:00 +0000

The following sections show two typical use cases for the tethering view.

🔗studio setup with screening

This is a pretty common use case. You have your studio and subject set up, the camera is connected to your computer and tethering view is active in darktable. You work at the camera and take images. Whenever you like, you can review the images directly on your computer monitor instead of using the camera LCD.

filmstrip

Mon, 01 Jan 0001 00:00:00 +0000

The filmstrip, when enabled, is shown at the bottom of the screen (except in the lighttable view, where it is replaced with the timeline module) and displays the images from the current collection (set in the lighttable view). You can navigate the filmstrip by scrolling with the mouse wheel.

The filmstrip allows you to interact with images while you are not in the lighttable view. For example, while developing an image in darkroom mode, you can switch to another image by double-clicking its thumbnail in the filmstrip. You can also rate and color-classify the images as you do in lighttable, as well as copy & paste the history stack using keyboard shortcuts. As as in the lighttable view, you can drag and drop thumbnail images to change images’ sequence when using a custom sort order.

GPU acceleration

Mon, 01 Jan 0001 00:00:00 +0000

Enabling GPU acceleration for darktable’s AI features is a two-step process:

Install a GPU-capable ONNX Runtime for your hardware (this page).
Point darktable at the new library via AI preferences – click detect to auto-scan standard install locations, or browse to the file by hand.

On Linux, the bundled runtime is CPU-only; on Windows, it uses DirectML; and on macOS, it uses CoreML. So, step 1 only applies if you want NVIDIA, AMD, or Intel GPU acceleration on Linux or Windows. Step 1 has three paths, covered below.

import

Mon, 01 Jan 0001 00:00:00 +0000

Control default file naming conventions used when importing images.

🔗session options

The following options define the default naming pattern for use in the “copy & import” or “copy & import from camera” options in the import module, or when taking photos in the tethering view.

The naming pattern consists of three parts: a base part defining the parent folder, a session part defining a filmroll (which is specific to the individual import session), and a file name part defining the filename structure for each imported image.

local copies

Mon, 01 Jan 0001 00:00:00 +0000

Many users have huge image collections stored on extra hard drives in their desktop computer, or on an external storage medium (RAID NAS, external hard drives etc.).

It is a common requirement to develop a number of images while travelling using a laptop and then later synchronize them back to the original storage medium. However, copying images manually from the main storage to the laptop and back is cumbersome and prone to errors. The “local copies” feature of darktable has been designed to directly support these use cases.

parametric masks

Mon, 01 Jan 0001 00:00:00 +0000

The parametric mask feature offers fine-grained selective control over how individual pixels are masked. It does this by automatically generating an intermediate blend mask from user-defined parameters. These parameters are color coordinates rather than the geometrical coordinates used in drawn masks.

For each data channel of a module (e.g. Lab, RGB) and several virtual data channels (e.g. hue, saturation) you can construct a per-channel opacity function. Depending on each pixel’s value for a given data channel this function calculates a blending factor between 0 and 1 (100%) for that pixel.

presets

Mon, 01 Jan 0001 00:00:00 +0000

Presets allow you to store commonly-used module settings for future use. Some modules already come with pre-defined (internal) presets and you may also define your own (user-defined). Both internal and user-defined presets can be shown by clicking the presets menu in the module header.

Most of the functionality described here applies to processing modules only. However, presets can also be used with some utility modules. When used with utility modules, the functionality to auto-apply or auto-show presets based on image Exif data is not available.

process

Mon, 01 Jan 0001 00:00:00 +0000

This section is intended to get you comfortable processing images in the darkroom view using a scene-referred workflow. You are advised to follow the guidelines provided below, up to the end of the image processing in 3 modules section and then choose other areas to learn as-and-when you need to use those techniques in your images.

🔗getting started

🔗take a well-exposed photograph

Good image processing techniques start in the camera – a well-exposed image (without blown highlights or heavily crushed blacks) will always make post-processing much more straightforward. Under- or over-exposure can be “fixed” by darktable to some extent but no software can recover information that is not present in the Raw image (clipped highlights). Where possible, you are advised to use exposure to-the-right (ETTR) techniques to maximize the amount of data available for processing while avoiding clipping. As a general rule of thumb, in cases where the scene-dynamic-range exceeds that of your camera, it is safe to underexpose all images by 0.5 to 1 EV (by reducing the ISO sensitivity if possible) even if the in-camera preview looks darker than expected (the preview is not the raw data). If the scene dynamic range is lower than that of your camera, you may wish to dial in some over-exposure (decrease shutter speed or increase aperture) to capture more light and reduce noise.

quick access panel

Mon, 01 Jan 0001 00:00:00 +0000

The quick access panel allows you to access widgets from a number of processing modules all in one place.

The initial set of modules (and widgets) in the panel is determined by the auto-apply pixel workflow defaults setting in processing preferences.

You can add or remove widgets in the panel by:

right-clicking on the .
right-clicking on the module name.
using the manage module layouts screen.
Ctrl+clicking on a widget in a processing module while in visual shortcut mapping mode.

Click on the icon to the left of the module name to enable/disable the module.

rendering method

Mon, 01 Jan 0001 00:00:00 +0000

darktable can render colors either with its own internal algorithms or by using the external library LittleCMS2. darktable’s internal method is, by an order of magnitude, faster than the external one. The external option gives you a choice of the rendering intent and might offer a slightly higher accuracy in some cases.

You can change the default method in preferences > processing > always use LittleCMS 2 to apply output color profile

source image

Mon, 01 Jan 0001 00:00:00 +0000

In the “source image” tab you set your source image, which requires two elements. The first element is an input file in Lab Portable Float Map format (extension .pfm). The source file represents the largely unmodified data as the camera sees it. Information about how to take photos of a color reference card and produce a .pfm output file are described below. The second element is a chart file that contains a formal description of the underlying color reference card’s layout (extension .cht). Chart files are usually shipped with your color reference card or can be downloaded from the internet.

the history stack

Mon, 01 Jan 0001 00:00:00 +0000

The history stack stores the entire editing history for a given image, in the order in which those edits were applied. It is saved to darktable’s library database and the image’s XMP sidecar file and persists between editing sessions.

Each time a processing module is enabled, disabled, moved or amended a new entry is added to the top of the history stack.

The history stack can be queried and modified within the history stack module in the darkroom.

thumbnails

Mon, 01 Jan 0001 00:00:00 +0000

Each image in the current collection is represented by a thumbnail in the lighttable view and filmstrip module. A cache of the most recently used thumbnails is stored in a file on disk and loaded into memory at startup.

🔗thumbnail creation

A thumbnail is created when an image is imported into darktable for the first time, after an image has been modified in the darkroom, or when revisiting an image whose thumbnail is no longer available.

undo/redo

Mon, 01 Jan 0001 00:00:00 +0000

Most changes made within the lighttable are recorded and can be reverted to a previous state. This includes modifications to color labels, ratings, geo-localization, tags, metadata, orientation, copy/paste of history, image duplication, or application of a style. Note that the facility to undo/redo actions is unlimited in the number of steps while in the lighttable view, but it is reset each time you switch to a different view.

Press Ctrl+Z to undo the last modification and Ctrl+Y to redo the last undone modification (if any).

memory & performance tuning

Mon, 01 Jan 0001 00:00:00 +0000

🔗memory requirements

Processing a Raw image in darktable requires a great deal of system memory. A simple calculation makes this clear: For a 20 megapixel image, darktable requires a 4x32-bit floating point cell to store each pixel, meaning that each full image of this size will require approximately 300MB of memory just to store the image data. In order to actually process this image through a given module, darktable needs at least two buffers (input and output) of this size, with more complex modules potentially requiring several additional buffers for intermediate data. Without further optimization, anything between 600MB and 3GB of memory might be required to store and process image data as the pixelpipe executes. On top of this is darktable’s code segment, the code and data of any dynamically-linked system libraries, as well as further buffers that darktable uses to store intermediate states (cache) for quick access during interactive work.

combining drawn & parametric masks

Mon, 01 Jan 0001 00:00:00 +0000

Drawn and parametric masks can be used in combination to form a single mask that can be applied to a module.

There are two main elements which control how individual masks are combined: the polarity setting of each individual mask (defined by the plus or minus buttons) and the setting in the “combine masks” combobox.

The “combine masks” combobox contains the following options, defining how the drawn and parametric masks will be combined:

darktable-chart

Mon, 01 Jan 0001 00:00:00 +0000

The darktable-chart binary is a dedicated utility to create styles out of pairs of images such as RAW+JPEG with in-camera processing. Details about its usage can be found in the using darktable-chart section.

darktable-chart can either start a GUI or be used as a command-line program.

darktable-chart
              [--help]
              [<input Lab pfm file>]
              [<cht file>]
              [<reference cgats/it8 or Lab pfm file>]

All parameters are optional, however, if you want to supply the second file name you also need to supply the first one. Starting darktable-chart this way opens a special GUI (details can be found in the using darktable-chart section).

export

Mon, 01 Jan 0001 00:00:00 +0000

darktable is a non-destructive editor, which means that all changes are recorded in the library database (with a backup stored in an XMP sidecar file), and the original Raw file is left untouched. You therefore need to export images in order to bake your edits into an output file that can be distributed outside of darktable.

Choose an export scenario.

The export module offers many options, but by far the most common use is to “save a developed raw image as a JPEG”. You can either export the currently-edited image directly from the darkroom view or select one or more images from the lighttable view and export them all at once.

full preview

Mon, 01 Jan 0001 00:00:00 +0000

From any of the lighttable modes, you can display a fully-zoomed preview of the image that is currently under the mouse pointer by pressing and holding down W. This is useful to more closely inspect an image while rating and selecting images.

Pressing and holding Ctrl+W fully zooms into the image and also identifies any regions of sharpness in the image that may indicate image focus. For this tool to work the input image needs to hold an embedded JPEG thumbnail, which is the case for most raw files.

lighttable

Mon, 01 Jan 0001 00:00:00 +0000

Control functionality in the lighttable view and modules.

🔗general

hide built-in presets for utility modules: If enabled, only user-defined presets will be shown in presets menu for utility modules – built-in presets will be hidden (default off).
use single-click in the collections module: Enable “single click” mode in the collections module, which allows ranges to be selected (default off).
prioritize the hovered image over the selected images: Controls which images are affected by an action (e.g. using the keyboard to set the number of stars). If this option is enabled, only the image hovered over is affected by the action. If disabled, all the selected images are affected (i.e. selection is prioritized) and the hovered-over image is only affected if it is also one of the selected images. (default on)
expand a single utility module at a time: Controls how utility modules are expanded. If this option is enabled, expanding a module by clicking collapses any other currently expanded panel. If you want to expand a panel without collapsing the others you can do so with Shift+click. Disabling this option inverts the meaning of click and Shift+click (default off).
scroll utility modules to the top when expanded: With this option enabled the side panerepresent will scroll a utility module to the top of the panel when it is expanded. (default off)
rating an image one star twice will not zero out the rating: Normally clicking a one star rating twice will set a zero star rating to that image. Check this option to disable this functionality (default off).
show scrollbars for center view: Choose whether to show scrollbars in the center view of the lighttable (default on).
show image time with milliseconds: Choose whether to include milliseconds when displaying time values (default off). If set, milliseconds are shown in the image information module and can also be used in the geotagging module.

🔗thumbnails

use raw file instead of embedded JPEG from size: When generating thumbnails for images that have not yet been processed in the darkroom, if the thumbnail size is greater than this value, generate it by processing the raw image data. If the thumbnail is below this size, use the JPEG preview image embedded in the raw file. Once an image has been processed in the darkroom, thumbnails will always be generated from raw data (you can revert back to the JPEG preview by discarding history). To render thumbnails with the best quality choose “always”.
high quality processing from size: If the thumbnail size is greater than this value and is being generated from raw data, it will be processed using the full quality rendering path, which is better but slower (default 720p). To render thumbnails with the best quality, choose “always”.
enable disk backend for thumbnail cache: If activated, darktable stores all thumbnails on disk as a secondary cache, and thereby keeps thumbnails accessible if they are dropped from the primary cache. This needs more disk space but speeds up the lighttable view as it avoids the reprocessing of thumbnails (default on).
enable disk backend for full preview cache: If enabled, darktable writes full preview images to disk (.cache/darktable/) when evicted from the memory cache. Note that this can take a lot of storage (several gigabytes for 20k images) and darktable will never delete cached images. It’s safe to delete these manually if you want. Enabling this option will greatly improve lighttable performance when zooming an image in full preview mode (default off).
enable smooth scrolling for lighttable thumbnails: If enabled, use fractional scrolling when navigating through the thumbnails in the filemanager layout for a smoother experience. When enabled, the top row of thumbnails may only show partial images as the scrolling is not aligned with each row. This setting is most useful when scrolling via a touchpad or other input device rather than a mouse with a scroll wheel (default off).
generate thumbnails in background: Choose whether to automatically generate thumbnails in the background when the user is in the lighttable view and is inactive (no keyboard/mouse activity). Thumbnails will be generated up to the selected size (default never).; Note: You can set the period of inactivity required before thumbnail generation will start by altering the backthumbs_inactivity setting in darktablerc in the darktable configuration directory (default 5 seconds).

manage module layouts

Mon, 01 Jan 0001 00:00:00 +0000

Manage the layout and grouping of processing modules and the quick access panel.

This maintenance screen can be accessed from the presets menu beside the module search box or module group icons (below the scopes module in the darkroom view). Ctrl+click on the preset menu to open this screen directly.

Settings are automatically saved when you exit the screen. Click reset to abandon any changes made in the current editing session.

module controls

Mon, 01 Jan 0001 00:00:00 +0000

This section describes how to interact with processing module controls.

🔗sliders

Sliders offer five different methods of interaction, depending on the level of control you require.

left-click (set): Click anywhere in the slider area to set the value. You can also click and drag to change it. You don’t have to aim for the triangle or even the line – you can click anywhere in the entire height of the slider, including the label.
mouse wheel (adjust): Hover over the slider with your mouse, then use your mouse wheel to adjust the value. You can alter the default speed at which the mouse scroll adjusts a slider by scrolling over that slider while in visual shortcut mapping mode.
keyboard arrow keys (adjust): When the slider has focus you can hover over the slider with your mouse, then use your keyboard’s arrow keys (←/↓ and →/↑) to adjust the value. In order to give focus to the widget without changing the current value you can right-click, then right-click again.
right-click (pop-up edit): When your mouse is over a slider right-clicking enables a multi-functional pop-up below the slider for fine control with your mouse or numerical entry using the keyboard.

performance & troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

🔗performance notes

CPU inference is acceptable for object masks (small one-shot evaluations) but much slower for denoise and upscale. A CUDA / MIGraphX / OpenVINO / DirectML / CoreML runtime is strongly recommended if you use those regularly.
Upscale at 4x on a large image is memory-hungry regardless of provider. Tiling is enabled automatically to keep memory in check, at a cost of some extra processing time.
Loading ONNX Runtime lazily on first use means the very first AI operation after startup takes an extra moment. This is normal.
When switching between execution providers (e.g. auto → CUDA), the new provider’s first inference incurs a graph-compilation delay. After that, runtime is steady for the rest of the session.
AMD (MIGraphX) has a multi-minute first-run cost per model. ROCm/MIGraphX compiles the model graph for your specific GPU the first time it sees it, which can take 1–3 minutes for large models (denoise, upscale); mask models are smaller and compile faster. The compiled graph is cached on disk under ~/.cache/darktable/ai_v*_migraphx_* and reused across darktable restarts, so subsequent runs of the same model are fast.
Model discovery is cached at startup. If you drop a new .dtmodel file into the models directory manually while darktable is running, open AI preferences and toggle any control to force a rescan.

🔗troubleshooting

Most AI problems fall into one of three buckets.

printing labeled images

Mon, 01 Jan 0001 00:00:00 +0000

The first example showed us the very basics of lua and allowed us to check that everything was working properly. Now let’s do something a little bit more complex. Let’s try to print a list of images that have a “red” label attached to them. But first of all, what is an image?

local darktable = require "darktable"
local debug = require "darktable.debug"
print(darktable.debug.dump(darktable.database[1]))

Running the code above will produce a lot of output. We will look at it in a moment, but first let’s look at the code itself.

reference values

Mon, 01 Jan 0001 00:00:00 +0000

The “reference values” tab determines the target values to which the source image must to be modified by the resulting style. You can either supply reference values in the form of measured data of your color reference card (mode “cie/it8 file”), or you can supply a photographic image (mode “color chart image”) much in the same way as described above. This second image must also be supplied in Lab Portable Float Map format. There is no need to supply the chart file again as darktable-chart takes the same one as defined under “source image”. You only need to again align the layout grid and the image and potentially adjust the “size” slider.

rendering intent

Mon, 01 Jan 0001 00:00:00 +0000

If rendering with LittleCMS2 is activated (see rendering method) you can define how to handle out-of-gamut colors when converting between color spaces. A selection box in the export, output color profile, and soft proof modules gives you a choice of the following rendering intents:

perceptual: Best suited to photographs as it maintains the relative position of colors. This is usually the best choice.
relative colorimetric: Out-of-gamut colors are converted to colors having the same lightness, but different saturation. Other colors remain unmodified.
saturation: Saturation is retained but lightness is slightly changed.
absolute colorimetric: Keep the white point.

setting up OpenCL

Mon, 01 Jan 0001 00:00:00 +0000

The huge diversity of systems and the marked differences between OpenCL vendors and driver versions makes it impossible to give an comprehensive overview of how to setup OpenCL. We only can give you an example, in this case for NVIDIA driver version 542.29.06 on Fedora 39. We hope that this will serve as a basic introduction and will help you to solve any problems specific to your setup.

The principle OpenCL function flow is like this:

star ratings & color labels

Mon, 01 Jan 0001 00:00:00 +0000

Star ratings and color labels help you to sort and rank images according to your own criteria. An image’s star rating and color labels can be displayed over thumbnails in the lighttable view and filmstrip module.

🔗star ratings

You can give an image a rating from zero to five stars. Whenever you import images, each image receives a default rating which you can define in the import module. You can also mark an image as “rejected”.

top panel

Mon, 01 Jan 0001 00:00:00 +0000

The top panel appears in all darktable views and provides access to common functions.

🔗On the left-hand-side

filter: Choose which of a collection’s images are displayed, making them available to different views for selection and action. Criteria can be altered in the collection filters module or by clicking the icon.
sort by: Choose the property that orders the displayed image sequence.
sort order: Switch the sort order (ascending / descending).

🔗On the right-hand-side

grouping: Expand or collapse grouped images.
thumbnail overlays: Define what information is overlaid on to thumbnails in the lighttable/filmstrip.; You can define different settings depending on the thumbnail size. See preferences > lighttable for details of how size delimiters are set.
context-sensitive help: Click this icon and then click on a control element to be directed to the appropriate online help page.
shortcut mapping: Click this icon to enter the visual shortcut mapping mode to create keyboard/mouse shortcuts.
preferences: View and amend darktable’s preferences & settings.

troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

This troubleshooting guide can be used to verify whether or not your camera can be used with tethering. This is done using the same (gphoto2) tool that darktable uses to interface with your camera.

Before you start, you first need to find your camera port name. Usually the port “usb:” is sufficient and is therefore used in the following guide.

🔗is your camera detected?

The following command will verify that your camera is connected to the computer and detected by gphoto2.

undo and redo

Mon, 01 Jan 0001 00:00:00 +0000

While you are editing your image, darktable records all of the modifications you make to that image. This means that it is possible to undo and redo changes to recover a previous editing state. Note that the undo/redo facility is unlimited in the number of steps while editing an image, but is reset each time the darkroom is switched to a new image.

Press Ctrl+Z to undo the last modification and Ctrl+Y to redo the last undone modification (if any).

adding a simple shortcut

Mon, 01 Jan 0001 00:00:00 +0000

So far, all our scripts have done things during startup. This is of limited use and doesn’t allow us to react to real user actions. To do more advanced things we need to register a function that will be called on a given event. The most common event to react to is a keyboard shortcut.

darktable = require "darktable"

local function hello_shortcut(event, shortcut)
darktable.print("Hello, I just received '"..event..
       "' with parameter '"..shortcut.."'")
end

darktable.register_event("hello shortcut",
       "shortcut",hello_shortcut,
       "A shortcut that prints its parameters")

Now start darktable, go to “preferences > shortcuts > lua > A shortcut that prints its parameters”, assign a shortcut and try it. You should see a nice message printed on the screen.

bottom panel

Mon, 01 Jan 0001 00:00:00 +0000

The bottom panel appears in all darktable views. Common controls are described here. View-specific controls are described in the appropriate pages:

🔗common controls

view log history

Display a scrollable popover showing stored log messages with timestamps. The log history viewer provides a persistent record of application log messages (e.g., export/import progress, library operations, warnings, and errors). The key features are:

Messages are stored in a circular buffer; when the buffer is full, older entries are removed as new ones arrive

Consecutive identical messages are automatically deduplicated (e.g., repeated “exporting image” updates)

Entries are displayed in monospace format with HH:MM:SS timestamps

Individual entries are selectable and can be copied to the clipboard with Ctrl+C

the viewer is closed by clicking anywhere outside the popover

curves

Mon, 01 Jan 0001 00:00:00 +0000

The base curve, tone curve and rgb curve modules use curves to control the tones in the image. These modules have some common features that warrant separate discussion.

🔗nodes

In their default state, curves are straight lines, defined by two anchor nodes at the top-right and bottom-left of the graph. You can move the nodes to modify the curve or generate new nodes by clicking on the curve. Ctrl+click to 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 the risk of accidentally modifying the curve. Up to 20 nodes can be defined per curve. To remove a node, click on it and drag it out of the widget area.

darkroom

Mon, 01 Jan 0001 00:00:00 +0000

Control functionality in the darkroom view and associated modules.

🔗general

scroll down to increase mask parameters: By default, scrolling your mouse up increases the value of the relevant shape parameters in drawn masks. Set this preference to reverse the behavior (default off).
middle mouse button zooms to 200%: When enabled, clicking the middle mouse button on the image canvas causes the zoom level to toggle between fit, 100% and 200%. When disabled, the middle mouse button toggles between fit and 100%. In the latter case, you can use Ctrl+middle-click to access the 200% zoom level (default on).
pattern for the image information line: Set the information to be displayed in the image information line. You can use any variables in the variables section as well as $(NL) for a new line. You can also include formatting (bold, italic, colors etc).
position of the image information line: Choose the darkroom panel in which the image information line is displayed. Choose between “top left” “top right” “top center” “bottom” and “hidden” (default “bottom”).
border around image in darkroom mode: Display the center image in darkroom mode with an outside border of the given number of pixels (default 20).
show scrollbars for center view: Choose whether to show scrollbars in the center view of the darkroom (default off).
show loading screen between images: Show gray loading screen when navigating between images in the darkroom. Switch this option off to just show a simple toast message and leave the previous image in place until the next image is loaded. Note that switching this option off can be very useful to quickly compare duplicate images, however, there might be issues with long loading times (leading you to think the next image has already loaded) and you may observe visual artifacts while the next image is loading (default on).

🔗modules

display of individual color channels

Control how individual color channels are displayed when activated in the parametric masks feature. You can choose between “false color” and “gray scale” (default “false color”).

hide built-in presets for processing modules

If enabled, only user-defined presets will be shown in the presets menu for processing modules – built-in presets will be hidden (default off).

show the guides widget in modules UI

Enable this to show the local guides & overlays interface directly within the UI of the modules that support it (default on).

expand a single processing module at a time

Control how processing modules are expanded in the darkroom. If this option is enabled, expanding a module by clicking collapses any currently expanded module. If you want to expand a module without collapsing the others you can do so with Shift+click. Disabling this option inverts the meaning of click and Shift+click (default on).

only collapse modules in current group

When choosing to expand a single processing module at a time (using the logic defined in the previous setting), only collapse other modules that appear in the current visible group. Disable this option to ensure that modules in non-visible groups are also collapsed (default on).

expand the module when it is activated, and collapse it when disabled

Select this option for the darkroom to automatically expand or collapse processing modules when they are enabled or disabled. (default off)

scroll processing modules to the top when expanded

With this option enabled processing modules are scrolled to the top of the right-hand panel when expanded. (default on)

swap the utility and processing modules panels

If enabled, swap the left and right side panels in the darkroom view (default off).

show right-side buttons in processing module headers

Choose whether to show the four buttons (mask indicator, multi-instance menu, reset, presets menu) on the right-hand-side of the module header for processing modules. These buttons will always appear when the mouse is over the module. At other times they will be shown or hidden according to this preference selection:

always: always show all buttons

active: only show the buttons when the mouse is over the module

dim: buttons are dimmed when mouse is not over the module

auto: hide the buttons when the panel is narrow

fade: fade out all buttons when the panel narrows

fit: hide all the buttons if the module name doesn’t fit

smooth: fade out all buttons in one header simultaneously

glide: gradually hide individual buttons as needed

(default always)

show mask indicator in module headers

If enabled, an icon will be shown in the header of any processing modules that have a mask applied (default on).

prompt for name on addition of new instance

If enabled, when creating a new instance of a processing module, a prompt will be immediately displayed allowing you to set a name for the new instance (default off).

automatically update module name

Automatically update the name (label) on processing modules if the current parameters of the module match those of a saved preset. The module name will only be updated if it hasn’t already been manually amended for the current image. It will be set either to the module name from which the preset was made (if the module name was manually adjusted before the preset was created) or to the name of the preset itself (default on).

darktable-cltest

Mon, 01 Jan 0001 00:00:00 +0000

The darktable-cltest binary checks if there is a usable OpenCL environment on your system that darktable can use. It emits some debug output that is equivalent to calling darktable -d opencl and then terminates.

darktable-cltest is called without command line parameters.

darktable's color spaces

Mon, 01 Jan 0001 00:00:00 +0000

Input images are either RGB files (like JPEGs or TIFFs) or camera RAWs. Both store visual information as a combination of primary colors (e.g. red, green and blue) which together describe a light emission to be recreated by a display.

The following image illustrates this concept.

The left-hand-side of the image depicts a colored light that we need to represent digitally. We can use three ideal color filters to decompose this light into three colored primary lights at different intensities. In order to recreate the original colored light from our ideal decomposition (as illustrated in the center of the image) we simply need to recombine those three primary lights by addition.

image grouping

Mon, 01 Jan 0001 00:00:00 +0000

Grouping images helps to improve the structure and clarity of your image collection when displayed in the lighttable view.

You can combine images into a group by selecting them and clicking the “group” button in the actions on selection module, or by pressing Ctrl+G. Likewise, you can remove selected images from a group by clicking the “ungroup” button, or pressing Ctrl+Shift+G.

Duplicated images are automatically grouped together. Similarly, if you import multiple images from the same directory, having the same base name, but different extensions (eg. IMG_1234.CR2 and IMG_1234.JPG), those images automatically form a group.

mask refinement & additional controls

Mon, 01 Jan 0001 00:00:00 +0000

When a mask is active, several additional sliders are shown which allow the mask to be further refined.

details threshold: This control allows you to alter the opacity of the mask based on the amount of detail in the image. Use this slider to select either areas with lots of detail (positive values) or areas that are flat and lacking in detail (negative values). The default (zero) effectively bypasses details refinement. This is mostly useful to apply sharpening and blurring effects that ignore out-of-focus (bokeh) regions or to sharpen only blurry parts, preventing over-sharpening of in-focus regions.

Note: The data used for the detail mask refinement is taken from the demosaic or rawprepare stage in the processing pipeline, not from the module’s input (which is used for the other parametric mask criteria). None of the processing modules after demosaic will have any effect on the detail mask and it is not available for non-RAW images.

possible problems & solutions

Mon, 01 Jan 0001 00:00:00 +0000

darktable will detect OpenCL run-time errors automatically. On detecting an error, it will then reprocess everything on the CPU. While this will slow down processing it should not affect the end result.

There can be various reasons why OpenCL might fail during the initialization phase. OpenCL depends on hardware requirements and on the presence of certain drivers and libraries. In addition all these have to fit in terms of maker, model and revision number. If anything does not fit (e.g. your graphics driver – loaded as a kernel module – does not match the version of your libOpenCL.so) OpenCL support will likely not be available.

process

Mon, 01 Jan 0001 00:00:00 +0000

If all of the required settings in the “source image” and “reference values” tabs are ready you can move on to the “process” tab.

First, you need to tell darktable-chart which of the patches represents the gray ramp. In the screenshot displayed above, the gray ramp is positioned in the lower part of the color reference chart, denoted as “GS00…GS23”.

The “number of final patches” input defines how many editable color patches the resulting style will use within the color look up table module.

AI masking

Mon, 01 Jan 0001 00:00:00 +0000

AI masking requires AI features to be enabled in AI preferences, with a model active for the AI task the specific masking tool uses (each tool below states which one). See the AI features overview for what runs where.

Currently darktable provides one AI masking tool:

AI object: Uses the mask task. Click on a subject to produce a mask around it; iterate by adding more clicks until it covers exactly what you want. The result is vectorised into a group of path shapes and can be edited like any other drawn shape – see drawn masks: AI object for details.

wavelets

Mon, 01 Jan 0001 00:00:00 +0000

Wavelets are used to separate (or decompose) an image into a number of distinct layers, each containing a different level of detail. After decomposing an image in this way, a module can limit its processing to one or more of these detail layers, and then piece the layers back together again at the end to form its output. This allows us to be surgical about which features in the image we wish to impact when working with a module.

deprecated modules

Mon, 01 Jan 0001 00:00:00 +0000

The darktable team regularly reviews old modules and updates their implementation where issues are found or updated science means that they can be improved. Most of the time we try to update existing modules with new functionality but occasionally that becomes problematic, often due to the overhead of having to maintain multiple versions of the module. In such circumstances a new replacement module is created and the old module becomes deprecated.

darktable-cmstest

Mon, 01 Jan 0001 00:00:00 +0000

The darktable-cmstest binary (Linux only) investigates whether the color management subsystem of your computer is correctly configured and displays some useful information about the installed monitor profile(s).

darktable-cmstest is called without command line parameters.

exporting images with lua

Mon, 01 Jan 0001 00:00:00 +0000

So far we have learned to use lua to adapt darktable to our particular workflow. Let’s look now at how to use lua to easily export images to an online service. If you are able to upload an image to a service via the command line then you can use lua to integrate this into darktable’s user interface.

In this next example we will use lua to export via scp. A new storage type will appear in darktable’s UI that will export images to a remote target via the copy mechanism in ssh.

keyboard shortcuts

Mon, 01 Jan 0001 00:00:00 +0000

Much of the functionality in darktable can be controlled via keyboard shortcuts, which can be customised in preferences > shortcuts.

Press the H key (for help) in any darktable view to show a list of all shortcuts that are applicable to the current view.

making input images for darktable-chart

Mon, 01 Jan 0001 00:00:00 +0000

To start with, you need a suitable photo of your color reference card in RAW+JPEG format. It goes beyond the scope of this manual to explain the details of how to take this photo, but in a nutshell you need to make the shot on a sunny day around midday with the light source (the sun) shining at an angle onto the card. You need to avoid any glare in the image. The neutral white color patch in the gray ramp (G00) should end up at the L value specified in the description of your card. Often this is L=92 and requires you to overexpose the shot by about 1/3 EV. Ideally you will make several shots with slightly different exposures and later select the right one in darktable. Make sure that the chart fills up most of the frame. Use a lens with a “normal” focal length (e.g. 50mm equivalent) and stop down a bit to avoid vignetting.

metadata and tagging

Mon, 01 Jan 0001 00:00:00 +0000

darktable allows you to store additional information about your images to allow them to be more easily searched and grouped. This information is stored in darktable’s database and XMP sidecar files and can also be included within exported images.

🔗metadata

Metadata (e.g. title, description) is free-format text that usually differs for each image. You can add metadata to images in the metadata editor module.

🔗tagging

Tags are usually shared between multiple images and are used to categorise, group, and/or sequence them. You can add tags to images in the tagging module.

raster masks

Mon, 01 Jan 0001 00:00:00 +0000

As described in the previous sections, the final output of a module’s mask (the combined effect of any drawn and parametric masks) is a grayscale raster image representing the extent to which the module’s effect should be applied to each pixel. This raster image is stored internally for active modules and can be subsequently reused by other modules in the pixelpipe.

As with any mask, if the opacity value for a pixel in a raster mask is zero, the module’s input is passed through the module unchanged. If the opacity is 1.0 the module has its full effect. For each value between 0 and 1.0 the module’s effect is applied proportionally at that location.

unbounded colors

Mon, 01 Jan 0001 00:00:00 +0000

Screens and most image file formats can only encode RGB intensities confined within a certain range. For example, images encoded on 8 bits can only contain values from 0 to 255, images on 10 bits from 0 to 1023, and so on… Graphic standards postulate that the maximum of that range, no matter its actual value, will always represent the maximum brightness that the display medium is able to render, usually between 100 and 160 Cd/m² (or nits) depending on the actual standard. We generally call this maximum “100 % display-referred”. The minimum of the range, encoded 0 no matter the bit-depth used, becomes then “0 % display-referred”. 100 % encodes pure white, 0 % encodes pure black.

variables

Mon, 01 Jan 0001 00:00:00 +0000

darktable supports variable substitution in a number of modules and preference settings. For example:

Defining file names in the export module
Displaying image information in the darkroom’s image information line
Displaying image information in the lighttable’s overlays and tooltips (see preferences > lighttable)
Placing text on an image in the watermark processing module

🔗available variables

The following variables are available, though they may not all be applicable in every context:

$(ROLL.NAME[n])            film roll of the input image, where n specifies the folder level
                           counting from the right, default n=1
$(FILE.FOLDER)             folder containing the input image
$(FILE.NAME)               basename of the input image
$(FILE.EXTENSION)          extension of the input image
$(ID)                      the image id
$(VERSION)                 the duplicate version number
$(VERSION.IF_MULTI)        same as $(VERSION) but null string if only one version exists
$(VERSION.NAME)            version name from metadata
$(DARKTABLE.VERSION)       the version of the running darktable instance
$(DARKTABLE.NAME)          name of darktable
$(SEQUENCE[n,m])           a sequence number within an export job with n digits and starting with m
                           parameters are optional, default is [4,1]
$(WIDTH.SENSOR)            width of RAW data in pixels before RAW crop
$(HEIGHT.SENSOR)           height of RAW data in pixels before RAW crop
$(WIDTH.RAW)               width of RAW data in pixels after RAW crop
$(HEIGHT.RAW)              height of RAW data in pixels after RAW crop
$(WIDTH.CROP)              image width in pixels at the end of the pixelpipe, but before export resize
$(HEIGHT.CROP)             image height in pixels at the end of the pixelpipe, but before export resize
$(WIDTH.EXPORT)            image width in pixels at the end of the pixelpipe and after export resize
$(HEIGHT.EXPORT)           image height in pixels at the end of the pixelpipe and after export resize
$(WIDTH.MAX)               maximum width entered in export module
$(HEIGHT.MAX)              maximum height entered in export module
$(YEAR)                    year at date of import/export
$(YEAR.SHORT)              two-digit year at date of import/export
$(MONTH)                   numeric (1-12) month at date of import/export
$(MONTH.LONG)              full month name at date of import/export
$(MONTH.SHORT)             abbreviated month name at date of import/export
$(DAY)                     day at date of import/export
$(HOUR)                    hour at time of import/export
$(MINUTE)                  minute at time of import/export
$(SECOND)                  second at time of import/export
$(MSEC)                    millisecond at time of import/export
$(EXIF.YEAR)               Exif year
$(EXIF.YEAR.SHORT)         Exif year, two-digit version
$(EXIF.MONTH)              Exif month, numeric
$(EXIF.MONTH.LONG)         Exif month, full name
$(EXIF.MONTH.SHORT)        Exif month, abbreviated name
$(EXIF.DAY)                Exif day
$(EXIF.HOUR)               Exif hour
$(EXIF.MINUTE)             Exif minute
$(EXIF.SECOND)             Exif second
$(EXIF.MSEC)               Exif millisecond
$(EXIF.DATE.REGIONAL)      Exif date using user's preferred regional date format
$(EXIF.TIME.REGIONAL)      Exif time using user's preferred regional date format
$(EXIF.ISO)                Exif ISO value
$(EXIF.EXPOSURE)           Exif exposure
$(EXIF.EXPOSURE.BIAS)      Exif exposure bias
$(EXIF.EXPOSURE.PROGRAM)   Exif exposure program set in camera
$(EXIF.APERTURE)           Exif aperture
$(EXIF.CROP_FACTOR)        Exif crop factor
$(EXIF.FLASH)              Exif flash setting
$(EXIF.FLASH.ICON)         flash symbol if Exif information says flash was fired, empty string if not
$(EXIF.FOCAL.LENGTH)       Exif focal length
$(EXIF.FOCAL.LENGTH.EQUIV) Exif 35 mm equivalent focal length
$(EXIF.FOCUS.DISTANCE)     Exif focus distance
$(EXIF.LENS)               Exif lens name
$(EXIF.MAKER)              Exif camera maker
$(EXIF.METERING)           Exif metering mode
$(EXIF.MODEL)              Exif camera model
$(EXIF.WHITEBALANCE)       Exif white balance set in camera
$(IMAGE.EXIF)              basic exposure information from Exif data (aperture, exposure, ISO)
$(IMAGE.ID)                the image id (note that this will be 0 during copy&import)
$(IMAGE.ID[n])             the image id (note that this will be 0 during copy&import), zero-padded to n digits
$(IMAGE.ID.NEXT)           the next image id to be assigned (can be used during copy&import)
$(IMAGE.ID.NEXT[n])        the next image id to be assigned (can be used during copy&import), zero-padded to n digits
$(IMAGE.TAGS)              tags list (Xmp.dc.Subject), with any hierarchy flattened
$(IMAGE.TAGS.HIERARCHY)    tags list (Xmp.dc.Subject), preserving hierarchy
$(LONGITUDE)               longitude
$(LATITUDE)                latitude
$(ELEVATION)               elevation
$(GPS.ELEVATION)           elevation
$(GPS.LATITUDE)            latitude
$(GPS.LONGITUDE)           longitude
$(GPS.LOCATION)            latitude, longitude, and elevation (omitting any values which are not set)
$(GPS.LOCATION.ICON)       symbol to indicate that geolocation information is present, empty string if not
$(STARS)                   star rating (text only)
$(RATING.ICONS)            star rating (using star characters)
$(LABELS)                  colorlabels (color labels as text)
$(LABELS.ICONS)            colorlabels (color labels as icons)
$(MAKER)                   camera maker
$(MODEL)                   camera model
$(LENS)                    lens
$(Xmp.dc.title)            title from metadata
$(Xmp.dc.description)      description from metadata
$(Xmp.dc.creator)          creator from metadata
$(Xmp.dc.publisher)        publisher from metadata
$(Xmp.dc.rights)           rights from metadata
$(TAGS)                    tags list (Xmp.dc.Subject)
$(CATEGORY[n,category])    tag name of level n [0,9] of selected category (or tag)
$(SIDECAR_TXT)             content of the text sidecar file (if any)
$(FOLDER.PICTURES)         pictures folder
$(FOLDER.HOME)             home folder
$(FOLDER.DESKTOP)          desktop folder
$(OPENCL.ACTIVATED)        whether OpenCL is activated
$(USERNAME)                user name defined by OS
$(NL)                      newline character
$(JOBCODE)                 internal jobcode of current job

🔗metadata

Fields from the metadata editor can be used for variable substitution using the full case-sensitive Xmp tag name as the variable name (e.g.Xmp.iptc.location).

building user interface elements

Mon, 01 Jan 0001 00:00:00 +0000

Our previous example was a bit limited. In particular the use of a preference for the export path wasn’t very nice. We can do better than that by adding elements to the user interface in the export dialog.

UI elements are created via the darktable.new_widget function. This function takes a type of widget as a parameter and returns a new object corresponding to that widget. You can then set various fields in that widget to set its parameters. You will then use that object as a parameter to various functions that will add it to the darktable UI. The following simple example adds a lib in the lighttable view with a simple label:

possible color artifacts

Mon, 01 Jan 0001 00:00:00 +0000

There are some infrequent situations that still can lead to problematic results unless the user takes some action. Some modules in Lab color space, like levels and monochrome, rely on the fact that the L channels carries all lightness information, with the a and b channels purely representing chroma and hue. Unbounded colors with negative L values are especially problematic to these modules and can lead to black pixel artifacts.

It has been found that highly saturated blue light sources in the image frame are likely candidates for pixels with negative L values. If you are engaged in stage photography you should pay close attention to such lights appearing in images.

processing

Mon, 01 Jan 0001 00:00:00 +0000

Control how images are processed.

🔗image processing

always use LittleCMS 2 to apply output color profile: If this option is activated, darktable will use the LittleCMS 2 system library to apply the output color profile instead of its own internal routines. This is significantly slower than the default but might give more accurate results in some cases.; If the given ICC is LUT-based or contains both a LUT and a matrix, darktable will use LittleCMS 2 to render the colors regardless of this parameter’s value (default off).

purge_non_existing_images.sh

Mon, 01 Jan 0001 00:00:00 +0000

Find and remove entries from the library database referencing images that no longer exist in the filesystem. You must close darktable before running this script.

The script can be called with the following command line parameters:

purge_non_existing_images.sh [-c|--configdir <path>]
                             [-l|--library <path>]
                             [-p|--purge]

Run the script with no options to perform a “dry run”, which generates a report of the missing files without committing any changes to the database.

The available options are:

darktable's color dimensions

Mon, 01 Jan 0001 00:00:00 +0000

This section defines the perceptual properties of color, both conceptually and quantitatively, in order to characterize and quantify the creative and corrective adjustments made to color in darktable.

🔗definitions

Color properties like “saturation”, “brightness” or “lightness” have passed into common usage but are largely misused and often used to mean different things. In color science, each of these terms has a precise meaning.

There are two frameworks within which color properties may be analyzed and described:

darktable's color pipeline

Mon, 01 Jan 0001 00:00:00 +0000

Most image processing applications come from the 1990s and/or inherit a 1990s workflow. These applications processed images encoded with 8 bit unsigned integers because it was more memory- and computationally-efficient. However, due to the use of an integer format (which implies rounding errors) they had to apply a “gamma” (essentially a transfer function applying a power 1/2.2 or 1/2.4 to encode the RGB values) and increase the bit-depth in the low-lights in order to reduce rounding errors there (humans are very sensitive to low-light details). The 8 bit integer formats are also technically limited to the 0-255 range. Anything outside of this range overflows and is clipped to the nearest bound.

scheduling profile

Mon, 01 Jan 0001 00:00:00 +0000

darktable can use the CPU and one or several OpenCL capable GPUs. Depending on the relative performance of these devices, users can choose among certain scheduling profiles to optimize performance. This is achieved by setting the configuration parameter preferences > processing > OpenCL > OpenCL scheduling profile, which offers the following choices:

default: If an OpenCL-capable GPU is found darktable uses it for processing the center image view while the navigation preview window is processed on the CPU in parallel. This is the preferred setting for systems with a reasonably fast CPU and a moderately fast GPU. The exact allocation of devices to the various pixelpipe types can be finetuned with the “opencl_device_priority” configuration parameter (see multiple devices).
very fast GPU: With this scheduling profile darktable processes the center image view and the preview window on the GPU sequentially. This is the preferred setting for systems with a GPU that strongly outperforms the CPU.
multiple GPUs: This setting addresses systems with multiple GPUs whose relative performance do not differ significantly. Whenever a processing job is started darktable uses any currently idle GPU but not the CPU. Users of systems with a variety of GPUs will need better control on their relative priority. They would be better off selecting the “default” profile and fine-tuning their system with the “opencl_device_priority” configuration parameter (see multiple devices).

On first start-up or after any detected change in the GPU configuration of your system darktable tries to identify the best suited profile for you. You can change it at any time in preferences > processing > OpenCL.

security

Mon, 01 Jan 0001 00:00:00 +0000

Control whether warning messages are shown before undertaking certain activities.

🔗general

ask before removing images from the library: Always ask before removing image information from darktable’s library database, where the xmp file is retained (default on).
ask before deleting images from disk: Always ask before deleting an image file (default on).
ask before discarding history stack: Always ask before discarding the history stack of an image (default on).
try to use trash when deleting images: Instead of physically deleting images from disk, attempt to put them into the system’s trash bin (default on).
ask before moving images from film roll folder: Always ask before moving an image file (default on).
ask before copying images to new film roll folder: Always ask before copying an image file to a new location (default on).
ask before removing empty folders: Always ask before removing any empty folder. This can happen after moving or deleting images (default off).
ask before deleting a tag: Always ask before deleting a tag from an image (default on).
ask before deleting a style: Always ask before deleting a style (default on).
ask before deleting a preset: Always ask before deleting a preset (default on).
ask before exporting in overwrite mode: Always ask before exporting images in overwrite mode.

🔗other

password storage backend to use: The backend to use for password storage. Options: “auto” (default), “none”, “libsecret”, “kwallet”, “apple_keychain” (on macOS), “windows_credentials” (on Windows).
auto login to storage server: When exporting images to an external storage server (Piwigo) select this option to automatically log in to the server. You must set a password storage backend (above) to use this option.
executable for playing audio files: Define an external program which is used in the lighttable view to play audio files that some cameras record to keep notes for images (default “aplay”).

sharing scripts

Mon, 01 Jan 0001 00:00:00 +0000

So far, all of our lua code has been in luarc. That’s a good way to develop your script but not very practical for distribution. We need to make this into a proper lua module. To do that, we save the code in a separate file (scp-storage.lua in this case):

--[[
SCP STORAGE
a simple storage to export images via scp

AUTHOR
Jérémy Rosen (jeremy.rosen@enst-bretagne.fr)

INSTALLATION
* copy this file in $CONFIGDIR/lua/
* add the following line in the file $CONFIGDIR/luarc
  require "scp-storage"

USAGE
* select "Export via SCP" in the storage selection menu
* set the target directory 
* export your images

LICENSE
GPLv2

]]

darktable = require "darktable"
dtutils = require "lib/dtutils"

dtutils.check_min_api_version("7.0.0", ...)

local scp_path = darktable.new_widget("entry"){
  tooltip = "Complete path to copy to. Can include user and hostname",
  text = "",
  reset_callback = function(self) self.text = "" end
}

darktable.register_storage("scp_export","Export via scp",
  function( storage, image, format, filename,
     number, total, high_quality, extra_data)
    if not darktable.control.execute("scp "..filename.." "..
      scp_path.text
    ) then
      darktable.print_error("scp failed for "..tostring(image))
    end
  end,
  nil, --finalize
  nil, --supported
  nil, --initialize
  darktable.new_widget("box") {
    orientation = "horizontal",
    darktable.new_widget("label"){ label = "target SCP PATH " },
    scp_path,
})

darktable will look for scripts (following the normal lua rules) in the standard directories plus $CONFIGDIR/lua/*.lua. So our script can be called by simply adding require "scp-storage" in the luarc file. A couple of extra notes…

gimp integration

Mon, 01 Jan 0001 00:00:00 +0000

GIMP can use darktable to open a Raw file if the darktable executable is on the PATH. If the GIMP user opens a RAW file, then GIMP invokes darktable with some special command line parameters to get a temporary file for GIMP to work with, as follows:

darktable --gimp [version]
                 [file <path>]
                 [thumb <path> <dim>]

In all cases, darktable will report its result to GIMP wrapped in tags like this (where <res> depends on the command given):

midi device support

Mon, 01 Jan 0001 00:00:00 +0000

🔗introduction

MIDI is a communication protocol used by many electronic musical instruments (“pianos”), digital audio studio equipment (“control surfaces”) and even dedicated “photo editing keyboards” like the Loupedeck/Loupedeck+ (but not their later products). Such devices commonly feature sets of keys/buttons and sometimes encoders (knobs/rotors) and faders (sliders). Buttons sometimes feature lights, which makes them ideal for toggling features in darktable, because the lights can reflect the current (on/off) status. Encoders and faders are ideal for use with on-screen sliders in processing modules. They can be “endless” (without a start/end point and without any markings on the knob) allowing greater than 360 degrees rotation, and they may be motorized. This is helpful when switching between images or points in the editing history since the “physical” position of the encoders/faders always corresponds to the on-screen position. You may also find a ring of LEDs around an encoder that indicates its current value.

calling lua from dbus

Mon, 01 Jan 0001 00:00:00 +0000

It is possible to send a lua command to darktable via its DBus interface. The method org.darktable.service.Remote.Lua takes a single string parameter which is interpreted as a lua command. The command will be executed in the current lua context and should return either nil or a string. The result will be passed back as the result of the DBus method.

If the Lua call results in an error, the DBus method call will return an error org.darktable.Error.LuaError with the lua error message as the message attached to the DBus error.

multiple devices

Mon, 01 Jan 0001 00:00:00 +0000

The scheduling of OpenCL devices can be optimized on most systems using the “OpenCL scheduling profile” settings. However, if your system is equipped with more than one GPU, you might want to set the relative device priority manually. To do this you need to select the “default” scheduling profile and change the settings in the “opencl_device_priority” configuration parameter.

It is important to understand how darktable uses OpenCL devices. Each processing sequence of an image – to convert an input to the final output using a history stack – is run in a pixelpipe. There are five different types of pixelpipe in darktable. One type is responsible for processing the center image view (or full view) in darkroom mode, another pixelpipe processes the preview image (navigation window, also required for histograms and more internal stuff relevant for correct output of the full view). Another preview pixelpipe would be required for showing a second darkroom window. There can be one of each of these three pixelpipes running at any time, with the full and preview pixelpipes running in parallel. In addition there can be multiple parallel pixelpipes performing file exports as well as multiple parallel pixelpipes generating thumbnails. If an OpenCL device is available, darktable dynamically allocates it to one specific pixelpipe for one run and releases it afterwards.

OpenCL still does not run for me

Mon, 01 Jan 0001 00:00:00 +0000

As has been mentioned, OpenCL systems come with a huge variety of setups: different GPU manufacturers and models, varying amounts of GPU memory, different drivers, different distributions etc..

Many of the potential problems will only appear with very specific combinations of these factors. As the darktable developers only have access to a small fraction of these variations, please understand that we might not be able to fix your specific problem. There is not much we can do if we are unable to reproduce your issue.

storage

Mon, 01 Jan 0001 00:00:00 +0000

The following options are related to darktable’s library database and XMP sidecar files.

🔗database

allow for multiple workspaces: Allows for multiple workspaces that can be selected via a popup window at startup. In the popup, it is possible to create a new workspace, delete workspaces, set a workspace as the default (used on startup until changed again), or to work from memory (no database). If remember selection and don’t ask again is checked when confirming a workspace, that selection is kept for the next launch without showing the popup, and allow for multiple workspaces is turned off so the popup stays hidden until you enable allow for multiple workspaces again here. A workspace is a combination of a library database and a darktablerc configuration file using the same shared configuration folder settings (data database and shortcuts). New workspaces can optionally be created by copying an existing workspace as a template; workspace-specific configuration is duplicated while paths, labels, collection history and similar keys are cleared so the new workspace keeps its own library database. See darktable invocation for more details around library.db, data.db and darktablerc. (default off)
create database snapshot: Specifies how often darktable should create database snapshots. Options are “never”, “once a month”, “once a week”, “once a day” and “on close” (default “once a week”)
how many snapshots to keep: Number of snapshots to keep after creating a new snapshot, not counting database backups taken when moving between darktable versions. Enter “-1” to store an unlimited number of snapshots. (default 10)

🔗XMP sidecar files

create XMP files

XMP sidecar files provide a redundant method of saving the changes that you have made to an image, in addition to the changes saved to darktable’s database. This option allows you to choose when files will first be written. Once written, they will subsequently be updated each time you edit or add a tag to the image. Choose from:

never: Don’t write sidecar files. This can be useful if you are running multiple version of darktable for development/testing purposes but is not normally recommended,

on import: A sidecar file will be written as soon as you add an image to darktable’s library,

after edit: A sidecar will not be written until the first time you edit or add a tag to an image.

It’s strongly recommended that you choose either “on import” or “after edit”. Sidecar files provide a useful fail-safe to prevent data loss if your database becomes corrupted. Backing up your raw file plus the accompanying sidecar file will allow you to fully restore your work at a later date by re-importing your edit history back into darktable (default “on import”).

translations setup

Mon, 01 Jan 0001 00:00:00 +0000

Translations of darktable’s documentation are maintained via Weblate.

🔗Overview of the setup and flow of information for translations using Weblate

In short:

The docs are primarily maintained in English in the .md files present in content/*.md.
From there a POT file (po/content.pot) of all translatable strings is maintained.
Weblate maintains each language’s individual PO files (po/content.{lang}.po) which contain the translated strings.
Upon deployment of the docs, language-specific .md-files are generated using generate-translations.sh which hugo then renders to .html files and the EPUB and PDF variants.

🔗GitHub to Weblate: source string synchronisation

The original English files (content/*.md) are changed through a pull request on GitHub (see workflow).
A nightly GitHub action updates the POT file (po/content.pot) housing all translatable strings with generate-translations.sh --no-translations. Note: The script updates POT and PO files but we don’t commit the updated PO files to the repository as in our setup the PO files are entirely managed by Weblate to avoid merge conflicts.
Weblate automatically pulls the updated POT file (triggered by the Weblate GitHub app) and internally populates the PO file of each translated language with new/updated strings
Weblate commits the changes to GitHub by opening a pull request.
The pull request gets merged after review.

🔗Weblate to GitHub: translation synchronisation

Translations happen on Weblate. See translators guide for a guide on how to translate.
Weblate internally updates each language’s PO file and commits them to GitHub via pull request. To keep the number of pull requests at bay this happens in batches.

🔗Deployment of translations

Upon deployment at docs.darktable.org translated .md-files are generated from the PO files in /po/ using generate-translations.sh --no-update. This step is disabled for the auto-build GitHub Pages.

using darktable from a lua script

Mon, 01 Jan 0001 00:00:00 +0000

Warning: This feature is very experimental. It is known that several elements don’t yet work in library mode. Careful testing is highly recommended.

The lua interface allows you to use darktable from any lua script. This will load darktable as a library and provide you with most of the lua API (darktable is configured headless, so the functions relating to the user interface are not available).

As an example, the following program will print the list of all images in your library:

batch-editing images

Mon, 01 Jan 0001 00:00:00 +0000

Batch-editing is the process of developing images in a semantically-related series that are expected to have a consistent final look, often with the intent of publishing the images in catalogues, magazines or books. It can be a tedious, frustrating and unexciting task, so darktable includes functionality to help make it faster and more reliable.

🔗preparation

🔗shooting color checkers

Shooting a color checker on-location can save a tremendous amount of time during batch post-processing of a series of images. The image of the color checker can be quickly used as a color reference in the post-processing workflow to neutralize any color cast – Datacolor and X-Rite color checkers (24 and 48) are natively supported.

lua API

Mon, 01 Jan 0001 00:00:00 +0000

darktable’s Lua API is documented in its own manual with a detailed description of all data structures and functions. You can download the API manual from here.

miscellaneous

Mon, 01 Jan 0001 00:00:00 +0000

🔗interface

show splash screen at startup: When activated, darktable will display a splash screen indicating progress loading and initializing its code and data and scanning for updated sidecars until it is ready to display its main window. When disabled, darktable displays nothing until loading is complete and it can display the lighttable – or darkrooom, if invoked with a single filename on the command line (default on).
show welcome screen on next run: When activated, the Welcome setup pages will be shown the next time darktable is started (default on, but is set to off after the welcome pages are shown).
load default shortcuts at startup: When launching the application, darktable loads default shortcuts first, and then loads user-defined shortcuts on top. This allows default shortcuts to be overridden with a new action but prevents them from being deleted (since the deleted shortcut will be automatically reloaded on the next restart). Deactivate this preference to stop loading default shortcuts on startup – only load the user-defined ones (including any defaults that you have not subsequently deleted or overridden). This makes deletion easier but also means that you will not benefit from new shortcuts added in future versions without first re-enabling this preference (default on).
scale slider step with min/max: When activated, the default step-size, when altering sliders, will depend on the current min/max values for that slider (default on).
sort built-in presets first: Choose how the presets menu is sorted. If this option is enabled, built-in presets are shown first. If the option is disabled, user presets are shown first (default on).
mouse wheel scrolls modules side panel by default: When enabled, the mouse wheel scrolls side panels by default and Ctrl+Alt+wheel scrolls data entry fields. When disabled, this behavior is reversed (default off).
enable touchpad gestures in darkroom: When enabled, use two-finger touchpad gestures in darkroom for panning (two-finger touchpad scrolling) and pinch-to-zoom. When disabled, touchpad gestures are ignored and darkroom uses only the mouse scrolling behavior for zooming in and out (default on).
constrain darkroom zoom between screen fit and 100%: When enabled, limits scroll-wheel and pinch-to-zoom in the darkroom to the range between screen fit (zoom out) and 100% (zoom in). Hold Ctrl while zooming to temporarily lift the limit and zoom beyond 100%. When disabled, zoom is never constrained and the additional Ctrl key press is not needed to zoom beyond 100% (default on).
always show panels’ scrollbars: Defines whether the panel scrollbars should be always visible or activated only depending on the panel content (default on). (needs a restart)
duration of the ui transitions in ms: Defines how long modules and other ui elements will take to transition between states (expand/collapse). Set to 0 to disable animation (default 250ms).
position of the scopes module: Choose whether to show the scopes module in the left or right panel (default right). (needs a restart)
method to use for getting the display profile: This option allows the user to force darktable to use a specific method to obtain the current display profile for color management. In the default setting “all”, darktable will choose to query the X display server’s xatom or the colord system service. You can set this option to “xatom” or “colord” to enforce a specific method if the two methods give different results. You can run the darktable-cmstest binary to examine your color management subsystem.
order or exclude midi devices: Semicolon-separated list of device-name fragments. If matched, load the midi device at the id given by the location in the list. If preceded by “-”, prevent the matched device from loading. You can also add encoding and number of knobs. For example “BeatStep:63:16”. Please see midi device support for more information.

🔗tags

omit hierarchy in simple tag lists: When exporting images any hierarchical tags are also added as a simple list of non-hierarchical tags to make them visible to some other programs. When this option is checked darktable will only include the last part of the hierarchy and ignore the rest. So foo|bar|baz will only add baz.

🔗shortcuts with multiple instances

It is possible to create multiple instances of many processing modules. In this scenario it is not always obvious which instance should be controlled by keyboard shortcut operations. The following options control rules that are applied (in order) to decide which module instance keyboard shortcuts should be applied to.

translators guide

Mon, 01 Jan 0001 00:00:00 +0000

You are welcome to help translate darktable’s docs. Please read through this guide to learn the conventions and requirements for translation work.

Translations are maintained through Weblate. Unregistered users can add suggestions for translations. To contribute to the translations you need to register with Weblate.

We do not accept automated AI translations without human review and quality control.

other resources

Mon, 01 Jan 0001 00:00:00 +0000

For help and support with using darktable you are encouraged to ask questions on the main discussion forums at discuss.pixls.us.

The official places to obtain information concerning darktable are the following:

The following articles provide some useful background information about darktable’s scene-referred workflow:

Legacy articles:

The following resources can provide a deeper understanding of the functionality of some specific processing modules:

shortcuts

Mon, 01 Jan 0001 00:00:00 +0000

Shortcuts are a way to control darktable using your keyboard, mouse, trackpad, or other input devices, such as MIDI and game controllers (as detailed in the midi device support section). They allow you to perform actions without interacting directly with a UI element.

An action is usually an operation that you might undertake using darktable’s point-and-click user interface. See common actions for a list of the most common ones. For example:

Increase, decrease or reset sliders
Scroll through dropdown lists
Enable, expand or focus modules
Click buttons
Switch between views

The recommended way to assign shortcuts to visual elements is the visual shortcut mapping mode.

presets

Mon, 01 Jan 0001 00:00:00 +0000

This menu provides an overview of the presets that are defined for darktable’s modules, and allows you to modify some of their properties.

Pre-defined presets (those that are included by default within darktable) are shown with a lock symbol. Their properties cannot be changed.

User-defined presets can be imported from exported .dtpreset files using the “import” button at the bottom of the screen. You can export all user-defined presets to a single directory using the “export” button.

AI

Mon, 01 Jan 0001 00:00:00 +0000

Control darktable’s AI features: enable or disable them, choose a hardware accelerator for model inference, point darktable at an ONNX Runtime library, and manage the AI models available on disk.

AI features are powered by ONNX Runtime. What runs out of the box and what GPU acceleration can be added on each platform:

OS	Bundled	Optional GPU acceleration
Linux	CPU only	NVIDIA CUDA, AMD ROCm/MIGraphX, Intel OpenVINO
Windows	DirectML (any DirectX 12 GPU)	NVIDIA CUDA, Intel OpenVINO
macOS	CoreML (Apple Silicon, integrated GPU)	–

Install scripts for the GPU runtimes are described below; see GPU acceleration for the full instructions.

lua options

Mon, 01 Jan 0001 00:00:00 +0000

🔗From 5.6 onward

These settings control how lua scripts are handled.

check for updated lua scripts on start up: automatically update (bundled) scripts to current version.
disable lua scripts: do not run lua scripts (bundled and user defined).

Note: If you have a previous lua scripts installation (e.g. Lua API 9.6.0 from darktable 5.4) in your configuration directory the option disable scripts will not be displayed. After (automatically) updating the scripts through the script manager the option will appear.

configuration directory

Mon, 01 Jan 0001 00:00:00 +0000

darktable stores its settings, presets, styles, library database, etc. in a default directory. This directory’s location depends on your operating system and installation method. It can be changed by using the --config-dir option (see darktable invocation).

Linux
- Installed via package manager or AppImage: $HOME/.config/darktable
- Flatpak: $HOME/.var/app/org.darktable.Darktable/config/darktable
- snap: $HOME/snap/darktable/current/
Windows: %LOCALAPPDATA%\darktable
- E.g. C:\Users\<username>\AppData\Local\darktable
macOS: $HOME/.config/darktable

🔗Notable files/folders:

lua (folder): Contains all lua scripts
styles (folder): User created styles
darktablerc: Main configuration file
data.db and library.db: Central libraries: Image File Locations, metadata, edits etc.
luarc: Defines Lua scripts to be loaded upon startup
shortcutsrc: Keyboard shortcut configuration
user.css: User-defined CSS-tweaks

(deprecated) lua scripts installer

Mon, 01 Jan 0001 00:00:00 +0000

🔗after 5.6

Lua scripts are bundled with darktable and do not need to be installed anymore.

🔗before 5.6

As described in lua scripts, darktable provides powerful scripting capabilities to extend its functionality and integrate with other software. Many such scripts are already available. The Lua script installer module helps to install them without the need for manual configuration. The first time it is run, instructions are displayed in the module.

For the module to be able to install the scripts, you will need to have git installed and available on your path. You can get it from git-scm.com.

actions on selection

Mon, 01 Jan 0001 00:00:00 +0000

Perform actions on images that have been selected in the lighttable view.

🔗module controls

The module controls are spread over two tabs for manipulating the image files and the related metadata.

🔗images tab

remove: Remove the selected images from the darktable library without deleting them. Removed images can no longer be viewed or edited within darktable but the image files remain on the filesystem along with any XMP sidecar files. As darktable keeps the XMP files up-to-date with your latest development history, you can fully restore your work later by re-importing the images.
delete / delete (trash): Remove the selected images from the darktable library and remove any associated XMP sidecar files from the filesystem. If no duplicates of a removed image remain in the darktable library, the image file itself is also deleted. You can control whether this action irrevocably deletes the files or attempts to put them into your system’s trash bin with a configuration item in preferences > security. A second configuration item in the same tab allows you to control whether or not to be prompted before deleting images.
move: Physically move selected images (the image files plus all associated XMP sidecars) to another folder on the filesystem. If an image with the given filename already exists in the target folder the source image will not be moved. After the move the target folder becomes the selected collection if the source folder is empty. If a collection is manually selected during a move, then darktable will not change the selection.
copy: Physically copy selected images (the image file plus all associated XMP sidecars) to another folder on the filesystem. If an image with the given filename already exists in the target folder it will not be overwritten – instead a new duplicate will be generated with the same history stack as the source image. After the copy the target folder becomes the selected collection. If a collection is manually selected during a copy, then darktable will not change the selection.
create hdr: Create a high dynamic range image from the selected images, and add the result to the library as a new image in DNG format. Images need to be properly aligned, which implies that they have been taken on a sturdy tripod. You can also generate HDRs with programs like Luminance HDR, and later import them into darktable for further processing. Note that darktable can only create HDR images from raw files.
duplicate: Create duplicates of the selected images within darktable. Duplicate images share the same image file, but each duplicate has its own XMP sidecar file and a separate entry in darktable’s library database. This allows you to test different edits on the same image.
rotation: Perform a clockwise or counter-clockwise rotation on the selected images. A third button can be used to reset the image rotation to the value stored in the image’s Exif data. This feature is directly linked to the orientation processing module – adjustments made here are automatically converted into a history stack item for that module.
copy locally: Create local copies of the selected images on the local drive. These copies will then be used when the original images are not accessible (see local copies).
resync local copy: Synchronize the XMP sidecar of the local copy of each selected image with the copy in external storage, and remove the local copies. Note that if a local copy has been modified and the external storage is not accessible the local copy will not be deleted (see local copies).
group: Create a new group from the selected images (see image grouping).
ungroup: Remove the selected images from their group (see image grouping).

🔗metadata tab

metadata type checkboxes: Choose the types of metadata (ratings, tags, metadata, colors, geo tags) that you want to operate on.
copy: Copy the chosen types of metadata from the selected image onto the clipboard. If you have more than one image selected, or no images selected, then this button is unavailable.
paste: Paste any metadata in the clipboard onto the selected images.
clear: Clear the chosen types of metadata from the selected images.
mode: When pasting metadata onto images, this option controls whether the metadata on the clipboard should be merged with the existing metadata (merge), or should replace it entirely (overwrite).
refresh exif: Refresh the Exif data from the source file. Warning: this may overwrite some tags and metadata that you have altered in darktable (such as star ratings).
monochrome: Flag the image as monochrome, meaning that it will receive any monochrome-specific workflow treatment that is offered by the processing modules. Refer to the developing monochrome images section for more details.
color: Remove the monochrome flag from the image so that it will receive the default workflow treatment that is normally used when developing color photos.

camera settings

Mon, 01 Jan 0001 00:00:00 +0000

Set up an image capture job.

This can include sequence, bracket and delayed captures. You are also able to control other camera settings such as focus mode, aperture, shutter speed, ISO and white balance.

clipping warning

Mon, 01 Jan 0001 00:00:00 +0000

Highlight areas of the image that may exhibit luminance or gamut clipping.

When an image is sent to a display device, each pixel is normally represented as a set of 3 numbers, representing the intensity of the red, green and blue primary colors in the output color space. Because the output color space is usually closely related to hardware with physical limitations, there is a maximum permitted value for the [R,G,B] channels, representing the maximum available intensity for that color space. Similarly, there is also a minimum value below which pixel values will be mapped to zero. When we try to convert from a larger color space to the final output color space, any values exceeding this maximum will be clamped to the maximum value, and any values below the minimum will be clamped to zero. This process is called “clipping” and it will lead to lost detail, or “incorrect” colors for any pixels with clipped channels.

collection filters

Mon, 01 Jan 0001 00:00:00 +0000

Filter the collection of images displayed in the lighttable view and filmstrip panel using image attributes, optionally pinning filters to the top panel for quick access.

Once you have defined a collection of images with the collections module, the collection filters module allows you to define additional filters and sort criteria. For example, you might wish to show all images in a given folder using the collections module and then define additional quick filters to narrow-down by star rating and/or color label.

collections

Mon, 01 Jan 0001 00:00:00 +0000

Filter the images shown in the lighttable view and filmstrip panel using image attributes. This set of filtered images is known as a collection.

Importing images into darktable stores information about them (filename, path, Exif data, data from XMP sidecar files etc.) in darktable’s library database. A collection may be defined by applying filtering rules to these attributes, thus creating a subset of images to display in the lighttable view and the filmstrip module.

color assessment

Mon, 01 Jan 0001 00:00:00 +0000

Assess colors and brightness in your image under neutral viewing conditions to avoid perceptual issues.

When developing an image, the way we perceive brightness, contrast and saturation is influenced by the surrounding ambient conditions. If an image is displayed against a dark background, this can have a number of adverse effects on our perception of that image:

Exaggeration of the perceived exposure makes the image seems brighter than it really is. This is nicely illustrated by the Adelson checkerboard shadow effect.
A decrease in the perceived saturation in the image makes the colors seem less rich than they really are (the Hunt effect).
A decrease in the perceived contrast in the image makes the tones seem flatter than they really are (Bartleson-Breneman effect 3)

The end result is that the final image can end up being too dark and overly-processed in terms of contrast and color saturation. To avoid this, the color assessment module in the darktroom places a grey and white frame around the image to help the user better assess the colors in the image

duplicate manager

Mon, 01 Jan 0001 00:00:00 +0000

View and create multiple versions of the current image. Each version can be edited independently without affecting other versions – all versions use the same underlying image file, but the editing history of each version is stored in its own independent XMP sidecar file.

The duplicate manager lists each version of the current darkroom image along with its preview thumbnail. Hold down the left mouse button on a thumbnail to temporarily show that version in the center view. Double-click to switch to that version and edit it.

export

Mon, 01 Jan 0001 00:00:00 +0000

Export selected images.

When used in the darkroom view, the currently-edited image will be exported if no other images are selected in the filmstrip.

Files can be exported to a file on disk, email, various online storage locations, a web album, or a book template.

🔗module controls

🔗storage options

target storage

The type of location to store your selected images. A number of different back-ends are implemented, including file on disk, LaTeX book template and various web albums. Depending on the selected target, you will be asked to provide additional information, such as filenames or account name and password.

filename template

Define the folder and file to which the image will be exported. This can be automatically generated using several pre-defined variables. For example, $(SEQUENCE) in a template records sequence number of the image exported to the target. See the variables section for details.

output directory selector

The button beside the filename template entry opens a dialog to select the parent directory for export.

on conflict

Choose what to do if the generated filename conflicts with an existing file on export:

create unique filename: Automatically choose a unique new file name by appending an integer to name of the conflicting file.

overwrite: Automatically overwrite existing files. This option will present you with a confirmation dialog in order to protect you from accidental data loss – you can disable this in preferences > security > ask before exporting in overwrite mode. Note: This dialog is not presented per-file but as a one-off confirmation before the export job starts.

overwrite if changed: Automatically overwrite existing files if the last export timestamp stored in darktable’s database does not match the last changed date/time on the existing file.

skip: Do not export images where the destination filename already exists.

🔗format options

file format: Choose the file format for the exported image. Additional options will appear (below) depending on the selected format.
quality: The quality of the exported file. Higher values lead to larger file sizes. The default quality (95) is a good setting for very high quality exports (e.g. for archiving or printing purposes). If you need a good compromise between size and quality (e.g. for online image display or uploads) you should consider a value of “90” instead.
bit depth: The number of bits used for each color channel. More bits means less posterization/color banding.
compression: The type of compression to use.
compression level: For export formats where compression can be specified, the compression level specifies how much compression to apply. The higher the level, the more the data will be compressed, at the cost of more CPU cycles.
b&w image: For TIFF export format, it is possible to save a monochrome image. This setting controls whether the resulting file encodes the shades of gray as separate RGB channels, or as a single grayscale channel. The latter option will result in smaller files.

🔗global options

set size

Choose how to measure the maximum size of your exported image

in pixels (for file): Enter the maximum width and height in pixels.

in cm (for print): Enter the maximum width and height in cm and define the image’s dpi. The equivalent size in pixels will be automatically calculated.

in inch (for print): Enter the maximum width and height in inches and define the image’s dpi. The equivalent size in pixels will be automatically calculated.

by scale (for file): Enter a multiplier to specify by how much the exported image should be scaled compared to the input image. For example, entering a value of 0.5 will result in an output image with half the width and height (in pixels) of the original image.

dpi

If units of cm or inches are chosen, set the dpi of the output image. The dpi will also be stored in the Exif data of the exported image. It will be automatically set to 300 if “in pixels” or “by scale” is chosen.

max size

Set the maximum width and height of the exported image(s) in pixels, cm or inches (depending on the selected unit) – zero means that no constraint will be set on that dimension. Exported images will be constrained so as not to exceed either of these values, while retaining the correct aspect ratio. Set both to zero to export with the original dimensions (after cropping). If the entered values exceed the original dimensions darktable will either export with the original dimensions or upscale the image, depending on the “allow upscaling” parameter.

allow upscaling

Set to “yes” to perform an upscaling step if the user-defined maximum width and height exceed the original dimensions of the image. If set to “no” the exported image’s dimensions will not exceed the dimensions of the original image (after cropping). This uses the pixel interpolator set in preferences; for higher-quality super-resolution upscaling using an AI model, see the neural restore module.

high quality resampling

Set this to ‘yes’ to perform high quality resampling on the image. The image will be processed in full resolution and only downscaled at the very end. This can sometimes result in better quality, but will always be slower.

store masks

Store masks as additional layers (for TIFF format) or channels (for EXR and XCF formats) in the exported image.

profile

The output color profile. Select “image settings” if you want the settings in the output color profile module of the individual images to be respected.

intent

This option lets you define the intent – the way in which darktable will handle out-of-gamut colors. See rendering intent for a more detailed description of the available options.

style

Choose a style which darktable will combine with the existing history stack to generate the output image. These history items are only added temporarily – the original history stack is not overwritten. You can use this feature to add processing steps and parameters that you want to be applied specifically to images before export. For example you may define a style that adds a stronger level of sharpening when you produce scaled-down JPEG files for the internet or add a certain level of exposure compensation to all of your output images.

mode

When applying a style during export this option defines whether the history stack items of that style replace the original history stack of the image or are appended to it. Technically speaking, in append mode history stack items of the style will constitute separate instances of the respective modules on top of any existing ones (see also multiple instances). As a consequence the original history stack will remain in effect with the new items being applied in addition. This way you can apply an overall adjustment (e.g. exposure) to a number of exported images while respecting the settings of each individual image.

start export

Press this button to start a background job to export all selected images. A bar at the bottom of the left hand panel displays the progress of the export job. Furthermore a notification message pops up reporting the completion of each individual export. You may click on the pop-up to make it disappear. You may abort the export job by clicking on the “x” icon located close to the progress bar.

multi-preset export

Expanding this section allows you to easily export each of the selected images with several different presets in a single export run. For example, you may wish to export each image in multiple sizes at the same time for use in a website. Simply create a preset for each type of export you wish to make, ensuring that the file path settings for each preset is unique (so that the exported images don’t overwrite one another). Select the desired presets and press the “start export” button as normal.

Note: Images that are selected but currently hidden (because they are members of a collapsed group) will not be exported.

filmstrip

Mon, 01 Jan 0001 00:00:00 +0000

The filmstrip can be used to quickly switch between images. The images shown are the same as those displayed in the lighttable view and are defined by the currently-selected collection.

The filmstrip can be switched on and off using the shortcut Ctrl+F. The height of the filmstrip panel can be changed by clicking and dragging its top border.

Quickly navigate through the images in the filmstrip by scrolling with the mouse. Increase scroll speed with Shift+scroll. Change the height of the filmstrip with Ctrl+scroll or by clicking+dragging the top of the panel. Change the custom sort order of images by dragging and dropping image thumbnails.

find location

Mon, 01 Jan 0001 00:00:00 +0000

Search for a location on the map. You must be connected to the internet to use this feature.

To use this module, type in a place name or address, press Enter and a list of results will be shown. Click on an item in the list and the map will zoom to that location. An outline covering that location or a pin pointing at the location will be displayed.

An outline (polygon) can be used to create a user location. Check the max polygon points parameter in the map settings module to ensure that sufficient points are available for a polygon to be displayed.

focus peaking

Mon, 01 Jan 0001 00:00:00 +0000

Identify which parts of the image contain high contrast details such as edges and textures, which are usually a useful guide to sharpness and therefore focus.

Activate the module by clicking on the icon. The sharpest parts of the image will be highlighted with a yellow, green and blue overlay:

Focus peaking works by filtering out most of the image noise, measuring the intensity gradients in the image and calculating average and standard deviation statistics. When the gradient of an edge differs significantly from the mean, the associated pixels are marked with a “heat map” indicating how sharp the edge is.

gamut check

Mon, 01 Jan 0001 00:00:00 +0000

Highlight areas of the image that may exhibit gamut clipping.

Click the icon to activate the gamut check display mode for your image. This function highlights, in cyan, all pixels that are out of gamut with respect to the selected softproof profile. You can also activate gamut check with the keyboard shortcut Ctrl+G. A message “gamut check” on the bottom left of your image tells you that you are in gamut check display mode. Gamut check and soft proof are mutually exclusive modes.

geotagging

Mon, 01 Jan 0001 00:00:00 +0000

Import and apply GPX track data to a selection of images.

This module is common to the lighttable and map views. The map view provides an enhanced mode that allows you to preview the position of the images along the GPS tracks while adjusting the images’ date/time offset and time zone.

🔗workflow overview

A GPS receiver calculates its current position based on information it receives from satellites, and records it in a GPX file together with the current date and time. The Exif data of the images also contains a time stamp defined by the camera settings. The geotagging module takes the time stamp of the image, looks up the position in the GPX file at that time, and stores the appropriate coordinates (latitude/longitude/elevation) in its database and the image’s XMP sidecar file.

global color picker

Mon, 01 Jan 0001 00:00:00 +0000

Take color samples from the current darkroom image, display their values in multiple ways and compare colors from different locations.

The color picker is activated by pressing the picker icon. The module’s parameters will remain in effect until you leave the darkroom mode.

Besides the global color picker described here, many darktable modules (e.g. tone curve) also contain local pickers which are used to set individual module parameters. You should be aware that these two forms of picker do not always work in the same color space. The global color picker works in the histogram color space and takes its samples after the complete pixelpipe has been processed. Local pickers run in the color space of the module in which they are activated and reflect the input or output data of that module within the pixelpipe.

guides & overlays

Mon, 01 Jan 0001 00:00:00 +0000

A number of commonly-used compositional guides can be overlaid on your image while you are editing. These can be enabled either globally (all the time) or locally (when certain modules are active).

Other darkroom functionality also draws colored overlay lines on the image (for example, drawn masks). An option is also provided to change the color of those overlays (see below).

🔗global guides

Left-click the icon in the bottom bar to globally display guide overlays. The overlays will remain switched on until you click the button a second time to switch them off.

high quality processing

Mon, 01 Jan 0001 00:00:00 +0000

Process the image in the darkroom view using “high quality mode”, so that the displayed image reflects the appearance of a full-sized export.

Activate this mode by clicking the icon at the bottom of the darkroom view.

Note that while this mode provides the most accurate representation of the processed image, it also results in significant performance degradation. Please see the types of pixelpipe section for a full discussion.

history stack

Mon, 01 Jan 0001 00:00:00 +0000

View and modify the history stack of the current darkroom image.

This module lists every change of state (activate/de-activate/move/change parameters) for all processing modules that have been modified for the current image. Select a point in the stack to return to that point in the development history of the image. Shift+click an item in the history stack to expand that module in the right-hand module panel without changing the current edit.

history stack

Mon, 01 Jan 0001 00:00:00 +0000

Manipulate the history stack of one or more selected images.

🔗module controls

selective copy…: Copy parts of the history stack from the selected image. A dialog will appear, from which you will be able to select which history stack items you want to copy. For any module, you may also choose to “reset” that module’s parameters – this will cause the module to be copied but with all controls set to their initial (default) state (as if you had clicked the module reset button).; If more than one image is selected, the history stack is taken from the image that was selected first. Double-click on a history item to copy that item only and immediately close the dialog.

image information

Mon, 01 Jan 0001 00:00:00 +0000

Display information embedded within an image’s Exif data as well as a number of additional data fields defined by darktable.

When hovering with the mouse over image thumbnails, the displayed data is automatically updated to show information about the image currently under the mouse cursor.

When several images are selected and the focus is not on a single image, the module only displays information that is the same for all images. If any fields differ between the images, the text “<various values>” is displayed instead.

image information line

Mon, 01 Jan 0001 00:00:00 +0000

Display information about the current image in a darkroom panel.

The contents of this line can be set in preferences > darkroom. See the variables section for information about the variables that can be used here. You can also insert a newline with $(NL).

The image information line can be displayed in the top, bottom, left or right panel depending on an additional configuration item in preferences > darkroom.

import

Mon, 01 Jan 0001 00:00:00 +0000

Add images to the darktable library, optionally copying them from another location on the filesystem or from a connected camera.

See supported file formats for more information.

🔗module controls

The following buttons are shown in the module’s UI by default:

add to library: Add existing images to the darktable library without copying or moving files. If you only add a single image to the library it will be automatically loaded in the darkroom.
copy & import: Create copies of images from the filesystem and then add those copies to the darktable library.

When a camera is detected, a new section will appear in the module for that device. If you hover your mouse over the camera label, a tooltip will display information about the camera (model, firmware version etc.)

live view

Mon, 01 Jan 0001 00:00:00 +0000

Control your camera’s live view mode.

Functionality such as focus control, rotation, guides and overlays are supported.

locations

Mon, 01 Jan 0001 00:00:00 +0000

Create areas or locations and organize them as hierarchical tags.

A location is shown as a shape on the map when selected. Initially each location is represented as a square or circle and can be changed to a rectangle or ellipse by adjusting the shape’s width and/or height.

A location can also be created from an OpenStreetMap region (city/country) polygon. To achieve this, first make sure the max polygon points parameter is large enough (some country polygons use more than 150,000 points). Then select the desired location in the find location module. When the corresponding region shape is displayed, a polygon symbol becomes available in the “shape” control (see below). Select it to create the new location.

map settings

Mon, 01 Jan 0001 00:00:00 +0000

Select preferred map data from various providers. Some will provide additional layers (satellite view etc.) which you can toggle.

🔗module controls

map source

Choose the provider to source map information from.

max polygon points

The find location module doesn’t display polygons with more points than this for performance reasons. Usually a country polygon has between 50,000 and 150,000 points.

show OSD

Choose whether to display the OSD controls at the top-left of the center view.

filtered images

Check this box to display only the images from the current collection (those shown in the filmstrip) in the center view. Un-check the box to display all images in the current library, where those images have associated GPS data. You can also toggle this option by pressing Ctrl+S.

max images

The maximum number of thumbnails to display on the map.

group size factor

Increase or decrease the size of area that causes images to be grouped.

min images per group

The minimum number of images that need to be placed in the same position in order to automatically create an image group for them.

thumbnail display

Define what information to show on the map display

thumbnails: Display image thumbnails along with a counter.

count: Just display the number of images (to free space on the map). Hover over the number of images to show the corresponding thumbnail(s). A count-only marker behaves the same way as a normal image thumbnail, in terms of color coding, scrolling, drag and drop etc.

none: Show nothing.

You can also cycle through these options by pressing Shift+S.

mask manager

Mon, 01 Jan 0001 00:00:00 +0000

Manage all drawn masks and shapes for the current image.

This module can be used to create, rename, edit and delete shapes. You can alter the shapes in a drawn mask, group shapes together, and combine them using set operators.

The top line of the mask manager panel contains buttons that can be used to create new shapes. These are the same as in the drawn mask interface of the processing modules.

metadata editor

Mon, 01 Jan 0001 00:00:00 +0000

Edit the metadata of selected images.

Metadata is freeformat text (title, description, creator, publisher, rights etc.) that describes your images.

🔗module controls

reset: Delete visible metadata (see below) from the selected images.
metadata entry fields: A separate entry field is displayed for each visible metadata item, containing its current value (if any). Press Ctrl+Enter to insert a new line in a field. Double-click on a field’s label to delete the contents of that field.; When several images are selected that have differing values for a given field, the module displays “<leave unchanged>” for that field – if you choose to apply changes, these fields will not be changed. If you right-click on such a field, the different values are listed at the end of the contextual menu. Select one of those values to apply that value to all of the selected images.

module order

Mon, 01 Jan 0001 00:00:00 +0000

Change the order of the processing modules in the darkroom using presets.

When processing an image, the active modules are applied in a specific order, which is shown in the right-hand panel of the darkroom view. This module provides information about the current ordering of the processing modules in the pixelpipe. The name of the currently-selected preset is shown in the module header (or “custom” if the user has manually modified the order). The following presets are available for selection.

navigation

Mon, 01 Jan 0001 00:00:00 +0000

Zoom and pan the current image.

The navigation panel (displayed on the top left hand side of the darkroom) shows a full preview of the current image with a rectangle showing the area that is currently visible in the central panel. You can interact with this module using your mouse in the same way as you can interact with the main image (scroll to zoom in/out, middle-click to cycle through zoom levels, click+drag to pan). Alternatively, the current zoom scale is displayed in a combobox to the bottom-right of the preview – click to choose from a number of common zoom levels or type a number to set the zoom level manually.

neural restore

Mon, 01 Jan 0001 00:00:00 +0000

Apply AI-powered restoration to selected images: raw denoise, RGB denoise, and 2x / 4x upscaling. Available in both the lighttable and darkroom views as a panel with a tabbed task picker, an interactive before/after preview, and a process button that runs the chosen task on every selected image. Outputs go to a new file – the original image is never modified.

The AI features this module drives are configured in AI preferences; see the AI features overview for what these tasks do and don’t do.

print settings

Mon, 01 Jan 0001 00:00:00 +0000

Manage settings for the print view and initiate printing.

🔗module controls

🔗printer

printer: Select one of the installed printers.
media: The type of media loaded on the printer (Plain Paper, Luster Photo Paper, etc.).
profile: The printer’s ICC profile for the loaded paper. This is the profile specific to the printer and paper. This profile is the last color space transformation applied to the image whose goal is to create a high quality print.
intent: The print rendering intent (“perceptual”, “relative colorimetric”, “saturation” or “absolute colorimetric”). See rendering intent for more details.
black point compensation: Whether to adjust the black point of the output profile, which is often lighter than the input profile. This should be “on” when the intent is set to “relative colorimetric”.

🔗page

paper size: The size of the paper on which to print.
orientation: Portrait or landscape (note that darktable chooses the best fit by default).
units: The unit to use for setting the margins: “mm”, “cm”, or “inch”.
margins: Set each margin separately, or all together by clicking on the middle “lock” button.
display grid: Select the grid size using the entry field (expressed in the currently selected unit). Tick the option to display the grid on the canvas.
snap to grid: Help setting the image areas by snapping them to the grid for proper alignment.
borderless mode required: Indicates whether the printer borderless mode is to be activated. This item is activated when the user’s margins are smaller than the printer hardware margins. Note that it is only an indicator as it does not activate the borderless mode automatically.

🔗image layout

image width/height: This information field displays the actual image width and height (given with the selected units) on the paper.
scale factor: This information field displays the scaling of the image to fit on the paper. If this value is less than 1 the image is down-scaled, otherwise it is up-scaled. This is an important factor to watch – a value that is too large (up-scale) may result in a low quality print. The corresponding dpi (dots per inch) is also displayed.
alignment: Select the alignment of the image on its area.
new image area button: Create a new image area. Drag and drop on the canvas to place it. If the option snap to grid is activated the area can be easily aligned to the grid lines. An image can be placed into this area by dragging it from the filmstrip and dropping it on the new area.
delete image area button: Remove the currently selected image area from the composition.
clear layout button: Remove all the image areas leaving the canvas empty.

The following four fields represent the position of currently selected area on the page – the top/left corner on the first line and the width/height of the area on the second line.

raw overexposed warning

Mon, 01 Jan 0001 00:00:00 +0000

Highlight areas of the image where color channels of the raw input file are clipped.

Clipped color channels imply an overexposed image with loss of information in the affected areas. Some of this information may be recoverable using the highlight reconstruction, color reconstruction or filmic rgb modules.

Click on the icon to show/hide the warning overlay. Right-click on the icon to open a dialog containing the following configuration parameters.

mode

Choose how to mark clipped areas:

mark with CFA color: Display a pattern of the respective primary colors (red, green, and blue) to indicate which color channels are clipped.

mark with solid color: Mark clipped areas with a user defined solid color (see below) independent of the affected color channels.

false color: Set clipped color channels to zero in the affected areas.

color scheme

Choose the solid color for the mark with solid color mode.

clipping threshold

Set the threshold defining what values are considered to be overexposed. You can safely leave this slider at its default value of 1.0 (white level) in most cases.

recently used collections

Mon, 01 Jan 0001 00:00:00 +0000

Display a list of recently used collections generated by the collections module.

Click on an entry to reopen the selected collection. This also updates the collections module with the appropriate filter criteria and rules.

🔗preferences

The “preferences…” option in the presets menu allows you to adjust the behavior of the recent collections module as follows:

number of recent collections to be stored: The number of recent collections to store and display in the recent collections module (default 10)
prefer a history button in the collections module: Set whether you prefer to use this module or the history button in the collections module.

scopes

Mon, 01 Jan 0001 00:00:00 +0000

This module provides various graphical depictions of the developed image’s light levels or chromaticity.

Hover the mouse over the module to reveal buttons that can be used to adjust the display. The buttons on the left-hand-side are used to choose the display mode, from left-to-right: vectorscope, waveform, split (waveform/vectorscope), rgb parade and histogram. The buttons on the right-hand-side control how the plot for the current scope is drawn.

scripts

Mon, 01 Jan 0001 00:00:00 +0000

The scripts module is created by the script manager and lets you start, stop, configure, install and update darktable’s Lua scripts directly from the lighttable. See basic principles for an explanation of how the script manager loads scripts.

Since darktable 5.6 a collection of scripts is bundled with the program, so this module is available without any manual installation. Documentation for the individual bundled scripts is available in the lua docs.

Installing or updating scripts requires git to be installed and available on your path.

selection

Mon, 01 Jan 0001 00:00:00 +0000

Select images in the lighttable according to simple criteria.

🔗module controls

select all: Select all images in the current collection.
select none: De-select all images.
invert selection: Select all images in the current collection that are not currently selected.
select film roll: Select all images in the current collection that are in the same film roll as the currently-selected images.
select untouched: Select all images in the current collection that have not yet been developed.

session

Mon, 01 Jan 0001 00:00:00 +0000

Set a session jobcode to allow the creation of a new film roll.

A session is a sequence of exposures taken in tethering mode and placed into a single film roll. A new session means the creation of a new film roll.

The session module allows you to set a jobcode, which can be used to create your new film roll. See preferences > import > session options for details about how to create new film rolls using the $(JOBCODE) variable in the session module.

snapshots

Mon, 01 Jan 0001 00:00:00 +0000

Store development snapshots and compare with the current edit.

Snapshots can be taken at any point in the development process and later overlaid onto the current center view or shown side-by-side. This allows you to undertake a comparison (by default left=snapshot, right=active edit) while you are tuning parameters of a module. It can also be combined with the history stack module to compare a snapshot against different stages of development.

To take a snapshot, click on the take snapshot button. Above the button you will see a list of the snapshots that have been taken for this editing session. The name of each snapshot reflects the name of the module selected in the history stack and its position at the time the snapshot was taken. You can choose your own label for a snapshot by Ctrl+clicking on the snapshot name – this will be displayed after the module name, separated with a bullet.

soft proof

Mon, 01 Jan 0001 00:00:00 +0000

View your image rendered using a selected color profile.

Click the icon to activate the soft proof display mode on your image. This allows you to preview your image rendered using a printer profile to see how colors will end up on the final print. You can also activate soft proof with the keyboard shortcut Ctrl+S. A message “soft proof" on the bottom left of your image tells you that you are in soft proof display mode.

styles

Mon, 01 Jan 0001 00:00:00 +0000

Create named styles from selected images’ history stacks and apply styles to selected images.

Styles can either be created within this panel or in the history stack module in the darkroom.

A list of all available styles is displayed in the module. A search field above the list allows you to locate a style by name or description. This module also allows styles to be edited and deleted.

Double-click on a style name to apply that style to all selected images. A style may also be applied to all selected images by pressing a shortcut key assigned to it (see preferences > shortcuts) while in the lighttable or darkroom view.

tagging

Mon, 01 Jan 0001 00:00:00 +0000

Manage tags attached to images.

Tags provide a means of adding information to images using a keyword dictionary. You can also manage tags as a hierarchical tree, which can be useful when their number becomes large.

Tags are physically stored in XMP sidecar files as well as in darktable’s library database and can be included in exported images.

🔗definitions

The following definitions assume that you have set up a single tag named “places|France|Nord|Lille”.

timeline

Mon, 01 Jan 0001 00:00:00 +0000

View your images by the date/time they were taken.

In the lighttable filemanager view, you can show/hide the timeline module in the bottom panel with the shortcut Ctrl+F.

Within the timeline, you can show the next and previous dates by scrolling your mouse; Ctrl+scroll to zoom in/out.

You can also use the timeline to select images by date range by clicking and dragging your mouse.