darktable 1.

4
darktable 1.4
Copyright 2010-2012 P.H. Andersson
Copyright 2010-2011 Olivier 1ribout
Copyright 2012-2013 Ulrich Pegelow
1he owner of the darktable pro|ect is Johannes Hanika. Main developers are Johannes Hanika, Henrik Andersson, 1obias
Ellinghaus, Pascal de Brui|n and Ulrich Pegelow.
darktable is free software: you can redistribute it and/or modify it under the terms of the CNU Ceneral Public License as
published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
darktable is distributed in the hope that it will be useful, but Wl1HOU1 ANY WAPPAN1Y, without even the implied warranty
of MEPCHAN1ABlLl1Y or Fl1NESS FOP A PAP1lCULAP PUPPOSE. See the CNU Ceneral Public License for more details.
You should have received a copy of the CNU Ceneral Public License along with darktable. lf not, see the GNU homepage [http://
www.gnu.org/licenses/j.
1he present user manual is under license cc by-sa , meaning Attribution Share Alike . You can visit the creative commons page
[http://creativecommons.org/about/licenses/j to get more information.
iii
Table of Contents
Preface to this manual .............................................................................................. vii
1. Overview ................................................................................................................ 1
1.1. Program invocation ...................................................................................... 3
1.1.1. darktable binary ............................................................................. 3
1.1.2. darktable-cli binary ..................................................................... 4
1.2. User interface .............................................................................................. 6
1.2.1. Views ................................................................................................ 6
1.2.2. Screen layout .................................................................................... 6
1.2.3. Filmstrip ............................................................................................ 7
1.2.4. Preferences ....................................................................................... 7
1.3. darktable basic workflow ............................................................................. 8
1.3.1. lmporting images .............................................................................. 8
1.3.2. Basic development steps ................................................................... 8
1.3.3. Exporting images ............................................................................ 10
2. Lighttable ............................................................................................................. 13
2.1. Overview ................................................................................................... 14
2.2. Lighttable concepts .................................................................................... 16
2.2.1. Film rolls ......................................................................................... 16
2.2.2. Collections ...................................................................................... 16
2.2.3. Star ratings and color labels ............................................................ 16
2.2.4. Filtering and sort order ................................................................... 17
2.2.S. lmage grouping ............................................................................... 17
2.2.6. Sidecar files ..................................................................................... 18
2.2.7. lmporting sidecar files generated by other applications .................... 19
2.2.8. Local copies ..................................................................................... 19
2.3. Lighttable panels ....................................................................................... 21
2.3.1. lmport ............................................................................................. 21
2.3.2. Collect images ................................................................................. 23
2.3.3. Pecently used collections ................................................................ 24
2.3.4. lmage information ........................................................................... 24
2.3.S. Select .............................................................................................. 2S
2.3.6. Selected image(s) ............................................................................ 2S
2.3.7. History stack ................................................................................... 27
2.3.8. Styles .............................................................................................. 28
2.3.9. Ceotagging ..................................................................................... 29
2.3.10. Metadata editor ............................................................................ 29
2.3.11. 1agging ......................................................................................... 29
2.3.12. Export selected ............................................................................. 30
3. Darkroom ............................................................................................................. 33
3.1. Overview ................................................................................................... 34
3.2. Darkroom concepts .................................................................................... 3S
3.2.1. lnteracting with modules ................................................................. 3S
3.2.2. Module presets ............................................................................... 36
3.2.3. Multiple instances ........................................................................... 37
3.2.4. Blending .......................................................................................... 38
3.2.S. Blending operators .......................................................................... 41
3.2.6. Drawn mask .................................................................................... 42
3.2.7. Parametric mask .............................................................................. 4S
3.2.8. Combining drawn and parametric masks .......................................... 48
3.3. Darkroom panels ........................................................................................ S0
3.3.1. Navigation ....................................................................................... S0
3.3.2. Snapshots ........................................................................................ S0
iv
3.3.3. History stack ................................................................................... S0
3.3.4. Clobal color picker ........................................................................... S1
3.3.S. Mask manager ................................................................................. S2
3.3.6. Histogram ....................................................................................... S4
3.3.7. Module groups ................................................................................ S4
3.3.8. More modules ................................................................................. S6
3.3.9. Bottom panel .................................................................................. S6
3.4. Modules ..................................................................................................... S8
3.4.1. Basic group ..................................................................................... S8
3.4.2. 1one group ...................................................................................... 66
3.4.3. Color group ..................................................................................... 72
3.4.4. Correction group ............................................................................. 80
3.4.S. Effect group .................................................................................... 88
3.S. Examples .................................................................................................. 10S
3.S.1. Converting to black and white ....................................................... 10S
3.S.2. Cross-processing ............................................................................ 106
3.S.3. Cyan toned image .......................................................................... 107
4. 1ethering ............................................................................................................ 109
4.1. Overview .................................................................................................. 110
4.1.1. 1ethering ....................................................................................... 110
4.2. 1ethering panels ...................................................................................... 111
4.2.1. Session .......................................................................................... 111
4.2.2. Live view ....................................................................................... 111
4.2.3. Camera settings ............................................................................ 111
4.3. Examples .................................................................................................. 112
4.3.1. Studio setup with screening ........................................................... 112
4.3.2. Capturing a timelapse .................................................................... 112
4.4. 1roubleshoot ............................................................................................ 113
4.4.1. Verify that your camera is supported ............................................. 113
4.4.2. So, now what! ............................................................................... 113
S. Map .................................................................................................................... 11S
S.1. Overview .................................................................................................. 116
S.1.1. Center map view ........................................................................... 116
S.2. Map panels .............................................................................................. 117
S.2.1. Left panels .................................................................................... 117
S.2.2. Find location ................................................................................. 117
S.2.3. Map settings ................................................................................. 117
S.2.4. 1agging ......................................................................................... 117
6. Preferences and settings .................................................................................... 119
6.1. CUl options .............................................................................................. 120
6.2. Core options ............................................................................................ 123
6.3. Shortcuts ................................................................................................. 12S
6.4. Presets ..................................................................................................... 128
7. Scripting with Lua ............................................................................................... 131
7.1. Lua usage ................................................................................................. 132
7.1.1. A note about beta ......................................................................... 132
7.1.2. Basic principles .............................................................................. 132
7.1.3. Handling scripts ............................................................................. 132
7.1.4. Yielding from Lua code .................................................................. 132
7.2. Lua APl .................................................................................................... 134
7.2.1. darktable ....................................................................................... 134
7.2.2. types ............................................................................................. 146
7.2.3. events ........................................................................................... 164
7.2.4. attributes ...................................................................................... 166
7.2.S. system ........................................................................................... 166
v
7.3. Lua scripts ................................................................................................ 168
7.3.1. Simple mosaic script ...................................................................... 168
7.3.2. Selection manipulation shortcuts ................................................... 168
7.4. Lua debugging ......................................................................................... 170
7.4.1. Enable error logging ...................................................................... 170
7.4.2. lnspecting internal ob|ects ............................................................. 170
7.4.3. Debugging unprotected calls ......................................................... 170
8. Special topics ...................................................................................................... 171
8.1. darktable and memory ............................................................................. 172
8.1.1. 1otal system memory .................................................................... 172
8.1.2. Available address space ................................................................. 172
8.1.3. Memory fragmentation .................................................................. 172
8.1.4. Further limitations ......................................................................... 173
8.1.S. Setting up darktable on 32-bit systems .......................................... 173
8.1.6. darktable on 64-bit systems ........................................................... 174
8.2. darktable and OpenCL .............................................................................. 17S
8.2.1. 1he background ............................................................................. 17S
8.2.2. How OpenCL works ....................................................................... 17S
8.2.3. How to activate OpenCL in darktable ............................................. 17S
8.2.4. Possible problems and solutions .................................................... 176
8.2.S. Setting up OpenCL for AMD/A1l devices ......................................... 177
8.2.6. OpenCL performance optimization ................................................ 178
8.2.7. Multiple OpenCL devices ............................................................... 180
8.2.8. OpenCL still does not run for me! .................................................. 181
lndex ...................................................................................................................... 183
vi
vii
Preface to this manual
User manual version and applicable darktable version are listed below:
version date
user manual 1.4.0 November 2013
darktable 1.4 November 2013
Many thanks to all contributors to this user manual. Special thanks for proof reading, style
improvement, and constructive criticism go to Colin Adams, Mark Carrow, Simon Harhues,
Ammon Piley, Pob Z. Smith, and David Vincent-Jones.
viii
1
Chapter1.Overview
darktable is an open source photography workflow application and PAW developer, a vir-
tual lighttable and darkroom for photographers.
lt manages your digital negatives in a database, lets you view them through a zoomable
lighttable and enables you to develop raw images and enhance them.
General Features
darktable runs on CNU/Linux / CNOME, Mac OS X / macports and Solaris 11 / CNOME.
Fully non-destructive editing.
All darktable core functions operate on 4x32-bit floating point pixel buffers for high
accuracy processing, preventing banding and color breaks.
darktable makes heavy use of Streaming SIMD Extensions 2 (SSE2) instructions of the
CPU to speed up processing. ln fact, darktable will only run on a CPU that supports SSE2.
CPU acceleration via OpenCL (runtime detection and enabling).
Most image processing is done in ClELab color space, which is much larger than the
gamut of modern displays, printers or even human vision.
Full color managed display with softproofing and gamut-check. Built-in lCC profile sup-
port for export: sPCB, Adobe PCB, XYZ and linear PCB.
A collect module allows you to execute flexible database queries, search your images
by tags, image rating (stars), color labels and many more. Filtering and sorting your col-
lections within the base query or simple tagging by related tags are useful tools in your
every-day photo workflow.
lmport a variety of standard, raw and high dynamic range image formats (e.g. JPC, CP2,
OpenEXP, PFM, ...).
darktable has a zero-latency fullscreen, zoomable user interface through multi-level
software caches.
1ethered shooting.
1he powerful export system supports Picasa webalbum, flickr upload, disk storage, 1:1
copy, email attachments and can generate a simple html-based web gallery. darktable
allows you to export to low dynamic range (JPEC, JPEC2000, PNC, 1lFF), 16-bit (PPM,
1lFF), or linear high dynamic range (PFM, EXP) images.
darktable uses both XMP sidecar files as well as its fast database for saving metadata
and processing settings. All Exif data is read and written using libexiv2.
darktable comes with S0 image operation modules which cover everything from basic
operations, tonal value changes, color manipulation, correction of common image de-
fects to artistic effects.
Many darktable modules can be combined with blending operators for even more de-
velopment options.
2
A powerful mask feature gives you fine control on module's effect to different parts
of an image. You can at your choice draw a mask using various shapes or define a para-
metric mask based on pixel values.
Most modules can exist as multiple instances. 1ogether with the mask feature, you can
let an operation have different effects on different parts of the image.
darktable introduces a highly efficient, yet simple single-click denoiser that always
|ust works. lt's designed as a module where the denoising performance only depends
on camera and lSO setting. A database of profiles contains parameters for over 100
popular camera models.
darktable comes with a versatile scripting interface for functionality enhancement us-
ing Lua as a scripting language.
3
1.1.Program invocation
darktable comes with two binaries: the standard CUl variant which is started by call-
ing darktable and a command line interface variant which is started by calling dark-
table-cli.
1.1.1.darktable binary
1his binary starts darktable with its CUl and full functionality, it is the standard way of
using darktable.
darktable is called with the following command line parameters:
darktable [-d {all,cache,camctl,control,dev,fswatch,
input,lighttable,masks,memory,nan,opencl,
perf,pwstorage,sql}]
[IMG_1234.{RAW,..}|image_folder/]
[--disable-opencl]
[--library <library file>]
[--datadir <data directory>]
[--moduledir <module directory>]
[--tmpdir <tmp directory>]
[--configdir <user config directory>]
[--cachedir <user cache directory>]
[--localedir <locale directory>]
[--conf <key>=<value>]
All parameters are optional, in most cases users will start darktable without any additional
parameters in which case darktable uses suitable defaults.
-d 1his option enables debug output to the terminal.
1here are several subsystems of darktable and debug-
ging of each of them can be activated separately. You
can use this option multiple times if you want debug-
ging output of more than one subsystem.
lMC_1234.{PAW,..} |
image_folder/
You may optionally supply the filename of an image or
the name of a folder containing image files. lf a file-
name is given darktable starts in darkroom view with
that file opened. lf a folder is given darktable starts in
lighttable view with the content of that folder as the
current collection.
--disable-opencl 1his option prevents darktable from initializing the
OpenCL subsystem. Use this option in case darktable
crashes at startup due to a defective OpenCL imple-
mentation.
--library <library file> darktable keeps image information in an sqlite data-
base for fast access. 1he default location of that data-
base file is SHOME/.config/darktable/library.db. You
may give an alternative location, e.g. if you want to do
some experiments without compromising your original
library.db. lf the database file does not exist, darktable
creates it for you. You may also give :memory: as a li-
brary file in which case the database is kept in system
4
memory - all changes are discarded when darktable ter-
minates.
--datadir <data directory> 1his option defines the directory where darktable finds
its runtime data. 1he default place depends on your
installation. 1ypical places are /opt/darktable/share/
darktable/ and /usr/share/darktable/.
--moduledir <module directo-
ry>
darktable has a modular structure and organizes its
modules as shared libraries for loading at runtime. With
this option you tell darktable where to look for its
shared libraries. 1he default place depends on your
installation, typical places are /opt/darktable/lib64/
darktable/ and /usr/lib64/darktable/.
--tmpdir <tmp directory> 1he place where darktable stores its temporary files. lf
this option is not supplied darktable uses the system
default.
--configdir <config directory> 1his option defines the directory where darktable
stores the user specific configuration. 1he default place
is SHOME/.config/darktable/.
--cachedir <cache directory> darktable keeps a cache of image thumbnails for fast
image preview and of precompiled OpenCL binaries
for fast startup. By default the cache is located in
SHOME/.cache/darktable/. 1here may exist multiple
thumbnail caches in parallel - one for each library file.
--localedir <locale directory> 1he place where darktable finds its language specific
text strings. 1he default place depends on your installa-
tion. 1ypical places are /opt/darktable/share/locale/
and /usr/share/locale/
--conf <key>=<value> darktable supports a rich set of configuration pa-
rameters which the user defines in darktablerc -
darktable's configuration file in the user config direc-
tory. You may temporarily overwrite individual settings
on the command line with this option - however, these
settings will not be stored in darktablerc.
1.1.2.darktable-cli binary
1his binary starts the command line interface variant of darktable which allows exporting
images.
darktable-cli is called with the following command line parameters:
darktable-cli <input file>
[<xmp file>]
<output file>
[--width <max width>]
[--height <max height>]
[--bpp <bpp>]
[--hq <0|1|true|false>]
[--verbose]
[--core <darktable options>]
S
1he user needs to supply an input filename and an output filename. All other parameters
are optional.
<input file> 1he name of the input file to export.
<xmp file> 1he optional name of an XMP sidecar file containing the
history stack data to be applied during export. lf this
option is not given darktable will search for an XMP file
that belongs to the given input file.
<output file> 1he name of the output file. darktable derives the ex-
port file format from the file extension.
--width <max width> 1his optional parameter allows to limit the width of the
exported image to that number of pixels.
--height <max height> 1his optional parameter allows to limit the height of the
exported image to that number of pixels.
--bpp <bpp> An optional parameter to define the bit depth of the
exported image, allowed values depend on the file for-
mat. Currently this option is not yet functional. lf you
need to define the bit depth you need to use the fol-
lowing workaround:
--core
--conf plugins/imageio/format/<FORMAT>/bpp=<VALUE>
where <FOPMA1> is the name of the selected output
format.
--hq <0|1|true|false> A flag that defines whether to use high quality resam-
pling during export (see Section 6.2, Core options).
Defaults to true.
--verbose Enables verbose output.
--core <darktable options> All command line parameters following --core are
passed to the darktable core and handled as standard
parameters. See Section1.1.1, darktable binary for
a detailed description.
6
1.2.User interface
1his section describes the layout of the user inter-
face.
1.2.1.Views
darktable consists of several views or modes. 1here are four available views as described
in this section. You can switch between views by clicking the view name at the top of the
right panel - the active view is highlighted - or by using one of the key accelerators:
l switches to lighttable
d switches to darkroom
t switches to camera tethering
m switches to map
1.2.1.1.Lighttable
1he lighttable view is where images and film rolls are managed. lt's also where you rate
images, add tags and colorlabels, and export images among other actions (see Chapter2,
Lighttable).
1.2.1.2.Darkroom
ln the darkroom view you develop a single image using the available modules (see Chap-
ter3, Darkroom).
1.2.1.3.Tethering
1his view is for shooting with the camera connected to the computer and remotely cap-
turing images that will be downloaded and shown on computer screen (see Chapter 4,
Tethering).
1.2.1.4.Map
1his view shows images with geo-tag data on a map and allows manually geo-tagging new
images (see ChapterS, Map).
1.2.2.Screen layout
1he general screen layout of all views is similar. 1here is a center area which contains most
of the relevant information of that view. 1hen there are panels left, right, top and bottom
to the center area. 1he left panel typically has an informational purpose. 1he right panel
offers functions to modify an image. 1he top and bottom panel give access to several
settings and shortcuts. Each of the panels can be collapsed or expanded by pressing a
triangle like , located close to the panel.
By pressing the TAB key all panels get collapsed, allowing the center area to occupy all
available space. Pressing TAB again brings you back to the previous view.
Fullscreen view can be toggled by pressing F11.
7
darktable's contrast can be changed by using F7 and F8 and darktable's lightness by using
F9 and F10.
1.2.3.Filmstrip
1he filmstrip along the bottom shows the same images as lighttable, with respect to filters
and sort order. lt is turned on/off with key accelerator ctrl-f. You can navigate along the
filmstrip by scrolling with the mouse wheel. 1he filmstrip allows you to interact with im-
ages while you are not in lighttable mode. For example, you can, while developing an im-
age in darkroom mode, switch to another image to develop, by double clicking the thumb-
nail in the filmstrip. You can also rate the images as you do in lighttable, copy/paste his-
tory stack, etc.
1.2.4.Preferences
A button located in the upper panel allows you to define various parameters which con-
trol darktable's behavior.
1he options are fairly self-explanatory. lf you need more information, hover the mouse
cursor over the text label or entry box, to display a popup tool-tip. All configuration para-
meters are explained in Chapter6, Preferences and settings.
8
1.3.darktable basic workflow
1his section describes a typical darktable workflow which novice users may take as a start-
ing point. We describe how to get an image into darktable, the basic steps of a raw devel-
opment workflow and how to export the final result.
1.3.1.Importing images
1o begin with darktable, you first need to import images. 1he import module is in the
left pane of the lighttable view (Section2.3.1, lmport). You can either import from the
filesystem or, if darktable supports your camera model, directly from camera.
1.3.1.1.Importing images from filesystem
When importing from disk, you can import either a single image or a folder. darktable will
analyse its content, detect images that are already imported and only import new images.
1.3.1.2.Importing from camera
Connect your camera to your system. lf your distribution tries to automount it, select the
option to abort the mount operation. Otherwise the camera will be locked and not acces-
sible from within darktable. lf you don't see your camera in the import pane, hit the scan
for devices button. Your camera will then appear in the same pane with additional choic-
es: import and tethering.
1.3.2.Basic development steps
1.3.2.1.Introduction
1his section will guide you through the basics of developing an image in the darkroom
view.
1o begin, open an image in darkroom mode by double clicking an image thumbnail on the
lighttable. 1he darkroom mode is where the actual ad|ustments for an image are made,
where an arsenal of modules are at hand to help you reach your goal.
Each change made on a module while developing an image is turned into a history stack
item. 1he history is stored in a database and in an XMP sidecar file for the specific image.
All changes are stored automatically. You can safely leave darkroom mode or quit dark-
table at any time and come back later to continue your work. 1hat said darktable does not
need a save button and it does not have one.
On the left panel in darkroom mode is the history stack, showing changes starting from
bottom, and building up with each change made to the image. You can select a point in
this history to show how the image looked at that point, for comparison of changes. 1he
stack can be compressed: it will be optimized and redundant changes will be discarded.
When you think you are done and are happy with what you have done, |ust compress the
history stack.
darktable ships with a number of modules, arranged into groups. 1hese module groups
are accessed via toggle buttons in the right panel, |ust under the histogram. 1here are
also two special module groups named active and favorites, which only show modules
enabled in the history for the current image, and modules selected as a favorite, respec-
tively. Marking a module as a favorite is done in the more modules dialog (Section3.3.8,
More modules), at the bottom of the right panel, by clicking a module until a star is dis-
played in front of the icon.
9
1.3.2.2.White balance
1he white balance module controls the white balance or color temperature of the image.
lt's always enabled and reads its default values from camera metadata embedded in the
image. 1he most common change is fine-tuning the white balance, which is done using
the temperature slider. Moving this slider left will make the color balance cooler, and
moving it right will make it warmer.
1.3.2.3.Exposure correction
1he exposure module is probably the most basic module of them all. Exposure is fine-tuned
either by using the slider, or by dragging with the mouse in the histogram. You can also
boost the black level to enhance contrast, but be careful: use small amounts, like steps of
0.00S. 1here is also an auto-correct feature.
1.3.2.4.Noise reduction
1he best starting point for noise reduction is profiled denoise. 1his module offers an almost
single-click solution to fight noise. From a user perspective the effect only depends on
camera type and lSO value, both derived from EXlF data. All other settings are taken from
a database of noise profiles that the darktable team has collected - now covering already
over 100 popular camera models. ln addition you have several other options in darktable
to reduce noise. 1here is raw denoise, denoising based on bilateral filter, denoising based
on non-local means, and equalizer, which is based on wavelets. lf your camera is not yet
supported by profiled denoise, denoising based on non-local means is probably the most
convenient, as it allows you to treat color and luminance noise separately.
1.3.2.5.Fixing spots
Sometimes you will need to remove spots caused by sensor dirt. 1he spot removal module
is at hand and can also correct other disturbing elements like skin blemishes. lf your cam-
era has stuck pixels or tends to produce hot pixels at high lSO values, or longer exposure
times, have a look at the hot pixels module for automatic correction.
1.3.2.6.Geometrical corrections
Quite frequently you want to only show part of the captured scene in your image, e.g. to
take away some disturbing feature close to the frame. ln other cases, the horizon in the
image may need levelling, or there are perspective distortions. All this can be corrected
in the crop and rotate module. lf you need to correct typical camera lens flaws like cush-
ion distortion, transversal chromatic aberrations or vignetting, there is a lens correction
module.
1.3.2.7.Bringing back detail
Digital PAW images often contain more information than you can see at first sight. Espe-
cially in the shadows of an image, there are lots of hidden details. 1he shadows and high-
lights module helps bring these details back into visible tonal values. Structural details in
fully blown-out highlights, by nature of the digital sensor, can not be recovered. Howev-
er, you can correct unfavorable color casts in these areas with the highlight reconstruction
module.
1.3.2.8.Adjusting tonal values
Almost every workflow is likely to include ad|usting the image's tonal range. darktable
offers several alternative modules to take care of that. 1he most basic one is the contrast
brightness saturation module. ln the tone curve module, tonal values are ad|usted by con-
10
structing a gradient curve. 1he levels module offers a concise interface, with three mark-
ers in a histogram. ln addition, there is a zone system module which allows control over
tonal values by zones, inspired by the work of Ansel Adams.
1.3.2.9.Enhancing local contrast
Local contrast enhancement can emphasize detail and clarity in your image. Carefully
used, it can give your photograph the right pop. darktable offers several modules for this
task. 1he local contrast module is easy to handle, with |ust a few parameters. A much more
versatile, but also more complex technique, is offered by the equalizer module. Have a
look at its presets, to get a feeling for how it works. Equalizer is darktable's "Swiss Army
Knife" for many ad|ustments where spatial dimension plays a role.
1.3.2.10.Color adjustments
darktable offers many modules for ad|usting colors in an image. A very straightforward
technique is implemented in the color correction module. Use it to give an image an over-
all tint or to ad|ust overall color saturation. 1he color zones module offers a much finer
control to ad|ust saturation, or lightness, and even hue, in user defined zones. darktable's
tone curve module - in addition to the classical ad|ustment of tonal values - gives you fine
control over the colors in an image. Finally, if you intend to convert an image into black
& white, a good starting point, with an easy to use and intuitive user interface, is offered
by the monochrome module. Alternatively, you might consider using darktable's channel
mixer.
1.3.2.11.Sharpening
lf you start your workflow from a PAW image, you will need to have your final out-
put sharpened. 1he sharpen module can do this with the classical USM (unsharp mask)
approach, available in most image processing software. Another very versatile way to
enhance edges in an image is offered by the highpass module, in combination with
darktable's rich set of blending operators.
1.3.2.12.Artistic effects
darktable comes with a rich set of artistic effect modules. 1o name |ust a few: with the
watermark module you add an individual watermark to your image. 1he grain module sim-
ulates the typical noise of classical analogue footage. Use the color mapping module to
transfer the look and feel of one color image onto another. darktable's low light module
allows to simulate human vision to make lowlight pictures look closer to reality. 1he grad-
uated density filter adds a neutral or colored gradient to your image for exposure and col-
or correction.
1.3.3.Exporting images
Changes to an image are not saved as in a regular image editor. darktable is a non-destruc-
tive editor, which means all changes are stored in a database, and the original image is
untouched. 1herefore, you need to export images to bake the processing options into an
output file that can be distributed outside of darktable.
lmages are exported from the lighttable view, using the export selected dialog in the right
panel (Section 2.3.12, Export selected). ln general, export means: save my developed
PAW image as a JPEC.
1he export is modularized into storage and format. darktable ships with several storage
modules such as save on disk, picasa and flickr webalbum and more. Format modules are
the actual image formats such as JPEC, PNC, 1lFF, OpenEXP and more.
11
Select images on the lighttable, choose the target storage and format, and set the maxi-
mum width and height image restraints. 1his means that none of the images will be bigger
than any of the width/height restraints and hit the export button. Leave the width and
height restraints at zero, if you want the original resolution.
12
13
Chapter2.Lighttable
1he lighttable is where you manage all your images, ratings, export and much more.
14
2.1.Overview
ln the central view, your images are shown as thumb-
nails, surrounded by a frame. When the mouse is over
an image, its rating and color labels are shown in the
frame, along with an indicator of whether the im-
age has already been altered in darkroom. Also, when
the mouse hovers over an image frame, image infor-
mation (EXlF data, metadata) is shown in the image
information panel in the bottom left.
While the mouse is over an image frame, there are a number of actions you can perform
on the image. Here is a table of keyboard shortcuts and assigned actions.
0 5 set the rating of the image, if an image has 1 star and you hit the
1 key, the image will be unrated. Pressing r re|ects the image.
F1 F5 set a color label
ctrl-c copy the history stack
ctrl-v paste the copied history stack
d open in darkroom view for developing
z fully zoom into the image while the key is pressed
At the bottom you have an option to choose between zoomable lighttable view or filem-
anager view of the thumbnails. ln zoomable lighttable view, scroll with your mouse wheel
to zoom in and out. Moving the mouse while pressing the left mouse button allows you to
navigate through your collection. ln filemanager view, you can can change the number of
images in each row, using the slider next to the filemanager option, or by using ctrl-(mouse
wheel). Use your mouse wheel to navigate through your collection.
While in filemanager mode, you can scroll (not select) up and down through your collection
using
/.
ln zoomable lighttable
///
allow you to move left/right/up/down through
your collection. Pressing g goes to the top, shift-g to the bottom.
1o locate where you are in a collection, there are indicators at the extreme borders of
the window: left/right for your position when you are in filemanager mode, left/right and
top/bottom for your vertical and your horizontal position, respectively, when you are in
zoomable lighttable view.
While holding down the z key a fully zoomed preview of the image under the mouse cur-
sor is displayed. You can use this feature for a quick inspection of image quality while rat-
ing and selecting images. lf the corresponding option in gui options (see Section6.1, CUl
options) is enabled darktable automatically analyses images for focus regions. Areas of
high sharpness are indicated by a red border - the higher the color intensity the better
the sharpness. ln case that no area of high sharpness is detected darktable indicates areas
of moderate sharpness with a blue border. For this tool to work the input image needs
to hold an embedded JPEC thumbnail which is the case for most PAW files. Sometimes
pressing z may not reveal an immediate effect - in that case please click into the center
area and press z again.
1S
Fully zoomed-in image view while holding down the z
key with indication of the areas in focus. Focus detec-
tion is based on an embedded JPEC thumbnail of the
original PAW file independent of further processing
steps within darktable.
16
2.2.Lighttable concepts
1his section explains some of the underlying concepts on how darktable organizes images
in the lighttable.
2.2.1.Film rolls
1he basic element for organizing images in darktable is called a film roll - a kind of virtual
folder. Whenever you import images from disk, the images are organized in a film roll
whose name is derived from the name of the disk folder. Pe-importing a disk folder will
add any new images to the existing film roll, images already present in the film roll are
not touched.
lt is important to note that importing images in darktable does not involve a physical copy
step. lmporting a folder into darktable is therefore not a backup operation of that folder.
2.2.2.Collections
darktable offers a versatile feature to organize your images according to various user de-
fined selection criteria. A set of images which is defined by a specific combination of se-
lection criteria is called a collection. 1he most basic kind of collection is a film roll - cover-
ing all the images which have been imported from a specific folder on disk.
You can easily construct other kind of collections based on various image attributes like
EXlF data, filename, tags etc. Multiple criteria can be logically combined to narrow or ex-
tend your collection (see Section2.3.2, Collect images).
darktable keeps a list of the most recently used collections for quick access (see Sec-
tion2.3.3, Pecently used collections).
2.2.3.Star ratings and color labels
Star ratings and color labels help you to select and rank images according to your own
criteria. An image's star rating and its color labels are displayed in the thumbnail.
You can give a rating from zero to five stars to an image. 1he quality criteria which lead
to a rating are fully up to you. On import each image receives a standard rating which you
can define in core options (see Section6.2, Core options). You can later revise the rating
at any time. As an extension to the rating system you can also mark an image as re|ected
by pressing the icon.
1here are several ways to change a rating. With the mouse pointer over an image you can
press a number key 0 5 to change the rating of a single image, this is probably the fastest
way when rating your images on first inspection of a film roll.
You can also directly click into the stars displayed in
the thumbnails. For example you click the second star
to get a rating of two stars etc. Clicking on the first
star gives a one star rating, clicking on it a second
time resets to zero stars.
ln order to rate multiple images at once you select
those images (see Section 2.3.S, Select) and then
set the desired star rating in the bottom panel of the
lighttable view.
17
Color labels are an option to mark images which can be used as an alternative or in addition
to star ratings. Each image can carry any combination of color labels in red, yellow,
green, blue, and purple.
1he color labels of a single image can be set or unset with the mouse pointer over the
thumbnail by pressing the function keys F1 F5 for the labels in the order given above.
1o toggle the color labels of multiple images you se-
lect the desired images (see Section 2.3.S, Select)
and then press the corresponding color button in the
bottom panel. ln order to remove all labels from the
selected images press the grey button.
2.2.4.Filtering and sort order
1he filtering and sort order of images in the light-
table view are controlled in the top panel.
With filtering you limit the number of displayed images of your current collection (see
also Section2.3.2, Collect images). Filtering is mainly based on the star ratings of your
images. At your choice you can make darktable display all images, only the unstarred
ones, images which have at least a certain minimum number of stars (from one to five),
only the re|ected images, and all but the re|ected ones.
lmages in the lighttable view can be displayed in different sort orders, depending on file-
name, time (when the photo was taken), rating (i.e. stars), id (an internal ordering
number of darktable), or color labels. You can reverse the sort order by toggling the tri-
angle button right to the sort by combobox.
2.2.5.Image grouping
Crouping images helps improve structure and clarity of your image collection when dis-
played in lighttable view.
You can combine images into a group by selecting them, and clicking the group button
in the selected image(s) panel (Section2.3.6, Selected image(s)), or by typing ctrl-g. Like-
wise, you can remove selected images from a group by clicking the ungroup button,
or typing shift-ctrl-g. lmages generated by duplicating an existing one, are automatically
grouped. lf you import images from the file system or camera, images with the same base
name, but different extensions (eg. lMC_1234.CP2 and lMC_1234.JPC), will form a group.
lmages which are members of a group are labeled
with a C symbol in their thumbnails.
18
1he group button in the top panel of the lightroom view toggles grouping mode on
and off. lf grouping is off, each image is displayed as an individual thumb. lf grouping is
on, images of a group are collapsed, which means they are represented by one thumbnail.
1he image you see is called the group head. lf you press C symbol in the thumbnail of
a group, only this group gets expanded, if another group was expanded at that time, it
gets collapsed. 1o collapse an expanded group again, |ust click on the C symbol of its
group head.
An expanded group in the filemanager mode of light-
table view is indicated by an orange frame which ap-
pears as soon as your mouse pointer hovers over one
of the images.
You can define which image constitutes the group head, while in an expanded view of a
group, clicking on the C symbol of the desired image.
lf you are in collapsed view, and enter darkroom mode with an image group (eg. by dou-
ble-clicking on the thumbnail), only the group head will be opened.
lmage groups are a convenient way to protect an existing history stack against uninten-
tional changes. Suppose you have |ust finalized an image, all you need to do now is gen-
erate a duplicate, make sure grouping is switched on, and the group collapsed. Whenever
you open the image group again in darkroom, only the group head will be altered. 1he
underlying duplicate remains unchanged. Please note that duplicating images only means
that a second copy of your history stack, and a second small XMP file, is generated. 1here
still is only one PAW file, so you don't waste a lot of disk space.
2.2.6.Sidecar files
darktable is a non-destructive image editor. 1his implies that darktable opens input im-
ages read-only. Any newly added metadata, tags and parameters of image operations (his-
tory stack) are stored in a separate file, a so called sidecar or XMP file. When you import
an input image into darktable for the first time an XMP file with default settings is gen-
erated automatically.
For a given source image multiple edits, called duplicates, can co-exist - sharing the same
input (PAW) data but each having their individual set of metadata, tags and history stack.
Each duplicate is represented by a separate XMP sidecar file with a filename constructed
in the form <basename>_nn.<extension>.xmp, where nn represents the (minimum two
digit) version number of that edit. 1he initial edit - the duplicate with version number zero
- is represented by sidecar file <basename>.<extension>.xmp. 1he version number of a
duplicate is displayed in the image information panel in each of darktable's views (see for
example Section2.3.4, lmage information).
Sidecar files get synchronized automatically by darktable without the need to press a
save button. When backing up your data, make sure you also keep the XMP files, as these
are needed to fully reconstruct your work in case of a disaster.
ln addition to the sidecar files darktable keeps all image related data in its database for
fast access. An image can only be viewed and edited from within darktable if its data is
loaded in that database. 1his automatically happens when you first import an image or
at any later time by re-importing it (see Section 2.3.1, lmport). ln the latter case the
database gets updated with data that darktable finds in the sidecar files belonging to that
image.
19
2.2.7.Importing sidecar files generated by other applications
When importing an image darktable automatically checks if this is accompanied by a side-
car file. Besides of the format <basename>.<extension>.xmp darktable also checks for
the presence of a file in the form <basename>.xmp. darktable's own sidecar files are
always stored in the first format - the latter one would only be read - not overwritten.
At present darktable is able to deal with the following metadata of Lightroom generated
sidecar files during the import phase:
tags and hierarchical tags
color labels
ratings
CPS information
ln addition darktable has been designed to help migrating some image operations from
specific other applications. 1he aim is not to make darktable a drop-in replacement for
any other software, it's |ust meant to help you recover part of the work you have invested
into your image in case you migrate to darktable. lt is very important to understand that
this import process will never give identical results. 1he underlying development engines
are very different from application to application and additionally depend a lot on the
specific image. ln some cases it will probably be close and in some cases the development
will need manual ad|ustment in darktable.
1he migration is automatically done when entering the darkroom view provided that a
corresponding XMP sidecar is found.
At present darktable is able to deal with the following development steps of Lightroom
generated XMP files (corresponding darktable module in parenthesis):
crop and rotate (crop and rotate)
black level (exposure)
exposure (exposure)
vignette (vignette)
clarity (local contrast)
tone curve (tone curve)
HSL (color zones)
split toning (split toning)
grain (grain)
spot removal (spot removal)
2.2.8.Local copies
Quite commonly users have huge image collections which they store on an external stor-
age medium like a PAlD NAS. lt is a frequent wish to be able to develop some of the im-
ages during travelling using a notebook and later synchronize them again with the exter-
20
nal storage. Copying images manually from external storage to the notebook and back is
prone to errors and cumbersome.
1he local copies feature of darktable has been designed to support directly those use
cases. With the help of this feature you can create local copies of selected pictures on
the local drive of your computer. 1his copy is then used when the original image is not
accessible. At a later point, when connected again with your external storage medium, you
can synchronize back the XMP sidecar files, deleting the local copy of your input image.
1hese operations can be found in the selected images panel (see Section2.3.6, Selected
image(s)).
For safety reasons, if local copies exist and the external storage is available the local XMP
sidecars are automatically synchronized at start up.
1he local copies are stored into the SHOME/.cache/darktable directory and named img-
<N>-<SlCNA1UPE>.<EX1>, where:
N is the image number in darktable
SIGNATURE is a hash signature (SHA-1) of the full pathname
EXT is the original filename extension
A local copy is identified in the lighttable view with a
white marker on the right of the thumbnail. ln addi-
tion all local copies carry the darktable|local-copy tag
for selecting them easily.
21
2.3.Lighttable panels
2.3.1.Import
1his panel is for importing images into film rolls. You can either import a complete folder,
by pressing import folder, or a single image with import image. You can also import
directly from a connected camera.
lmported images are organized as film rolls (see Section2.2.1, Film rolls). All film rolls
are accessible through the collect images module (see Section2.3.2, Collect images). lf
you set the selection attribute to film roll you get a list of available film rolls, which can
be filtered using the editbox to fast find the one of interest. Double-click on a film roll
in the list and it will open in the lighttable. You can also click the items in recently used
collections (see Section2.3.3, Pecently used collections) to open the latest ones you have
worked with.
2.3.1.1.Import from filesystem
You can import either a single image, or a folder. lf a folder is imported, the images in
that folder will show up in a film roll with the same name as the imported folder. lf single
images are imported, they will show up in the film roll called single images.
Clicking on import image or import folder opens a file selector dialog. Navigate
through the filesystem, and select the item to import. On the lower part of the dialog, are
some further import options.
As the name implies, checking import directories recursively will import images in the
currently selected directory, and all subdirectories. lt is not recommended, and wastes
resources, to do this on an exhaustive list of images. darktable would generate thumbnails
for all of them, but in the end only keep the recent ones in its cache. lt is better to import
images in smaller chunks, making logical film rolls.
Checking ignore |peg files is a good choice if there are JPEC images in the same folder
that you do not want to process, eg. if the camera stores PAW+JPEC, you often only want
to work on the PAWs, leaving the JPEC images alone.
You can also apply some metadata during import, see Section2.3.10, Metadata editor
for more details.
22
lmporting a folder does not mean that darktable copies your images into another folder.
lt |ust means that the images are visible in lighttable and thus can be developed. lf you
delete an image or a folder from disk after having imported them, darktable cannot access
them anymore. lmporting an image or folder in darktable is not a backup of your filesys-
tem! Moreover, darktable does not watch for changes in the filesystem. 1hus, if you add
an image to a folder, after having imported that folder in darktable, the new image will
not be shown until explicitly imported.
2.3.1.2.Import from camera
When a camera is detected, it will show up in the device panel. lf you hover your mouse
over the camera tab label, a tooltip will pop up with information about the camera, such
as model, firmware version, and more. Depending on the camera's support, buttons with
actions will be available such as import images and tethering.
Import images
1his will bring up an import dialog, showing the images on camera that can be selected
for import into a film roll in darktable.
Tethering
1ethering is used to integrate darktable with your camera. While you take images with
your camera, they are automatically imported into darktable, so you can review the result
of the shoot. You can also setup remote capture |obs, controlling the number of images
and time between captures, along with camera settings such as exposure time, aperture
and more.
lf supported by your camera, tethering will take you into the capture view for tethered
shooting. Pead more about tethering in Chapter4, Tethering.
2.3.1.3.Supported file formats
darktable is focused on managing and developing camera PAW files. lt supports a huge
number of file formats from various camera manufacturers. ln addition darktable can read
specific low dynamic range and high dynamic range images - mainly for data exchange be-
tween darktable and other software.
ln order for darktable to consider a file for import, it must have one of the following ex-
tensions (case independent): 3FP, APW, BAY, BMQ, CAP, ClNE, CP2, CPW, CS1, DC2, DCP,
DNC, EPF, FFF, EXP, lA, llQ, JPEC, JPC, K2S, KC2, KDC, MDC, MEF, MOS, MPW, NEF, NPW,
OPF, PEF, PFM, PNC, PXN, Q1K, PAW, PAW, PDC, PW1, PW2, SP2, SPF, SPW, S1l, 1lF, 1lFF,
X3F.
lf darktable was compiled with JPEC2000 support, these extensions are also recognized:
J2C, J2K, JP2, JPC.
lf darktable was compiled with CraphicsMagick support, the following extensions are rec-
ognized in addition to the standard ones: BMP, DCM, ClF, JNC, JPC, JP2, MlFF, MNC, PBM,
PCM, PNM, PPM.
Camera RAW files
darktable reads PAW files using two open source libraries: PawSpeed (developed by Klaus
Post) and - failing that - with LibPaw. 1he number of supported cameras and file formats
is constantly increasing. lt is beyond the scope of this manual to give an exhaustive list.
Most modern camera models are supported, and new ones tend to get added very quickly.
23
darktable does not decode images from cameras with non-Bayer sensors (e.g. Fu|i X-Pro1
or Sigmas with the Foveon X3 sensor).
LDR image files
darktable natively reads ordinary images in JPEC, 8-bit/16-bit PNC and 8-bit/16-bit 1lFF
format. JPEC2000 is also supported if the required libraries are built into darktable at
compile time. Similarly, if darktable was compiled with CraphicsMagick support, there are
further import formats, like ClF, Dicom DCM, additional exotic 1lFF formats, and some of
Sun's portable xyz-map family.
HDR image files
darktable reads high dynamic range images in OpenEXP, PCBE and PFM format.
2.3.2.Collect images
1he current view in lighttable is called a collection.
With this panel you can manage the collection by fil-
tering with different criteria.
All images imported into darktable are kept in a database with various attributes describ-
ing each image. A collection is defined by applying certain filtering rules to these attrib-
utes which leads to a subset of your images being displayed in the lighttable view.
1he default collection is based on the film roll attribute - it displays all images of the last
imported film roll or any other film roll chosen.
1he left combobox lets you choose from the available attributes:
film roll the film roll to which the image belongs
folders the disk folder where the input image file is located
camera the EXlF string describing the camera
tag any tag that is attached to the image, if activated a hierarchical list
of known tags is displayed for quick selection
date the date when the photo was taken in the format YYYY:MM:DD
time the time (date and time of day) when the photo was taken in the
format YYYY:MM:DD hh:mm:ss
history a boolean field stating if the image's history stack has been altered
or not
color label any color label that is attached to the image: red, yellow,
green, blue, purple
24
title the title string as defined in the image's metadata
description the description string as defined in the image's metadata
creator the creator string as defined in the image's metadata
publisher the publisher string as defined in the image's metadata
rights the copyrights string as defined in the image's metadata
lens the EXlF string describing the lens
lSO the lSO value as derived from EXlF data
aperture the aperture value as derived from EXlF data
filename the filename of the physical input image
ln the text field right to the attribute you supply a pattern. 1he pattern is compared
against all image's database entries of the selected attribute. A match is detected if the
pattern is a substring of the image's attribute. You may use % as wildcard character. 1he
collection gets limited to those images where the query matches. Leaving the text field
empty matches all images.
Clicking on the triangle button right to the text field opens a drop-down menu with op-
tions to finetune your collection by adding further rules:
clear this rule
Pemoves this rule - or resets to default if this is the only rule defined.
narrow down search
Adds a new rule which is combined with the previous ones in a logical AND operation. An
image is only part of the collection if it additionally fulfills the added rule.
add more images
Adds a new rule which is combined with the previous ones in a logical OR operation. lmages
that fulfill the new rule are added to the collection.
exclude images
Adds a new rule which is combined with the previous ones in a logical EXCEPT operation.
lmages which are selected by the new rule are exempted from the collection.
1he logical operators defining the combination of rules are displayed right to the rule:
AND by the symbol, OR by the symbol, and EXCEPT by the symbol. Clicking on either
symbol gives a choice to change the logical operation.
1he table below the rules lists all matching database entries of the query you are currently
working on. 1he table gets updated continuously as you type. You may scroll through the
list and select the data of your choice by double-clicking.
2.3.3.Recently used collections
1his panel keeps tracks of the latest collections you
have used, so you can |ump within recently used col-
lections without remembering what rules were spec-
ified in the collection.
2.3.4.Image information
2S
1his panel shows information embedded within an
image's EXlF data. When hovering with the mouse
over thumbnails, darktable will update this view, dis-
playing information of the image currently under the
mouse cursor. 1his panel is also available in dark-
room, tethering and map view.
2.3.5.Select
1his panel allows for a quick selection of images, ac-
cording to some common criteria.
select all
Select all images in the current view (collection), with respect to the filters.
select none
De-select all images.
invert selection
Select all images that are not currently selected.
select film roll
Select all images that are in the same film roll as the currently selected images.
select untouched
Select all images that have not yet been developed.
2.3.6.Selected image(s)
1his panel provides some actions that operate on se-
lected images.
remove
Pemove the selected images from the darktable database. 1hose images will not be shown
in lighttable anymore, but remain on the filesystem. As darktable stores XMP files with
your development parameters on disk, you can later fully reconstruct your work by |ust
re-importing the images.
26
When backing up your PAWs make sure to also save the XMP files!
delete
Physically delete selected images from filesystem. See also preference option ask before
erasing images from disk (Section6.1, CUl options). lf this configuration option is not
active, darktable will delete the file(s) without further question! 1his is irreversible, and
will also erase your development work of these images.
When deleting an image with duplicates, darktable keeps the original input file on disk
until the last of the duplicates gets deleted.
move
Physically move selected images (parent file plus all accompanying XMP sidecar files) to
another filesystem folder. darktable does not overwrite images in the target folder. lf an
input image with the given filename already exists in the target folder the source image
is not moved but kept where it is.
copy
Physically copy selected images (parent file plus accompanying XMP sidecar file) to anoth-
er filesystem folder. lf an image with the given name already exists in the target folder
it does not get overwritten - instead a new duplicate with the given history stack is gen-
erated.
create hdr
Create a high dynamic range image from the selected images, and store it as a new source
file in DNC format. lmages need to be properly aligned, which implies that they have been
taken on a sturdy tripod. You can also generate HDPs with programs like Luminance HDR
[http://qtpfsgui.sourceforge.net/j, and later import them into darktable for further pro-
cessing (see Section2.3.1.3, Supported file formats).
duplicate
Create a virtual copy of selected images within darktable. lt allows testing different de-
velopments for the same image, for example. Duplicate images share the same parent
input file, but each have their own XMP sidecar file.
rotation
Perform a counter-clockwise or clockwise rotation on selected images. 1he third button
resets the image rotation to the value in the EXlF data.
cache locally
1his action will create local copies of the selected images into the local drive. 1hese copies
will then be used when the original images are not accessible (see Section 2.2.8, Local
copies).
reset cache
1his action will synchronize back the XMP sidecars if needed and will remove the local
copies. Note that if a local copy has been modified and the external storage is not acces-
sible the local copy won't be deleted (see Section2.2.8, Local copies).
group
27
Create a new group from selected images (see Section2.2.S, lmage grouping).
ungroup
Pemove selected images from the group (see Section2.2.S, lmage grouping).
2.3.7.History stack
1his panel allows manipulating the history stack (de-
velopment) of images. For each image, development
is written in a sidecar file (.xmp), and is fully non-de-
structive.
copy
Copy the history stack of the selected image. You will be prompted for which items are to
be include. lf more than one image is selected, the history stack is taken from the image
that has been selected first.
copy all
Copy the complete history stack of the first selected image, all items will be included. lf
more than one image is selected, the history stack is taken from the image that has been
selected first.
discard
Physically delete the history stack of the selected images. Beware, this action can not be
undone!
overwrite/append
Describes how a new history stack behaves when pasted on an image that already has a
history stack. Overwrite will delete the previous history stack, whereas append will
concatenate the two history stacks.
paste
Paste a previously copied history stack onto all selected images. You will be prompted
for which items to include. 1his button is greyed out, until a history stack is copied from
another image.
paste all
Paste all previously copied items of a history history stack onto all selected images. 1his
button is greyed out, until a history stack is copied from another image.
load sidecar file
Opens a dialog box to select an XMP file, thus loading a history stack that you can paste
on images.
Files that were exported by darktable typically contain the full history stack if the file
format supports embedded metadata (see Section 2.3.12, Export selected about this
feature and its limitations). You can load an exported image as a sidecar file in the same
way as you do with an XMP file. 1his feature allows you to recover all parameter settings
28
in case you have accidentally lost or overwritten the XMP file. All you need is the source
image, typically a PAW, and the exported file.
write sidecar files
Write XMP sidecar files for all selected images. 1he filename is generated by appending
.xmp to the name of the underlying input file.
By default darktable generates and updates sidecar files automatically whenever you
work on an image and change the history stack. You can disable automatic sidecar file
generation in the preferences dialog (see Section 6.2, Core options). However, this is
not recommended.
2.3.8.Styles
1his panel provides a powerful functionality in dark-
table: storing a history stack as a style, and apply-
ing it to other images. Styles are created within this
panel or in the darkroom (see Section3.3.3, History
stack). 1hey are managed within this lighttable pan-
el, which allows you to create, apply, edit and delete
styles.
1his panel displays a list of all available styles. A search field above the list allows you
to input a text string which is compared against the styles' names and descriptions, thus
limiting the list to the matching ones.
Double clicking on a style name applies the style to all selected images.
create duplicate
When applying a style to selected images, activating this box creates a duplicate of the
image before applying the style. Disable this option if you want to try various styles with-
out creating multiple duplicates, beware that in this case any existing history stack gets
overwritten and cannot be recovered.
create
1his creates new styles out of the history stacks of the selected images. For each image a
style creation window pops up. You need to supply a unique name for the new style and
you can add an additional descriptive text. You have the option to de-select those history
stack items which you want to not be part of the newly created style.
edit
Styles are collections of history stack items. After pressing edit, you are prompted with
a dialogue to include or exclude specific items from the stack. Check option duplicate
if you want to create a new style, instead of overwriting the existing one, you need to
provide a new unique style name in this case.
delete
1his deletes the selected style, without further question.
29
import
You can import a style which has been previously saved by darktable. darktable stores
styles as XML files with the extension .dtstyle.
export
1his option saves a selected style to disk as a .dtstyle file. 1his allows publishing styles
and sharing styles with other users.
2.3.9.Geotagging
Use this panel to import and apply CPX track data on
a selection of images. You can add a time offset to
existing CPX tracks, to correct time differences be-
tween your camera and CPS receiver. Alternatively,
you can manually geotag images within the Map view
(see ChapterS, Map).
2.3.10.Metadata editor
Edit metadata of an image, like title, description, cre-
ator, publisher, or rights. You can define your own pre-
sets, if you want to apply specific settings frequently.
clear
Delete existing metadata from the selected image(s).
apply
Apply new settings, as defined in the fields above, to the selected image(s).
2.3.11.Tagging
1his panel is for managing tags on images. 1ags are
stored in both, sidecar files (.xmp), and within the
darktable database for a faster access. 1he panel is
divided into two parts: the upper part contains the
tag(s) currently set for the image under mouse (if the
mouse is over an image) or the selected image (if the
mouse is outside the lighttable). 1he lower part con-
tains all available tags, which can be filtered in the
upper text box.
30
attach
Attach the selected tag(s) from the list below to all selected images.
detach
Detach selected tag(s) from the list above from all selected images.
new
Create a new tag for the list.
delete
Delete a tag from the list.
2.3.12.Export selected
Each workflow ends in this panel: the export of your
developed images. You can export either to a file on
disk, or to various on-line storage places. 1ip: you can
use ctrl-e from within darkroom mode to export.
All settings of this panel can be saved for later reuse. Press the button to manage your
presets.
target storage
Where to store your selected images. Different back-ends are implemented, including file
on disk, a La1eX book template and various web albums. Depending on the selected tar-
get, you will be asked to give additional information, like filenames, or account name and
password.
filename template
You can define filenames that darktable generates for export. Several pre-defined vari-
ables can be used as placeholders:
S(POLL_NAME) roll of the input image
S(FlLE_FOLDEP) folder containing the input image
S(FlLE_NAME) basename of the input image
S(FlLE_EX1ENSlON) extension of the input image
S(SEQUENCE) a sequence number within export |ob
31
S(YEAP) year at date of export
S(MON1H) month at date of export
S(DAY) day at date of export
S(HOUP) hour at time of export
S(MlNU1E) minute at time of export
S(SECOND) second at time of export
S(EXlF_YEAP) exif year
S(EXlF_MON1H) exif month
S(EXlF_DAY) exif day
S(EXlF_HOUP) exif hour
S(EXlF_MlNU1E) exif minute
S(EXlF_SECOND) exif second
S(S1APS) star rating
S(LABELS) colorlabels
S(PlC1UPES_FOLDEP) pictures folder
S(HOME) home folder
S(DESK1OP) desktop folder
output directory
Pressing button opens a dialog to select the parent directory for export.
file format
darktable can export to various file formats. For some of them you need to define the
desired bit depth of the exported image. lf you export to a JPEC file you can define an
output quality. Higher values will lead to larger file sizes.
lf the file format supports embedded metadata, like JPEC, JPEC2000 and 1lFF, darktable
will try to store the history stack as XMP tags within the output file. 1his information can
later be used to reconstruct your parameters and settings that have produced the export-
ed image (see Section2.3.7, History stack).
Caution: for various reasons embedding XMP tags into output files may fail without notice,
eg. if certain size limits are exceeded. Users are therefore advised to not rely their backup
strategy on this feature. To backup your data make sure to save your input (RAW) file as well
as all of darktable's XMP sidecar files.
lf you don't want to distribute history stack data with your images, there are various tools
to delete embedded XMP tags. As an example you can use the program exiftool [http://
www.sno.phy.queensu.ca/~phil/exiftool/j with:
exiftool -XMP:all= image.jpg

max size
Set the maximum width and height of the output images in pixels. Set both to a value
of "0" to export with full resolution. darktable currently can only do down-scaling, the
maximum output resolution is defined by the parent image.
32
Caution: it's a frequent pitfall to accidentally put low values, like 1 or 10, in these fields,
causing darktable to produce miniature output files. You might think darktable's output is
broken, but in fact it only generated what you asked for.
intent
1his option lets you define the intent, i.e. the way darktable will deal with out-of-gamut
colors. See Section3.4.3.3, Output color profile for a more detailed description of the
available options.
profile
1his defines the output color profile. Select image settings if you want the settings in the
output color profile (see Section3.4.3.3, Output color profile) module of the individual
images to take precedence.
style
1his option lets you choose a style, i.e. a collection of history stack items, which darktable
concatenates with the existing history stack to generate the output image. 1hese 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 specifi-
cally to exported images, e.g. you may define a style that adds a stronger level of sharp-
ening when you produce scaled-down JPEC files for the internet. Learn more about styles
in Section2.3.8, Styles, and Section3.3.3, History stack.
export
Pressing this button starts a background |ob to export all selected images. A bar at the
bottom of the left side panel displays the progress. Whenever a file is successfully export-
ed, a notification message pops up for a few seconds. You may click on the pop-up to make
it disappear.
33
Chapter3.Darkroom
1he darkroom view is where you develop your image.
34
3.1.Overview
Darkroom mode is for photographic development of the image that you selected from
the lighttable. Numerous tools, named modules, are available for processing that image.
On the left hand side you have navigation, snapshot, history and masks manager panels,
described in Section3.3, Darkroom panels. ln the right hand panel you can see the his-
togram and a list of modules available for working with the image. At the bottom of the
right hand panel you can enable/disable the view of individual modules.
You can use middle-click to zoom 1:1. A double middle-click takes you to 2:1. Alternatively
you can zoom in and out between 1:1 and fit-to-screen by mouse scrolling. Mouse scrolling
while holding the control key pressed gives an extended zoom range between 2:1 and
1:10.
You normally export multiple images from the lighttable view but you can also export the
current image directly from the darkroom by using the shortcut ctrl-e. Export parameters
are then those currently selected in the lighttable.
3S
3.2.Darkroom concepts
1his section tries to explain some of the basic concepts on how darktable develops images
in the darkroom.
1he basic element of an image operation in darktable is called a module. darktable comes
with a rich set of over S0 modules for all kind of image manipulations. ln Section3.4, Mod-
ules you will find a description for each of the available modules.
Modules are applied in a fixed order. 1his differentiates darktable, as a non-destructive
image editor, from classical image manipulation programs like 1he Cimp.
3.2.1.Interacting with modules
A module has an expander bar . Clicking on the name of the
module expands the module's CUl with all parameters.
ln its default setting darktable will only expand one CUl at a time. lf you click the expander
bar of another module, the previous CUl gets collapsed. lf you want to see more than one
CUl expanded, you may expand further modules with shift-click - all previously expanded
CUls remain opened. 1he expander bar behavior on click and shift-click, respectively, is
controlled by a preference setting in gui options (see Section6.1, CUl options).
Expanding a module does not activate it. You need to click the icon to turn a module
on or off.
lcon accesses the module's available presets or creates a new preset from your current
settings (see Section3.2.2, Module presets).
1he icon is used to reset the module parameters to their default values.
Many of darktable's modules can have multiple instances, each with different settings.
Click on the icon to generate new instances and control existing ones (see Section3.2.3,
Multiple instances).
1he most frequently used control elements of modules are sliders, comboboxes and
curves.
Sliders
Sliders offer four different ways of interaction, depending on the level of control you
need.
1. 1riangular marker
Left-click the slider's triangular marker and drag it to the left or right.
2. Mouse wheel
Hover over any place on the slider with your mouse, then use your mouse wheel to
ad|ust the value step by step.
3. Pight-click
When your mouse is over a slider right-click gives you a multi-functional pop-up below
the slider for fine control with your mouse or numerical entry using the keyboard.
36
darktable's innovative input method: for both
coarse and fine value ad|ustments in a single con-
trol element combined with keyboard input.
A bent line extending from the triangular marker moves as you move your mouse.
1he closer your mouse pointer is to the triangular marker the coarser the control, the
further away from the triangular marker the finer is your control. Left-click with your
mouse to accept the new value and go back to normal control.
Alternatively you can type in a new value using your keyboard and commit by hitting the
enter key. You may even supply the new value in the form of an arithmetic expressions
which darktable will calculate for you - the old value is referenced as x.
4. Double-click
You can double-click on a parameter label to reset its value to default.
Comboboxes
Clicking on a combobox will open a list of available options. Click on the item you want to
select. Sometimes the selection list opens close to the bottom or top of the screen and
only part of the items are visible, scroll with your mouse wheel to bring up the full list.
Curves
Some modules are controlled by ad|usting curves. More detail is given later in this chapter
when the respective modules are explained.
3.2.2.Module presets
Presets are stored configurations for a module's parameters. Some modules already have
internal pre-defined presets but you can also define your own. Both internal and user-
defined presets are displayed by clicking the icon with the currently activated preset
shown in bold text.
1he preset system also supports automatic preset selection based on image data such as
focal length, lSO, camera model and other fields.
3.2.2.1.Creating a new preset
First configure the module's parameters then click the icon and select store new pre-
set. 1he following dialog will be shown for configuring the preset:
37
1he first two fields are used to name and describe the preset.
ln the example above we have also checked the auto apply option. 1his brings up addi-
tional selection fields where you can define a filter used to decide if the preset should be
automatically applied when opening other similar images in darkroom for the first time.
1he example dialog above sets up following rules: if lens name matches and aperture is
greater or equal to f/8 and focal length is between 24 and 3Smm the preset will be auto-
matically applied. Also the second checkbox is clicked so this preset will only be shown in
the preset list if the image matches the rule.
darktable finds this data in your image's EXlF information. lf you want a preset to be ap-
plied to all images from a specific camera leave all fields at default values except for the
model field.
1ip: 1he image information panel for your image displays your model name, use this to
ensure you have the correct spelling (see Section2.3.4, lmage information).
3.2.2.2.Managing Presets
Both user created and pre-defined presets can be viewed and managed from within the
presets menu (Section6.4, Presets) in the preferences dialog (see Chapter6, Preferences
and settings).
3.2.3.Multiple instances
Many of darktable's modules can be applied multiple times. Each instance of that module
behaves like any other module, taking its input from the module below in the pixelpipe
delivering its output to the module above.
3.2.3.1.Typical use cases
1here are many occasions where it makes sense to have an operation act more than once
in the pixelpipe. Here are a few use cases.
Most of our modules are highly versatile and depending on parameters can deliver quite
varying effects. For example the fill light module (Section3.4.2.1, Fill light) allows local
modification of lightness based on pixel values. You might want to do two lightness cor-
rections in your image at the same time - one for dark tones and another one for lighter
tones.
You might want to apply a denoising module like denoise (profile) (Section3.4.4.3, Denoise
- profiled) with two different parameter sets. One to do luma denoising and another set
38
of parameters to do chroma denoising. You could do so by generating two instances and
use the first one only on luma by selecting blend mode lightness and use the second one
|ust for chroma by selecting blend mode color (see Section3.2.S, Blending operators).
ln an even more elaborate case you could have a module act on different parts of your
image. As an example you might want to apply a certain gradation curve with module
tone curve (Section3.4.2.3, 1one curve) to your complete image and have a second curve
being applied specifically to skin tones. All of the controls offered by drawn masks (Sec-
tion3.2.6, Drawn mask) and parametric masks (Section3.2.7, Parametric mask) may be
used to select those parts of an image where each of the module instances are applied.
Please be aware that of course each instance also adds to the workload of your pixelpipe.
Cenerating too many instances - especially of the more demanding modules - will certainly
cause some noticeable slow-down.
3.2.3.2.Managing instances
When clicking on the icon a drop-down menu will
appear.
Selecting new instance generates a new module instance below any existing ones. All
parameters are set to default values. 1he new instance gets its own complete set of CUl
controls and a number appended to the base module name for distinction.
Selecting duplicate instance behaves in a similar way. 1he only difference: the new in-
stance will inherit all parameter settings from its parent.
darktable applies all modules in a defined order according to their type. 1herefore all in-
stances of a particular module will occur together in the pixelpipe. You can however de-
cide on the relative order in which the different instances of a module are applied by se-
lecting move up or move down to shift the position of the instance among its peers.
1o delete an instance |ust press delete from the drop-down menu.
3.2.4.Blending
3.2.4.1.Overview
By default a module takes its input from the preceding module, performs its calculations
and handles its output over to the next module in the pixelpipe. On demand you can ac-
tivate an additional step where a module's output is reprocessed with its input before
giving the result to the next module. 1his additional processing step is called blending.
lnput and output can be processed with different algorithms, called blending operators
or blend modes.
Each blend mode is further controlled by a parameter called opacity, which can have a
value between 0% and 100% and defines how input and output image contribute to the
final result. 1ypically an opacity value of 0% gives as a result an image that is identical to
39
the input image - the module remains without effect. An opacity value of 100% delivers
the maximum effect of the module with the blend mode chosen.
1he opacity value can be the same for all image pixels. ln this case blending acts uniformily
on the image. Alternatively you can make opacity values to vary between different image
locations or pixel values. 1his is called a mask and gives fine control over what parts of
an image are affected by a module and to what extent. At your choice you may activate a
drawn mask or a parametric mask or a combination of both.
3.2.4.2.Usage
Modules with blending support exhibit an additional
combobox blend at the bottom of their CUl.
blend
Blending is activated with this combobox. Depending on the value selected additional con-
trol elements will show up.
off
module's output is passed to the next module in pixelpipe without additional reprocess-
ing. No further controls are displayed.
uniformily
reprocessing takes place with the chosen blend mode and opacity value - the same for
all pixels. Additional controls to select blend mode and opacity value are displayed. 1he
default blend mode is normal with an opacity of 100%.
drawn mask
reprocessing takes place with the chosen blend mode and opacity. Additional controls
are displayed which allow you to draw a mask. lf no mask elements are drawn all pixels
have the same opacity, defined by the opacity slider. lf you draw a mask element, e.g. a
circle, the inner area of the circle will get maximum opacity, surrounded by a transition
area or border with a gradual decay of opacity and the remaining image with an opacity of
0%. Different graphical shapes can be used. See Section3.2.6, Drawn mask for further
details.
parametric mask
reprocessing takes place with the chosen blend mode and opacity. Additional controls
are displayed which allow you to ad|ust the opacity on a per-pixel basis determined by
pixel values. ln previous versions of darktable this was called conditional blending. See
Section3.2.7, Parametric mask for further details.
drawn and parametric mask
this option combines drawn and parametric masks and shows the full set of both controls.
See Section3.2.8, Combining drawn and parametric masks to learn how to best use this
combination.
invert mask
When drawn mask is selected there is an additional combobox to invert the mask by
switching mask inversion on or off.
40
combine masks
When either parametric masks, or drawn and parametric mask are selected an ad-
ditional combobox is shown that controls how the individual masks are combined to
form the final mask. Details on the combination of individual masks can be found in Sec-
tion3.2.8, Combining drawn and parametric masks.
When blending with a mask there are some additional options to deal with the final mask:
you may blur the mask, temporarily disable it, or display it as an overlay image.
mask blur
Blurring the mask creates a softer transition between blended and unblended parts of
an image and avoids artifacts. 1he mask blur slider controls the radius of a gaussian blur
applied to the final blend mask. 1he higher the radius, the stronger the blur - or set to 0
for an unblurred mask.
temporarily switch off mask
Sometimes it is useful to visualize the module's effect without the mask taking action. You
can do so by clicking on the symbol, which will temporarily deactivate the mask - the
selected blend mode and opacity remain in effect. Switch this button on and off to see if
the mask is acting on the image as intended.
display mask
Clicking on the symbol will display the current mask as a yellow overlay over a black-
and-white version of your image. Solid yellow indicates an opacity of 100%, a fully visible
gray background image without yellow overlay indicates an opacity of 0%.
3.2.4.3.Examples
Texturing an image
1he watermark module supports SVC files with embedded images that can be used as a
texture source. Blending operators then allow control of how that texture is expressed.
Gritty details
When blending operators were introduced into dark-
table, a new module named highpass (see Sec-
tion 3.4.S.7, Highpass) was added. lt provides a
highpass filter of the image to be implicitly used with
blending. lt is used to produce a gritty detailed image
and is a method widely used in the workflow of other
imaging software.
1his is the original image, pretty heavily processed:
first monochrome, then some blue splittoning but as
you see it lacks pop in details and is a bit out of fo-
cus...
41
Here we applied the highpass filter with the values
shown above. You can now see that the details are
greatly boosted and we now have a really gritty de-
tailed image.
3.2.5.Blending operators
1here are several blend modes implemented and more might be added in future. For now
all of the most commonly used ones are included and you will recognize a few of them
from other imaging software. A good introduction on many common blend modes is giv-
en in The Gimp Manual (Chapter 8.2, Layer Modes) [http://docs.gimp.org/2.8/en/gimp-
concepts-layer-modes.htmlj. 1herefore we only discuss a few blend modes here in more
detail.
3.2.5.1.blend modes
normal
1his will probably be the most used blend mode. lt |ust mixes input and output and, de-
pending on the opacity value, it reduces the strength of a module's effect. Cenerally this
is also the blend mode of choice if you want to apply a module's effect locally using masks.
normal bounded
1his blend mode acts similarly to blend mode normal, except that input and output da-
ta are clamped to a particular min/max value range. Out-of-range values are effectively
blocked and do not pass to the following modules. Sometimes this helps to prevent arti-
facts. However, in most cases (e.g. highly color saturated extreme highlights) it is better
to let unbound values travel through the pixelpipe in order to properly deal with them at
the right place (e.g. in module output color profile). Blend mode normal is most often
the preferred choice.
lightness
1his blend mode mixes lightness from the input and output images. Color data (chroma
and hue) are taken unaltered from the input image.
chroma
1his blend mode mixes chroma (saturation) from the input and output images. Lightness
and hue are taken unaltered from the input image.
hue
1his blend mode mixes hue (color tint) from the input and output images. Lightness and
chroma are taken unaltered from the input image. Caution: When modules drastically
modify hue (e.g. when generating complementary colors) this blend mode can result in
strong color noise.
color
1his blend mode mixes color (chroma and hue) from the input and output images. Light-
ness is taken unaltered from the input image. Caution: When modules drastically modify
42
hue (e.g. when generating complementary colors) this blend mode can result in strong
color noise.
Lab lightness
Only available with modules that work in the Lab color space, this blend mode mixes light-
ness from the input and output images, while color data are taken unaltered from the
input image. ln contrast to blend mode lightness this blend mode does not involve any
color space conversion and does not clamp any data. ln some cases this is less prone to
artifacts in comparison to lightness.
Lab color
Only available with modules that work in the Lab color space, this blend mode mixes Lab
color channels a and b from the input and output images, while lightness data are taken
unaltered from the input image. ln contrast to blend mode color this blend mode does
not involve any color space conversion and does not clamp any data. ln some cases this is
less prone to artifacts in comparison to color.
HSV lightness
Only available with modules that work in the PCB color space, this blend mode mixes light-
ness from the input and output images, while color data are taken only from the input
image. ln contrast to blend mode lightness this mode does not involve clamping.
HSV color
Only available with modules that work in the PCB color space, this blend mode mixes col-
or from the input and output images, while lightness data are taken only from the input
image. ln contrast to blend mode color this mode does not involve clamping.
color adjustment
Some modules act predominantly on the tonal values of an image but also perform some
color saturation ad|ustments, e.g. module levels and tone curve. 1he color ad|ustment
blend mode takes the lightness only from output data and mixes colors from input and
output enabling control of the module's color ad|ustments.
3.2.6.Drawn mask
Almost all darktable modules have the option to narrow down their effect by a drawn
mask and thus allowing local ad|ustments.
3.2.6.1.Overview
With the drawn mask feature you can construct a mask by drawing directly on the image
base. Different drawing operators, called shapes, are available and can be used alone or
in combination. A flexible editing feature allows you to change single aspects of a shape,
remove shapes or import shapes already defined in other modules.
lnternally shapes are stored as vector graphics and rendered with the needed resolution
during pixelpipe processing. Shapes are expressed in the coordinate system of the original
image and transformed with all distorting modules. 1his way a shape will always work on
the same image area regardless of warping or other modifications that may be applied.
43
3.2.6.2.Usage
1o draw a shape you need to click on one of the shape
symbols. You will automatically be moved into the
edit mode in which you generate a new instance of
the selected shape and afterwards change its prop-
erties.
You leave edit mode by clicking on the symbol. You can at any time go back to edit mode
and do further ad|ustments by clicking the edit symbol again. ln edit mode you can also
remove a shape by right-clicking on it - the shape is removed from the current mask but
it's still in the list of defined shapes.
lf you ctrl-click on the edit mode symbol you enter a restricted edit mode. Certain actions
like dragging a complete shape or changing its size are blocked. Only finetuning changes
like dragging a node are allowed.
Currently five shapes are implemented.
brush
Clicking the symbol adds a brush stroke.
Start drawing by left-clicking into the canvas and moving the mouse while keeping the
button pressed. 1he brush stroke is finalized once you release the mouse button. Brush
size, hardness and opacity can be changed by scrolling, shift+scrolling, and ctrl+scrolling,
respectively, either before you start drawing or at any time on your way.
lf you have a graphic tablet with pen pressure sensitivity, darktable can apply the recorded
pen pressure to certain attributes of the brush stroke. See Section6.1, CUl options for
more details.
Nodes and segments of a brush stroke can be modified individually. See the documenta-
tion on path below for more details.
Pendering a complex brush shape can consume a significant number of CPU cycles, con-
sider to revert to the circle, ellipse or path shape if possible.
A brush stroke with controls and activated mask dis-
play.
circle
Clicking the symbol adds a circle shape.
Click into the canvas to place the circle. Left-click and drag the circle to a different position
if needed. Use the scroll-wheel of your mouse while in the circle to change the diameter,
scroll within the circle border to ad|ust the width of the gradual decay. With ctrl+scroll
you can ad|ust the opacity of the circle - this is best observed with the mask displayed by
pressing the button.
44
A circle shape with controls and activated mask dis-
play.
ellipse
Clicking the symbol adds an ellipse shape.
1he general principle is the same as for the circle shape. ln addition you get four nodes on
the ellipse line. Click on the nodes to ad|ust the ellipse's eccentricity. ctrl+click on them
to rotate the ellipse.
An ellipse shape with controls and activated mask
display.
path
Clicking the symbol adds a shape defined by a user defined closed path.
Left-click into the canvas to define path nodes, terminate the path by right-clicking after
having set the last point. Per default nodes are connected by smooth lines. lf you want a
node to define a sharp corner, you can do so by creating it with ctrl+click.
ln the edit mode you can convert existing nodes from smooth to sharp corners and vice
versa by ctrl-clicking on them. You can insert additional nodes by ctrl-clicking on one of
the line segments. Single nodes can be deleted by right-clicking on them, make sure that
the mouse pointer is over the desired node and the node is highlighted, or else you might
accidentally remove the whole path.
1he size of the complete shape can be modified by scrolling - analogeous to the circle
shape. 1he same holds true for the width of the border, i.e. the area with a gradual opacity
decay. Single nodes as well as path segments can be moved by mouse dragging. lf a node
is selected by clicking on it, a further control point appears - you can move it around to
modify the curvature of the line. Dragging one of the control points on the border ad|usts
the border width |ust in that part of the shape.
Consider to finetune a path in the restricted edit mode (see above), which allows you to
ad|ust single nodes and segments without the risk of accidentally shifting or resizing the
whole shape.
A path shape with controls and activated mask dis-
play.
4S
gradient
Clicking the symbol adds a gradient to the mask. 1his does not generate a confined
shape but produces a linear gradient extending the whole image.
Click into the canvas to define the position of the line where opacity is at S0%. 1he line
has two anchor nodes which you can drag to change the rotation of the gradient.
Scrolling close to the center line changes the steepness of the gradient. Dotted lines indi-
cate the distance beyond which the opacity is 100% and 0%, respectively. Between these
dotted lines the opacity changes linearly. 1he gradient is best seen and modified when
the mask is displayed by pressing the button.
A gradient with controls and activated mask display.
drawn mask
1he number of shapes that are used in the current mask is displayed in the drawn mask
field. Clicking on that field opens a dropdown box with all shapes that have already been
defined in the context of the current image but are not yet used in the current mask. You
can click on any of these items in order to add it to the current mask. 1he list also contains
shapes once generated but no longer in use. 1his way you can even get back a deleted
shape.
A polarity button ( and , respectively) allows the user to toggle between the normal
and the inverted state of the drawn mask, i.e. the opacity values get inverted - 100% be-
comes 0% and vice versa. You need this feature when combining drawn and parametric
masks (see Section3.2.8, Combining drawn and parametric masks).
More functionality to control the interaction of multiple shapes within a mask can be
found in the mask manager panel (see Section3.3.S, Mask manager). Here you can give
individual names to your shapes which will help you to keep track of your shapes. You can
also select individual shapes for editing - a helpful feature if your masks happens to con-
tain several shapes with overlapping control elements.
3.2.7.Parametric mask
1he parametric mask feature, formerly called conditional blending, offers fine-grained
selective control over how individual pixels are blended. lt does so by automatically gen-
erating an intermediate blend mask from user defined parameters. 1hese parameters are
color coordinates not the geometrical coordinates used in drawn masks.
1he parametric mask is a powerful tool with a certain level of complexity.
3.2.7.1.Overview
For each data channel of a module (Lab, PCB) and additionally for several virtual data chan-
nels (e.g. hue, saturation) users can construct a per-channel opacity function. Depending
46
on the pixel's value for this data channel this function determines a blending factor be-
tween 0 and 1 (or 100%) for that pixel.
Each pixel of an image thus has different blending factors for each of its data channels
(real and virtual). All blending factors are finally pixel-wise multiplied together with the
value of the global opacity slider (see Section3.2.S, Blending operators) to form a blend
mask for the image.
lf for a given pixel the blend mask has a value of 0, the input of the module is left un-
changed. lf for a pixel the blend mask has its maximum value of 1 (or 100%), the module
has full effect.
3.2.7.2.Usage
When parametric mask is activated in combobox
blend an additional set of tabbed controls is shown.
Channel tabs
Each tab selects a data channel - real or virtual. Modules acting in Lab color space have
data channels for L, a, b, C (chroma of LCh) and h (hue of LCh). Modules acting in PCB
color space have data channels for g (gray), P, C, B, H (hue of HSL), S (saturation of HSL),
and L (lightness of HSL). Consult for example Wikipedia's article on color spaces [http://
en.wikipedia.org/wiki/Color_spacej for a deeper look.
Each tab provides two sliders for its data channels: one for the input data that the module
receives and one for the output data that the module produces prior to blending.
Color channel sliders
With the color channel slider you construct a trapezoidal opacity function. For this purpose
there are four markers per slider. 1wo triangles above the slider mark the range of values
where opacity is 1. 1wo triangles below the slider mark the range values where opacity is
zero. lntermediate points between full and zero opacities are given a proportional opacity.
1he filled triangles, or inside markers, indicate the closed (mostly narrower) edge of the
trapezoidal function. 1he open triangles, or outside markers, indicate the open (mostly
wider) edge of the trapezoidal function. 1he sequence of the markers always remains un-
changed: they can touch but they can not switch position.
A polarity button ( and , respectively) to the right of the slider switches between range
select and range de-select function modes with visual confirmation provided by exchanging
the upper and the lower triangle markers. 1hese two types of trapezoidal functions are
represented graphically in the following images.
Pange select function Pange de-select function
47
A trapezoidal function that selects a
narrow range of values for blending.
A trapezoidal function that de-selects a
narrow range of values from blending.
ln their default state all markers are at their extreme positions, maximum left and maxi-
mum right, respectively. ln this state a range select function selects the whole range of
values giving an all at 100% mask. Starting from there one can move the sliders inwards
to gradually take out more an more parts of the image except of the remaining narrow
range.
A range de-select function per default deselects the whole range of values, giving an all-
zero mask as a starting point. Moving the sliders inwards gradually extends the mask
more and more except of the remaining narrow range.
For more information on the polarity feature read Section3.2.8, Combining drawn and
parametric masks.
Control buttons
Control buttons help you when designing a parametric mask.
With the color picker button you can select a probe from your image. 1he corresponding
values for the real and virtual data channels are then displayed within each color channel
slider.
With the invert button you can toggle the polarities of all channels (including a poten-
tially activated drawn mask) and change the method how channels are combined into the
final mask. More on that topic can be found in Section3.2.8, Combining drawn and para-
metric masks.
With the reset button you can put all settings back to their default state.
3.2.7.3.Examples
Colorkey effect
1o create a colorkey effect with this poppy blos-
som in red and the remainder of the image in mono-
chrome, we could apply module monochrome to all
parts of the image except for of the saturated red
petals.
We choose the hue channel to control our mask as
hue provides good separation between the petals
and background.
48
1hese settings in hue channel construct a parametric
blend mask that excludes the red petals. 1he small
white bar in the gradient was obtained by using the
color picker on one of the petals and the markers
then closely centered on the indicated hue to in-
crease the selectivity of our mask.
1he resulting blend mask.
1he final image after module monochrome is applied.
3.2.8.Combining drawn and parametric masks
1his section describes how darktable combines individual masks to form the final mask of
a module. lndividual masks are the drawn mask and all the single channels of a parametric
mask. 1he topic is rather advanced - if you don't want to go through all the theoretical
details |ust |ump down where we describe two typical use cases.
3.2.8.1.Overview
1here are two main elements which control how individual masks are combined: the po-
larity setting of each individual mask, defined by the plus or minus buttons, and the set-
ting in the combine masks combobox (see Section3.2.4, Blending).
Masks can be regarded as grayscale images which take up values between 0 and 1.0 (or
from 0% to 100%) for each pixel.
A straightforward way to combine masks is by multiplying the individual pixel values. 1he
final mask will have a pixel value of 0 whenever one of the individual masks is 0 at that
pixel location. 1he final mask can only reach a maximum pixel value of 1.0 if each and every
of the individual masks has a value of 1.0 at that location. We call this way of combination
exclusive. Any individual mask can exclude a pixel by setting its value to zero, regardless
of what the other individual masks do. Once a pixel is excluded (its value is 0) by any mask
there is no way to include it again by any other individual mask.
An alternative way to combine masks is the following: we first invert each individual mask
- calculating 1.0 minus its value - then we multiply these inverted masks and as a last step
invert the final mask again. Now if one of the non-inverted individual masks has a value of
1.0 at a pixel location the final will also be 1.0. 1he final mask can only reach a pixel value of
0 if all the individual masks have a value of 0. We call this way of combination inclusive.
Any individual mask can include a pixel by setting its value to 1.0, regardless of what the
other individual masks do. Once a pixel is included (its value is 1.0) by any mask there is no
way to exclude it again by any other individual mask.
49
1hese two combination methods alone would still be rather limiting. We gain maximum
flexibility by allowing an additional inversion step for each individual mask. 1his is gov-
erned by the polarity buttons and that you find close to the individual channels. 1og-
gling the polarity button of a mask inverts its values, i.e. it recalculates the pixel values to
1.0 minus the original value.
Finally within the combine masks combobox you may once again invert the final result
to fit your needs by selecting the exclusive & inverted or inclusive & inverted options.
3.2.8.2.Usage
You will typically want to combine drawn and para-
metric masks to first select a certain region of your
image - either by the drawn or the parametric mask
- and use the other mask type to finetune your se-
lection. Finetuning can either mean that you want to
include further parts of the image, which are not in-
cluded in the first place, or you want to exclude parts
of the image that were previously included.
1his gives two typical use cases:
Inclusive mode
For this mode you set the combine masks combobox to inclusive and make sure that all
polarity buttons of all the individual channels and of the drawn mask are set to negative
( ). Your starting point is a mask where all pixels have a value of zero, i.e. no pixel is
selected. You now ad|ust the parametric mask sliders to bring more and more pixels into
the selection or you draw shapes on the canvas to select specific areas of your image.
Exclusive mode
ln the opposite case you set the combine masks combobox to exclusive and make sure
that all polarity buttons are set to positive ( ). Your starting point is a mask with all
values at 1.0, i.e. all pixels selected. You now gradually change the parametric mask sliders
to exclude parts of your image as needed or you directly draw shapes on the canvas to
specifically exclude these areas.
For your convenience you find in the parametric masks CUl a toggle button that inverts
all channel polarities and toggles between inclusive and exclusive mode in the combine
masks combobox.
For novice users it is recommended to stick to these two use cases. 1his implies that you
should decide beforehand how you want to construct your mask. Advanced users will find
their way to take advantage of the many possible combinations of polarities and mask
combination modes.
S0
3.3.Darkroom panels
1his section contains documentation for panels that are specific to the darkroom view.
3.3.1.Navigation
1he navigation panel displays a full preview of your
image with a rectangle showing the currently visi-
ble zoom area. Drag the rectangle around to pan the
zoomed-in view. 1he current zoom scale is displayed
to the right of the preview image. Click on that figure
for a quick access to some common zoom levels.
3.3.2.Snapshots
You can take snapshots of images as you process
them. A snapshot is stored as a bitmap of the current
center view and is kept as long as you stay in the dark-
room. A snapshot can then be selected and overlayed
in the current center view to help you with a side by
side comparison (left: snapshot, right: active) when
you are tuning parameters of a module. 1his can also
be combined with history (see Section3.3.3, Histo-
ry stack) to compare the snapshot against different
stages of development.
You can control the split view by moving the splitline back and forth. lf you hover with the
mouse over the splitline, a small rotation icon will appear on the center of the line. Click
it to change between vertical and horizontal split view.
3.3.3.History stack
1he history stack lists every change of state (acti-
vate/de-activated) for all modules. Here you can se-
lect a point in stack to return to that point of devel-
opment history. lf you then activate a new module or
change a module parameter, all modules above the
current point will be discarded.
Caution: activating any module action using key accelerators will discard all modules above
the currently selected one. It is easy to lose all development work on an image this way!
Hitting compress history stack generates the shortest history stack that produces the
current image, i.e. suppressing all de-activated modules. 1his also will discard all modules
above the currently selected one.
1he button to the right lets you create a new style for applying your history stack to
other images. Use the first line of the popup dialog window to name your style and the
second to add a searchable description. You are prompted for which of the current history
stack modules to include in the style.
Once created styles are then managed and applied to other images in the lighttable's
styles panel (see Section2.3.8, Styles).
S1
3.3.4.Global color picker
Using the global color picker you can take color sam-
ples from your image, display their values in multiple
ways and compare colors from different locations.
1he color picker is activated by pressing the icon.
1here are multiple parameters for controlling how
the color picker works, whose settings remain in ef-
fect until you leave the darkroom mode.
Besides the global color picker described here there are also local color pickers in some of
the modules (eg. tone curve). Clobal and local color pickers are different. 1he global color
picker works in monitor color space and takes samples after the complete pixelpipe has
been processed. 1he local color pickers run in the color space of the individual module,
which is usually Lab, they reflect the input and output data of that specific module within
pixelpipe.
1he global color picker can be run in point or area mode. When in point mode only a small
spot under your cursor is taken as a sample. ln area mode you can draw a rectangle and
darktable samples the area within that rectangle. 1he combobox to switch between point
and area mode can also be used to toggle the mode of local color pickers.
lf samples are taken in area mode, darktable will calculate mean, min and max color chan-
nel values. A combobox allows you to select which of those are displayed. For obvious
statistical reasons mean, min and max are identical for the single sample of point mode.
A color swatch representing the sampled point or area is displayed. Numerical values are
shown as well. As said before global color picker works in monitor PCB color space. You
can also let darktable translate these numerical values into Lab color space. Beware that
Lab values are approximated here, depending on monitor color profile there can be some
deviations from the real values.
When the checkbox restrict histogram to selection is ticked, only the values of your se-
lected area or point are taken into account by the main histogram at the top of the right
hand panel (see Section3.3.6, Histogram). 1his is a way to show which tonal values are
present in a specific area.
1he sampled colors in either area or point mode can be stored as live samples by pressing
the add button. darktable will then show a color swatch and numerical values for each
stored sample. You can once again select which numerical value (mean, min, max) is to be
displayed and if this is to be done in PCB or Lab color space.
Newly created live samples are not locked. lf you change your image the changes will be
reflected in your live samples. Use this if you want see how changing parameters effects
different parts of an image. Clicking on a live sample's color swatch locks it and a lock
symbol is displayed. Further image changes will then no longer affect the sample. You can
for example take two live samples from the same location and lock |ust one of them to
provide a before and after sample comparison.
Live sample locations are indicated in your image if you check option display sample areas
on image.
S2
3.3.5.Mask manager
3.3.5.1.Overview
1he masks manager panel is the central place where you manage all masks and shapes
within the context of the current image. Here you create, delete and change shapes or
give them unique names. You can add shapes to and remove shapes from a mask, and you
define how multiple shapes interact within a mask.
3.3.5.2.Usage
ln the top line of the masks manager panel you find
buttons to create new shapes. 1hey are the same
as in the drawn mask CUl (see Section3.2.6, Drawn
mask for more details).
1he lines below list all masks used and all individual shapes defined. 1he masks are noted
with a headline in the form grp levels indicating the module in which they are used. 1he
list of masks is followed by a list of all individual shapes which have been generated in the
context of the given image. lf a shape is in use by any of the masks it is marked by the
symbol to the right of the shape name.
3.3.5.3.Shapes
By default shapes receive an automatically generated name, consisting of the shape type
(brush, circle, ellipse, path, gradient) and a number that is incremented automat-
ically. You can replace these automatically generated names by more meaningful ones.
Double-clicking on the existing shape name prompts you for a new one. Civing a mean-
ingful name is a good habit, especially if you are going to use the same selection in differ-
ent masks. A name like house front makes it easier to get the right shape, rather than
something like path #32.
Clicking on the shape name shows the selected shape in the center canvas with all its
controls. 1his is a convenient way to edit the properties of a specific shape. Especially if
there are so many shapes within a mask that their controls overlap and make it difficult
to hit the right target.
Pight-clicking on a shape name gives you a drop-down menu with the options to remove
the current shape or to remove all shapes currently not in use.
All shapes ever defined for the current image are kept in the list unless you remove them
explicitly. lf you have worked a lot with shapes on one image, this list can get quite long. All
settings - with all defined shapes - are part of the XMP tags of an image and are included in
exported files. lf the list of shapes is very long the needed space to store all shapes might
exceed the given limits of certain file formats, like JPEC. ln that case storing the XMP
tags might fail during export. 1his is normally not a problem - however, you can no longer
S3
rely on the exported file to contain your full history stack (see Section 2.3.12, Export
selected).
3.3.5.4.Masks
Clicking on the name of a mask expands a list showing the individual shapes which consti-
tute that mask.
Pight-clicking on the shape name opens a drop-down
menu. Here you define the way that the individual
shapes interact to form the mask. You can also re-
move shapes from that mask.
Masks are constructed by adding the shapes in the order that they are listed from top to
bottom. Each shape adds to the mask by using at your choice one out of four logical set
operators.
As order matters when combining shapes you may move each shape up or down if needed.
Each shape before being added can be inverted and is then depicted by the symbol.
3.3.5.5.Set operators
We use as an example a combination of a gradient
followed by a path to demonstrate the effect of the
set operator which we apply to the path shape. As a
convention we say that a pixel is selected in a mask
or shape if it has a value higher than zero.
union
1his is the default set operator. lt is depicted by the
symbol left to the shape name. 1he shape adds
to the existing mask in such a way that the resulting
mask contains the pixels that are either selected in
the existing mask or in the added shape. ln overlap-
ping areas the maximum value is taken.
S4
intersection
1his set operator is depicted by the symbol left to
the shape name. 1he shape adds to the existing mask
in such a way that the resulting mask contains only
pixels that are selected in both, the existing mask and
the added shape. ln overlapping areas the minimum
value is used. ln the given example we use this oper-
ator to imprint the path with a gradient.
difference
1his set operator is depicted by the symbol. ln
the non-overlapping area the existing mask is un-
changed. ln the resulting mask pixels get selected on-
ly if they are selected in the existing mask but not in
the added shape. 1his set operator can be chosen if
you want to cut out a region from within an exist-
ing selection.
exclusion
1his set operator is depicted by the symbol. 1he
resulting mask has all pixels selected that are either
selected in the existing mask and not in the added
shape or vice versa. 1his is equivalent to an exclusive
or.
3.3.6.Histogram
1his shows a histogram of the developed image's
light levels. ln its default state curves for all three
PCB color channels are displayed. You can toggle the
colored squares to enable or disable specific color
channels. A curve button is also provided to toggle
between linear view, logarithmic view and wavefront
view.
1he histogram is directly linked to the exposure mod-
ule described in Section3.4.1.4, Exposure, and you
can operate some of the exposure module's controls
from the histogram. You can left-click towards the
right hand side of the histogram and then drag right
to increase or drag left to decrease the exposure. ln
a similar manner you can control the black level by
clicking and dragging in the left hand side.
3.3.7.Module groups
SS
1he module groups button bar gives you quick access
to darktable's processing modules.
Here follows a description of the module groups available:
Active Modules you have activated and are using on the cur-
rent image.
Favorites Modules you have marked as favorites using more
modules (see Section3.3.8, More modules).
Basic Modules that are frequently used, such as exposure,
temperature etc. (see Section3.4.1, Basic group).
1one Modules for working with the image's tonal values,
e.g. levels, tonemap etc. (see Section 3.4.2, 1one
group).
Color Modules for processing colors, such as color correc-
tion, vibrance etc. (see Section3.4.3, Color group).
Correction Modules making corrections to the image, e.g. de-
noise, CA correction etc. (see Section3.4.4, Correc-
tion group).
Effect Modules with a more artistic output, such as vi-
gnetting, softening etc. (see Section 3.4.S, Effect
group).
Clicking on one of the group symbols will show the modules in that group. lf you once
again click on the symbol, grouping will be de-activated and all non-hidden modules will be
shown in one long list. 1his list shows the sequence in which modules are applied from bot-
tom to top. As a general principle darktable applies modules in a pre-defined sequence.
For those who are interested here is some information about darktable's internals: 1he
long list helps you to figure out in which color space a specific module acts. ln fact there
are only three modules which convert from one color space to another: demosaic, input
color profile and output color profile.
up to demosaic lmage is in raw data format with only latent colors.
Each pixel carries lightness and color information for
only one base color. Please mind that some of the
S6
modules in this part can also act on non-PAW input
images in PCB format.
between demosaic and input
color profile
lmage is in PCB format within the color space of the
specific camera or input file.
between input color profile
and output color profile
lmage is in Lab format. 1his is a very huge universal
color space which covers all colors visible to the hu-
man eye (and even more). As darktable processes im-
ages in 4x32-bit floating point buffers, we can handle
the Lab color space without risking banding or tonal
breaks.
after output color profile lmage is in PCB format as defined by the selected dis-
play or output lCC profile.
3.3.8.More modules
More modules at the bottom of the right panel is
used to show the less frequently used modules. By
default only standard modules are shown to the user
but you can use this function to make the extra mod-
ules visible, or alternatively to hide away modules
you don't typically use.
Each module is shown with a small icon next to its name. Left-click with your mouse to
toggle the status between visible, hidden and favorite. Favorite modules are indicated
by a star in front of the icon and in addition to appearing in their normal module group
will also be visible in the module group favorites. 1his is a good way to get fast access to
modules that you use very frequently. Visible modules are indicated in the list by a light
grey background whilst hidden modules have a dark grey background and do not display
any of their controls.
Hiding or un-hiding modules is not meant to be part of your daily workflow, you should
only occasionally need to review the modules you typically use.
3.3.9.Bottom panel
1he bottom panel provides quick access to apply presets and styles to your image and
allows to activate the over/underexposure warning. You can also activate a filmstrip for
quick navigation within the current collection.
3.3.9.1.Quick access to favorite presets
Clicking the icon opens a combobox that gives you quick access to your favorite
module's presets. Click on the preset name to apply it to the image.
3.3.9.2.Quick access to styles
Clicking the icon opens a combobox with your styles. Hovering with the mouse over a
style name opens a tooltip showing the involved modules. Click on a style name to apply
that style to the image.
3.3.9.3.Over/underexposed warning
S7
By clicking the icon an over/underexposed warning is toggled on or off. Pixels outside
the dynamic range, close to pure white or close to pure black, are prominently displayed
in a signal color. You can also activate the over/underexposure warning with the keyboard
shortcut o.
Pight-clicking on the icon opens a dialog with config-
uration parameters.
color scheme
ln the default color scheme underexposed pixels are shown in blue and overexposed pixels
in red. 1hese colors are easy to identify in most cases. ln some cases you may want to
change the color scheme to black & white or purple & green, eg. if you experience
overexposed highlights in red blossoms.
lower threshold
Sets the threshold for underexposure warning, expressed as a percentage of the maximal
brightness.
upper threshold
Sets the threshold for overexposure warning, expressed as a percentage of the maximal
brightness.
3.3.9.4.Filmstrip
1he optional filmstrip can be used to quickly switch between images while remaining in
the darkroom view. 1he images viewed are the same as the ones in the lighttable view.
1he filmstrip can be switched on and off using the shortcut ctrl-f. You can scroll with your
mouse to quickly navigate through the images and change the height of the filmstrip panel
by dragging its top.
S8
3.4.Modules
Modules are organized into five functional groups: basic, tone, color, correction and ef-
fect. You either view all modules in one long list or instead click on a group to |ust display
modules belonging to that group.
3.4.1.Basic group
1he basic group of modules contains the modules for basic development. 1hese are ones
you probably will use most often, such as exposure, white balance etc.
3.4.1.1.Crop and rotate
Overview
1his module is used to crop, rotate and correct per-
spective distortions of your image. You can overlay
your image with various helpful guidelines that assist
you using the tools.
Some of the tools of this module, namely ad|ustment of angle and corrections of perspec-
tive distortion, will require the original image data to be interpolated. For best sharpness
results set lanczos3 as pixel interpolator in core options (see Section6.2, Core options).
Usage
Whenever the user interface of this module is in focus, you will see the full uncropped
image overlayed with handles and guiding lines.
First off, select what aspect ratio you want and size the crop boundaries by dragging bor-
der and corner handles. Use the button right of the aspect box, to swap between portrait
and landscape mode. You can move around the crop rectangle by holding down left mouse
button and move around. When you are done and want to execute the crop, |ust give fo-
cus to another module. You can at any time change your crop area by |ust revisiting this
module.
flip
1his tool is used to flip the image on the horizontal,vertical or both axis.
angle
1his tool corrects the rotation angle helping you level an image. You can either set a nu-
merical value or use your mouse directly on the image. 1o use your mouse, right-click, hold
it down and draw a line along the horizon, as soon as you release the mouse button the
image is rotated so the line you drew matches the horizontal axis.
keystone
1his tool is used to correct perspective distortions in your image. Useful for example when
you shoot a high building from ground with a short focal length, aiming upwards with your
camera. 1he combobox lets you select the type of correction you want to use :
vertical if you want to limit the correction to vertical lines
S9
horizontal limit the correction to horizontal lines
free if you want to correct horizontal and vertical lines
Depending on the selected correction type you will
see two or four straight ad|ustment lines overlaid to
your image. 1wo red circles on every line let you mod-
ify the line positions with your mouse. Each line ad-
ditionally carries a symmetry button. lf activated
(and highlighted in red) all movements of the affect-
ed line will be mirrored by the opposite line.
ln order to correct perspective distortions, you need
to find suitable horizontal and/or vertical features in
your image and align the ad|ustment lines with them.
When done, press the OK button, which is locat-
ed close to the center of your image. 1he image will
be corrected immediately. You can at any time come
back and refine your corrections by selecting correc-
tion applied in combobox keystone.
automatic cropping
Use this options to avoid black edges on the image borders. Useful when you rotate the
image.
aspect
Here you can change what aspect ratio you want to have on the result, thus constraining
the ability to drag and crop rectangle out of the aspect ratio of your choice. Many com-
mon numerical ratios are pre-defined. You can also select any other ratio after opening
the combobox and typing it in the form of x:y. A few special aspect ratios deserve ex-
planation:
free free forming the rectangle without any ratio restrictions
image this option constrains the ratio to be equal to image ratio
golden cut this option constrains the ratio to be equal the golden number
square this option constrains the ratio to be 1
guides
Many self-explaining guides are available to help you compose your image.
Examples
A cropped image in center view when module crop
and rotate is in focus. 1he cropped area is visible as
well as some guiding lines.
3.4.1.2.Shadows and Highlights
60
Overview
1he shadows and highlights module allows ad|ust-
ment to the tonal range of darker parts of an image
(shadows) and lighter parts (highlights), it can bring
back details in shadows and highlights by enhancing
local contrast.
Usage
shadows
1his slider controls the effect on shadows, positive values will lighten up shadows while
negative values will darken them.
highlights
1his slider controls the effect on highlights, negative values will darken highlights while
positive values will lighten them up.
soften with
1his combobox chooses the underlying blurring filter, gaussian or bilateral. 1ry bilateral
filter if you experience halos with gaussian blur.
radius
1his slider controls the radius of the involved blurring filter. Higher values give softer tran-
sitions between shadows and highlights but might introduce halos. Lower values will re-
duce the size of halos but may lead to an artificial look. As said, bilateral filter is much less
prone to halo artifacts.
compress
1his slider controls how strong the effect extends to midtones, high values reduce the ef-
fect to the extreme shadows and highlights, low values cause strong ad|ustments also to
midtones. You normally only need to touch this parameter if you want to limit the effects
to the extreme shadows and highlights, increase the value in this case. At 100% this mod-
ule has no visible effect any longer as only absolute black and absolute white are affected.
shadows color adjustment
1his slider controls the color saturation ad|ustment made to shadows, high values cause
saturation enhancements on lightened shadows, low values cause desaturation on light-
ened shadows. lt is normally safe to leave this at its default of 100%. 1his gives a natural
saturation boost on shadows - similar to the one you would also expect in nature if shad-
ows would receive more light.
highlights color adjustment
1his slider controls the color saturation ad|ustment made to highlights, high values cause
saturation enhancements on darkened highlights, low values cause desaturation on dark-
61
ened highlights. Often highlights do not contain enough color information to give con-
vincing colors when darkened. You might need to play a bit with this parameter in order to
find the best fitting value depending on your specific image, but be aware that sometimes
results still might not be fully satisfying.
Examples
Original image exposed for the outer sunlit wall to
avoid clipped highlights. As a consequence the inte-
rior of the barn has pitch black shadows.
Shadows get lightened, highlights are untouched,
overall effect toned down a bit by blend mode nor-
mal and an opacity of 6S%.
Pesulting image.
3.4.1.3.Base curve
62
Overview
Camera sensors provide data in linear PCB format,
the original image appears flat and dull. 1hat's the
reason why camera manufacturers apply their char-
acteristic base curves to the PAW data when they
generate in-camera JPEC images with better colors
and contrast. darktable comes with base curve pre-
sets that mimic the curves of various manufacturers.
1hese are automatically applied to PAW images ac-
cording to the manufacturer lD found in EXlF data.
Usage
You can ad|ust an existing base curve or create a new one. 1he base curve is defined by
two or more nodes. You can click on any node and drag to modify it. You can also create
additional nodes by clicking on a curve segment between two nodes. ln order to remove
a node drag it outside of the widget area.
scale
1his combobox toggles between linear and logarithmic view. ln the double logarithmic
view more space is given to the lower values allowing a more fine-grained ad|ustment of
the shadows.
1ip: lf you intend to take full manual control of the tonal values with the tone curve module
or the zone system module (see Section3.4.2.3, 1one curve and Section3.4.2.4, Zone
system) it may be easier to leave the image in linear PCB. Disable the base curve module
in this case.
3.4.1.4.Exposure
Overview
1his module is used to tweak the exposure. lt is di-
rectly linked to the histogram panel. lndeed, if you
correct exposure graphically, using the histogram
(see Section 3.3.6, Histogram), you automatically
activate the exposure module. 1he histogram simply
acts as a view for the exposure module.
You can activate multiple instances of this module each with different parameters acting
on different parts of the image which you select by a drawn mask (see Section3.2.3, Mul-
tiple instances and Section3.2.6, Drawn mask). 1he histogram is always linked to the
lowest instance in pixelpipe.
Usage
1his module is responsible for one of the most basic steps in each raw image development.
An exposure ad|ustment value allows you - within certain limits - to correct for under- or
overexposure. A shift by 1EV is equivalent to a change of exposure time by a factor of 2.
Positive exposure corrections will make the image brighter. As a side effect noise level
gets higher. Depending on the basic noise level of your camera and the lSO value of your
63
image, positive exposure compensations with up to 1EV or 2EV still give reasonable re-
sults.
Negative exposure corrections will make the image darker. Civen the nature of digital im-
ages this can not correct for blown out highlights (see also Section3.4.1.7, Highlight re-
construction).
A black level ad|ustment is a basic tool to increase contrast and pop of an image. 1he
value defines at what threshold dark gray values are cut off to pure black. Use with care
as the clipped values can not be recovered in other modules further down the pixelpipe.
Please also have a look at the tone curve module (see Section3.4.2.3, 1one curve) and
the levels module (see Section3.4.2.2, Levels) which can produce similar results with less
side effects as they come later in pixelpipe.
black
Ad|ust the black level.
exposure
Ad|ust the exposure correction [EVj.
auto
Calculate a correct exposition for the rectangular view appearing in the centre of the im-
age. You can draw your own selection using your mouse. An ad|ustment slider right to
the auto exposure checkbox lets you define what percentage of bright values are to be
clipped out in the calculation.
3.4.1.5.Contrast Brightness Saturation
Overview
1his module offers a very basic tool for ad|usting an
image's contrast, brightness and saturation.
Usage
1he module has sliders for each of the three affected attributes. ln their neutral position
(zero) the image remains unchanged. Shifting sliders left to negative values reduces con-
trast, brightness and saturation, respectively. Shifting right to positive values leads to an
increase.
Much more versatility for contrast and brightness ad|ustment is offered by the tone curve,
levels, and zone system modules (see Section3.4.2.3, 1one curve, Section3.4.2.2, Lev-
els, and Section 3.4.2.4, Zone system). Likewise you may ad|ust color saturation in a
more detailed way with the tone curve, color contrast, and color zones modules (see Sec-
tion 3.4.2.3, 1one curve, Section 3.4.3.4, Color contrast, and Section 3.4.3.7, Color
zones).
contrast
1his slider ad|usts the image's contrast.
64
brightness
1his slider ad|usts the image's brightness.
saturation
1his slider ad|usts the color saturation.
3.4.1.6.Demosaic
Overview
1his module allows you to control how the demosaic
is processed.
Usage
Demosaic is an essential step of any raw image development process.
A detailed description would be beyond the scope of this manual. ln a nutshell, the sen-
sor cells of a digital camera are only able to record different levels of lightness, not dif-
ferent color. ln order to get a color image, each cell is covered by a color filter, either in
red, green or blue. Due to the color sensitivity of the human vision, there are two times
more green cells than red or blue. Filters are arranged in a certain mosaic, called Bayer
pattern. 1herefore each pixel of your image originally only has information about one col-
or channel. Demosaic reconstructs the missing color channels by interpolation with data
of the neighboring pixels. For further reading see the Wikipedia article on the Bayer filter
[http://en.wikipedia.org/wiki/Bayer_filterj.
As interpolation is prone to produce artifacts, various different demosaic algorithms have
been developed in the past. Artifacts would typically be visible as moir-like patterns
when you strongly zoom into your image. Currently darktable supports PPC and AMAZE.
Both algorithms produce high quality output with a low tendency to artifacts. AMAZE is
reported to sometimes give slightly better results. However, as AMAZE is significantly
slower, darktable uses PPC as a default.
Some further parameters of this module can activate additional averaging and smoothing
steps. 1hey might help to reduce remaining artifacts in special cases.
Demosaic is always applied when exporting images. Demosaic is done on monitor display
only when zoom is greater than S0% or when the according preference setting demosaic-
ing for zoomed out darkroom mode (see Section6.2, Core options) is set accordingly.
Else color channels are taken from neighboring pixels without an expensive interpolation.
method
Set the demosaic method. darktable currently supports PPC and AMAZE.
edge threshold
Set the threshold for an additional median pass. Defaults to 0 which disables median
filtering.
color smoothing
Activates a number of additional color smoothing passes. Defaults to off.
6S
match greens
ln some cameras the green filters have slightly varying properties. 1his parameter adds an
additional equalization step to suppress artifacts. Available options are disabled, local
average, full average and full and local average.
3.4.1.7.Highlight reconstruction
Overview
1his module tries to reconstruct color information
that is usually clipped because of incomplete infor-
mation in some of the channels. lf you do nothing,
your clipped areas are often toned to the not clipped
channel. For example, if your green and blue chan-
nels are clipped, then your image will appear red in
the clipped areas.
Usage
method
You can choose between two methods: clipping highlight or reconstructing in LCh. Clip-
ping highlight analyses each pixel having at least one channel clipped. 1hen it sets all chan-
nels to the minimum value found among the channels. Peconstruct in LCh analyses each
pixel having at least one channel clipped and transforms the information in LCh color space
to linearly mix the channels.
clipping threshold
Manually ad|ust the clipping threshold against magenta highlights. 1he default is usually
satisfactory without any need for additional ad|ustments.
3.4.1.8.White balance
Overview
1his module is used to set the white balance. You
have three ways to interact with it: (a) Set up tint and
temperature, (b) define the value of each channel, or
(c) choose from predefined white balances.
Usage
tint
Alter the colour tint of the image, from magenta (value < 1) to green (value > 1). 1he chan-
nel sliders will be updated when you ad|ust this parameter.
temperature
Set the color temperature (in Kelvin). 1he channel sliders will be updated when you ad|ust
this parameter. darktable derives the color temperature from the EXlF data using some
model assumptions. 1he value given is not meant to be authoritative. ln the end only the
updated channel values determine how the image is modified.
66
red, green and blue channels
Set the channel values on a scale from 0 to 8.
preset
Select a preset white balance.
camera white balance (default) White balance reported by the camera.
spot white balance Select a square area in your image containing mostly
grey pixels. 1he white balance is calculated based on
the selected area.
passthrough Show without ad|usting for white balance.
camera presets Camera specific white balance presets. Examples: di-
rect sunlight, flash, cloudy, shade and a number of in-
door lighting options.
finetune
Some cameras offer additional finetuning parameters if one of the camera presets is se-
lected. Depending on camera white balance, can be ad|usted in steps within a certain
range. 1he ad|ustments are usually towards yellow (value < 1) or blue (value > 1).
3.4.1.9.Invert
Overview
1he main purpose of this module is to invert scanned
negatives.
Usage
color of film material
1he only control element of this module is a color selector which allows to ad|ust for dif-
ferent colors of your film material. Clicking on the colored field will open a color selector
dialog which allows to define a color in HSL or PCB color space. You can also activate a
color picker by pressing and take a color probe from your image - preferably from the
unexposed border of your negative.
3.4.2.Tone group
1his group contains modules that operate on the tonal values of an image, modulating
brightness while leaving color values intact.
3.4.2.1.Fill light
Overview
1his module allows local modification of the expo-
sure based on pixel lightness.
67
Usage
Pushes exposure by increasing lightness with a Caussian curve of a specified width, cen-
tered on a given lightness.
exposure
Sets fill-light exposure in [EVj.
center
Sets the median lightness impacted by the fill-light. A color picker is activated by pressing
. lt shows the picked lightness value in the gradient bar, which helps find the desired
center value.
width
Sets the width of the Caussian curve. 1his number is expressed in zones, with the whole
dynamic range being 10 zones. As the Caussian curve is symmetric, only even numbers
can be entered.
3.4.2.2.Levels
Overview
A tool for ad|usting black, white, and mid-gray points.
1his module is especially useful if the histogram of
an image does not span the whole horizontal range,
from pure black to pure white.
Usage
1he levels tool shows a histogram of the image, and displays three bars with handles. Drag-
ging the handles modifies the tones in the image. 1hose bars control the black, middle
gray and white points.
You can move the black and white bars to match the left and right border of the histogram,
which will make the output image span the full available tonal range. A previously flat
looking image will get more contrast and pop.
Moving the middle bar will modify the middle gray tones. Shifting it left will make the im-
age look brighter, shifting it right will make it darker. 1his is often referred to as a change
of image gamma.
1here are three color pickers in black, gray, and white, available by pressing the respec-
tively colored icon. You can use them to sample the corresponding level directly from
the image.
1he auto button autoad|usts the black and white point and puts the gray point exactly
in the mean between them.
3.4.2.3.Tone curve
68
Overview
1his module is a classic digital photography tool. Un-
like other image manipulation software, however,
darktable's tone curve acts in Lab color space. 1hus, it
offers three independent curves for L, a, and b chan-
nels.
Usage
ln its default state, curves will be straight lines, defined by few anchor nodes. You can
move the nodes with your mouse to modify the curve. You can also generate new nodes
by clicking on the curve. Up to 20 nodes per curve can be defined. 1o remove a node, move
it out of the widget area. A color picker is activated by pressing and will show the picked
values in the graph. Numerical Lab values of input and output (see below) at the selected
spot are shown on top left of the widget.
L-channel curve
1he tone curve in L-channel works on Lightness. For a better overview a lightness his-
togram is displayed in the diagram.
1he horizontal line represents the input image pixels' lightness. 1he vertical line repre-
sents the lightness of the output image pixels. A straight line does not change anything. A
point above the default diagonal increases the lightness, whereas a point under decreases
it. Shifting the center of the curve upwards will lighten the image, shifting it downwards
will darken the image. An S-like curve will enhance the contrast of the image.
a/b-channel curves
1he curves in the a and b channels work on color values. 1hey are only displayed and active
if the scale chroma combobox is set to manual. 1he horizontal line represents the color
channel value of the input image pixels. 1he vertical line represents the color channel
value of the output image pixels. Positive a-values correspond to more magenta colors,
negative a-values correspond to more greenish colors. Positive b-values correspond to
more yellowish colors, negative b-values correspond to more blueish colors.
A straight line does not change anything. Shifting the center of the curve will give the
image a color tint: shifting a-channel upwards gives a magenta tint, shifting b-channel up-
wards gives a yellow tint, shifting a-channel downwards gives a green tint, shifting b-chan-
nel downwards gives a blue tint.
lncreasing/decreasing the steepness of the curves, without shifting its center, will in-
crease/decrease the color saturation of the respective channel. With properly defined
curves you can exert fine control on color saturation, depending on the input pixel's colors.
scale chroma
darktable does an automatic ad|ustment of color saturation, if this combobox is set to au-
to. 1he level of this ad|ustment depends on the pixel's color values and its L-value modi-
69
fication by the L-channel tone curve. lt is designed to give an overall boost in color satura-
tion, if the L-curve gives a contrast boost. Look at blend mode colorad|ustment to ad|ust
the strength of this effect (see Section3.2.S, Blending operators). lf this combobox is
set to manual, you can modify color saturation using the curves in channels a and b.
Examples
Original image
1one curve settings. Please note how the center
node of our b-curve was shifted down to negative val-
ues. 1his gives the image its blue tint.
Pesulting image
3.4.2.4.Zone system
Overview
1his module is another way to change the lightness
of your image, based on Ansel Adams' system. lt al-
lows modification of a zone's lightness taking into ac-
count the effect on the ad|acent zones. lt divides the
lightness range into a user-defined number of zones.
Usage
1he lightness is processed on the L channel from Lab.
1he center view shows the image broken down in zones.
When hovering above a zone on the lightness scale, that zone is highlighted on the pre-
view. 1he number of zones can be changed by mouse-scrolling on the lightness scale.
70
Left click and drag a handle in the zonebar to modify the zonemapping, use right click to
remove a controlpoint.
Examples
1he original image.
Here, the darker and lighter zones were compressed
to increase contrast, then the upper parts of darker
zones were expanded to increase their visual impact.
3.4.2.5.Local contrast
Overview
1his module allows enhancing local contrast. lt uses
the unnormalized bilateral filter, and works on the L
channel from Lab.
Usage
Local contrast boosts details of your image, much like the equalizer does (see Sec-
tion3.4.4.2, Equalizer). However, it is easier to use as it does not require you to work on
different frequency bands.
coarseness
Make the details you want to ad|ust finer or coarser.
contrast
How strongly the algorithm distinguishes between brightness levels. lncreasing the value
results in a more contrasty look.
detail
Add or remove detail. Higher values will increase local contrast.
Example
Before
71
After, a little overdone to demonstrate the effect.
Use this sparingly, to avoid a cheap, overprocessed
look.
3.4.2.6.Tonemapping
Overview
1his module compresses the tonal range of HDP im-
ages, so they fit into the limits of a normal, low dy-
namic range image, using Durand's 2002 algorithm.
darktable can import HDP images if they come in
OpenEXP, PCBE or PFM format or as a DNC generat-
ed by darktable's HDP creation mechanism (see Sec-
tion2.3.6, Selected image(s)).
Usage
1he underlying algorithm uses a bilateral filter to decompose an image into a coarse base
layer and a detail layer. 1he contrast of the base layer is compressed, while the detail layer
is preserved, then both layers are re-combined.
contrast compression
Sets the compression level of the contrast layer to fit the lower dynamic range.
spatial extent
Sets the spatial extent of the bilateral filter. Lower values cause the contrast compression
to have stronger effects on image details.
3.4.2.7.Global tonemap
Overview
1his modules implements another approach to com-
pressing the tonal range of an HDP image into the
limited tonal range of a typical LDP output file. lt of-
fers several implementations of global tonemap op-
erators.
Usage
Clobal tonemapping processes each pixel of an HDP image, without taking the local sur-
rounding into account. 1his is generally faster than local tonemapping, as implemented in
the tonemapping module but might lead to less convincing results with very high dynamic
scenes. As an enhancement to the original operators, darktable can preserve detail of the
input image, and transfer it back to the output image.
operator
Peinhard, Filmic and Drago global tonemap operators are available for use. Depending
on the selected operator, different parameters can be ad|usted. Some operators are fully
self-ad|usting, and do not require specific controls.
72
bias
Only offered for the Drago operator. 1his parameter influences the contrast of the output
image. lt is an essential parameter for ad|usting the compression of high values and the
visibility of details in dark areas. According to the original paper, a value of 0.8S is recom-
mended as a starting point.
target
Only offered for the Drago operator. 1his is a scale factor to ad|ust the global image bright-
ness to the brightness of the intended display. lt is measured in cd/m
2
, and should match
the according value of your output device. Higher values lead to a brighter image, while
lower values lead to a darker image.
detail
Offered as an addition to all operators. 1his parameter controls how much detail is pre-
served and transferred back into the output image after tonemapping.
3.4.3.Color group
Modules for working specifically on your image's color are found here in the color group.
3.4.3.1.Velvia
Overview
1he velvia module enhances image saturation. lts ef-
fect is tailored to increases saturation less on lower
saturated pixels than on highly saturated pixels.
Usage
strength
1his slider controls the strength of the effect.
mid-tones bias
Velvia can reduce its effect for mid-tones to avoid unnatural skin tones. 1he mid-tones bias
slider controls this selectivity, reducing its value reduces mid-tone protection and makes
the overall velvia effect stronger.
3.4.3.2.Channel mixer
Overview
1his module is a powerful tool to manage channels.
lt accepts red, green and blue channels as an input.
As output it provides red, green, blue, gray, hue, sat-
uration and lightness channels.
Usage
First select your output channel and then set the amount each input channel feeds into
that output channel.
73
Examples
For skin tones the blue channel tends to represent
detail, with red tending to also have smoother tones
than green. 1herefore tonal rendering is controlled
by how we blend of the three input channels.
Here a monochrome portrait is produced by simply
selecting the grey channel as output. A smooth skin
tone is achieved by reducing the blue channels input
and also emphasizing the red channels input relative
to green. An PCB mix of 0.9, 0.3, -0.3 was used togeth-
er with an 0.1 EV exposure increase to lighten the im-
age.
ln this example an PCB mix of 0.4, 0.7S, -0.1S uses
more green than red, bringing back some features.
We still reduce the blue channel in the mix to de-em-
phasize unwanted skin texture.
Table of mixing values for some b/w films
Classic black and white films have different characteristic color responses. Select gray as
output mixing channel, and try out the values suggested below for your favorite film type.
Film 1ype Ped Creen Blue
ACFA 200X 0.18 0.41 0.41
Agfapan 2S 0.2S 0.39 0.36
Agfapan 100 0.21 0.40 0.39
Agfapan 400 0.20 0.41 0.39
llford Delta 100 0.21 0.42 0.37
llford Delta 400 0.22 0.42 0.36
llford Delta 3200 0.31 0.36 0.33
llford FP4 0.28 0.41 0.31
llford HPS 0.23 0.37 0.40
74
llford Pan F 0.33 0.36 0.31
llford SFX 0.36 0.31 0.33
llford XP2 Super 0.21 0.42 0.37
Kodak 1-Max 100 0.24 0.37 0.39
Kodak 1-Max 400 0.27 0.36 0.37
Kodak 1ri-X 400 0.2S 0.3S 0.40
Normal Contrast 0.43 0.33 0.30
High Contrast 0.40 0.34 0.60
Ceneric B/W 0.24 0.68 0.08
3.4.3.3.Output color profile
Overview
1his module manages the output profiles for display
and export as well as the rendering intent to be used
when mapping between the different color spaces.
darktable comes with pre-defined profiles sPCB,
AdobePCB, XYZ and linear PCB but you
can provide additional profiles by placing
these in SDAPK1ABLE/share/darktable/color/out
and SHOME/.config/darktable/color/out. SDAPK-
1ABLE is used here to represent your chosen dark-
table installation directory and SHOME your home di-
rectory.
Usage
A configuration parameter always try to use littlecms2 in darktable's core options (see
Section6.2, Core options) defines how darktable renders colors for display and export.
lf the configuration parameter is disabled darktable uses a simplified and very fast inter-
nal rendering algorithm. lf the option is checked the external library littlecms2 [http://
www.littlecms.com/j with higher accuracy and significantly higher processing overhead is
used instead.
output intent
Sets the rendering intent for output/export. You can easily override this setting whenever
you do exports from lighttable mode.
perceptual Suited to pictures as it maintains the relative position
of colors. 1his 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 kept but lightness is slightly changed.
absolute colorimetric Keep the white point.
Only rendering with littelcms2 gives you a choice of rendering intent. 1he option is hidden,
if darktable's internal rendering routines are used.
7S
display intent
Sets the rendering intent for your display. See above for available options.
output profile
Sets the color profile for output/export.
softproof profile
Sets the color profile for softproofing.
softproof allows you to preview your image rendered using a printer profile so as to see
how colors will end up on the final print and is toggled on and off by pressing s.
Likewise gamut check is toggled on and off by pressing g, this function highlights in cyan
all pixels out of gamut with respect to the selected softproof profile.
softproof and gamut check are mutually exclusive modes that can be activated at any place
in darkroom mode and when this module is in focus the status is displayed below the
image.
1ip: at other times it may not be obvious if the softproof mode is still active or not. lf in
doubt press g, which will switch to gamut check and be clearly distinguishable by cyan
marked pixels. Press g again and you are back to normal display mode.
display profile
Sets the color profile for the display. 1he additional option system display profile is the
preferred setting when working with a calibrated display, the profile is taken either from
your system's color manager or from your X display server. ln gui options (see Section6.1,
CUl options) you can specify which method to use.
3.4.3.4.Color contrast
Overview
1he color contrast module provides simplified con-
trol for changing the contrast or separation of colors
between either green/magenta or blue/yellow axis.
Usage
Higher values increase color contrast, lower values decrease it. 1he effect of this module's
sliders are similar to applying a steepened or flattened a- or b-curve in module tone curve
(see Section3.4.2.3, 1one curve).
green vs. magenta
Changes color contrast for green versus magenta.
blue vs. yellow
Changes color contrast for blue versus yellow.
3.4.3.5.Color correction
76
Overview
1his module can be used to modify the global satura-
tion, give a tint to the image or to split tone it.
Usage
color board
For split toning drag 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
Use the saturation slider to correct the global saturation.
3.4.3.6.Monochrome
Overview
1his module is a quick way to convert an image into
black and white and provides a variable color filter
for that conversion.
Usage
1he default central location of the filter has a neutral effect but dragging it to an alternate
position applies a filter analogously to taking a b&w photograph through a conventional
color filter.
As well as position you can change the filter size by scrolling with your mouse wheel. 1his
makes the filter's range of hues more or less selective.
1ip: First reduce the filter size to concentrate its effect and move it across the hue pallet
to find the best filter value for your desired image rendition. 1hen expand the filter to
include more hues and thus more natural tonality.
77
3.4.3.7.Color zones
Overview
1his module selectively modifies the colors in your
image. lt is highly versatile and allows every transfor-
mation possible in the LCh colorspace.
Usage
1he horizontal axis represent the different values you can modify. 1he vertical axis shows
the changes you can achieve.
For both horizontal and vertical axes you can work on lightness, saturation or hue. A color
picker is activated by pressing and will show the picked values in the diagram.
You can click on any of the eight nodes on the curve and drag to ad|ust it vertically. A circle
indicates how strong ad|acent nodes will be affected. Use the scroll wheel of your mouse
to change the circle diameter. You can also use the eight controlpoints (triangles which
define the vertical value of the nodes) at bottom to ad|ust the curve.
3.4.3.1.Color balance
3.4.3.1.1.Overview
1his module offers a versatile tool for ad|usting an
image's color balance.
3.4.3.1.2.Usage
For each of the three primary colors - red, green, and blue - there are three sliders lift,
gamma and gain to control dark tones, mid tones and high tones, respectively. Chang-
78
ing these parameters adds offsets to the individual PCB channels and influences the color
balance of the image.
Additional factor sliders act on all colors at once. 1heir effect is similar to the controls
of the levels module (see Section3.4.2.2, Levels).
1he way to best envision the module's way of working is if you consider lift, gamma
and gain as parameters influencing the properties of a tone curve which - in its original
state - is a straight line going diagonally from bottom left to top right.
1he lift parameter ad|usts the left axis intercept of the line - the intercept can be shifted
from its default zero value to negative or positive values. 1he gamma parameter modifies
the line shape - the default shape is linear and can be turned into a convex curve with
increased or into a concave curve with lowered gamma values. Finally, the gain parameter
defines the steepness of the curve - by default the curve runs diagonally, higher values
lead to a steeper curve and lower values to a flatter one.
Side note: although this module acts on PCB colors its location in pixelpipe puts it into
the Lab color space. Accordingly the modules converts from Lab to PCB, does its color
ad|ustments, and then converts back to Lab.
lift
lncreases the value of dark colors with individual sliders for each PCB color and with a
factor slider acting on all three colors at once.
gamma
Ad|usts the mid tones with individual sliders for each PCB color and with a factor slider
acting on all three colors at once.
gain
Ad|usts the high tones with individual sliders for each PCB color and with a factor slider
acting on all three colors at once.
3.4.3.8.Vibrance
Overview
Vibrance is a widely used term in image processing
but the mechanism and end result differ from pro-
gram to program. Vibrance in darktable saturates
and brings down the lightness of the most saturated
pixels to make the colors more vivid.
Usage
Vibrance only has one parameter which controls the amount applied.
vibrance
1he amount of vibrance to apply to the image.
3.4.3.9.Input color profile
79
Overview
1his module can be used to override darktable's au-
tomatic allocation of input color profile if there is an
alternative that more closely matches your original
image's color space.
Usage
profile
Choose the profile or color matrix to apply, darktable offers many widespread matrices
along with an enhanced matrix for some camera models. 1he enhanced matrices were
processed by the darktable team in order to provide a look closer to the manufacturer's.
You can also supply your own input lCC profiles and put them into SDAPK1ABLE/share/
darktable/color/in or SHOME/.config/darktable/color/in. SDAPK1ABLE is used here to
represent darktable's installation directory and SHOME your home directory. One com-
mon source of lCC profiles is the software that is shipped with your camera, it often con-
tains profiles specific to your camera model. You may need to activate module unbreak
input profile (see Section3.4.3.10, Unbreak input profile) to use your extra profiles.
lf your input image is a low dynamic range file like JPEC, or a raw in DNC format, it might
already contain an embedded lCC profile which darktable will use as a default. You can
always overrule darktable and select a different profile or select embedded icc profile
to restore the default.
3.4.3.10.Unbreak input profile
Overview
1his module adds a correction curve to image data,
which is required if you have selected certain input
profiles in module input color profile.
Usage
lf you decide in module input color profile to use an lCC profile from the camera manu-
facturer, a correction curve very frequently needs to be pre-applied to image data - or
else the final output looks much too dark. 1his extra processing is not required if you use
darktable's standard or enhanced color matrices. 1he correction curve is defined with a
linear part extending from the shadows to some upper limit and a gamma curve covering
mid-tones and highlights. For further reading please also have a look at darktable's neigh-
bouring pro|ect UFPaw [http://ufraw.sourceforge.netj.
linear
Set the upper limit for the region counted as shadows and where no gamma correction is
performed. 1ypically values between 0.0 and 0.1 are required by the profile.
gamma
Set the gamma value to compensate your input profile. Often the required value is 0.4S
(the reciprocal of 2.2 gamma used by some manufacturer's profile).
80
3.4.4.Correction group
1he correction group contains the modules that will correct typical problems in an photo
such as hotpixels, spot removal, noise, lens correction among others. 1his group also in-
cludes the basic sharpening tools.
3.4.4.1.Sharpen
Overview
1his is an standard UnSharp Mask (USM) tool for
sharpening the details of an image.
Usage
1his module works by enhancing the contrast around edges and thereby enhances the
impression of sharpness of an image. ln darktable this module is only applied to the L-
channel in Lab color space.
radius
USM applies a gaussian blur to your image as part of its algorithm. 1his controls the blur
radius which in turn defines the spatial extent of edge enhancement. 1oo high values will
lead to ugly over-sharpening.
amount
1his controls the strength of the sharpening.
threshold
Contrast differences below this threshold are excluded from sharpening. Use this to avoid
amplification of noise.
3.4.4.2.Equalizer
Overview
1his versatile module can be used to achieve a variety
of effects, such as: bloom, denoising, clarity, and lo-
cal contrast enhancement. lt works in the wavelet do-
main and parameters can be tuned for each frequen-
cy band separately.
Usage
Each frequence band can be tweaked independently. ln particular, you can ad|ust contrast
boost and denoise threshold splines for both lightness and chromaticity, as well as the
sharpness of the wavelet basis on each frequency scale.
81
Each spline can be dragged with a proportional ed-
it approach, use the mouse wheel to ad|ust the ra-
dius in which your changes will have an effect. 1he
transparent area indicates where you would drag the
spline with the current mouse position and radius.
1he small little triangles on the x-axis can be moved
to alter the x-position of the spline nodes.
Drag the upper line (bright circles, here for the light-
ness channel) to affect local contrast. Pulling it up,
as shown here, will result in a contrast boost for that
frequency band. Higher frequencies, i.e. smaller de-
tails, are to the right of the grid. Pulling it down
works, too.
1he bottom spline (black circles) is used to perform
denoising. lt ad|usts the wavelet shrinkage threshold
for each frequency band. Pull it up to see the effect.
ln this example, the noise which has been amplified
by local contrast enhancement is removed.
1his screen shows the effect of the sharpen para-
meter. lt is here pulled down to zero for all bands.
1his is effectively a regular trous wavelet, without
edge detection, and results in the characteristic ha-
los around sharp edges in the image.
1his image is the other extreme. 1he wavelet basis
now oversharpens, which results in ugly gradient re-
versals near the ridge of the rock.
Note that the sharpness parameter only affects the wavelet basis, not the image directly.
You will have to change some denoise/contrast boost parameters to see an effect follow-
ing ad|ustments to the sharpness parameter.
1his module additionally has a mix slider below the spline CUl. Ad|usting the slider will
upscale or downscale the splines on the y-axis. 1he slider was added as a convenience tool
to help you modify the strength of the effect. lt is not a module parameter in itself, when
you leave darkroom mode all changes will be consolidated into the spline curves.
82
Have a look at the presets where there are a broad variety of examples that will provide
a good starting point to gain an intuitive understanding of the controls. Among others
there are two presets to enhance an image's clarity.
3.4.4.3.Denoise - profiled
Overview
1his module offers an easy to use and - at the same
time - highly efficient denoise operation. Under the
hood it applies (your choice of) a non-local means or
edge-aware wavelet denoise algorithm with parame-
ters specifically profiled for certain camera models
and lSO settings.
Usage
1he darktable team, with the help of many users, has measured noise profiles for various
cameras. Differentiated by lSO settings we evaluated how the noise statistics develop
with brightness for the three color channels. Our set of profiles already covers about 100
popular camera models from all ma|or manufacturers.
profile
Based on EXlF data of your PAW file, darktable will automatically determine the camera
model and lSO setting. lf found in its database, the corresponding noise profile will be
used. lf your image has an intermediate lSO value, the statistical properties will be inter-
polated between the two closest datasets in the database, and this interpolated setting
will show up as the first line in the combo box. You also have the option to manually over-
write this selection to suit your personal preferences better. 1he top-most entry in the
combo box brings you back to the profile darktable deems most suited.
mode
1his module can eliminate noise with two different core algorithms. non-local means
is a bit better suited to tackle luma (lightness) noise, wavelet has its strength in elim-
inating chroma (color) noise. lf needed you can apply two instances of this module (see
Section3.2.3, Multiple instances). 1he non-local means instance should be combined
with blend mode lightness or HSV lightness, the wavelet instance with blend mode
color or HSV color. For more information on blend modes have a look at Section3.2.S,
Blending operators.
patch size
1his slider is only available if mode non-local means is selected. lt controls the size of the
patches being matched when deciding which pixels to average (see also Section3.4.4.4,
Denoise - Non local means). Setting this to higher values can give more sharpness. Pro-
cessing time will stay about the same.
strength
1his parameter is here to fine-tune the strength of the denoise effect. 1he default value
has been chosen to maximize the peak signal to noise ratio. lt's mostly a matter of taste
if you prefer a rather low noise level at the costs of a higher loss of detail, or if you accept
more remaining noise in order to have finer structures better preserved within your image.
3.4.4.4.Denoise - Non local means
83
Overview
1his is a denoise algorithm, which will work on chro-
ma and/or luma.
Usage
1his module reduces noise in your image but preserves structures. 1his is accomplished by
averaging a pixel with other pixels in the image. 1he weight of averaging depends on the
similarity of the surrounding pixel's neighborhood with the neighborhood of the one pixel
to be denoised. A patch with a certain size is used to measure that similarity. As denoising
is a resource hungry process, it slows down pixelpipe processing significantly, consider
activating this module late in your workflow.
patch size
1he radius of the patch for similarity evaluation.
strength
1he strength of the denoise. Higher values lead to a stronger effect.
luma
Amount of denoise to apply to luma. Select carefully in order not to lose too much struc-
ture.
chroma
Amount of denoise to apply to chroma. You can be much more aggressive with this para-
meter compared to luma.
3.4.4.5.Denoise - bilateral
Overview
1his module is used to denoise high lSO pictures.
lt is flagged as a slow module due to its high re-
source consumption, both in terms of CPU cycles and
in terms of memory usage. Quite counter-intuitive-
ly, the greater the values for sliders, the lesser re-
sources.
Usage
1his module reduces noise in your image but preserves sharp edges. 1his is accomplished
by averaging pixels with their neighbors, taking into account not only the geometric dis-
tance but also the distance on the range scale, i.e. differences in color intensities. As de-
noising is a resource hungry process, it slows down pixelpipe processing significantly, con-
sider to activate this module late in your workflow.
radius
Set the spatial extent of the gaussian blur.
84
red
Blur intensity for red channel.
green
Blur intensity for green channel.
blue
Blur intensity for blue channel.
3.4.4.6.Lens correction
Overview
1his module is able to correct certain lens flaws,
namely distortions, transversal chromatic aberra-
tions (1CA) and vignetting. lt relies on the external
library lensfun, which comes with correction profiles
for many (but not all) common cameras end lenses.
Usage
ln order to perform lens corrections the module uses EXlF data of your image to identify
the specific camera/lens combination and collects the needed correction parameters from
a profile in lensfun's database.
camera
1he camera make and model as determined by EXlF data. You can override this manually
and select your camera from a hierarchical menu.
lens
1he lens make and model as determined by EXlF data. You can override this manually and
select your lens from a hierarchical menu. 1his is mainly needed for pure mechanical lens-
es.
photometric parameters: focal length, aperture, focal distance
Corrections additionally depend on certain photometric parameters that are read from
EXlF-data: focal length (needed for distortion, 1CA, vignetting), aperture (needed for 1CA,
vignetting) and focal distance (needed for vignetting). Many cameras do not record focal
distance in their EXlF data, most likely you need to set this manually.
You can manually override all automatically selected parameters. Either take one of the
predefined values from the pull-down menu, or - with the pull-down menu still open - |ust
type in your own value.
lf you system's lensfun library has no correction profile for the automatically identified
camera/lens combination the controls for the three photometric parameters are not dis-
played, and you get a warning message instead. You may try to find the right profile your-
self by searching for it in the menu. lf there is no matching profile for your lens, please
visit this lens calibration service [http://www.darktable.org/2013/07/have-your-lens-cali-
8S
brated/j offered by 1orsten Bronger, one of darktable's users. Alternatively you may go to
lensfun's home page [http://lensfun.berlios.dej and learn how to generate your own set
of correction parameters. Don't forget to share your profile with the lensfun team!
corrections
1his combobox gives you a choice about which corrections (out of distortion, 1CA and
vignetting) darktable shall apply. Change this from its default all, if your camera has
already done some internal corrections (e.g. of vignetting), or if you plan to do certain
corrections with a separate program.
geometry
ln addition to the correction of lens flaws, this module can change the pro|ection type of
your image. Set this combobox to the aimed pro|ection type, like rectilinear, fish-eye,
panoramic, equirectangular.
scale
1his slider allows you to ad|ust the scaling factor of your image. Pressing the auto scale
button (right to the slider) will let darktable find the best fit to avoid black corners.
mode
1he default behavior of this module is to correct lens flaws. Switch this togglebutton to
distort in order to simulate the behavior of a specific lens (inverted effect).
TCA red
1his slider allows to override the correction parameter for 1CA. You can also use this slider
to manually set the parameter in case the lens profile does not support 1CA correction.
Look out for colored seams at features with high contrast edges and ad|ust this parameter
and the following one to minimize those seams.
TCA blue
1his slider allows to override the correction parameter for 1CA. You can also use this slider
to manually set the parameter in case the lens profile does not support 1CA correction.
corrections done
You will sometimes observe that for a given camera/lens combination only part of the
possible corrections (distortion, 1CA, vignetting) are supported by lensfun's profiles. 1his
message box will tell you what corrections have actually been applied.
3.4.4.7.Spot removal
Overview
Spot removal allows you to correct an area in your
image by using another area as model.
Usage
1his module uses some of the shapes that are offered in drawn masks, namely circles,
ellipses and path shapes. 1he user interface and the controls are the same as in drawn
mask and explained in more detail in Section3.2.6, Drawn mask.
86
Select the desired shape by clicking the corresponding icon, then click on the canvas to
choose the area to be healed, i.e. the target area.
1he source area is preliminary positioned at a location with a default distance to the target.
Source area and target area can then be shifted independently until the result matches
your expectations. An arrow helps to tell source from target area.
Use the shape specific controls to ad|ust its size, its border width, and other attributes.
Pight-click on a shape to delete it.
Collapse the module to complete the changes.
Examples
Let's use this portrait as example, we want to remove
some dirt and unwanted catchlight from camera pop-
up strobe.
l have marked all the spots that l want to remove
from the image with circle shapes and appropriately
selected source areas.
And here is the result image of the spotremoval.
3.4.4.8.Raw denoise
Overview
Paw denoise allows you to perform denoising on
pre-demosaic data. lt is ported from dcraw [http://
www.cybercom.net/~dcoffin/dcraw/j.
Usage
noise threshold
Set the threshold for noise detection. Higher values lead to stronger noise removal and
higher loss of image detail.
3.4.4.9.Dithering
87
Overview
1his module eliminates some of the typical banding
artifacts which can occur, when darktable's internal
32-bit floating point data are transferred into a dis-
crete 8-bit or 16-bit integer output format for display
or file export.
Banding is a problem which can arise, when an image is downsampled into a lower bit-
depth. Downsampling happens regularly, when darktable displays or exports the results
of a pixelpipe. ln order to avoid banding, you may activate this modules.
lf you export images with a reduced width/height and want best dithering results, please
make sure that you de-activate option do high quality resampling during export in core
options (see Section6.2, Core options), else the final scaling step will counteract dither-
ing.
Viewing from some distance an image dithered into a very low bit depth (like floyd-stein-
berg 1-bit b&w) will give the impression of a homogeneous grayscale image. We try to
mimic this impression in darktable when you look at zoomed-out images in the center
view, in the navigation window and for thumbnails. 1his is accomplished by dithering those
images into a higher number of grayscale levels. Note that as a consequence the histogram
- which is derived from the navigation window - will show this increased number of levels
and is no longer a full match of the output image.
Usage
method
1his combobox sets the dithering method. Floyd-Steinberg error diffusion - with some
typical output bit depths - and random noise dithering are both supported. Floyd-Stein-
berg systematically distributes quantization errors over neighboring pixels, whereas ran-
dom dithering |ust adds some level of randomness to break sharp tonal value bands. 1he
default setting is floyd-steinberg auto, which automatically adapts to the desired out-
put format.
damping
1his slider is only displayed if you choose method random. lt controls the level of added
random noise expressed as a damping factor in a 10*log
2
basis. A value of -80 is a good fit
for 8-bit output formats and -160 for 16-bit ones.
3.4.4.10.Hotpixels
Overview
1his module is able to automatically detect and elim-
inate hotpixels. Hotpixels are pixels which failed to
record light level correctly. Detected hotpixels are
replaced by an average value of their neighbors.
Usage
You control the detection sensitivity with the threshold parameter and the level of elim-
ination with the strength parameter.
88
threshold
1he threshold of the detection, i.e. how strong a pixel's value needs to deviate from its
neighbors to be regarded as a hotpixel.
strength
1he strength of blending hotpixels with their surrounding.
detect by 3 neighbours
1his will extend the detection of hotpixels, it will even regard a pixel as hot if a minimum
of only three (instead of four) neighbor pixels deviate by more than the threshold level.
mark fixed pixels
1his options will mark the pixels that have been corrected. lt also displays the count of
detected and fixed pixels.
3.4.4.11.Chromatic aberrations
Overview
1his module allows you to correct chromatic aberra-
tions.
Usage
1he module has no parameters. On activation it will automatically try to optimize away
visible CA's.
1he underlying model assumes as input an uncropped photographic image. 1he module is
likely to fail when you zoom into the image, as in that case it will only receive parts of your
photograph as input in darktable's pixelpipe. As a consequence, chromatic aberrations do
not get corrected properly in the center view. 1his limitation only applies to interactive
work, not to file export.
3.4.5.Effect group
ln the effect group you will find modules with a more artistic touch.
3.4.5.1.Watermark
Overview
1he watermark module provides a way to render a
vector-based overlay onto your image. Watermarks
are standard SVC documents and can be designed us-
ing Inkscape [http://www.inkscape.orgj.
1he SVC processor of darktable also substitutes strings within the SVC document, which
gives the opportunity to include image dependent information in the watermark such as
aperture, exposure time and other metadata.
89
User-designed watermarks are placed into the directory SHOME/.config/darktable/water-
marks. Once in place, use the reload button at the right of the watermark file name to
update the list of available watermarks to use.
Here follows a list of available variable strings that is supported for substitution within
the svg document.
S(DAPK1ABLE.NAME) 1he application name
S(DAPK1ABLE.VEPSlON) 1he version of darktable
S(lMACE.lD) 1he unique image id within current library
S(lMACE.FlLENAME) 1he image filename
S(lMACE.EXlF) 1he image exif string
S(EXlF.DA1E) 1he image date
S(EXlF.DA1E.SECOND) Seconds from the image EXlF data
S(EXlF.DA1E.MlNU1E) Minutes from the image EXlF data
S(EXlF.DA1E.HOUP) Hours from the image EXlF data (24h)
S(EXlF.DA1E.HOUP_AMPM) Hours from the image EXlF data (12h, AM/
PM)
S(EXlF.DA1E.DAY) Day from the image EXlF data
S(EXlF.DA1E.MON1H)
S(EXlF.DA1E.SHOP1_MON1H)
S(EXlF.DA1E.LONC_MON1H)
S(EXlF.DA1E.SHOP1_YEAP) Abbreviated year from the image EXlF data
(2013 is "13")
S(EXlF.DA1E.LONC_YEAP) Full year from the image EXlF data
S(DA1E) Current system date
S(DA1E.SECOND) Current system time seconds
S(DA1E.MlNU1E) Current system time minutes
S(DA1E.HOUP) Current system time hours (24h)
S(DA1E.HOUP_AMPM) Current system time hours (12, AP/PM)
S(DA1E.DAY) Current system time day
S(DA1E.MON1H) Current system time month
S(DA1E.SHOP1_MON1H)
S(DA1E.LONC_MON1H)
S(DA1E.SHOP1_YEAP) Current system time year (abbreviated)
S(DA1E.LONC_YEAP) Current system time year
S(EXlF.MAKEP) 1he maker of camera model
S(EXlF.MODEL) 1he camera model
S(EXlF.LENS) 1he specific lens used
S(Xmp.dc.creator) 1he creator string
S(Xmp.dc.publisher) 1he publisher string
S(Xmp.dc.title) 1he title of the image
S(Xmp.dc.description) 1he description of the image
S(Xmp.dc.rights) 1he rights assigned to the image
90
Usage
marker
Choose the watermark of interest. You can use the reload button next to the combobox
to update the list with all newly added watermarks.
opacity
Set the opacity of the render of watermark.
scale
Scale the watermark pixel-independently.
alignment
Use these controls to align the watermark to any edge or center of the image.
x offset
Pixel-independent offset relative to the choice of alignment on x-axis.
y offset
Pixel-independent offset relative to the choice of alignment on y-axis.
3.4.5.2.Framing
Overview
1his module is an artistic feature to generate a frame
around your image. 1he frame consists of a border
with a user defined color and a frame line inside that
border, which has another user defined color. 1here
are various options for you to control the geometry
of your frame.
Usage
border size
1his slider controls the size of the frame in percent of the underlying full image.
aspect
With this combobox you can choose between different aspect ratios for the final output
of this module, i.e. underlying image plus frame.
orientation
lf you select a non-square aspect ratio this combobox defines the orientation - portrait or
landscape. Set to auto if you want darktable to select the most reasonable orientation
based on the underlying image.
91
horizontal position
Select from a set of pre-defined ratios where you want your underlying image be posi-
tioned on the horizontal axis. You can also right click and enter your own ratio as x/y.
vertical position
Select from a set of pre-defined ratios where you want your underlying image be posi-
tioned on the vertical axis. You can also right click and enter your own ratio as x/y.
frame line size
1he percentage of the frame line size relative to the border size at its smallest part.
frame line offset
Where the frame line is positioned relative to the underlying image. Select a value of 0 for
a frame line touching the image, 100% for a frame line touching the outer border limits.
border color
Clicking on the colored field will open a color selector dialog which allows one to define
a color for the border in HSL or PCB color space. You can also activate a color picker by
pressing and take a color probe from your image.
frame line color
Clicking on the colored field will open a color selector dialog which allows one to define
a color for the frame in HSL or PCB color space. You can also activate a color picker by
pressing and take a color probe from your image.
Examples
Example image with a user defined frame.
3.4.5.3.Splittoning
Overview
darktable's splittoning method creates a two color
linear toning effect where the shadows and high-
lights are represented by two different colors. ln the
example image below you can see an original black
and white image and one where a splittoning effect
is applied with blue in shadows and a yellowish color
in highlights.
92
Compared to traditional splittoning our module has more parameters to influence its be-
havior. We have parameter balance, which offsets the S0% gray level in your image - at
your choice - more to the shadows or more to the highlights. Additionally, with parameter
compression you can compress toning in the shadows and highlights and leave a gap in
the mid-tones, which remain untouched by the effect.
1he splittoning module does not convert images to black and white and has limited ben-
efits on color images. So, if you want to do traditional splittoning, use the monochrome
module (see Section3.4.3.6, Monochrome) to make the image black and white before
playing around with splittoning effect.
Usage
shadows and highlights color
1hese controls are used to set the color of the splittoning effect, you select the desired
color and saturation for both shadows and highlights, you can also click the color preview
box to bring up a common color picker dialog.
balance
1his parameter represents the ratio of toning between shadows and highlights. For a value
of S0% half of the lightness range in image is used for shadows toning and the other half
for highlights toning.
compression
Compression is a percentage of total lightness range that is not affected by color toning.
Default value is set to 33%, this is not the default behavior of an original splittoning which
would be 0% compression. 1he choice of 33% as a default is to invite you experimenting
with these parameters and how it extends the original splittoning method.
Examples
Original black and white image.
Splittoning with blue shadows and yellow highlights.
3.4.5.4.Vignetting
93
Overview
1his module is an artistic feature which creates vi-
gnetting (modification of the brightness/saturation
at the borders).
Usage
1he vignetting module has an extensive set of parameters to precisely tune its effect. lt
also will display graphical controls within the image if the module is in focus. Cive it a try
to get a feeling of how it works. On-screen controls and parameter sliders will stay in sync.
scale
Set the radius of the vignetting area.
fall-off strength
Sets the progressiveness of the fall-off. Higher values will cause a steeper transition.
brightness
Sets the intensity of brightening (positive values) or darkening (negative values).
saturation
Controls how strong colors become when desaturated or saturated in the darkened or
brightened vignetting area.
horizontal center
Shifts the center of the vignetting area horizontally.
vertical center
Shifts the center of the vignetting area vertically.
shape
lnfluences the shape of the vignetting area. 1he default value of 1 causes a circular or
elliptical area. Smaller values will shift the shape into a more square one, higher values
turn it into a cross-like shape.
automatic ratio
Click this button to automatically ad|ust the width/height ratio of the vignetting area to
the aspect ratio of the underlying image. 1he vignetting area will typically become ellip-
tical.
94
width/height ratio
Manually ad|ust the width/height ratio of the vignetting area.
dithering
With this combobox you can activate random noise dithering to overcome banding arti-
facts caused by vignette gradients. Select 8-bit output to prevent banding on monitor
display and for JPECs. When set to 16-bit output, only a little dithering will be applied,
|ust strong enough to compensate for banding on the fine grained 16-bit level. 1his fea-
ture is mostly obsoleted by our new module dithering (see Section3.4.4.9, Dithering).
Examples
An image with vignetting and with graphical vi-
gnetting controls displayed.
3.4.5.5.Soften
Overview
1his module is an artistic feature that creates a soft-
ened image, commonly known as the Orton effect.
Usage
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
those into a final image where the overexposed image was blurred.
1his module is almost a copy of Orton's analogue process into the digital domain. You
can control brightness and blur with the provided parameters, we also add a control for
saturation of the overexposured image for more play.
size
Set the size of blur of the overexposed image in the process, the bigger the softer.
saturation
Set the saturation of the overexposed image.
brightness
Expressed in [EVj, the brightness slider selects the increase in brightness.
9S
mix
Controls the mix of the overexposed image and the overall effect.
Examples
1his is the original image, use it as reference for the
changes below...
ln this image l used the default values, and added
0.33EV to brightness for a little more light in the soft
layer.
1his version is the same as above but with 2S% satu-
ration.
3.4.5.6.Grain
Overview
1his module is an artistic feature which simulates the
grain of a film.
Usage
1he grain is processed on the L channel from ClELAB.
coarseness
Set the grain size, which has been scaled to simulate an lSO number.
strength
Set the strength of the effect.
3.4.5.7.Highpass
96
Overview
Highpass acts as a high pass filter. 1he primary usage
for this filter is in combination with a blending op-
erator. 1ry out blend mode soft light to get high-
pass sharpening. Use the opacity slider to ad|ust the
strength of the effect or use a drawn mask (see Sec-
tion 3.2.6, Drawn mask) or parametric mask (see
Section3.2.7, Parametric mask) to limit the effect
to only parts of your image.
Usage
sharpen
Set the sharpness. 1he higher, the more details.
contrast boost
Set the contrast boost.
3.4.5.8.Lowpass
Overview
A lowpass filter (eg. gaussian blur) with additional
control of the outcome both of contrast and satura-
tion. 1he primary usage for lowpass filter is in com-
bination with a blending operator (see Section3.2.S,
Blending operators). 1ry out the preset named lo-
cal contrast mask with an overlay blending opera-
tion.
Usage
1his module offers enormous artistic potential, albeit, with results that are sometimes
difficult to predict.
radius
Set the radius of the blur.
soften with
1his combobox defines the blur algorithm, you can choose between gaussian blur (de-
fault) and bilateral filter. 1he latter leads to an edge preserving blur. gaussian will blur
all image channels: L, a and b. bilateral will only blur L channel.
contrast
Changes the contrast. Negative values result in an inverted negative image. Higher ab-
solute values increase contrast, lower absolute values reduce contrast. A value of zero
leads to a neutral plane.
brightness
Changes the brightness. Negative values result in a darker image. Positive values increase
the image's brightness.
97
saturation
Changes the color saturation. Negative values result in complementary colors by inverting
the a/b-channels. Higher absolute values increase color saturation, lower absolute values
reduce color saturation. A value of zero leads to a desaturated black&white image.
Examples
1he original image, already heavily processed. 1he
boat is almost a silhouette.
Bilateral blur with high radius. Desaturated, inverted
and with high contrast.
lntermediate result after lowpass filter ...
... and final image after this was applied with blend
mode "vividlight".
3.4.5.9.Low light
Overview
1he low light module allows one to simulate human
lowlight vision, thus providing ability to make low-
light pictures look closer to reality. lt can also be used
to perform a day to night conversion.
1he idea is to calculate a scotopic vision [http://
en.wikipedia.org/wiki/Scotopic_visionj image which
is perceived by rods rather than than cones in the eye
under low light. Scotopic lightness then is mixed with
photopic value (regular color image pixel) using some
blending function. Also this module is able to simu-
98
late the Purkin|e effect [http://en.wikipedia.org/wi-
ki/Purkin|e_effectj by adding some blueness to the
dark parts of the image.
Usage
1his module comes with several presets. Cive them a try to get a better feeling how it
works.
curve
1he horizontal axis is about pixel lightness from dark (left) to bright (right). 1he vertical
axis represents the kind of vision from night vision (bottom) to day vision (top)
blue
Set the blue hint in shadows (Purkin|e effect).
Examples
lmage 1. 1his is the original image.
lmage 1. With low light module on.
lmage 2. 1his is the original image.
lmage 2. With low light module on.
3.4.5.10.Bloom
99
Overview
1his module boost highlights and creates a soft
blooms them over the image, hence the name of the
effect. 1here are numerous ways to use this module
depending on the image's actual scenery lighting.
Usage
Starting from the default settings change the strength value for a pleasant look, then
change the size to control the spread of light.
size
Pepresents the spatial extent of the bloom effect.
threshold
Set the threshold for the increase in brightness.
strength
Set the strength of overlightning for the effect.
Examples
1his is the original image, use it as reference for the
changes below...
Here we have chosen to use a size of 10%, which is
a rather small radius for the soft light spread. We
boosted up the strength to S0% for a more exagger-
ated effect.
3.4.5.11.Colorize
Overview
1his module is an artistic feature that adds a solid lay-
er of color to your image.
Usage
Several parameters control the effect of this module. Much more versatility can be
reached if you apply blending and masks. (see Section3.2.4, Blending).
100
hue
Selects the hue of the color layer.
saturation
Selects the color saturation of shadow tones.
lightness
Selects the lightness of the color layer.
source mix
1his slider controls how the lightness of the input image is mixed in. lf you set this to zero
a uniformly colored plane will result.
3.4.5.12.Color mapping
Overview
1his module transfers the look and feel from one im-
age onto another. lt statistically analyses the color
characteristics of a source image and a target image.
1he colors of the source image are then mapped to
corresponding colors of the target image.
Usage
1o use this module two steps are required.
First you open the source image in darkroom mode and acquire its color characteristics by
pressing the acquire as source button. A set of color clusters is generated and displayed
in the source clusters area. Each cluster is represented by a set of color swatches with
the mean value in the center surrounded by swatches indicating the color variance within
that cluster. 1he clusters are sorted in ascending order by their weight, i.e. the number of
pixels that contribute to the clusters.
Next you open your target image in darkroom mode. darktable has remembered the pre-
viously collected source clusters, if they are not yet displayed, press the button. You
now press the acquire as target button to generate a corresponding set of color clusters
for your target image, which gets displayed in the target clusters area.
When both source and target clusters are collected an automatic color mapping is applied
to the target image. ln its default settings the overall effect is quite exaggerated. A set
of sliders gives you control of the effect's strength. You can also use blending operator
normal to tame the effect (see Section3.2.S, Blending operators). As the color map-
101
ping module comes early in the pixelpipe, you can finetune the colors with modules like
tone curve (see Section3.4.2.3, 1one curve) or color correction (see Section3.4.3.S, Col-
or correction).
acquire as source/target
Press these buttons to generate color clusters for the source and target image, respec-
tively. 1he processing takes a few seconds during which the CUl remains unresponsive.
number of clusters
Sets the number of color clusters to use. lf you change this parameter all collected color
clusters are reset and need to be acquired anew.
color dominance
1his parameter controls the mapping between source and target clusters. At the lowest
value mapping is based on color proximity. 1his typically leads to very subtle effects on
the target image. At the maximum value mapping is based on the relative weight of the
color clusters - dominant colors of the source image are mapped to dominant colors of the
target image. 1his typically leads to a very bold effect. ln-between values incrementally
shift between the extremes.
histogram equalization
Besides mapping of color characteristics this module can modify the target image's con-
trast by matching its histogram with the histogram of the source image. 1his slider con-
trols the extent of the effect.
Examples
1he source image taken shortly after sunset under
front lighting conditions.
1he target image taken in the afternoon with a part-
ly clouded sky. Our goal is to transfer the evening at-
mosphere of the source image.
1he target image with color mapping applied. A num-
ber of 2 clusters was used. color dominance is set to
100% for a bold but still credible effect. histogram
equalization is set to 80%.
102
3.4.5.13.Graduated Density
Overview
1his module aims at simulating a graduated density
filter, in order to correct exposure and color in a pro-
gressive manner.
Usage
1he module uses a gradient to modify the exposure and the color cast of the image in a
non-homogeneously manner.
density
Set the density of the filter in [evj. A low value underexposes slightly whereas a high value
creates a strong filter.
lt is expressed as [evj that is equivalent to f-stops. Lens filters are often referred as ND2,
ND4, ND8 and so on. Each time you add an [evj you double the ND. So ND2 is 1 ev, ND4 is 2
ev, and so on. You can also express it in optical density or transmittance. 1he table below
sums up the different approach for the most common filters:
ND [evj or f-stop absorbance transmittance
ND2 -1 0.3 S0%
ND4 -2 0.6 2S%
ND8 -3 0.9 12.S%
ND400 -9 2.7 0.19S%
compression
Set progressiveness of the gradient. A low value creates a smooth transition, whereas a
high value makes the transition abrupt.
hue
Set the hue to add a color cast to the gradient.
saturation
Set the saturation to add a color cast to the gradient.
position
You can set the position of the gradient directly on
the image by moving the white line. For fine tuning,
you can also use the rotation slider. Negative values
turn clockwise.
103
1lP: lf you know you intend to use the graduated density filter before actually making a
shot with your camera you might want to underexpose by one or two thirds of an f-stop
to make sure detail remains in the highlights. When all detail has truly been blown out
the graduated density filter cannot produce a pleasing results, this is a limitation that is
inherent to digital postprocessing. For instructions on how to intentionally underexpose,
please consult your camera's manual, look for exposure compensation.
Examples
Here is an example that shows various options of darktable's graduated density filter:
1his is the original image with a pretty overexposed
sky, use it as reference for the changes below...
And now we have added a neutral ND8 filter which
does a pretty good |ob on the image..
And at last, l added an orange colored filter rotating
it -180 degrees, applying it on water/trees for a more
artistic use of the filter.
darktable's graduated density filter is a powerful tool. Nevertheless, hardware filters have
some advantages over a pure software solution. With a physical CND filter you can in fact
reduce the dynamic range of your scene to make it better fit the limits of your camera
sensor.
ln this example a hardware CND filter (Hitech ND0.6,
soft edge) helped me to prevent over-exposure in
the sky and tree tops, while at the same time get-
ting a well exposed image of the ground. A rather dis-
turbing element is the decay of lightness in the tree
trunks from bottom to top.
darktable's graduated density filter together with
the parametric mask feature (see Section 3.2.7,
Parametric mask) comes in handy. We can add a
lightness gradient that is |ust inverted in relation to
the hardware filter. As we only want to compensate
the unnatural decay of lightness in the tree trunks,
we combine the module with a suited blend mask.
104
1he resulting image.
10S
3.5.Examples
3.5.1.Converting to black and white
3.5.1.1.Overview
Black and white conversion can be achieved in several
ways with darktable. lndeed, darktable comes with a
lot of modules, especially for color manipulation. ln
this manual, l will show you 4 ways to perform a black
and white conversion.
3.5.1.2.The obvious way: monochrome module
1o perform the conversion, |ust activate the monochrome module (Section3.4.3.6, Mono-
chrome). You can then simulate a color filter, by dragging the circle above the colours you
want to filter. Filter size can be modified thanks to wheel scrolling.
3.5.1.3.The simple way: color correction module
1o perform such conversion we use the color correction module (Section 3.4.3.S, Color
correction).
1. Activate the color correction module
2. Use the bottom slider to set saturation to zero
3.5.1.4.The artistic way: color zones module
1o perform the conversion we use the color zone module (Section3.4.3.7, Color zones).
1. Activate the colour zones module
2. By default, the first radio-buttons row is set to colorness whereas the second is set
to hue which means that color are selected according to their hue (horizontal scale)
and you can change for each hue its colorness (vertical scale). You simply need to set
all points to the minimum of the vertical scale to de-saturate every hue.
3. But now if you want, you can keep some hues a little bit saturated, so your image will be
all black and white but some hue. A classical use for portrait is to keep red hue saturated
in order to make the lips standing out.
You can also use presets that perform black and white conversion, keeping some hues
saturated.
3.5.1.5.The sophisticated way: channel mixer module
1o perform the conversion we use the channel mixer module (Section 3.4.3.2, Channel
mixer).
1. Activate the channel mixer module
2. Select the gray output channel
106
3. Set the proportion of each color, the sum having to equal 1 if you want to keep your
global lightness.
3.5.2.Cross-processing
3.5.2.1.Overview
Cross-processing is a analog processing technique
where slide film (normally developed thanks to an E6
solution) is processed in chemicals used for process-
ing print film (C41). 1he resulting images get skewed
colors usually a cyan hue and increased contrast and
saturation.
1he standard way for doing digital cross-processing is to use a channel curve tool but dark-
table lacks this tool for the moment and another way to accomodate the effect is used.
3.5.2.2.Procedure
1his procedure uses tone curve, channel mixer and splittoning modules.
1. lmage preparation
Prepare the image for the cross process steps by ad|usting the base settings such as
exposure, whitebalance etc. for a correctly looking image.
2. Boost contrast
Select the medium contrast curve preset for tone curve module (Section3.4.2.3, 1one
curve) to boost the overall contrast in the image. You might later return here to tune
the curve for better result.
3. Color cast
1his step changes the color cast as the base for the effect using the channel mixer mod-
ule (Section3.4.3.2, Channel mixer). You might later again return to this and finetune
the colorcast of the final result.
a. Enable the channel mixer module
b. Select blue channel and set blue color value to 0.8
c. Select red channel and change blue color value to 0.1
d. Select green channel and change blue color value to 0.1
4. Splittoning
We use splittoning (Section3.4.S.3, Splittoning) to add some more coloring to the re-
sult for cyan/blue shadows and yellow highlight.
a. Enable the splittoning module
b. Select a cyan/blue tone for shadows and set saturation around S0%
c. Select a yellow/orange tone for highlights and set saturation around 70%
107
d. Set compression to 10%
e. Use the balance slider to tune the splittoning effect. 1his differs on every image due
to it's exposure, motive etc.
3.5.3.Cyan toned image
3.5.3.1.Overview
Cyan is a nice color touchup for black and white im-
ages, this example guides you through how to make
this with darktable and how to control the tone. You
can choose any tone of your like for this tutorial...
3.5.3.2.Procedure
1his procedure uses tone curve, channel mixer and splittoning modules.
1. lmage preparation
Prepare the image for the cyan toned steps by ad|usting the base settings such as
exposure,black level, contrast etc. for a correctly looking image.
2. Black and white
Enable the monochrome module (Section 3.4.3.6, Monochrome) to make the image
black and white.
3. Add color tone
1his step selects the base tone of the image using channel mixer (Section3.4.3.2, Chan-
nel mixer), we are going for cyan tone but you can choose any tone that you like here.
a. Enable the channel mixer module
b. Select red channel destination and set red color value to 0.7
c. Select green channel destination and red color value to 1.1S
d. Select blue channel destination and red color value to 1.1S
As you notice we mix blue and green color to get a cyan tone, we substract 0.3 from
red channel and add them to blue and green.
4. Splittoning
1he result of previous step does also add a color cast on highlight that we actually want
to have white for a prettier result. We also want to add some blue color cast to the
shadows in order to emphasis them. Module splittoning (Section3.4.S.3, Splittoning)
can accomplish this.
a. Enable the splittoning module
108
b. Select a blue/cyan tone for shadows and set saturation around S0%
c. Set highlights saturation to zero, to remove saturation on highlights.
d. Set compression to zero
e. Use the balance slider to tune the effect, our example uses a balance of 70/30
109
Chapter4.Tethering
1he tethering view allows you to capture images directly into darktable from your con-
nected camera.
110
4.1.Overview
1o use the tethering feature you 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. lf that happens automatically, you will need to unmount/e|ect the
camera. 1his is required to unlock the camera so darktable can lock it for usage.
After the USB cable is connected, look at the import panel in lighttable mode (see Sec-
tion 2.3.1, lmport). lf your camera is not visible in this panel, click the scan devices
button and it will appear with two functions: import from camera and tethered shoot.
Click tethered shoot to enter the tethering mode.
darktable uses gphoto2 to interface with your camera. lf you have problems finding the
connected camera as described above, check the troubleshoot section in this chapter in
order to verify your camera has tethering support.
4.1.1.Tethering
ln the center view images are shown while you cap-
ture them. You can get an exposure by either us-
ing darktable's userinterface or manually triggering
a capture on your camera. lf you are using LiveView
it will be shown in darktable's center view.
When entering tethering view, a film roll will be created using the same structure as de-
fined when you import from the camera. Job code will be predefined as capture.
lf you want to group your captures into different film rolls, you should use the session
panel in right side. When entering a new name and pressing enter, a new film roll will be
created and captured images will go into this new film roll.
darktable provides some nifty tools to setup a capture in the user interface. You can setup
timelapse captures and brackets for HDP creations. 1he configuration is so dynamic that
you can create sequential capture of brackets - go figure... For more information read the
documentation about the capture panel and the examples in this chapter.
111
4.2.Tethering panels
1his section contains documentation for panels that are specific to the tethering view.
4.2.1.Session
A session is a sequence of exposures taken in tether-
ing mode and going into a single film roll. A new ses-
sion equals a new film roll. A film roll is created with
the same storage structure that is used when you im-
port images from camera into darktable.
lt's a bit awkward, but configuring this storage struc-
ture is done in the camera import dialog for now.
4.2.2.Live view
1his panel gives you control of your camera's live
view mode. Functionality such as focus setting, rota-
tion, adding guides and overlays are supported.
4.2.3.Camera settings
1he camera settings section allows you to set up a
capture |ob. 1his can include sequence, bracket and
delayed captures. You are also able to control other
camera settings such as focus mode, aperture, shut-
ter speed, lSO and white balance.
112
4.3.Examples
1his section contains examples of typical usages of tethering.
4.3.1.Studio setup with screening
1his is a pretty common use case. You have your studio and sub|ect 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 want, you can screen the image directly on your
computer monitor instead of using the camera LCD for validation.
1his workflow is efficient and effective, since you can immediately review your captures
instead of waiting until after the shoot when everyone is gone. lf you're shooting a model
this is a pretty nice way to pre-view the captures with the client instead of fumbling around
with your camera.
Working in the tethered mode can save you time and aggravation. Set a session name,
shoot your images and they will save in the correct film roll for the session for easy on-
site review.
4.3.2.Capturing a timelapse
A timelapse is a video clip composed of images taken in a time sequence. A typical example
is to take a timelapse of cityscapes where you capture clouds and traffic etc.
1o setup a timelapse capture, create a new session as described previously. Now decide if
you want to shoot in manual or auto mode. Only use auto in situations were the ambient
light will change significantly during the time of the shoot, eg. shooting a timelapse over
24 hours might give you easier control of light in that kind of captured sequence.
1he camera settings panel is where you define delay and sequence. Sequence will give you
the opportunity to choose how many images you want to capture and delay will set the
time in seconds between captures.
1o start the capture click the capture button in the same panel and watch the filmstrip fill
up with images. 1he latest captured image is always displayed in center view.
113
4.4.Troubleshoot
4.4.1.Verify that your camera is supported
1his troubleshooting guide will give you steps to verify your camera can be used with
tethering. 1his is done using the gphoto2 commandline tools. 1his is what darktable uses
to interface with your camera.
1. Verify that camera is detected
1he following command will verify a camera that is connected to the computer and
detected by gphoto2. Find your camera port name to use it in the following tests below.
Usually port usb: will be enough and therefore used in these examples.
env LANG=C gphoto2 --auto-detect

2. Verify camera driver abilities
Execute the following command and verify that the capture choices ability supports
lmage and configuration support is yes. darktable will check these two abilities and
decide if tethered shoot button should be shown or not.
env LANG=C gphoto2 --port usb: --abilities

3. Verify camera remote capture
1his step will verify that your camera can be remotely controlled, that it can capture an
image, download it to your computer and display it within darktable.
env LANG=C gphoto2 --port usb: --capture-image-and-download

4. Verify camera tethered capture
And this last step tests if your camera supports events which darktable heavily relies
on. Punning this command will make the gphoto2 process wait for an image capture
event which you must manually trigger on your camera. lf successful, the image will be
downloaded to your computer.
env LANG=C gphoto2 --port usb: --capture-tethered

4.4.2.So, now what?
lf any of the steps above failed, there are problems with your specific camera and driver.
Please report the issues to gphoto2 mailing list for further help. You can find the mailing
list at www.gphoto.org [http://www.gphoto.org/mailinglists/j. Add the following flags to
the failed command above for better support and attach the log output to your mail:
--debug --debug-file gphoto2_debug.log
114

lf you successfully went through all the tests above, your camera will most likely be sup-
ported by darktable. Even if successful, if you stumble upon a problem in darktable, please
file a bug at redmine [http://www.darktable.org/redminej. Please attach the log outputs
from the steps above and the log file output generated after starting darktable with the
following command.
darktable -d camctl 2>1 >camctl.log

11S
Chapter5.Map
1he Map view is were you geotag your images.
116
5.1.Overview
Map view will show you a world map with the currently open image, or film roll of images,
pinned to their geotagged location. 1his requires that the image was geotagged by a cam-
era with that feature. Some newer cameras, including smartphones, are already equipped
with CPS receivers. Other cameras may need additional CPS hardware to do this.
Even if your camera doesn't support this feature, there is an alternative method. darktable
can match the EXlF time and date data in your image(s) to a separate CPX data tracking
file created by a CPS tracker recording your movements. 1hese can be handheld devices
or a CPS tracker app on your smartphone. 1his is all done in the lighttable view (see Sec-
tion2.3.9, Ceotagging).
5.1.1.Center map view
ln the center of the map view you will see a map.
Map data are taken from open map sources on the internet. New map data are only avail-
able if you are connected to the internet. darktable keeps a disk cache of previously loaded
map data.
Your mouse will allow navigation in the map. Left-click will drag the map, using the scroll-
wheel will zoom in or out.
1here are on-screen controls and displays that assist you to find your way. A navigation
area is located on top left of the map. Use it as an alternative to mouse-dragging and
scrolling. 1he scale of your map is displayed on bottom left. On bottom right you see the
geographical coordinates for the center of the map.
lmages that already have geo location attributes in their metadata are displayed as small
icons on the map.
ln order to assign geo coordinates to an image, activate the film-strip on the lower panel
(press Ctrl-f). You can simply assign a geo location to an image by dragging the image icon
from the film-strip and position it onto the map. darktable will record the new geo location
(longitude and latitude) as part of the image metadata. Exported images will include this
data.
ln order to remove geo coordinates from an image |ust drag it from the map and drop it
onto the filmstrip.
Left and right to the central map there are panels for additional control.
117
5.2.Map panels
1his section contains documentation for panels that are specific to the map view.
5.2.1.Left panels
1he panels on the left side we already know from
lighttable mode (Section2.3, Lighttable panels).
Choose your image selection rules with the collect im-
ages panel. Pecently used collections can be chosen
with their respective names in a separate panel. You
can also get an overview of the information of the im-
age under your mouse cursor in a panel labeled im-
age information.
5.2.2.Find location
1he find location module is used to search for a place
on map. You need to be connected to the internet to
use this feature.
1o use, type in a place or address, press enter and a
list of results will be shown. Click on one of the re-
sulting items and the map will zoom to that location.
Now drag images from the film strip at the bottom
of the screen to their location on the map. 1he CPS
location will be embedded in the image.
5.2.3.Map settings
ln the map settings panel you can select your pre-
ferred map data from various providers. Some will
provide different layers, such as satellite view etc.,
which you can toggle.
5.2.4.Tagging
1he tagging panel allows you to attach or detach dif-
ferent tags to an image as well as creating or delet-
ing a tag. lt is divided into two parts. 1he upper part
contains tags that are currently attached to the im-
age. 1he lower part contains all available tags. You
must select or mouse over an image for the data to
be displayed. See Section2.3.11, 1agging for more
details.
118
119
Chapter6.Preferences and settings
darktable comes with a number of settings that can be configured by users. You reach the
configuration menu by clicking at the top of the screen.
120
6.1.GUI options
1hese options control the look and feel of darktable.
width of the side panels in pixels
1his controls the size of side panels in pixels. Side panels are found left and right to the
center view (default 300).
don't use embedded preview jpeg but half-size raw
Check this option to not use the embedded |peg from the raw file but process the raw
data. 1his is slower but gives you color managed thumbnails (default off).
ask before removing images from database
Always ask the user before any image is removed from the database (default on).
ask before erasing images from disk
Always ask the user before any image file is deleted (default on).
ask before moving images from film roll folder
Always ask the user before any image file is moved (default on).
ask before copying images to new film roll folder
Always ask the user before any image file is copied (default on).
number of folder levels to show in lists
1he number of folder levels to show in film roll names, starting from the right (default 1).
ignore jpeg images when importing film rolls
When having PAW+JPEC images together in one directory it makes no sense to import
both. With this flag one can ignore all |pegs found (default off).
recursive directory traversal when importing film rolls
Not only import images from the directory selected but recursively go through all subdi-
rectories as well (default off).
creator to be applied when importing
lf provided, automatically add this string as a creator tag when importing images (default
none).
publisher to be applied when importing
lf provided, automatically add this string as a publisher tag when importing images (de-
fault none).
rights to be applied when importing
lf provided, automatically add this string as a copyrights tag when importing images (de-
fault none).
121
comma separated tags to be applied when importing
lf you want to add further tags when importing images, you can give them as a comma
separated list (default none).
initial import rating
lnitial star rating (from 0 to S) for all images when importing a film roll (default 1).
indicate focus regions
lf enabled an overlay indicating image sharpness is displayed in full screen preview in light-
table mode (z-option, see Section2.1, Overview). Very sharp areas are indicated in red,
slightly less sharp areas in blue (default off).
enable filmstrip
Enable the filmstrip in darkroom, tethering and geomapping modes (default on).
maximum width of image drawing area
Maximum width of the image drawing area in darkroom mode - ad|ust to your screen.
Needs a restart and will invalidate current thumbnail caches (default 1300).
maximum height of image drawing area
Maximum height of the image drawing area in darkroom mode - ad|ust to your screen.
Needs a restart and will invalidate current thumbnail caches (default 1000).
compression of thumbnail images
Controls the compression of thumbnail images in memory and on disk. Options: off, low
quality (fast), high quality (slow), (default off).
pen pressure control for brush masks
Controls how the pressure reading of a graphics tablet impacts newly generated brush
strokes (see Section3.2.6, Drawn mask). You can control the brush width, its hardness
and its opacity. Absolute control means that the pressure reading directly defines the
attribute with a value between 0% and 100%. Pelative means that the pressure reading
ad|usts the attribute between zero and the pre-defined default value (default off).
ask before deleting a tag
Always ask user before deleting a tag from an image (default on).
maximum number of images drawn on map
1he maximum number of geotagged images drawn on the map. lncreasing this number
can slow down the drawing of the map. Needs a restart if changed (default 100).
pretty print the image location
Show a more readable representation of the geo location in the image information mod-
ule (default on).
expand a single lighttable module at a time
Controls how lighttable panels are expanded. lf this option is enabled, expanding a panel
by clicking collapses any currently expanded panel. lf you want to expand a panel without
122
collapsing the others you do so with shift+click. Disabling this option reverts the meaning
of click and shift+click (default off).
expand a single darkroom module at a time
Controls how darkroom modules are expanded. lf this option is enabled, expanding a mod-
ule by clicking collapses any currently expanded module. lf you want to expand a module
without collapsing the others you do so with shift+click. Disabling this option reverts the
meaning of click and shift+click (default on).
method to use for getting the display profile
1his option allows to force a specific means of getting the current display profile in the
output color profile module (see Section 3.4.3.3, Output color profile). ln the default
setting all darktable will either 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
alternative gives wrong results.
123
6.2.Core options
1hese options control some of the internals of darktable.
memory in megabytes to use for mipmap cache
On order to speed-up display of film rolls, darktable stores thumbnails in a cache on disk
and loads it into memory at startup. 1his value controls the cache size in megabytes. lt
needs a restart if changed (default S12MB).
number of background threads
1his controls how many parallel threads are used to create thumbnails during import. On
32bit systems it is strongly recommended to set this to 1. Needs a restart if changed (de-
fault 2).
host memory limit (in MB) for tiling
ln order to manage large images on systems with limited memory darktable does tile-wise
processing. 1his variable controls the maximum amount of memory (in MB) a module may
use during image processing. Lower values will force memory hungry modules to process
an image with increasing number of tiles. Setting this to 0 will omit any limits. Values below
S00 will be treated as S00. On a 32bit system you should set this to S00. Needs a restart
if changed (default 1S00).
minimum amount of memory (in MB) for a single buffer in tiling
lf set to a positive, non-zero value, this variable defines the minimum amount of memory
(in MB) that darktable should take for a single tile. On a 32bit system you should set this
to 8. 64bit systems can live with higher values. Needs a restart if changed (default 16).
write sidecar file for each image
1hese redundant XMP files can later be re-imported into a different database, preserving
your changes to the image. lt's strongly recommended to have this option activated so
you don't lose data in case of a database corruption. Backing up your PAW file plus the
accompanying XMP file will allow you to fully restore your work (default on).
store xmp tags in compressed format
Entries in XMP tags can get rather large and may exceed the available space to store the
history stack in output files. 1his option allows binary XMP tags to be compressed in order
to save space. Available options are never, always, and only large entries (default).
activate opencl support
darktable can use your CPU to speed up processing significantly. lnterface OpenCL re-
quires suitable hardware and matching OpenCL drivers on your system. lf one of those
is not found the option is greyed out. Can be switched on and off at any time and takes
immediate effect (default on).
always try to use littlecms2
lf this option is activated, darktable will use system library littlecms2 instead of its own
routines. 1his is about 28x slower than the default but might give more accurate results
in some cases (default off).
124
do high quality resampling during export
1he image will first be processed in full resolution, and downscaled at the very end. 1his
can result in better quality sometimes, but will always be slower (default off).
demosaicing for zoomed out darkroom mode
lnterpolation when not viewing 1:1 in darkroom mode: always bilinear (fast) is fastest,
but not as sharp. at most ppg (reasonable) is using ppg + interpolation modes specified
below, full (possibly slow) will use exactly the settings for full-size export (default at
most ppg (reasonable)).
pixel interpolator
Pixel interpolator used in rotation, lens correction, up- and downscaling, options are bi-
linear, bicubic, lanczos2, lanczos3 (default).
password storage backend to use
1he storage backend for password storage. Options: none, kwallet, gnome keyring
(default none).
12S
6.3.Shortcuts
darktable has a large set of keyboard shortcuts that, with the work of Pobert Bieber, is
now user configurable through the preference pane.
When you open the shortcuts menu you are presented with a hierarchical list of all actions
that can receive a keyboard shortcut. Co to the action you want to change and double click.
You are then prompted to press the new key combination to be mapped to the selected
action. ln order to remove an existing keyboard shortcut, click on the action and press
backspace.
You can export your mappings to a file or import mappings from a file. Press default to
reset all keyaccelerators to their default state.
Below is a table with the default keybindings for actions available in darktable.
<darktable>/global/lighttable view l
<darktable>/global/darkroom view d
<darktable>/global/capture view t
<darktable>/global/map view m
<darktable>/global/increase brightness F10
<darktable>/global/decrease brightness F9
<darktable>/global/increase contrast F8
<darktable>/global/decrease contrast F7
<darktable>/global/leave fullscreen Escape
<darktable>/global/quit <Primary>q
<darktable>/global/switch view period
<darktable>/global/toggle fullscreen F11
<darktable>/global/toggle header <Primary>h
<darktable>/global/toggle side borders 1ab
<darktable>/views/lighttable/color red F1
<darktable>/views/lighttable/color yellow F2
<darktable>/views/lighttable/color green F3
<darktable>/views/lighttable/color blue F4
<darktable>/views/lighttable/color purple FS
<darktable>/views/lighttable/navigate down <Shift>g
<darktable>/views/lighttable/navigate page down Page_Down
<darktable>/views/lighttable/navigate page up Page_Up
<darktable>/views/lighttable/navigate up g
<darktable>/views/lighttable/preview z
<darktable>/views/lighttable/rate 1 1
<darktable>/views/lighttable/rate 2 2
<darktable>/views/lighttable/rate 3 3
<darktable>/views/lighttable/rate 4 4
<darktable>/views/lighttable/rate S S
<darktable>/views/lighttable/rate desert 0
126
<darktable>/views/lighttable/rate re|ect r
<darktable>/views/lighttable/realign images to grid l
<darktable>/views/lighttable/scroll center apostrophe
<darktable>/views/lighttable/scroll down Down
<darktable>/views/lighttable/scroll left Left
<darktable>/views/lighttable/scroll right Pight
<darktable>/views/lighttable/scroll up Up
<darktable>/views/darkroom/export <Primary>e
<darktable>/views/darkroom/image forward space
<darktable>/views/darkroom/image back BackSpace
<darktable>/views/darkroom/overexposed o
<darktable>/views/darkroom/toggle film strip <Primary>f
<darktable>/views/darkroom/zoom close-up <Alt>1
<darktable>/views/darkroom/zoom fill <Alt>2
<darktable>/views/darkroom/zoom fit <Alt>3
<darktable>/views/map/redo <Primary>r
<darktable>/views/map/undo <Primary>z
<darktable>/views/capture/toggle film strip <Primary>f
<darktable>/modules/copy_history/copy all <Primary>c
<darktable>/modules/copy_history/copy <Primary><Shift>c
<darktable>/modules/copy_history/paste all <Primary>v
<darktable>/modules/copy_history/paste <Primary><Shift>v
<darktable>/modules/export/export <Primary>e
<darktable>/modules/filmstrip/color red F1
<darktable>/modules/filmstrip/color yellow F2
<darktable>/modules/filmstrip/color green F3
<darktable>/modules/filmstrip/color blue F4
<darktable>/modules/filmstrip/color purple FS
<darktable>/modules/filmstrip/duplicate image <Primary>d
<darktable>/modules/filmstrip/copy history parts <Primary><Shift>c
<darktable>/modules/filmstrip/copy history <Primary>c
<darktable>/modules/filmstrip/paste history parts <Primary><Shift>v
<darktable>/modules/filmstrip/paste history <Primary>v
<darktable>/modules/filmstrip/rate 1 1
<darktable>/modules/filmstrip/rate 2 2
<darktable>/modules/filmstrip/rate 3 3
<darktable>/modules/filmstrip/rate 4 4
<darktable>/modules/filmstrip/rate S S
<darktable>/modules/filmstrip/rate desert 0
<darktable>/modules/filmstrip/rate re|ect r
<darktable>/modules/image/group <Primary>g
127
<darktable>/modules/image/ungroup <Primary><Shift>g
<darktable>/modules/image/remove from collection Delete
<darktable>/modules/lighttable_mode/zoom max <Alt>1
<darktable>/modules/lighttable_mode/zoom in <Alt>2
<darktable>/modules/lighttable_mode/zoom out <Alt>3
<darktable>/modules/lighttable_mode/zoom min <Alt>4
<darktable>/modules/live_view/toggle live view v
<darktable>/modules/select/select all <Primary>a
<darktable>/modules/select/invert selection <Primary>i
<darktable>/modules/select/select none <Primary><Shift>a
<darktable>/modules/tagging/tag <Primary>t
<darktable>/image operations/clipping/commit Peturn
<darktable>/image operations/colorout/toggle gamutcheck g
<darktable>/image operations/colorout/toggle softproofing s
<darktable>/image operations/flip/rotate 90 degrees ccw bracketleft
<darktable>/image operations/flip/rotate 90 degrees cw bracketright
128
6.4.Presets
1his menu gives you an overview of the presets that are defined for darktable's modules.
ln this dialog you can select whether a certain user defined preset shall be auto-applied
to matching images.
darktable already comes with a set of pre-defined presets for several modules. ln addi-
tion you can define your own presets from within each module in darkroom mode (see
Section3.2.2, Module presets).
Pre-defined presets are shown with a lock symbol. 1heir auto-apply properties can not be
changed.
Double clicking on a user-defined preset will open a menu.
auto apply this preset to matching images
activate this checkbutton to automatically apply the preset on newly imported images, a
set of fields is displayed where you can define patterns to be matched against EXlF data.
only show this preset for matching images
activate this checkbutton to hide the preset in darkroom mode if it does not match the
defined patterns.
model
a pattern to be matched against the EXlF field that describes your camera model, use "%"
as wildcard.
maker
a pattern to be matched against the EXlF field that describes the maker of your camera,
use "%" as wildcard.
lens
a pattern to be matched against the EXlF field that describes your lens, use "%" as wild-
card.
iso
only apply the preset if the lSO value of your image lies within the given range.
129
exposure
only apply the preset if the exposure time of your image lies within the given range, set
"+" as the upper value to match arbitrarily long exposures.
aperture
only apply the preset if the aperture of your image lies within the given range, set "f/0" as
the lower value to match arbitrarily open apertures, set "f/+" as the upper value to match
arbitrarily closed apertures.
focal length
only apply the preset if the focal length of your image lies within the given range (from
0 to 1000).
130
131
Chapter7.Scripting with Lua
darktable comes with a versatile scripting interface for functionality enhancement.
132
7.1.Lua usage
Lua can be used to define actions which darktable should perform whenever a specified
event is triggered. One example might be calling an external application during file export
in order to apply additional processing steps outside of darktable.
darktable uses Lua [http://www.lua.org/j, which is an independent pro|ect founded in
1993, providing a powerful, fast, lightweight, embeddable scripting language. Lua is wide-
ly used by many open source applications, in commercial programs, and for games pro-
gramming.
darktable uses Lua version S.2. Describing the principles and syntax of Lua is beyond
the scope of this usermanual. For a detailed introduction see the Lua reference manual
[http://www.lua.org/manual/S.2/manual.htmlj.
7.1.1.A note about beta
darktable's Lua APl is still in a beta phase of development. 1his has multiple implications
you should be aware of when writing Lua code:
1he APl might change without notice. ln particular if we find out that the APl is not
practical.
1he APl is incomplete. lf you find something missing please report on lPC, in the mailing
list, or open a feature request.
darktable's Lua APl is for lighttable functions. Our goal is to be able to do with Lua
everything that can be done in the lighttable, but anything that can only be done in
darkroom mode is off-limit.
7.1.2.Basic principles
At startup, darktable will automatically run two Lua scripts:
a script called luarc in $DARKTABLE/share/darktable
a script called luarc in the user's configuration directory
SDAPK1ABLE is used here to represent your system's darktable installation directory.
1his is the only time darktable will run Lua scripts by itself. Scripts can register callbacks
to perform actions. See the corresponding section in Section7.2, Lua APl.
7.1.3.Handling scripts
darktable will look for Lua modules in the system provided Lua path, but it will also look
into the following places:
S(CONFlC_DlP)/lua/!.lua
S(USEP_DlP)/lua/!.lua
ln other word, if you place a file called c.lua in the directory ~/.config/darktable/lua/a/b/
then @require "a.b.c" will find your script. 1he normal way to install a script is to place
it in ~/.config/darktable/lua/ then add a require line to the file ~/.config/darktable/luarc.
7.1.4.Yielding from Lua code
Lua employs a cooperative multitasking concept. Without further action a Lua thread (e.g.
a routine that is triggered by a certain event) continues to run till the end - effectively
133
blocking other Lua threads from being executed in the meantime. 1his behavior can only
be changed if the first Lua thread voluntarily and temporarily gives back control to the
system, thus allowing other Lua threads to be run in parallel. 1his is accomplished by the
yield() call.
lt is important to yield whenever you have some code that you expect to block other Lua
code from being executed. ln particular you should always yield when calling an external
program from Lua - especially if it is a long, time consuming task.
134
7.2.Lua API
1o access the darktable specific functions you must load the darktable environement:
darktable = require "darktable"
All functions and data are accessed through the darktable module.
1his documentation was generated with darktable version 1.3+147S~gb837db7.
7.2.1.darktable
1he darktable library is the main entry point for all access to the darktable internals.
7.2.1.1.darktable.print
function(message)
Will print a string to the darktable control log (the long overlayed window that appears
over the main panel).
message string
1he string to display which should be a single line.
7.2.1.2.darktable.print_error
function(message)
1his function will print its parameter if the Lua logdomain is activated. Start darktable
with the "-d lua" command line option to enable the Lua logdomain.
message string
1he string to display.
7.2.1.3.darktable.register_event
function(event_type,callback,...)
1his function registers a callback to be called when a given event happens.
Events are documented in the event section.
event_type string
1he name of the event to register to.
callback function
1he function to call on event. 1he signature of the function depends on
the type of event.
... variable
Some events need extra parameters at registraion time, these must be
specified here.
13S
7.2.1.4.darktable.register_storage
function(plugin_name,name,[store],[finalize],[supported])
1his function will add a new storage implemented in Lua.
A storage is a module that is responsible for handling images once they have been gener-
ated during export. Examples of core storages include filesystem, e-mail, facebook...
plugin_name string
A Unique name for the plugin.
name string
A human readable name for the plugin.
store function(storage,image,format,filename,number,total,
high_quality,extra_data)
1his function is called once for each exported image. lmages can be ex-
ported in parallel but the calls to this function will be serialized.
storage types.dt_imageio_module_storage
1he storage ob|ect used for the export.
image types.dt_lua_image_t
1he exported image ob|ect.
format types.dt_imageio_module_format
1he format ob|ect used for the export.
filename string
1he name of a temporary file where the processed im-
age is stored.
number integer
1he number of the image out of the export series.
total integer
1he total number of images in the export series.
high_quality boolean
1rue if the export is high quality.
extra_data table
An empty Lua table to take extra data. 1his table is
common to all calls to store and the call to finalize in
a given export series.
finalize function(storage,image_table,extra_data)
136
1his function is called once all images are processed and all store calls
are finished.
storage types.dt_imageio_module_storage
1he storage ob|ect used for the export.
image_table table
A table keyed by the exported image ob|ects and valued
with the corresponding temporary export filename.
extra_data table
An empty Lua table to store extra data. 1his table is com-
mon to all calls to store and the call to finalize in a given
export series.
supported function(storage,format):boolean
A function called to check if a given image format is supported by the Lua
storage, this is used to build the dropdown format list for the CUl.
Nate that the parameters in the format are the ones currently set in the
CUl, the user might change them before export.
storage types.dt_imageio_module_storage
1he storage ob|ect tested.
format types.dt_imageio_module_format
1he format ob|ect to report about.
return boolean
1rue if the corresponding format is supported.
7.2.1.5.darktable.films
A table containing all the film ob|ects in the database.
Attributes: has_ipairs, has_length, has_pairs
darktable.films.#
types.dt_lua_film_t
Each film has a numeric entry in the database.
7.2.1.6.darktable.gui
1his subtable contains function and data to manipulate the darktable user interface with
Lua.
Most of these function won't do anything if the CUl is not enabled (i.e you are using the
command line version darktabl-cli instead of darktable).
137
Attributes: has_pairs
darktable.gui.action_images
table
A table of images on which the user expects us to act.
lt is based on both the hovered image and the selection and is
consistent with the way darktable works.
lt is recommended to use this table to implement Lua actions rather than dt.gui.hovered
or dt.gui.selected to be consistant with darktable's CUl.
darktable.gui.hovered
1he image under the cursor or nil if no image is hovered.
darktable.gui.selection
function([selection]):table
Allows to change the set of selected images.
Attributes: implicit_yield
selection table
A table of images which will define the selected images. lf this parameter
is not given the selection will be untouched. lf an empty table is given the
selection will be emptied.
return table
A table containing the selection as it was before the function was called.
7.2.1.7.darktable.tags
Allows access to all existing tags.
Attributes: has_ipairs, has_length, has_pairs
darktable.tags.#
types.dt_lua_tag_t
Each existing tag has a numeric entry in the tags table - use ipairs to iterate over them.
darktable.tags.create
function(name)
Creates a new tag and return it. lf the tag exists return the existing tag.
name string
1he name of the new tag.
138
darktable.tags.find
function(name):types.dt_lua_tag_t
Peturns the tag ob|ect or nil if the tag doesn't exist.
name string
1he name of the tag to find.
return types.dt_lua_tag_t
1he tag ob|ect or nil.
darktable.tags.delete
function(tag)
Deletes the tag ob|ect, detaching it from all images.
tag types.dt_lua_tag_t
1he tag to be deleted.
darktable.tags.attach
function(tag,image)
Attach a tag to an image, the order of the parameters can be reversed.
tag types.dt_lua_tag_t
1he tag to be attached.
image types.dt_lua_image_t
1he image to attach the tag to.
darktable.tags.detach
function(tag,image)
Detach a tag from an image, the order of the parameters can be reversed.
tag types.dt_lua_tag_t
1he tag to be detached.
image types.dt_lua_image_t
1he image to detach the tag from.
darktable.tags.get_tags
function(image):table
Cets all tags attached to an image.
image types.dt_lua_image_t
139
1he image to get the tags from.
return table
A table of tags that are attached to the image.
7.2.1.8.darktable.configuration
table
1his table regroups values that describe details of the configuration of darktable.
darktable.configuration.version
string
1he version number of darktable.
darktable.configuration.has_gui
boolean
1rue if darktable has a CUl (launched through the main darktable command, not dark-
table-cli).
darktable.configuration.verbose
boolean
1rue if the Lua logdomain is enabled.
darktable.configuration.tmp_dir
string
1he name of the directory where darktable will store temporary files.
darktable.configuration.config_dir
string
1he name of the directory where darktable will find its global configuration ob|ects (mod-
ules).
darktable.configuration.cache_dir
string
1he name of the directory where darktable will store its mipmaps.
7.2.1.9.darktable.preferences
table
Lua allows you do manipulate preferences. Lua has its own namespace for preferences
and you can't access nor write normal darktable preferences.
140
Preference handling functions take a _script_ parameter. 1his is a string used to avoid
name collision in preferences (i.e namespace). Set it to something unique, usually the
name of the script handling the preference.
Preference handling functions can't guess the type of a parameter. You must pass the type
of the preference you are handling. Allowed values are the following strings
* string
* bool
* integer
darktable.preferences.register
function(script,name,type,label,tooltip,[default],[min],[max])
Creates a new preference entry in the Lua tab of the preference screen. lf this function
is not called the preference can't be set by the user (you can still read and write invisible
preferences).
script string
lnvisible prefix to guarantee unicity of preferences.
name string
A unique name used with the script part to identify the preference.
type string
1he type of the preference - one of the string values described above.
label string
1he label displayed in the preference screen.
tooltip string
1he tooltip to display in the preference menue.
default depends on type
Default value to use when not set explicitely or by the user.
min int
Minimum value (integer preferences only).
max int
Maximum value (integer preferences only).
darktable.preferences.read
function(script,name,type):depends on type
Peads a value from a Lua preference.
141
script string
lnvisible prefix to guarantee unicity of preferences.
name string
1he name of the preference displayed in the preference screen.
type string
1he type of the preference - one of the string values described above.
return depends on type
1he value of the preference.
darktable.preferences.write
function(script,name,type,value)
Writes a value to a Lua preference.
script string
lnvisible prefix to guarantee unicity of preferences.
name string
1he name of the preference displayed in the preference screen.
type string
1he type of the preference - one of the string values described above.
value depends on type
1he value to set the preference to.
7.2.1.10.darktable.styles
1his pseude table allows you to access and manipulate styles.
Attributes: has_ipairs, has_length, has_pairs
darktable.styles.#
types.dt_style_t
Each existing style has a numeric index, you can iterate them using ipairs.
darktable.styles.create
function(image,name,description):types.dt_style_t
Create a new style based on an image.
image types.dt_lua_image_t
1he image to create the style from.
142
name string
1he name to give to the new style.
description string
1he description of the new style.
return types.dt_style_t
1he new style ob|ect.
darktable.styles.delete
function(style)
Deletes an existing style.
style types.dt_style_t
the style to delete
darktable.styles.duplicate
function(style,name,description):types.dt_style_t
Create a new style based on an existing style.
style types.dt_style_t
1he style to base the new style on.
name string
1he new style's name.
description string
1he new style's description.
return types.dt_style_t
1he new style ob|ect.
darktable.styles.apply
function(style,image)
Apply a style to an image. 1he order of parameters can be inverted.
style types.dt_style_t
1he style to use.
image types.dt_lua_image_t
1he image to apply the style to.
7.2.1.11.darktable.database
143
Allows to access the database of images. Note that duplicate images (images with the
same PAW but different XMP) will appear multiple times with different duplicate indexes.
Also note that all images are here. 1his table is not influenced by any CUl filtering (collec-
tions, stars etc...).
Attributes: has_ipairs, has_length, has_pairs
darktable.database.#
types.dt_lua_image_t
Each image in the database appears with a numerical index, you can interate them using
ipairs.
darktable.database.duplicate
function(image):types.dt_lua_image_t
Creates a duplicate of an image and returns it.
image types.dt_lua_image_t
the image to duplicate
return types.dt_lua_image_t
1he created image if an image is imported or the toplevel film ob|ect if a film
was imported.
darktable.database.import
function(location)
lmports new images into the database.
location string
1he filename or directory to import images from.
NO1E: lf the images are set to be imported recursively in preferences only
the toplevel film is returned (the one whose path was given as a parameter).
NO1E2: lf the parameter is a directory the call is non-blocking, the film ob|ect
will not have the newly imported images yet. Use a post-import-film filtering
on that film to react when images are actually imported.
7.2.1.12.darktable.modules
table
1his table describe the different loadable modules of darktable.
darktable.modules.format
Functions to get parameter ob|ects for the different export formats.
144
Attributes: has_pairs
darktable.modules.format.png
function():types.dt_imageio_module_format_data_png
Used to get a new png format ob|ect.
return types.dt_imageio_module_format_data_png
A new format ob|ect describing the parameters to export to png - initialised to
the values contained in the CUl.
darktable.modules.format.tiff
see darktable.modules.format.png
darktable.modules.format.exr
see darktable.modules.format.png
darktable.modules.format.copy
see darktable.modules.format.png
darktable.modules.format.pfm
see darktable.modules.format.png
darktable.modules.format.jpeg
see darktable.modules.format.png
darktable.modules.format.ppm
see darktable.modules.format.png
darktable.modules.format.webp
see darktable.modules.format.png
darktable.modules.format.j2k
see darktable.modules.format.png
darktable.modules.storage
Functions to get parameter ob|ects for the different export storages.
New values may appear in this table if new storages are registered using Lua.
Attributes: has_pairs
darktable.modules.storage.email
function():types.dt_imageio_module_storage
Used to get a new email storage ob|ect.
return types.dt_imageio_module_storage
A new storage ob|ect describing the parameters to export with - initialised to
the values contained in the CUl.
darktable.modules.storage.latex
see darktable.modules.storage.email
darktable.modules.storage.disk
14S
see darktable.modules.storage.email
darktable.modules.storage.gallery
see darktable.modules.storage.email
darktable.modules.storage.flickr
see darktable.modules.storage.email
darktable.modules.storage.facebook
see darktable.modules.storage.email
darktable.modules.storage.picasa
see darktable.modules.storage.email
7.2.1.13.darktable.debug
table
1his section must be activated separately by calling
require "darktable.debug"
darktable.debug.dump
function(object,[name]):string
1his will return a string describing everything Lua knows about an ob|ect, used to know
what an ob|ect is.
1his function is recursion-safe and can be used to dump _C if needed.
ob|ect anything
1he ob|ect to dump.
name string
A name to use for the ob|ect.
return string
A string containing a text description of the ob|ect - can be very long.
darktable.debug.debug
boolean
lnitialized to false, set it to true to also dump information about metatables.
darktable.debug.type
function(object):string
Similar to the system function type() but it will return the real type instead of "userdata"
for darktable specific ob|ects.
ob|ect anything
146
1he ob|ect whos type must be reported.
return string
A string describing the type of the ob|ect.
7.2.2.types
1his section documents types that are specific to darktable's Lua APl.
7.2.2.1.types.dt_imageio_module_storage_data_email
dt_type
1BSL, force first
Attributes: has_pairs
types.dt_imageio_module_storage_data_email.plugin_name
see types.dt_imageio_module_storage.plugin_name
types.dt_imageio_module_storage_data_email.name
see types.dt_imageio_module_storage.name
types.dt_imageio_module_storage_data_email.width
see types.dt_imageio_module_storage.width
types.dt_imageio_module_storage_data_email.height
see types.dt_imageio_module_storage.height
types.dt_imageio_module_storage_data_email.recommended_width
see types.dt_imageio_module_storage.recommended_width
types.dt_imageio_module_storage_data_email.recommended_height
see types.dt_imageio_module_storage.recommended_height
types.dt_imageio_module_storage_data_email.supports_format
see types.dt_imageio_module_storage.supports_format
7.2.2.2.types.dt_lua_image_t
dt_type
lmage ob|ects represent an image in the database. 1his is slightly different from a file on
disk since a file can have multiple developements.
Note that this is the real image ob|ect, changing the value of a field will immediately
change it in darktable and will be reflected on any copy of that image ob|ect you may have
kept.
Attributes: has_equal, has_pairs, has_tostring
types.dt_lua_image_t.attach_tag
see darktable.tags.attach
types.dt_lua_image_t.detach_tag
147
see darktable.tags.detach
types.dt_lua_image_t.get_tags
see darktable.tags.get_tags
types.dt_lua_image_t.create_style
see darktable.styles.create
types.dt_lua_image_t.apply_style
see darktable.styles.apply
types.dt_lua_image_t.duplicate
see darktable.database.duplicate
types.dt_lua_image_t.id
number
A unique id identifying the image in the database.
types.dt_lua_image_t.path
string
1he file the directory containing the image.
types.dt_lua_image_t.film
types.dt_lua_film_t
1he film ob|ect that contains this image.
types.dt_lua_image_t.filename
string
1he filename of the image.
types.dt_lua_image_t.duplicate_index
number
lf there are multiple images based on a same file, each will have a unique number, starting
from 0.
types.dt_lua_image_t.publisher
string
1he publisher field of the image.
types.dt_lua_image_t.title
string
1he title field of the image.
types.dt_lua_image_t.creator
148
string
1he creator field of the image.
types.dt_lua_image_t.rights
string
1he rights field of the image.
types.dt_lua_image_t.description
string
1he description field for the image.
types.dt_lua_image_t.exif_maker
string
1he maker exif data.
types.dt_lua_image_t.exif_model
string
1he camera model used.
types.dt_lua_image_t.exif_lens
string
1he id string of the lens used.
types.dt_lua_image_t.exif_aperture
number
1he aperture saved in the exif data.
types.dt_lua_image_t.exif_exposure
number
1he exposure time of the image.
types.dt_lua_image_t.exif_focal_length
number
1he focal length of the image.
types.dt_lua_image_t.exif_iso
number
1he iso used on the image.
types.dt_lua_image_t.exif_datetime_taken
149
string
1he date and time of the image.
types.dt_lua_image_t.exif_focus_distance
number
1he distance of the sub|ect.
types.dt_lua_image_t.exif_crop
number
1he exif crop data.
types.dt_lua_image_t.latitude
number
CPS latitude data of the image.
types.dt_lua_image_t.longitude
number
CPS longitude data of the image.
types.dt_lua_image_t.is_raw
boolean
1rue if the image is a PAW file.
types.dt_lua_image_t.is_ldr
boolean
1rue if the image is a ldr image.
types.dt_lua_image_t.is_hdr
boolean
1rue if the image is a hdr image.
types.dt_lua_image_t.width
number
1he width of the image.
types.dt_lua_image_t.height
number
1he height of the image.
types.dt_lua_image_t.rating
1S0
number
1he rating of the image (-1 for re|ected).
types.dt_lua_image_t.red
boolean
1rue if the image has the corresponding colorlabel.
types.dt_lua_image_t.blue
see types.dt_lua_image_t.red
types.dt_lua_image_t.green
see types.dt_lua_image_t.red
types.dt_lua_image_t.yellow
see types.dt_lua_image_t.red
types.dt_lua_image_t.purple
see types.dt_lua_image_t.red
types.dt_lua_image_t.group_with
function(image,[image2])
Puts the first image in the same group as the second image. lf no second image is provided
the image will be in its own group.
image types.dt_lua_image_t
1he image whose group must be changed.
image2 types.dt_lua_image_t
1he image we want to group with.
types.dt_lua_image_t.make_group_leader
function(image)
Makes the image the leader of its group.
image types.dt_lua_image_t
1he image we want as the leader.
types.dt_lua_image_t.get_group_members
function(image):table
Peturns a table containing all images of the group. 1he group leader is both at a numeric
key and at the "leader" special key (so you probably want to use ipairs to iterate through
that table).
image types.dt_lua_image_t
1he image whose group we are querying.
1S1
return table
A table of image ob|ects containing all images that are in the same group as the
image.
types.dt_lua_image_t.group_leader
types.dt_lua_image_t
1he image which is the leader of the group this image is a member of.
7.2.2.3.types.dt_imageio_module_format
virtual type
A virtual type representing all format types.
types.dt_imageio_module_format.plugin_name
string
A unique name for the plugin.
types.dt_imageio_module_format.name
string
A human readable name for the plugin.
types.dt_imageio_module_format.extension
string
1he typical filename extension for that format.
types.dt_imageio_module_format.mime
string
1he mime type associated with the format.
types.dt_imageio_module_format.max_width
number
1he max width allowed for the format (0 = unlimited).
types.dt_imageio_module_format.max_height
number
1he max height allowed for the format (0 = unlimited).
types.dt_imageio_module_format.write_image
function(format,image,filename):boolean
Exports an image to a file. 1his is a blocking operation that will not return until the image
is exported.
1S2
Attributes: implicit_yield
format types.dt_imageio_module_format
1he format that will be used to export.
image types.dt_lua_image_t
1he image ob|ect to export.
filename string
1he filename to export to.
return boolean
Peturns true on success.
7.2.2.4.types.dt_imageio_module_format_data_png
dt_type
1ype ob|ect describing parameters to export to png.
Attributes: has_pairs
types.dt_imageio_module_format_data_png.plugin_name
see types.dt_imageio_module_format.plugin_name
types.dt_imageio_module_format_data_png.name
see types.dt_imageio_module_format.name
types.dt_imageio_module_format_data_png.extension
see types.dt_imageio_module_format.extension
types.dt_imageio_module_format_data_png.mime
see types.dt_imageio_module_format.mime
types.dt_imageio_module_format_data_png.max_width
see types.dt_imageio_module_format.max_width
types.dt_imageio_module_format_data_png.max_height
see types.dt_imageio_module_format.max_height
types.dt_imageio_module_format_data_png.write_image
see types.dt_imageio_module_format.write_image
types.dt_imageio_module_format_data_png.bpp
number
1he bpp parameter to use when exporting.
7.2.2.5.types.dt_imageio_module_format_data_tiff
dt_type
1ype ob|ect describing parameters to export to tiff.
1S3
Attributes: has_pairs
types.dt_imageio_module_format_data_tiff.plugin_name
see types.dt_imageio_module_format.plugin_name
types.dt_imageio_module_format_data_tiff.name
see types.dt_imageio_module_format.name
types.dt_imageio_module_format_data_tiff.extension
see types.dt_imageio_module_format.extension
types.dt_imageio_module_format_data_tiff.mime
see types.dt_imageio_module_format.mime
types.dt_imageio_module_format_data_tiff.max_width
see types.dt_imageio_module_format.max_width
types.dt_imageio_module_format_data_tiff.max_height
see types.dt_imageio_module_format.max_height
types.dt_imageio_module_format_data_tiff.write_image
see types.dt_imageio_module_format.write_image
types.dt_imageio_module_format_data_tiff.bpp
number
1he bpp parameter to use when exporting.
7.2.2.6.types.dt_imageio_module_format_data_exr
dt_type
1ype ob|ect describing parameters to export to exr.
Attributes: has_pairs
types.dt_imageio_module_format_data_exr.plugin_name
see types.dt_imageio_module_format.plugin_name
types.dt_imageio_module_format_data_exr.name
see types.dt_imageio_module_format.name
types.dt_imageio_module_format_data_exr.extension
see types.dt_imageio_module_format.extension
types.dt_imageio_module_format_data_exr.mime
see types.dt_imageio_module_format.mime
types.dt_imageio_module_format_data_exr.max_width
see types.dt_imageio_module_format.max_width
types.dt_imageio_module_format_data_exr.max_height
see types.dt_imageio_module_format.max_height
types.dt_imageio_module_format_data_exr.write_image
see types.dt_imageio_module_format.write_image
1S4
7.2.2.7.types.dt_imageio_module_format_data_copy
dt_type
1ype ob|ect describing parameters to export to copy.
Attributes: has_pairs
types.dt_imageio_module_format_data_copy.plugin_name
see types.dt_imageio_module_format.plugin_name
types.dt_imageio_module_format_data_copy.name
see types.dt_imageio_module_format.name
types.dt_imageio_module_format_data_copy.extension
see types.dt_imageio_module_format.extension
types.dt_imageio_module_format_data_copy.mime
see types.dt_imageio_module_format.mime
types.dt_imageio_module_format_data_copy.max_width
see types.dt_imageio_module_format.max_width
types.dt_imageio_module_format_data_copy.max_height
see types.dt_imageio_module_format.max_height
types.dt_imageio_module_format_data_copy.write_image
see types.dt_imageio_module_format.write_image
7.2.2.8.types.dt_imageio_module_format_data_pfm
dt_type
1ype ob|ect describing parameters to export to pfm.
Attributes: has_pairs
types.dt_imageio_module_format_data_pfm.plugin_name
see types.dt_imageio_module_format.plugin_name
types.dt_imageio_module_format_data_pfm.name
see types.dt_imageio_module_format.name
types.dt_imageio_module_format_data_pfm.extension
see types.dt_imageio_module_format.extension
types.dt_imageio_module_format_data_pfm.mime
see types.dt_imageio_module_format.mime
types.dt_imageio_module_format_data_pfm.max_width
see types.dt_imageio_module_format.max_width
types.dt_imageio_module_format_data_pfm.max_height
see types.dt_imageio_module_format.max_height
types.dt_imageio_module_format_data_pfm.write_image
see types.dt_imageio_module_format.write_image
1SS
7.2.2.9.types.dt_imageio_module_format_data_jpeg
dt_type
1ype ob|ect describing parameters to export to |peg.
Attributes: has_pairs
types.dt_imageio_module_format_data_jpeg.plugin_name
see types.dt_imageio_module_format.plugin_name
types.dt_imageio_module_format_data_jpeg.name
see types.dt_imageio_module_format.name
types.dt_imageio_module_format_data_jpeg.extension
see types.dt_imageio_module_format.extension
types.dt_imageio_module_format_data_jpeg.mime
see types.dt_imageio_module_format.mime
types.dt_imageio_module_format_data_jpeg.max_width
see types.dt_imageio_module_format.max_width
types.dt_imageio_module_format_data_jpeg.max_height
see types.dt_imageio_module_format.max_height
types.dt_imageio_module_format_data_jpeg.write_image
see types.dt_imageio_module_format.write_image
types.dt_imageio_module_format_data_jpeg.quality
number
1he quality to use at export time.
7.2.2.10.types.dt_imageio_module_format_data_ppm
dt_type
1ype ob|ect describing parameters to export to ppm.
Attributes: has_pairs
types.dt_imageio_module_format_data_ppm.plugin_name
see types.dt_imageio_module_format.plugin_name
types.dt_imageio_module_format_data_ppm.name
see types.dt_imageio_module_format.name
types.dt_imageio_module_format_data_ppm.extension
see types.dt_imageio_module_format.extension
types.dt_imageio_module_format_data_ppm.mime
see types.dt_imageio_module_format.mime
types.dt_imageio_module_format_data_ppm.max_width
see types.dt_imageio_module_format.max_width
1S6
types.dt_imageio_module_format_data_ppm.max_height
see types.dt_imageio_module_format.max_height
types.dt_imageio_module_format_data_ppm.write_image
see types.dt_imageio_module_format.write_image
7.2.2.11.types.dt_imageio_module_format_data_webp
dt_type
1ype ob|ect describing parameters to export to webp.
Attributes: has_pairs
types.dt_imageio_module_format_data_webp.plugin_name
see types.dt_imageio_module_format.plugin_name
types.dt_imageio_module_format_data_webp.name
see types.dt_imageio_module_format.name
types.dt_imageio_module_format_data_webp.extension
see types.dt_imageio_module_format.extension
types.dt_imageio_module_format_data_webp.mime
see types.dt_imageio_module_format.mime
types.dt_imageio_module_format_data_webp.max_width
see types.dt_imageio_module_format.max_width
types.dt_imageio_module_format_data_webp.max_height
see types.dt_imageio_module_format.max_height
types.dt_imageio_module_format_data_webp.write_image
see types.dt_imageio_module_format.write_image
types.dt_imageio_module_format_data_webp.quality
number
1he quality to use at export time.
types.dt_imageio_module_format_data_webp.comp_type
string
1he overall quality to use, can be one of "webp_lossy" or "webp_lossless".
types.dt_imageio_module_format_data_webp.hint
string
A hint on the overall content of the image, can be one of "hint_default", "hint_picture",
"hint_photo", "hint_graphic".
7.2.2.12.types.dt_imageio_module_format_data_j2k
dt_type
1S7
1ype ob|ect describing parameters to export to |peg2000.
Attributes: has_pairs
types.dt_imageio_module_format_data_j2k.plugin_name
see types.dt_imageio_module_format.plugin_name
types.dt_imageio_module_format_data_j2k.name
see types.dt_imageio_module_format.name
types.dt_imageio_module_format_data_j2k.extension
see types.dt_imageio_module_format.extension
types.dt_imageio_module_format_data_j2k.mime
see types.dt_imageio_module_format.mime
types.dt_imageio_module_format_data_j2k.max_width
see types.dt_imageio_module_format.max_width
types.dt_imageio_module_format_data_j2k.max_height
see types.dt_imageio_module_format.max_height
types.dt_imageio_module_format_data_j2k.write_image
see types.dt_imageio_module_format.write_image
types.dt_imageio_module_format_data_j2k.quality
number
1he quality to use at export time.
types.dt_imageio_module_format_data_j2k.bpp
number
1he bpp parameter to use when exporting.
types.dt_imageio_module_format_data_j2k.format
string
1he format to use can be one of "|2k" or "|p2".
types.dt_imageio_module_format_data_j2k.preset
string
1he preset to use can be one of "cinema2k_24", "cinema2k_48", "cinema4k_24".
7.2.2.13.types.dt_imageio_module_storage
virtual type
A virtual type representing all storage types.
types.dt_imageio_module_storage.plugin_name
string
1S8
A unique name for the plugin.
types.dt_imageio_module_storage.name
string
A human readable name for the plugin.
types.dt_imageio_module_storage.width
number
1he currently selected width for the plugin.
types.dt_imageio_module_storage.height
number
1he currently selected height for the plugin.
types.dt_imageio_module_storage.recommended_width
number
1he recommended width for the plugin.
types.dt_imageio_module_storage.recommended_height
number
1he recommended height for the plugin.
types.dt_imageio_module_storage.supports_format
function(storage,format):boolean
Checks if a format is supported by this storage.
storage types.dt_imageio_module_storage
1he storage type to check against.
format types.dt_imageio_module_format
1he format type to check.
return boolean
1rue if the format is supported by the storage.
7.2.2.14.types.dt_imageio_module_storage_data_flickr
dt_type
An ob|ect containing parameters to export to flickr.
Attributes: has_pairs
types.dt_imageio_module_storage_data_flickr.plugin_name
see types.dt_imageio_module_storage.plugin_name
1S9
types.dt_imageio_module_storage_data_flickr.name
see types.dt_imageio_module_storage.name
types.dt_imageio_module_storage_data_flickr.width
see types.dt_imageio_module_storage.width
types.dt_imageio_module_storage_data_flickr.height
see types.dt_imageio_module_storage.height
types.dt_imageio_module_storage_data_flickr.recommended_width
see types.dt_imageio_module_storage.recommended_width
types.dt_imageio_module_storage_data_flickr.recommended_height
see types.dt_imageio_module_storage.recommended_height
types.dt_imageio_module_storage_data_flickr.supports_format
see types.dt_imageio_module_storage.supports_format
7.2.2.15.types.dt_imageio_module_storage_data_facebook
dt_type
An ob|ect containing parameters to export to facebook.
Attributes: has_pairs
types.dt_imageio_module_storage_data_facebook.plugin_name
see types.dt_imageio_module_storage.plugin_name
types.dt_imageio_module_storage_data_facebook.name
see types.dt_imageio_module_storage.name
types.dt_imageio_module_storage_data_facebook.width
see types.dt_imageio_module_storage.width
types.dt_imageio_module_storage_data_facebook.height
see types.dt_imageio_module_storage.height
types.dt_imageio_module_storage_data_facebook.recommended_width
see types.dt_imageio_module_storage.recommended_width
types.dt_imageio_module_storage_data_facebook.recommended_height
see types.dt_imageio_module_storage.recommended_height
types.dt_imageio_module_storage_data_facebook.supports_format
see types.dt_imageio_module_storage.supports_format
7.2.2.16.types.dt_imageio_module_storage_data_latex
dt_type
An ob|ect containing parameters to export to latex.
Attributes: has_pairs
types.dt_imageio_module_storage_data_latex.plugin_name
see types.dt_imageio_module_storage.plugin_name
160
types.dt_imageio_module_storage_data_latex.name
see types.dt_imageio_module_storage.name
types.dt_imageio_module_storage_data_latex.width
see types.dt_imageio_module_storage.width
types.dt_imageio_module_storage_data_latex.height
see types.dt_imageio_module_storage.height
types.dt_imageio_module_storage_data_latex.recommended_width
see types.dt_imageio_module_storage.recommended_width
types.dt_imageio_module_storage_data_latex.recommended_height
see types.dt_imageio_module_storage.recommended_height
types.dt_imageio_module_storage_data_latex.supports_format
see types.dt_imageio_module_storage.supports_format
types.dt_imageio_module_storage_data_latex.filename
string
1he filename to export to.
types.dt_imageio_module_storage_data_latex.title
string
1he title to use for export.
7.2.2.17.types.dt_imageio_module_storage_data_picasa
dt_type
An ob|ect containing parameters to export to picasa.
Attributes: has_pairs
types.dt_imageio_module_storage_data_picasa.plugin_name
see types.dt_imageio_module_storage.plugin_name
types.dt_imageio_module_storage_data_picasa.name
see types.dt_imageio_module_storage.name
types.dt_imageio_module_storage_data_picasa.width
see types.dt_imageio_module_storage.width
types.dt_imageio_module_storage_data_picasa.height
see types.dt_imageio_module_storage.height
types.dt_imageio_module_storage_data_picasa.recommended_width
see types.dt_imageio_module_storage.recommended_width
types.dt_imageio_module_storage_data_picasa.recommended_height
see types.dt_imageio_module_storage.recommended_height
types.dt_imageio_module_storage_data_picasa.supports_format
161
see types.dt_imageio_module_storage.supports_format
7.2.2.18.types.dt_imageio_module_storage_data_gallery
dt_type
An ob|ect containing parameters to export to gallery.
Attributes: has_pairs
types.dt_imageio_module_storage_data_gallery.plugin_name
see types.dt_imageio_module_storage.plugin_name
types.dt_imageio_module_storage_data_gallery.name
see types.dt_imageio_module_storage.name
types.dt_imageio_module_storage_data_gallery.width
see types.dt_imageio_module_storage.width
types.dt_imageio_module_storage_data_gallery.height
see types.dt_imageio_module_storage.height
types.dt_imageio_module_storage_data_gallery.recommended_width
see types.dt_imageio_module_storage.recommended_width
types.dt_imageio_module_storage_data_gallery.recommended_height
see types.dt_imageio_module_storage.recommended_height
types.dt_imageio_module_storage_data_gallery.supports_format
see types.dt_imageio_module_storage.supports_format
types.dt_imageio_module_storage_data_gallery.filename
string
1he filename to export to.
types.dt_imageio_module_storage_data_gallery.title
string
1he title to use for export.
7.2.2.19.types.dt_imageio_module_storage_data_disk
dt_type
An ob|ect containing parameters to export to disk.
Attributes: has_pairs
types.dt_imageio_module_storage_data_disk.plugin_name
see types.dt_imageio_module_storage.plugin_name
types.dt_imageio_module_storage_data_disk.name
see types.dt_imageio_module_storage.name
types.dt_imageio_module_storage_data_disk.width
162
see types.dt_imageio_module_storage.width
types.dt_imageio_module_storage_data_disk.height
see types.dt_imageio_module_storage.height
types.dt_imageio_module_storage_data_disk.recommended_width
see types.dt_imageio_module_storage.recommended_width
types.dt_imageio_module_storage_data_disk.recommended_height
see types.dt_imageio_module_storage.recommended_height
types.dt_imageio_module_storage_data_disk.supports_format
see types.dt_imageio_module_storage.supports_format
types.dt_imageio_module_storage_data_disk.filename
string
1he filename to export to.
7.2.2.20.types.dt_lua_film_t
dt_type
A film in darktable, this represents a directory containing imported images.
Attributes: has_equal, has_ipairs, has_length, has_pairs, has_tostring
types.dt_lua_film_t.#
types.dt_lua_image_t
1he different images within the film.
types.dt_lua_film_t.id
number
A unique numeric id used by this film.
types.dt_lua_film_t.path
string
1he path represented by this film.
7.2.2.21.types.dt_style_t
dt_type
A style that can be applied to an image.
Attributes: has_ipairs, has_length, has_pairs, has_tostring
types.dt_style_t.delete
see darktable.styles.delete
types.dt_style_t.duplicate
163
see darktable.styles.duplicate
types.dt_style_t.apply
see darktable.styles.apply
types.dt_style_t.name
string
1he name of the style.
types.dt_style_t.description
string
1he description of the style.
types.dt_style_t.#
types.dt_style_item_t
1he different items that make the style.
7.2.2.22.types.dt_style_item_t
dt_type
An element that is part of a style.
Attributes: has_pairs, has_tostring
types.dt_style_item_t.name
string
1he name of the style item.
types.dt_style_item_t.num
number
1he position of the style item within its style.
7.2.2.23.types.dt_lua_tag_t
dt_type
A tag that can be attached to an image.
Attributes: has_equal, has_ipairs, has_length, has_pairs, has_tostring
types.dt_lua_tag_t.delete
see darktable.tags.delete
types.dt_lua_tag_t.attach
see darktable.tags.attach
types.dt_lua_tag_t.detach
see darktable.tags.detach
164
types.dt_lua_tag_t.name
string
1he name of the tag.
types.dt_lua_tag_t.#
undocumented
1he images that have that tag attached to them.
Attributes: read
7.2.3.events
1his section documents events that can be used to trigger Lua callbacks.
7.2.3.1.events.intermediate-export-image
event
1his event is called each time an image is exported, once for each image after the image
has been processed to an image format but before the storage has moved the image to
its final destination.
events.intermediate-export-image.callback
function(event,image,filename)
event string
1he name of the event that triggered the callback.
image types.dt_lua_image_t
1he image ob|ect that has been exported.
filename string
1he name of the file that is the result of the image being processed.
events.intermediate-export-image.extra_registration_parameters
1his event has no extra registration parameters.
7.2.3.2.events.post-import-image
event
1his event is triggered whenever a new image is imported into the database.
1his event can be registered multiple times, all callbacks will be called.
events.post-import-image.callback
function(event,image)
16S
event string
1he name of the event that triggered the callback.
image types.dt_lua_image_t
1he image ob|ect that has been exported.
events.post-import-image.extra_registration_parameters
1his event has no extra registration parameters.
7.2.3.3.events.shortcut
event
1his event registers a new keyboad shortcut. 1he shortcut isn't bound to any key until the
users does so in the preference panel.
1he event is triggered whenever the shortcut is triggered.
1his event can only be registered once per value of shortcut.
events.shortcut.callback
function(event,shortcut)
event string
1he name of the event that triggered the callback.
shortcut string
1he tooltip string that was given at registration time.
events.shortcut.extra_registration_parameters
tooltip string
1he string that will be displayed on the shortcut preference panel describing
the shortcut.
7.2.3.4.events.post-import-film
event
1his event is triggered when an film import is finished (all post-import-image callbacks
have already been triggered). 1his event can be registered multiple times.
events.post-import-film.callback
function(event,film)
166
event string
1he name of the event that triggered the callback.
film types.dt_lua_film_t
1he new film that has been added. lf multiple films were added recursively only
the top level film is reported.
events.post-import-film.extra_registration_parameters
1his event has no extra registration parameters.
7.2.4.attributes
1his section documents various attributes used throughout the documentation.
7.2.4.1.attributes.write
1his ob|ect is a variable that can be written to.
7.2.4.2.attributes.read
1his ob|ect is a variable that can be read.
7.2.4.3.attributes.has_pairs
1his ob|ect can be used as an argument to the system function "pairs" and iterated upon.
7.2.4.4.attributes.has_ipairs
1his ob|ect can be used as an argument to the system function "ipairs" and iterated upon.
7.2.4.5.attributes.has_equal
1his ob|ect has a specific comparison function that will be used when comparing it to an
ob|ect of the same type.
7.2.4.6.attributes.has_length
1his ob|ect has a specific length function that will be used by the # operator.
7.2.4.7.attributes.has_tostring
1his ob|ect has a specific reimplementation of the "tostring" method that allows pret-
ty-printing it.
7.2.4.8.attributes.implicit_yield
1his call will release the Lua lock while executing, thus allowing other Lua callbacks to run.
7.2.5.system
1his section documents changes to system functions.
7.2.5.1.system.yield
function(type,extra):variable
167
Lua functions can yield at any point. 1he parameters and return types depend on why we
want to yield.
A callback that is yielding allows other Lua code to run.
* wait_ms: one extra parameter, the execution will pause for that many miliseconds, yield
returns nothing,
* file_readable: an opened file from a call to the OS library, will return when the file is
readable, returns nothing,
* run_command: a command to be run by "sh -c", will return when the command termi-
nates, returns the return code of the execution.
type string
1he type of yield, can be one of "wait_ms", "file_readable", "run_command".
extra variable
An extra parameter: integer for "wait_ms", open file for "file_readable", string
for "run_command".
return variable
Nothing for "wait_ms" and "file_readable", the returned code of the command
for "run_command".
168
7.3.Lua scripts
1his section presents a list of scripts provided by beta testers of the Lua APl. 1here is no
guarentee whatsoever that they will work as the APl is still in beta and might have changed
since the script was uploaded.
7.3.1.Simple mosaic script
author: boucman
tested with: 1.3+26S~gd7f3d1a
download: mosaic.lua [http://www.darktable.org/redmine/attachments/down-
load/S72/mosaic.luaj
dt = require "darktable"
dt.register_storage("module_stitcher","mosaic generator",nil,
function(storage,image_table)
dt.print_error("Will try to stitch now")
command = "gm convert "
for _,v in pairs(image_table) do
command = command..v.." "
end
command = command.."-append -resize 15% "
..dt.configuration.tmp_dir.."/tmp.png"
dt.print_error("this is the command: "..command)
os.execute(command)
dt.print("Stitching saved to "..dt.configuration.tmp_dir
.."/tmp.png")
end
)
1his script is an example of storage implemented in Lua. 1his is not complete nor polished
but it shows how to implement a storage module in Lua.
1he script must be saved in ~/.config/darktable/lua/ (the directory might not exist).
Add the following line in the file ~/.config/darktable/luarc (again, the file might not exist):
require "mosaic"
A new entry mosaic generator will be added to the storage list. Using it will create a mosaic
of selected images in a temporary directory.
1hanks to hal_from_2001 for the idea an the original implementation.
7.3.2.Selection manipulation shortcuts
author: boucman
tested with: 1.3+26S~gd7f3d1a
download: save_selection.lua [http://www.darktable.org/redmine/attachments/down-
load/636/save_selection.luaj
dt = require "darktable"
169
local buffer_count = 5
for i=1,buffer_count do
local saved_selection
dt.register_event("shortcut",function()
saved_selection = dt.gui.selection()
end,"save to buffer "..i)
dt.register_event("shortcut",function()
dt.gui.selection(saved_selection)
end,"restore from buffer "..i)
end
local bounce_buffer = {}
dt.register_event("shortcut",function()
bounce_buffer = dt.gui.selection(bounce_buffer)
end,"switch selection with temporary buffer")
1his script will add two new shortcuts save to buffer and restore from buffer to help
manipulate selections.
Save this script in ~/.config/darktable/lua/ (the directory might need to be created) and
add the following line in the file ~/.config/darktable/luarc (the file might need to be cre-
ated):
require "save_selection"
Now these new options will appear under global->lua. and allow you to save and restore
the current selection to/from five different save bufffers. 1he third shortcut switch se-
lection with temporary buffer exchanges the current selection with the content of a fast
buffer.
170
7.4.Lua debugging
7.4.1.Enable error logging
Start darktable with the command line darktable -d lua to enable Lua error logging.
messages printed from Lua using darktable.print_error will be visible on the standard
out.
for fatal Lua errors the whole traceback (and not |ust the error message) will be printed
to the console.
7.4.2.Inspecting internal objects
darktable provides some debugging helpers which can be called from Lua as per the fol-
lowing example:
dt_debug = require "darktable.debug"
dt_debug.debug.debug = true
print(dt_debug.dump(_G,"Global environement")
1he main function provided is darktable.debug.dump(object,name). 1his function returns a
string that describes an ob|ect. 1he ob|ect can be anything and this function will use its
knowledge of the darktable APl to be smart about the type of ob|ects.
1he boolean variable darktable.debug.debug is initialized to false. When this variable is set
true, dt_debug.dump will also dump metatables for ob|ects. You usually only want to see
those when debugging the internals of darktable's Lua APl.
7.4.3.Debugging unprotected calls
When experimenting with Lua, darktable might crash with the following message:
PANIC: unprotected error in call to lua API (some message here)
1his is always a bug in darktable's Lua APl. Please open a bug report and attach the script
that caused the crash.
171
Chapter8.Special topics
1his chapter touches several technical topics which might help you to get darktable run-
ning on specific hardware or optimize its performance. A lot of additional technical back-
ground information and many tips and tricks are also covered in an extensive blog section
that you can find on our homepage [http://www.darktable.orgj.
172
8.1.darktable and memory
darktable's memory requirements are high. A simple calculation makes this clear. lf you
have a 20MPx image, darktable for precision reasons will store this internally as a 4 32-
bit floating point cell for each pixel. Each full image of this size will need about 300MB
of memory. As we want to process the image, we will at least need two buffers for each
module one for input and one for output. lf we have a more complex module, its algo-
rithm might additionally require several intermediate buffers of the same size. Without
further optimization, anything between 600MB and 3CB would be needed only to store
and process image data. On top we have darktables code segment, the code and data of
all dynamically linked system libraries, and not to forget further buffers where darktable
stores intermediate images for quick access during interactive work (mip map cache). All
in all, darktable would like to see a minimum of about 4CB to run happily.
8.1.1.Total system memory
From what l said before, it is evident that your computer needs a sane memory setup to
properly run darktable. We suggest that you have a least 4CB of physical PAM plus 4 to
8CB of additional swap space installed. 1he latter is required, so that your system can
swap out temporarily unneeded data to disk in order to free physical PAM.
1heoretically, you could also run darktable with lower amounts of physical PAM and bal-
ance this with enough swap space. However, you should be prepared that your system
could then heavily thrash, as it reads or writes data pages to and from the hard disk.
We have positive reports that this functions well for several users, but it still might get
extremely slow for others...
8.1.2.Available address space
Besides the total amount of system memory there is another limiting factor: the available
address space of your hardware architecture. How much memory can be addressed by
a process depends on the number of address bits your CPU offers. For a CPU with 32-
bit address registers, this is 2^32 bytes, which makes a total of 4CB. 1his is the absolute
upper limit of memory that can be used by a process and it constitutes a tight situation
for darktable as we have seen above.
darktables escape route is called tiling. lnstead of processing an image in one big chunk,
we split the image into smaller parts for every processing step (module). 1his will still re-
quire one full input and output buffer, but intermediate buffers can be made small enough
to have everything fit into the hardware limits.
8.1.3.Memory fragmentation
Unfortunately this is not the full story yet. 1here is an effect called memory fragmenta-
tion, which can and will hit software that needs to do extensive memory management. lf
such a program allocates S times 300MB at a time and frees it again, that memory should
normally be available for one big 1.SCB allocation afterwards. 1his however is often not
the case. 1he systems memory allocator may no longer see this area as one contiguous
1.SCB block but as a row of 300MB areas. lf there is no other free area of 1.SCB available,
the allocation would fail. During a program run this mechanism will take away more and
more of the larger memory blocks in favor of smaller ones. darktable 1.0 introduces a
caching algorithm to address this problem. lt pre-allocates blocks of memory and makes
them available on request.
173
8.1.4.Further limitations
As if this were not challenging enough, there are further things that might limit your ac-
cess to memory. On some older boards you need to activate BlOS option memory remap-
ping in order to have all physically installed memory enabled. ln addition if you are on a
32-bit OS you will probably need a kernel version that has Physical Address Extension
(PAE) enabled. 1his is often but not always the case for Linux. Many distributions deliver
different kernels, some with and some without PAE activated, you need to choose the
right one. 1o check if the system is setup correctly, use the command free in a terminal
and examine the output. lf the output reports less PAM than you have installed, you have
an issue needing correction, for example you have 4CB on your board, but your kernel is
only seeing 3CB or less. You need to consult your BlOS manual and the information about
your Linux variant for further help.
8.1.5.Setting up darktable on 32-bit systems
As weve seen 32-bit systems are difficult environments for darktable. Still many users are
successfully running darktable on them, if the basic requirements in terms of total system
memory and the topics mentioned in the paragraphs above are addressed properly.
1here are several ad|ustment parameters to get it running. lf you install fresh, darktable
will detect your system and set conservative values by default. However, if you upgrade
darktable from an older version (e.g. coming from 0.9.3 and going to 1.0), chances are
you have unfavorable settings in your preferences. 1he consequences might be darktable
aborting due to allocation failures or very typically darktable not being able to properly
import a new film roll. As a frequent symptom you get skulls displayed instead of thumbs
for many of your pictures.
lf this is the case, take a minute to optimize the preference settings in this case. You will
find them under core options (Section6.2, Core options) in darktables preference di-
alog. You should also find these parameters as configuration variables in SHOME/.config/
darktable/darktablerc and edit them there.
Here is a short explanation of the relevant parameters and their proposed settings.
number of background threads
1his parameter defines the maximum number of threads that are allowed in parallel when
importing film rolls or doing other background stuff. For obvious reasons on 32-bit sys-
tems you can only have one thread eating resources at a time. So you need set this para-
meter to 1, anything higher will kill you. For the same reason you also must set the number
of parallel export threads to 1.
host memory limit (in MB) for tiling
1his parameter tells darktable how much memory (in MB) it should assume is available to
store image buffers during module operations. lf an image can not be processed within
these limits in one chunk, tiling will take over and process the image in several parts, one
after the other. Set this to the lowest possible value of S00 as a starting point. You might
experiment later whether you can increase it a bit in order to reduce the overhead of tiling.
minimum amount of memory (in MB) for a single buffer in tiling
1his is a second parameter that controls tiling. lt sets a lower limit for the size of interme-
diate image buffers in megabytes. 1he parameter is needed to avoid excessive tiling in
some cases (for some modules). Set this parameter to a low value of 8. You might tenta-
tively increase it to 16 later.
174
memory in bytes to use for mipmap cache
1his controls how many thumbnails (or mip maps) can be stored in memory at a time. As
a starting point set this to something like 2S6MB (give the number in bytes). 1o avoid
the problem of memory fragmentation during longer runs of darktable, the new caching
scheme frontloads the memory costs and allocates this cache once at the beginning. Some
Linux kernels use over-committing memory allocation, which means you don't immediate-
ly pay for all of the memory in terms of PSS (resident set size, the non-swapped physical
memory), but in any case you pay for the address space. As explained before, this poses
a problem for 32-bit systems and will, at first sight, appear as a regression over the 0.9.3-
style cache. ln the long run however, this is all the memory that's ever going to be allocat-
ed for thumbnails. So if we can successfully grab this portion once, we are relieving a lot
of pressure on fragmentation for long sessions.
8.1.6.darktable on 64-bit systems
1here's not much to be said here. Of course also 64-bit systems require a sufficient amount
of main memory, so the 4CB plus swap recommendation holds true. On the other hand,
64-bit architectures do not suffer from the specific 32-bit limitations like small address
space and fragmentation madness.
Most modern lntel or AMD 64-bit CPUs will have available address space in the range of
several 1erabytes. 1he word modern is relative in this context: all AMD and lntel CPUs
introduced since 2003 and 2004, respectively, offer a 64-bit mode. Linux 64-bit has been
available for many years.
All relevant Linux distributions give you the choice to install a 32-bit or a 64-bit version
with no added costs. You can even run old 32-bit binaries on a 64-bit Linux. 1he only thing
you need to do: invest some time into the migration. ln the end we strongly recommend
moving to a 64-bit version of Linux. 1here really is no reason not to upgrade to 64-bit.
On a 64-bit system you can safely leave the tiling related configuration parameters at their
defaults: host memory limit (in MB) for tiling should have a value of 1S00 and minimum
amount of memory (in MB) for a single buffer in tiling should be set to 16. ln case you are
migrating from a 32-bit to a 64-bit system you should check these settings and manually
change them if needed.
17S
8.2.darktable and OpenCL
darktable can use CPU acceleration via OpenCL to improve performance.
8.2.1.The background
Processing high resolution images is a demanding task needing a modern computer. Both
in terms of memory requirements and in terms of CPU power, getting the best out of a
typical 1S, 20 or 2S Megapixel image can quickly bring your computer to its limits.
darktables requirements are no exception. Our decision to not compromise processing
quality, has led to all calculations being done on 4 32bit floating point numbers. 1his
is slower than ordinary 8 or 16bit integer algebra, but eliminates all problems of tonal
breaks or loss of information.
A lot of hand optimization has been invested to make darktable as fast as possible. lf you
run a current version of darktable on a modern computer, you might not notice any slow-
ness. However, there are conditions and certain modules where you will feel (or hear from
the howling of your CPU fan) how much your poor multi-core processor has to struggle.
1hats where OpenCL comes in. OpenCL allows us to take advantage of the enormous
power of modern graphics cards. Camers demand for high detailed 3D worlds in modern
ego shooters has fostered CPU development. A1l, NVlDlA and Co had to put enormous
processing power into their CPUs to meet these demands. 1he result is modern graphics
cards with highly parallelized CPUs to quickly calculate surfaces and textures at high frame
rates.
You are not a gamer and you dont take advantage of that power! Well, then you should at
least use it in darktable! For the task of highly parallel floating point calculations modern
CPUs are much faster than CPUs. 1hat is especially true, when you want to do the same few
processing steps over millions of items. 1ypical use case: processing of megapixel images.
8.2.2.How OpenCL works
As you can imagine, hardware architectures of CPUs can vary significantly. 1here are dif-
ferent manufacturers, and even different generations of CPUs from the same manufac-
turer may differ. At the same time CPU manufacturers don't normally disclose all hardware
details of their products to the public. One of the known consequences is the need to use
proprietary drivers under Linux, if you want to take full advantage of your graphics card.
Fortunately an industry consortium lead by 1he Khronos Croup has developed an open,
standardized interface called OpenCL. lt allows the use of your CPU as a numerical pro-
cessing device. OpenCL offers a C99-like programming language with a strong focus on
parallel computing. An application that wants to use OpenCL will need OpenCL source
code that it hands over to a hardware specific OpenCL compiler at run-time. 1his way the
application can use OpenCL on different CPU architectures (even at the same time). All
hardware secrets are hidden in this compiler and are normally not visible to the user (or
the application). 1he compiled OpenCL code is loaded onto your CPU and - with certain
APl calls - it is ready to do calculations for you.
8.2.3.How to activate OpenCL in darktable
Using OpenCL in darktable requires that your PC is equipped with a suitable graphics card
and that it has the required libraries in place. Namely modern graphics cards from NVlDlA
and A1l come with full OpenCL support. 1he OpenCL compiler is normally shipped as part
of the proprietary graphics driver, it is used as a dynamic library called libOpenCL.so.
1his library must be in a folder where it is found by your systems dynamic linker.
176
When darktable starts, it will first try to find and load libOpenCL.so and on success
check if the available graphics card comes with OpenCL support. A sufficient amount of
graphics memory (1CB+) needs to be available to take advantage of the CPU. lf that is
OK, darktable tries to setup its OpenCL environment: a processing context needs to be
initialized, a calculation pipeline to be started, OpenCL source code files (extension is .cl)
need to be read and compiled and the included routines (called OpenCL kernels) need to
be prepared for darktableles modules. lf all that is done, the preparation is finished.
Per default OpenCL support is activated in darktable if all the above steps were successful.
lf you want to de-activate it you can do so in core options (Section6.2, Core options)
by unchecking activate opencl support. 1his configuration parameter also tells you if
OpenCL initialization failed: it is greyed out in that case.
You can at any time switch OpenCL support off and on, this will happen immediately. De-
pending on the type of modules you are using, you will notice the effect as a general
speed-up during interactive work and during export. Most modules in darktable can take
advantage of OpenCL but not all modules are demanding enough to make a noticeable
difference. ln order to feel a real difference, take modules like shadows and highlights,
sharpen, lowpass, highpass or even more extreme equalizer and profiled denoise.
lf you are interested in profiling figures, you can start darktable with command line para-
meters -d opencl -d perf. After each run of the pixelpipe you will get a detailed alloca-
tion of processing time to each module plus an even more fine grained profile for all used
OpenCL kernels.
Besides the speed-up you should not see any difference in the results between CPU and
CPU processing. Except of rounding errors, the results are designed to be identical. lf, for
some reasons, darktable fails to properly finish a CPU calculation, it will normally notice
and automatically (and transparently) fall back to CPU processing.
8.2.4.Possible problems and solutions
darktable will detect OpenCL run-time problems automatically. lt will then reprocess
everything on CPU, only speed is affected, the final result should not be endangered.
1here can be various reasons why OpenCL could fail during initialization phase. We depend
on hardware requirements and on the presence of certain drivers and libraries. ln addition
all these have to fit in terms of maker model and revision number. lf 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 is likely not available.
ln that case, the best thing to do is start darktable from a console with
darktable -d opencl

1his will give additional debugging output about the initialization and use of OpenCL.
First see if you find a line that starts with [opencl_initj FlNALLY 1his should tell you,
if OpenCL support is available for you or not. lf initialization failed, look at the messages
above for anything that reads like could not be detected or could not be created. Check
if there is a hint about where it failed.
Here are a few cases observed in the past:
darktable might tell you that no OpenCL aware graphics card is detected or that the avail-
able memory on your CPU is too low and the device is discarded. ln that case you might
need to buy a new card, if you really want OpenCL support.
177
darktable might find your libOpenCL.so but then tell you that it couldn't get a plat-
form. NVlDlA drivers will often give error code -1001 in that case. 1his happens because
libOpenCL.so is only a wrapper library. For the real work further libraries - specific to ven-
dor, device and driver - need to be loaded. 1his failed for some reason. 1here is a structure
of files in /etc/OpenCL on your system that libOpenCL.so consults to find these libraries.
Check if you find something fishy in there and try to fix it. Often the needed libraries can-
not be found by your system's dynamic loader. Civing full path names might help.
darktable might also tell you that a context could not be created. 1his often indicates a
version mismatch between (loaded) graphics driver and libOpenCL. Check if you have left-
over kernel modules or graphics libraries of an older install and take appropriate action. ln
doubt, make a clean reinstall of your graphics driver. Sometimes, immediately after a dri-
ver update, the loaded kernel driver does not match the newly installed libraries: reboot
your system in that case.
darktable might crash in very rare cases directly during startup. 1his can happen if your
OpenCL setup is completely broken or if driver/library contains a severe bug. lf you cant
fix it, you can still use darktable with option --disable-opencl, which will skip the entire
OpenCL initialization step.
darktable might fail to compile its OpenCL source files at run-time. ln that case you will
get a number of error messages looking like typical compiler errors. 1his could indicate
an incompatibility between your OpenCL implementation and our interpretation of the
standard. ln that case visit us at [email protected] and report the prob-
lem. Chances are good that we can help you. Please also report if you see significant dif-
ferences between CPU and CPU processing of an image!
1here also exists a few on-CPU implementations of OpenCL. 1hese come as drivers provid-
ed by lN1EL or AMD. We observed that they do not give us any speed gain versus our hand-
optimized CPU code. 1herefore we simply discard these devices by default. 1his behavior
can be changed by setting the configuration variable opencl_use_cpu_devices to 1PUE.
8.2.5.Setting up OpenCL for AMD/ATI devices
While NVlDlA devices and most modern AMD/A1l devices will most often run out of the
box, there is more to do for older AMD/A1l graphics cards, namely those prior to the
HD7xxx series. 1his starts with the fact that those devices will only report to darktable
part of their total CPU memory. For a 1CB device this typically amounts to S12MB, a val-
ue which darktable in its standard configuration will refuse as not being sufficient for its
tasks. Consequence: the device will not be used.
On the web you might find as a tip to set environment variable CPU_MAX_HEAP_SlZE to
a value of 100 in this case. lndeed this will cause the AMD/A1l driver to report the full
installed memory to darktable. However, there is a problem. On many (most!) cards this
will cause buffers to be allocated on your computer (host) not on the video card! ln this
case all memory accesses will need to go through the slow PCle bus. 1his will cost you a
factor of 10x or more in performance and will render OpenCL useless for you, especially
when exporting files.
Another environment variable which changes driver behavior is
CPU_MAX_ALLOC_PEPCEN1. You could set this to 100 in order to allow memory alloca-
tions as high as 1CB on your AMD/A1l card. 1he problem is, this tends to cause darktable
to crash sooner or later.
Our recommendation is to leave these settings untouched. Often your card will be recog-
nized with S12MB memory and a maximum allocation size of 128MB. 1here are three con-
178
figuration parameter which you set in file SHOME/.config/darktable/darktablerc to get
things running. Here are the details:
opencl_memory_requirement
Set this parameter to S00 so that darktable will accept your S12MB graphics memory as
being sufficient in memory.
opencl_memory_headroom
1his parameter controls how much graphics memory (out of the reported one) darktable
should leave untouched for driver and display use. As for AMD/A1l devices we anyhow only
can get half of the available PAM it's safe to set this to zero. So all of the S12MB can be
used by darktable.
opencl_avoid_atomics
Atomic operations in OpenCL are a special way of data synchronization. 1hey are only used
in a few kernels. Unfortunately, some (most!) AMD/A1l devices are extremely slow in pro-
cessing atomics. lt's better to process the affected modules on CPU rather than accepting
an ultra-slow CPU codepath. Set this parameter to 1PUE if you experience slow processing
of modules like shadows and highlights, monochrome, local contrast, or global tonemap or
if you even get intermittent system freezes.
1hese recommendations do not apply to the more recent Padeon HD7xxx series with CCN
architecture. Besides being very fast in terms of CPU computing they normally run out of
the box. You only might consider to try some of the performance optimization options
which are described in the following section.
8.2.6.OpenCL performance optimization
1here are some configuration parameters in SHOME/.config/darktable/darktablerc that
help to finetune your system's OpenCL performance. Performance in this context mostly
means the latency of darktable during interactive work, i.e. how long it takes to reprocess
your pixelpipe. For a comfortable workflow it is essential to keep latency low.
ln order to get profiling info you start darktable from a terminal with
darktable -d opencl -d perf

After each reprocessing of pixelpipe - caused by module parameter change, zooming, pan-
ning, etc. - you will get the total time and the time spent in each of our OpenCL kernels.
1he most reliable value is the total time spent in pixelpipe. Please note that the timings
given for each individual module are unreliable when running the OpenCL pixelpipe asyn-
chronously (see opencl_async_pixelpipe below).
1o allow for a fast pixelpipe processing with OpenCL it is essential that we keep the CPU
busy. Any interrupts or a stalled data flow will add to the total processing time. 1his is
especially important for the small image buffers we need to handle during interactive
work. 1hey can be processed quickly by a fast CPU. However, even short-term stalls of the
pixelpipe will easily become a bottleneck.
On the other hand darktable's performance during file exports is more or less only gov-
erned by the speed of our algorithms and the horse-power of your CPU. Short-term stalls
will not have a noticeable effect on the total time of an export.
179
darktable comes with default settings that should deliver a decent CPU performance on
most systems. However, if you want to fiddle around a bit by yourself and try to optimize
things further, here is a description of the relevant configuration parameters.
opencl_async_pixelpipe
1his boolean flag controls how often we block the OpenCL pixelpipe and get a status on
success/failure of all the kernels that have been run. For optimum latency set this to 1PUE,
so darktable runs the pixelpipe asynchronously and tries to use as few interrupts as pos-
sible. lf you experience OpenCL errors like failing kernels, set the parameter to FALSE.
darktable will then interrupt after each module so you can more easily isolate the prob-
lem. Problems have been reported with some older A1l/AMD cards, like HDS7xx, which
can produce garbled output if this parameter is set to 1PUE. lf in doubt, leave it at its de-
fault FALSE.
opencl_number_event_handles
Event handles are used so we can monitor success/failure of kernels and profiling info
even if the pixelpipe is run asynchronously. 1he number of event handles is a limited re-
source of your OpenCL driver. For sure we can recycle them, but there is a limited number
that we can use at the same time. Unfortunately, there is no way to find out what the re-
source limits are, so we need to guess. Our default value of 2S is quite conservative. You
might want to try if higher values like 100 give better OpenCL performance. lf your driver
runs out of free handles you would experience failing OpenCL kernels with error code -S
(CL_OU1_OF_PESOUPCES) or even crashes or system freezes, reduce the number again
in that case. A value of 0 will block darktable from using any event handles. 1his will pre-
vent darktable from properly monitoring the success of your OpenCL kernels but saves
some driver overhead. 1he consequence is that any failures will likely lead to garbled out-
put without darktable taking notice, only recommended if you know for sure that your
system runs rock-solid. You can also set this parameter to -1, which means that darktable
assumes no restriction in the number of event handles, this is not recommended.
opencl_synch_cache
1his parameter, if set to 1PUE, will force darktable to fetch image buffers from your CPU
after each module and store them in its pixelpipe cache. 1his is a very resource consuming
operation. lt only makes sense if you have a rather slow CPU. ln that case darktable might
in fact save some time when module parameters have changed, as it can go back to some
cached intermediate state and reprocess only part of the pixelpipe. ln most cases this
parameter should be set to FALSE (default).
opencl_micro_nap
ln an ideal case you keep your CPU busy at 100% when reprocessing the pixelpipe. 1hat's
good. On the other hand your CPU is also needed to do regular CUl updates. lt might
happen that there is no sufficient time left for this task. Consequence would by a |erky
reaction of your CUl on panning, zooming or when moving sliders. darktable can add small
naps into its pixelpipe processing to have the CPU catch some breath and do CUl related
stuff. Parameter opencl_micro_nap controls the duration of these naps in microseconds.
You need to experiment in order to find an optimum value for your system. Values of 0,
100, S00 and 1000 are good starting points to try. Defaults to 1000.
opencl_use_pinned_memory
During tiling huge amounts of memory need to be transferred between host and device.
On some devices (namely AMD) direct memory transfers to and from an arbitrary host
memory region may give a huge performance penalty. 1his is especially noticeable when
180
exporting large images. Setting this configuration parameter to 1PUE tells darktable to
use a special kind of intermediate buffer for host-device data transfers. On some devices
this can speed up exporting of large files by a factor of 2 to 3. NVlDlA devices and drivers
seem to have a more efficient memory transfer technique even for arbitrary memory re-
gions. 1hey may deliver better performance if opencl_use_pinned_memory is left at its
default FALSE.
8.2.7.Multiple OpenCL devices
While most systems will only have one OpenCL capable CPU installed, darktable is also
able to make use of multiple devices in parallel. 1here is a configuration parameter which
helps to optimize CPU priorities in that case.
lt is important to understand how darktable uses OpenCL devices. Each processing se-
quence of an image - to convert an input to the final output using a certain history stack
- is run in a so called pixelpipe. 1here are four different types of pixelpipe in darktable.
One type is responsible to process the center image view (or full view) in darkroom mode,
another pixelpipe processes the preview image (navigation window) top left in darkroom
mode. Of each of these two pixelpipe there can be one at a time - with the full and the
preview pixelpipe running in parallel. ln addition there can be multiple parallel pixelpipes
doing file exports and there can be multiple parallel pixelpipes generating thumbnails. lf
an OpenCL device is available darktable dynamically allocates it to one specific pixelpipe
for one run and releases it afterwards.
1he computational demand depends a lot on the pixelpipe type. Preview image and
thumbnails have a low resolution and can be processed quickly, center image view is more
demanding, let alone the pixelpipe doing a file export. lf you have a reasonably fast CPU
and want to get a low latency during interactive work, it is therefore important that your
CPU is allocated to do the more demanding center image (full) pixelpipe, while the smaller
preview image can be processed in parallel by the CPU. Older versions of darktable would
therefore not allow the preview pixelpipe to grab any OpenCL device.
Starting with darktable 1.2 there is a more flexible scheme to allocate and prioritize your
OpenCL device(s). Configuration parameter opencl_device_priority holds a string with
the following structure:
a,b,c.../k,l,m.../o,p,q.../x,y,z...

Each letter represents one specific OpenCL device. 1here are four fields in the parame-
ter string separated by a slash, each representing one type of pixelpipe. a,b,c... defines
the devices that are allowed to process the center image (full) pixelpipe. Likewise devices
k,l,m... can process the preview pixelpipe, devices o,p,q... the export pixelpipes and
finally devices x,y,z... the thumbnail pixelpipes. An empty field means that no OpenCL
device may serve this type of pixelpipe.
darktable has an internal numbering system, where the first available OpenCL device will
receive number 0. All further devices are numbered consecutively. 1his number together
with the device name is displayed when you start darktable with darktable -d opencl.
You can specify a device either by number or by name (upper/lower case and whitespace
do not matter). lf you have more than one device - all with the same name - you need to
use the device numbers in order to differentiate them.
A device specifier can be preceded by an exclamation mark !, in which case the device
is excluded from processing this pixelpipe. You can also give an asterisk * as a wildcard,
representing all devices not mentioned explicitly before in that group.
181
Sequence order within a group matters. darktable will read the list from left to right and
whenever it tries to allocate an OpenCL device to a pixelpipe it will scan the devices in
that order, taking the first free device it finds.
darktable's default setting for opencl_device_priority is:
*/!0,*/*/*

Any detected OpenCL device is allowed to process our center view image. 1he first Open-
CL device (0) is not allowed to process the preview pixelpipe. As a consequence, if there is
only one CPU owned by your system, preview pixelpipe will always be processed on CPU,
keeping your single CPU exclusively for the more demanding center image view. 1his is
reasonable and identical to the old behavior. No restrictions apply to export and thumb-
nail pixelpipes.
1he default is a good choice if you have only one device. lf you have several devices it forms
a reasonable starting point. However, as your devices might have quite different levels of
processing power, it makes sense to invest a few thoughts and optimize your priority list.
Here is an example. Let's assume we have a system with two devices, a fast Padeon
HD79S0 and an older and slower CeForce C1S4S0. darktable (started with darktable -d
opencl) will report the following devices:
[opencl_init] successfully initialized.
[opencl_init] here are the internal numbers and names of
OpenCL devices available to darktable:
[opencl_init] 0 'GeForce GTS 450'
[opencl_init] 1 'Tahiti'
[opencl_init] FINALLY: opencl is AVAILABLE on this system.

So the CeForce C1S 4S0 is detected as the first device, the Padeon HD79S0 ('1ahiti') as
the second one. 1his order will normally not change unless the hardware or driver config-
uration is modified. But it's better to use device names rather than numbers to be on the
safe side.
As the C1S4S0 is slower than the HD79S0, an optimized opencl_device_priority could look
like:
!GeForce GTS450,*/!Tahiti,*/Tahiti,*/Tahiti,*

1he C1S4S0 is explicitly excluded from doing the center image pixelpipe, this is reserved
to all other devices (i.e. the HD79S0/1ahiti). Completely the opposite for our preview
pixelpipe. Here the 1ahiti is excluded, so that only the C1S4S0 will be allowed to do the
work.
For file export and thumbnail generation we want all hands on deck. However, darktable
should first look if device 1ahiti is free, because it's faster. lf that's not the case, all other
devices - in fact only the C1S4S0 - are checked.
8.2.8.OpenCL still does not run for me!
As has been said before OpenCL systems come with a huge variety of setups: different
CPU manufacturers, different CPU models, varying amounts of CPU memory, different
182
drivers, different distributions etc. Many of the potential problems will only appear with
a very specific combination of those factors.
As we developers of darktable on our computers only have access to a small fraction of
those variations, please understand that we might not be able to fix your specific problem.
1here is not much we can do, if there is no way for us to reproduce.
lf nothing else helps, the best option might be to start darktable with
darktable --disable-opencl

ln the end there is nothing in darktable which only runs on CPU. Don't let OpenCL discour-
age you, also darktable's CPU code is highly optimized for performance!
183
Index
B
base curve, 61
basic workflow, 8
blending, 38
blending operators, 41
bloom, 98
brightness, 63
(see also levels)
(see also tone curve)
brush, 43
C
camera import, 21
channel mixer, 72
chromatic aberration, 88
(see also lens correction)
circle, 43
clarity (see equalizer)
cloning, 8S
collect images, 23
collections, 16, 23
color balance, 77
color contrast, 7S
color correction, 7S
color labels, 16
color management
display profile, 7S
gamut check, 7S
input color profile, 79
output color profile, 74
softproof, 7S
unbreak input profile, 79
color mapping, 100
color picker, S1
color zones, 77
colorize, 99
comboboxes, 36
command line parameters, 3
conditional blending, 4S
contrast, 63
(see also levels)
(see also tone curve)
copy images, 26
create images, 26
crop and rotate, S8
cropping an image, S8
D
darkroom, 33-108
darkroom panels, S0-S7
bottom panel, S6
color picker, S1
filmstrip, S7
histogram, S4
history stack, S0
mask manager, S2
module groups, S4
more modules, S6
navigation, S0
overexposed warning, S6
snapshots, S0
underexposed warning, S7
darktable, vii
darktable-cli, 4
delete images, 26
demosaic, 64
denoise
bilateral, 83
equalizer, 80
non local means, 82
profiled, 82
raw, 86
display profile, 7S
dithering, 86
E
ellipse, 44
equalizer, 80
EXlF data, 24
export, 30
exposure, 62
F
file export, 30
file import, 21
fill light, 66
film rolls, 16
filtering, 17
focus detection, 14
framing, 90
G
geo tagging, 29
global tonemap, 71
CPU computing, 17S
gradient, 4S
graduated density, 102
grain, 9S
group images, 17, 26
H
HDP images, 23, 26
highlight reconstruction, 6S
highpass, 9S
histogram, S4
184
history stack, 27, S0
hotpixels, 87
I
image information, 24
import, 21
HDP files, 23
LDP files, 23
PAW files, 22
input color profile, 79
invert, 66
L
lens correction, 84
levels, 67
lighttable panels
collect images, 23
export, 30
geo tagging, 29
history stack, 27
image information, 24
import, 21
metadata editor, 29
recently used collections, 24
selected images, 2S
selecting images, 2S
styles, 28
tagging, 29
lighttable view, 13-32
local ad|ustments, 42
local contrast, 70
(see also equalizer)
local copies, 19, 26
lowlight, 97
lowpass, 96
Lua, 131-170
Lua APl, 134
#, 136, 137, 141, 143, 162, 163, 164
action_images, 137
apply, 142, 163
apply_style, 147
attach, 138, 163
attach_tag, 146
attributes, 166
blue, 1S0
bpp, 1S2, 1S3, 1S7
cache_dir, 139
callback, 164, 164, 16S, 16S
comp_type, 1S6
configuration, 139
config_dir, 139
copy, 144
create, 137, 141
create_style, 147
creator, 147
darktable, 134
database, 142
debug, 14S, 14S
delete, 138, 142, 162, 163
description, 148, 163
detach, 138, 163
detach_tag, 146
disk, 144
dt_imageio_module_format, 1S1
dt_imageio_module_format_data_copy, 1S4
dt_imageio_module_format_data_exr, 1S3
dt_imageio_module_format_data_|2k, 1S6
dt_imageio_module_format_data_|peg, 1SS
dt_imageio_module_format_data_pfm, 1S4
dt_imageio_module_format_data_png, 1S2
dt_imageio_module_format_data_ppm, 1SS
dt_imageio_module_format_data_tiff, 1S2
dt_imageio_module_format_data_webp, 1S6
dt_imageio_module_storage, 1S7
dt_imageio_module_storage_data_disk, 161
dt_imageio_module_storage_data_email, 146
dt_imageio_module_storage_data_facebook,
1S9
dt_imageio_module_storage_data_flickr, 1S8
dt_imageio_module_storage_data_gallery,
161
dt_imageio_module_storage_data_latex, 1S9
dt_imageio_module_storage_data_picasa,
160
dt_lua_film_t, 162
dt_lua_image_t, 146
dt_lua_tag_t, 163
dt_style_item_t, 163
dt_style_t, 162
dump, 14S
duplicate, 142, 143, 147, 162
duplicate_index, 147
email, 144
events, 164
exif_aperture, 148
exif_crop, 149
exif_datetime_taken, 148
exif_exposure, 148
exif_focal_length, 148
exif_focus_distance, 149
exif_iso, 148
exif_lens, 148
exif_maker, 148
exif_model, 148
exr, 144
extension, 1S1, 1S2, 1S3, 1S3, 1S4, 1S4, 1SS,
1SS, 1S6, 1S7
extra_registration_parameters, 164, 16S, 16S,
166
18S
facebook, 14S
filename, 147, 160, 161, 162
film, 147
films, 136
find, 138
flickr, 14S
format, 143, 1S7
gallery, 14S
get_group_members, 1S0
get_tags, 138, 147
green, 1S0
group_leader, 1S1
group_with, 1S0
gui, 136
has_equal, 166
has_gui, 139
has_ipairs, 166
has_length, 166
has_pairs, 166
has_tostring, 166
height, 146, 149, 1S8, 1S9, 1S9, 160, 160, 161,
162
hint, 1S6
hovered, 137
id, 147, 162
implicit_yield, 166
import, 143
intermediate-export-image, 164
is_hdr, 149
is_ldr, 149
is_raw, 149
|2k, 144
|peg, 144
latex, 144
latitude, 149
longitude, 149
make_group_leader, 1S0
max_height, 1S1, 1S2, 1S3, 1S3, 1S4, 1S4, 1SS,
1S6, 1S6, 1S7
max_width, 1S1, 1S2, 1S3, 1S31J
1S6U, Ug-AUU U49 U161U{
1Sl,p { {filight,- UaUUUU
1
{
{
H
U
l
s

.
|
H

O
U

.
U

.
U

.
o
{
H
U
1

.
U
U
1
{
H
U
H
U
H
U
U
H
U
H
U
U
H
U
H
U

.
U
H
U
H
U
U
H
U
-
_
p
a
i
r
m
,
p
U

U
K

.
U
H
U
U

U
t
,
y

.
U
H
X
U
H
l
3
l
|

l
|
O
H

186
path, 44
masks, 42-49
combined masks, 48
drawn masks, 42
parametric masks, 4S
memory setup, 172-174
32-bit systems, 173
64-bit systems, 174
metadata editor, 29
module groups, SS
module presets, 36
module usage, 3S
comboboxes, 36
sliders, 3S
modules, S8-104
base curve, 61
bloom, 98
channel mixer, 72
chromatic aberration, 88
color balance, 77
color contrast, 7S
color correction, 7S
color mapping, 100
color zones, 77
colorize, 99
contrast brightness saturation, 63
crop and rotate, S8
demosaic, 64
denoise - bilateral, 83
denoise - non local means, 82
denoise - profiled, 82
dithering, 86
equalizer, 80
exposure, 62
fill light, 66
framing, 90
global tonemap, 71
graduated density, 102
grain, 9S
highlight reconstruction, 6S
highpass, 9S
hotpixels, 87
input color profile, 78
invert, 66
lens correction, 84
levels, 67
local contrast, 70
lowlight, 97
lowpass, 96
monochrome, 76
output color profile, 74
raw denoise, 86
shadows and highlights, S9
sharpen, 80
soften, 94
splittoning, 91
spot removal, 8S
tone curve, 67
tonemapping, 71
unbreak input profile, 79
velvia, 72
vibrance, 78
vignetting, 92
watermark, 88
white balance, 6S
zone system, 69
monitor profile, 7S
monochrome, 76
more modules, S6
move images, 26
multiple instances, 37
N
navigation, S0
noise removal (see denoise)
O
OpenCL, 17S-182
output color profile, 74
overexposed warning, S7
P
path, 44
Preface, vii
preferences and settings, 119-129
core options, 123
CUl options, 120
presets, 128
shortcuts, 12S
presets, 128
module presets, 36
program invocation, 3
R
recently used collections, 24
remove images, 2S
rotating an image, S8
S
saturation, 63
(see also color contrast)
(see also color zones)
(see also tone curve)
save button, 8, 18
scripting, 131
selected images, 2S
selecting images, 2S
shadows and highlights, 60
shapes (see mask shapes)
187
sharpen, 80
sidecar files, 18, 27
sliders, 3S
snapshots, S0
soften, 94
sort order, 17
splittoning, 91
spot removal, 8S
star ratings, 16
styles, 28
T
tags, 29
tethering view, 109-114
camera settings, 111
live view, 111
sessions, 111
tiling, 173
tone curve, 67
tonemapping, 71
(see also global tonemap)
U
unbreak input profile, 79
underexposed warning, S7
V
velvia, 72
vibrance, 78
vignetting, 93
W
watermark, 88
white balance, 6S
X
XMP files, 18, 27
Z
zone system, 69
zoom, 34, S0
188