overview.xml
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % darktable_dtd SYSTEM "../dtd/darktable.dtd">
%darktable_dtd;
]>
<chapter status="final" id="overview_chapter">
<chapterinfo>
<keywordset>
<keyword>darktable</keyword>
<keyword>overview</keyword>
<keyword>application</keyword>
</keywordset>
</chapterinfo>
<title>Overview</title>
<para>
darktable is an open source photography workflow application and raw developer, a virtual
lighttable and darkroom for photographers.
</para>
<para>
It 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.
</para>
<itemizedlist>
<title>General Features</title>
<listitem><para>
darktable runs on GNU/Linux / GTK3, Mac OS X / macports and Solaris 11 / GTK3.
</para></listitem>
<listitem><para>
Fully non-destructive editing.
</para></listitem>
<listitem><para>
All darktable core functions operate on 4x32-bit floating point pixel buffers for high
accuracy processing, preventing banding and color breaks.
</para></listitem>
<listitem><para>
darktable makes heavy use of <emphasis>Streaming SIMD Extensions 2</emphasis> (SSE2)
instructions of the CPU to speed up processing. In fact, darktable requires either an
SSE2-capable x86 processor or an ARM64 processor.
</para></listitem>
<listitem><para>
GPU acceleration via OpenCL (runtime detection and enabling).
</para></listitem>
<listitem><para>
Most image processing is done in CIELab color space, which is much larger than the gamut
of modern displays, printers or even human vision.
</para></listitem>
<listitem><para>
Full color managed display with softproofing and gamut-check. Built-in ICC profile support
for export: sRGB, Adobe RGB, XYZ and linear RGB.
</para></listitem>
<listitem><para>
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
collections within the base query or simple tagging by related tags are useful tools in
your every-day photo workflow.
</para></listitem>
<listitem><para>
Import a variety of standard, raw and high dynamic range image formats (e.g. JPEG, CR2,
DNG, OpenEXR, PFM, ...).
</para></listitem>
<listitem><para>
darktable has a zero-latency fullscreen, zoomable user interface through multi-level
software caches.
</para></listitem>
<listitem><para>
Tethered shooting.
</para></listitem>
<listitem><para>
The 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 (JPEG, JPEG2000, PNG, TIFF, PDF), 16-bit (PPM, TIFF),
or linear high dynamic range (PFM, EXR) images.
</para></listitem>
<listitem><para>
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.
</para></listitem>
<listitem><para>
darktable comes with more than 60 image operation modules which cover everything from
basic operations, tonal value changes, color manipulation, correction of common image
defects to artistic effects.
</para></listitem>
<listitem><para>
Many darktable modules can be combined with blending operators for even more development
options.
</para></listitem>
<listitem><para>
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 parametric mask
based on pixel values.
</para></listitem>
<listitem><para>
Most modules can exist as multiple instances. Together with the mask feature, you can let
an operation have different effects on different parts of the image.
</para></listitem>
<listitem><para>
darktable introduces a highly efficient, yet simple <quote>single-click</quote> denoiser
that always just works™. It's designed as a module where the denoising performance
only depends on camera and ISO setting. A database of profiles contains parameters for
well above 200 popular camera models.
</para></listitem>
<listitem><para>
darktable comes with a versatile scripting interface for functionality enhancement using
Lua as a scripting language.
</para></listitem>
<listitem><para>
Images containing geo coordinates can be displayed on a map with various map sources at
your choice. Geo coordinates can be assigned to images by manually placing them on the
map, or by automatically applying GPX track data.
</para></listitem>
<listitem><para>
darktable has a built-in slideshow feature that lets you display your collection of images
fullscreen.
</para></listitem>
<listitem><para>
A versatile print module lets you send your image to a connected printer with full color
management support.
</para></listitem>
</itemizedlist>
<sect1 status="final" id="program_invocation">
<title>Program invocation</title>
<indexterm>
<primary>program invocation</primary>
</indexterm>
<indexterm>
<primary>command line parameters</primary>
</indexterm>
<para>
darktable comes with two main binaries: the standard GUI variant which is started by
calling <filename>darktable</filename> and a command line interface variant which is
started by calling <filename>darktable-cli</filename> . Additionally darktable is shipped
with some further binaries for special purposes.
</para>
<sect2 status="final" id="darktable_commandline_parameters">
<title><filename>darktable</filename> binary</title>
<para>
This binary starts darktable with its GUI and full functionality; it is the standard way
of using darktable.
</para>
<para>
<filename>darktable</filename> is called with the following command line parameters:
</para>
<synopsis>darktable [-d {all,cache,camctl,camsupport,control,dev,
fswatch,input,lighttable,lua,masks,memory,nan,
opencl,perf,pwstorage,print,sql}]
[<input file>|<image folder>]
[--version]
[--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>]
[--luacmd <lua command>]
[--noiseprofiles <noiseprofiles json file>]
[--conf <key>=<value>]</synopsis>
<para>
All parameters are optional; in most cases users will start darktable without any
additional parameters in which case darktable uses suitable defaults.
<variablelist>
<varlistentry>
<term>-d</term>
<listitem><para>
This option enables debug output to the terminal. There are several subsystems of
darktable and debugging of each of them can be activated separately. You can use
this option multiple times if you want debugging output of more than one
subsystem.
</para></listitem>
</varlistentry>
<varlistentry>
<term><input file>|<image folder></term>
<listitem><para>
You may optionally supply the filename of an image or the name of a folder
containing image files. If a filename is given darktable starts in darkroom view
with that file opened. If a folder is given darktable starts in lighttable view
with the content of that folder as the current collection.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--version</term>
<listitem><para>
This option causes darktable to print its version number, a copyright notice, some
other useful information, and then terminate.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--disable-opencl</term>
<listitem><para>
This option prevents darktable from initializing the OpenCL subsystem. Use this
option in case darktable crashes at startup due to a defective OpenCL
implementation.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--library <library file></term>
<listitem><para>
darktable keeps image information in an sqlite database for fast access. The
default location of that database file is
<quote>$HOME/.config/darktable/library.db</quote>. You may give an alternative
location, e.g. if you want to do some experiments without compromising your
original library.db. If the database file does not exist, darktable creates it for
you. You may also give <quote>:memory:</quote> as a library file in which case the
database is kept in system memory – all changes are discarded when
darktable terminates.
</para>
<para>
Whenever darktable starts, it will lock the library to the current user. It does
this by writing the current process identifier (PID) into a lock file
<quote><library file>.lock</quote> next to the library specified. If
darktable finds an existing lock file for the library, it will terminate
immediately.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--datadir <data directory></term>
<listitem><para>
This option defines the directory where darktable finds its runtime data. The
default place depends on your installation. Typical places are
<quote>/opt/darktable/share/darktable/</quote> and
<quote>/usr/share/darktable/</quote>.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--moduledir <module directory></term>
<listitem><para>
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. The default place depends on your installation; typical places
are <quote>/opt/darktable/lib64/darktable/</quote> and
<quote>/usr/lib64/darktable/</quote>.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--tmpdir <tmp directory></term>
<listitem><para>
The place where darktable stores its temporary files. If this option is not
supplied darktable uses the system default.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--configdir <config directory></term>
<listitem><para>
This option defines the directory where darktable stores the user specific
configuration. The default place is <quote>$HOME/.config/darktable/</quote>.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--cachedir <cache directory></term>
<listitem><para>
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
<quote>$HOME/.cache/darktable/</quote>. There may exist multiple thumbnail caches
in parallel – one for each library file.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--localedir <locale directory></term>
<listitem><para>
The place where darktable finds its language specific text strings. The default
place depends on your installation. Typical places are
<quote>/opt/darktable/share/locale/</quote> and <quote>/usr/share/locale/</quote>.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--luacmd <lua command></term>
<listitem><para>
A string containing lua commands to execute after lua initialization. These
commands will be run after your <quote>luarc</quote> file.
</para>
<para>
If lua is not compiled in, this option will be accepted but won't do anything.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--noiseprofiles <noiseprofiles json file></term>
<listitem><para>
The json file that contains the camera specific noise profiles. The default
location depends on your installation. Typical places are
<quote>/opt/darktable/share/darktable/noiseprofile.json</quote> and
<quote>/usr/share/darktable/noiseprofile.json</quote>.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--conf <key>=<value></term>
<listitem><para>
darktable supports a rich set of configuration parameters which the user defines
in <quote>darktablerc</quote> – darktable's configuration file in the
user config directory. You may temporarily overwrite individual settings on the
command line with this option – however, these settings will not be
stored in <quote>darktablerc</quote>.
</para></listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 status="final" id="darktable_cli_commandline_parameters">
<title><filename>darktable-cli</filename> binary</title>
<indexterm>
<primary>darktable-cli</primary>
</indexterm>
<para>
This binary starts the command line interface variant of darktable which allows
exporting images.
</para>
<para>
This variant does not open any display, so it will work in pure console mode without
using any X11, wayland, etc. – this mode is useful for servers running
background jobs.
</para>
<para>
<filename>darktable-cli</filename> is called with the following command line parameters:
</para>
<synopsis>darktable-cli <input file>|<image folder>
[<xmp file>]
<output file>
[--width <max width>]
[--height <max height>]
[--bpp <bpp>]
[--hq <0|1|true|false>]
[--verbose]
[--core <darktable options>]</synopsis>
<para>
The user needs to supply an input filename and an output filename. All other parameters
are optional.
<variablelist>
<varlistentry>
<term><input file></term>
<listitem><para>
The name of the input file to export or the name of an folder containing input
images which are to be exported.
</para></listitem>
</varlistentry>
<varlistentry>
<term><xmp file></term>
<listitem><para>
The optional name of an XMP sidecar file containing the history stack data to be
applied during export. If this option is not given darktable will search for an
XMP file that belongs to the given input file(s).
</para></listitem>
</varlistentry>
<varlistentry>
<term><output file></term>
<listitem><para>
The name of the output file. darktable derives the export file format from the
file extension. You can also use all the variables available in darktable's export
module in the output filename (see <xref linkend="export_selected"/>). For obvious
reasons this is mandatory if you use the program on an image folder containing
multiple images.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--width <max width></term>
<listitem><para>
This optional parameter allows to limit the width of the exported image to that
number of pixels.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--height <max height></term>
<listitem><para>
This optional parameter allows to limit the height of the exported image to that
number of pixels.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--bpp <bpp></term>
<listitem><para>
An optional parameter to define the bit depth of the exported image; allowed
values depend on the file format. Currently this option is not yet functional. If
you need to define the bit depth you need to use the following workaround:
</para>
<synopsis>--core
--conf plugins/imageio/format/<FORMAT>/bpp=<VALUE></synopsis>
<para>
where <FORMAT> is the name of the selected output format.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--hq <0|1|true|false></term>
<listitem><para>
A flag that defines whether to use high quality resampling during export (see
<xref linkend="core_options"/>). Defaults to true.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--verbose</term>
<listitem><para>
Enables verbose output.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--core <darktable options></term>
<listitem><para>
All command line parameters following <quote>--core</quote> are passed to the
darktable core and handled as standard parameters. See
<xref linkend="darktable_commandline_parameters"/> for a detailed description.
</para></listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 status="final" id="darktable_generate_cache_commandline_parameters">
<title><filename>darktable-generate-cache</filename> binary</title>
<indexterm>
<primary>darktable-generate-cache</primary>
</indexterm>
<para>
This binary updates darktable's thumbnail cache. You can start this program to generate
all missing thumbnails in the background when your computer is idle.
</para>
<para>
<filename>darktable-generate-cache</filename> is called with the following command line
parameters:
</para>
<synopsis>darktable-generate-cache
[-h, --help]
[--version]
[--min-mip <0-7>] [-m, --max-mip <0 - 7>]
[--min-imgid <N>] [--max-imgid <N>]
[--core <darktable options>]</synopsis>
<para>
All parameters are optional. If started without parameters
<filename>darktable-generate-cache</filename> uses reasonable defaults.
<variablelist>
<varlistentry>
<term>-h, --help</term>
<listitem><para>
Gives usage information and terminates.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--version</term>
<listitem><para>
Gives copyright and version information and terminates.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--min-mip <0 - 7></term>
<term>-m, --max-mip <0 - 7></term>
<listitem><para>
darktable can handle and store thumbnails with up to eight different resolution
steps for each image. These parameters define which maximum resolution should be
generated and default to a range of 0-2. There is normally no need to generate all
possible resolutions here; missing ones will be automatically generated by
darktable the moment they are needed. When asked to generate multiple resolutions
at once, the lower-resolution images are quickly downsampled from the
highest-resolution image.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--min-imgid <N></term>
<term>--max-imgid <N></term>
<listitem><para>
Specifies the range of internal image IDs from the database to work on. If no
range is given, darktable-generate-cache will process all images from the entire
collection.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--core <darktable options></term>
<listitem><para>
All command line parameters following <quote>--core</quote> are passed to the
darktable core and handled as standard parameters. See
<xref linkend="darktable_commandline_parameters"/> for a detailed description.
</para></listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 status="final" id="darktable_chart_commandline_parameters">
<title><filename>darktable-chart</filename> binary</title>
<indexterm>
<primary>darktable-chart</primary>
</indexterm>
<para>
This binary is a dedicated utility to create styles out of pairs of images such as
RAW+JPEG with in-camera processing. Details about its usage can be found in
<xref linkend="darktable_chart"/>.
</para>
<para>
<filename>darktable-chart</filename> either starts a GUI or is used as a command-line
program.
</para>
<synopsis>darktable-chart
[--help]
[<input Lab pfm file>]
[<cht file>]
[<reference cgats/it8 or Lab pfm file>]</synopsis>
<para>
All parameters are optional, however, if you want to supply the second file name you
also need to supply the first one etc. Starting <filename>darktable-chart</filename>
this way opens a special GUI (details can be found in
<xref linkend="darktable_chart"/>).
<variablelist>
<varlistentry>
<term>--help</term>
<listitem><para>
Gives usage information and terminates.
</para></listitem>
</varlistentry>
<varlistentry>
<term><input Lab pfm file></term>
<listitem><para>
Opens the utility with the given file as source image. The input file needs to be
in Lab Portable Float Map format.
</para></listitem>
</varlistentry>
<varlistentry>
<term><cht file></term>
<listitem><para>
Specifies a chart file describing the layout of the used color reference chart.
</para></listitem>
</varlistentry>
<varlistentry>
<term><reference cgats/it8 or Lab pfm file></term>
<listitem><para>
Specifies the reference values, either as measured values according to the CGATS
standard, or as a reference image in Lab Portable Float Map format.
</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
Alternatively <filename>darktable-chart</filename> can be used as a command line program
to generate darktable style files out of previously saved CSV files.
</para>
<synopsis>darktable-chart
--csv
<csv file>
<number patches>
<output dtstyle file></synopsis>
<para>
All parameters are mandatory.
<variablelist>
<varlistentry>
<term><csv file></term>
<listitem><para>
A CSV file previously saved from within <filename>darktable-chart</filename>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><number patches></term>
<listitem><para>
The number of color patches to be used in the <emphasis>color look up
table</emphasis> settings of the created style.
</para></listitem>
</varlistentry>
<varlistentry>
<term><output dtstyle file></term>
<listitem><para>
The name of the style file to be created.
</para></listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 status="final" id="darktable_cltest_commandline_parameters">
<title><filename>darktable-cltest</filename> binary</title>
<indexterm>
<primary>darktable-cltest</primary>
</indexterm>
<para>
This binary checks if there is a usable OpenCL environment on your system that darktable
can use. It emits some debug output that is equivalent to calling <quote>darktable -d
opencl</quote> and then terminates.
</para>
<para>
<filename>darktable-cltest</filename> is called without command line parameters:
</para>
<synopsis>darktable-cltest</synopsis>
</sect2>
<sect2 status="final" id="darktable_cmstest_commandline_parameters">
<title><filename>darktable-cmstest</filename> binary</title>
<indexterm>
<primary>darktable-cmstest</primary>
</indexterm>
<para>
This binary investigates if the color management subsystem of your computer is correctly
configured and it displays some useful information about the installed monitor
profile(s).
</para>
<para>
<filename>darktable-cmstest</filename> is called without command line parameters:
</para>
<synopsis>darktable-cmstest</synopsis>
</sect2>
</sect1>
<sect1 status="final" id="user_interface">
<title>User interface</title>
<informaltable frame="none">
<tgroup cols="2" colsep="0" rowsep="0">
<colspec colwidth='6*'/>
<colspec colwidth='4*'/>
<tbody>
<row>
<entry>
<para>
This section describes the layout of the user interface.
</para>
</entry>
<entry>
<graphic fileref="images/lighttable_view.png" scalefit="1" width="80%" align="center" />
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<sect2 status="final" id="views">
<title>Views</title>
<para>
darktable consists of several views or modes. There are five 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:
<informaltable frame="none" width="60%">
<tgroup cols="2" colsep="0" rowsep="0">
<colspec colwidth='1*'/>
<colspec colwidth='9*'/>
<tbody>
<row>
<entry>
<emphasis>l</emphasis>
</entry>
<entry>
switches to lighttable
</entry>
</row>
<row>
<entry>
<emphasis>d</emphasis>
</entry>
<entry>
switches to darkroom
</entry>
</row>
<row>
<entry>
<emphasis>t</emphasis>
</entry>
<entry>
switches to camera tethering
</entry>
</row>
<row>
<entry>
<emphasis>m</emphasis>
</entry>
<entry>
switches to map
</entry>
</row>
<row>
<entry>
<emphasis>s</emphasis>
</entry>
<entry>
switches to slideshow
</entry>
</row>
<row>
<entry>
<emphasis>p</emphasis>
</entry>
<entry>
switches to print
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<sect3 status="final">
<title>Lighttable</title>
<para>
The lighttable view is where images and film rolls are managed. It's also where you
rate images, add tags and colorlabels, and export images among other actions (see
<xref linkend="lighttable_chapter"/>).
</para>
</sect3>
<sect3 status="final">
<title>Darkroom</title>
<para>
In the darkroom view you develop a single image using the available modules (see
<xref linkend="darkroom_chapter"/>).
</para>
</sect3>
<sect3 status="final">
<title>Tethering</title>
<para>
This view is for shooting with the camera connected to the computer and remotely
capturing images that will be downloaded and shown on computer screen (see
<xref linkend="tethering_chapter"/>).
</para>
</sect3>
<sect3 status="final">
<title>Map</title>
<para>
This view shows images with geo-tag data on a map and allows manually geo-tagging new
images (see <xref linkend="map_chapter"/>).
</para>
</sect3>
<sect3 status="final">
<title>Slideshow</title>
<para>
This view shows images as a slideshow, processing them on-the-fly (see
<xref linkend="slideshow_chapter"/>).
</para>
</sect3>
<sect3 status="final">
<title>Print</title>
<para>
This view allows you to send images to your printer (see
<xref linkend="print_chapter"/>).
</para>
</sect3>
</sect2>
<sect2 status="final" id="screen_layout">
<title>Screen layout</title>
<para>
The general screen layout of all views is similar. There is a center area which contains
most of the relevant information of that view. Then there are panels left, right, top
and bottom to the center area. The left panel typically has an informational purpose.
The right panel offers functions to modify an image. The 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
<inlinegraphic fileref="&icon_general_collapse;" scalefit="1" width="2%"/>
, located close to the panel.
</para>
<para>
By pressing the <emphasis>TAB</emphasis> key all panels get collapsed, allowing the
center area to occupy all available space. Pressing <emphasis>TAB</emphasis> again
brings you back to the previous view.
</para>
<para>
Fullscreen view can be toggled by pressing <emphasis>F11</emphasis>.
</para>
</sect2>
<sect2 status="final" id="filmstrip_overview">
<title>Filmstrip</title>
<indexterm>
<primary>filmstrip</primary>
</indexterm>
<para>
The filmstrip along the bottom shows the same images as lighttable, with respect to
filters and sort order. It is turned on/off with key accelerator
<emphasis>ctrl-f</emphasis>. You can navigate along the filmstrip by scrolling with the
mouse wheel and change the height of the filmstrip panel by dragging its top. The
filmstrip allows you to interact with images while you are not in lighttable mode. For
example, you can, while developing an image in darkroom mode, switch to another image to
develop, by double clicking the thumbnail in the filmstrip. You can also rate the images
as you do in lighttable, copy/paste history stack, etc.
</para>
<para>
<graphic fileref="overview/images/filmstrip.png" scalefit="1" width="80%" align="center" />
</para>
</sect2>
<sect2 status="final" id="preferences">
<title>Preferences</title>
<para>
A button
<inlinegraphic fileref="&icon_preferences;" scalefit="1" width="2%" align="center" />
located in the upper panel allows you to define various parameters which control
darktable's behavior.
</para>
<para>
The options are fairly self-explanatory. If you need more information, hover the mouse
cursor over the text label or entry box, to display a popup tool-tip. All configuration
parameters are explained in <xref linkend="preferences_chapter"/>.
</para>
</sect2>
</sect1>
<sect1 status="final" id="darktable_basic_workflow">
<title>darktable basic workflow</title>
<indexterm>
<primary>basic workflow</primary>
</indexterm>
<para>
This section describes a typical darktable workflow which novice users may take as a
starting point. We describe how to get an image into darktable, the basic steps of a raw
development workflow and how to export the final result.
</para>
<sect2 status ="final">
<title>Importing images</title>
<para>
To begin with darktable, you first need to import images. The import module is in the
left panel of the lighttable view (<xref linkend="import"/>). You can either import from
the filesystem or, if darktable supports your camera model, directly from camera.
</para>
<sect3 status="final">
<title>Importing images from filesystem</title>
<para>
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.
</para>
</sect3>
<sect3 status="final">
<title>Importing from camera</title>
<para>
Connect your camera to your system. If your distribution tries to automount it, select
the option to abort the mount operation. Otherwise the camera will be locked and not
accessible from within darktable. If you don't see your camera in the import module,
hit the <quote>scan for devices</quote> button. Your camera will then appear in the
same module with additional choices: <emphasis>import</emphasis> and
<emphasis>tethering</emphasis>.
</para>
</sect3>
</sect2>
<sect2 status="final" id="basic_development_steps">
<title>Basic development steps</title>
<sect3>
<title>Introduction</title>
<para>
This section will guide you through the basics of developing an image in the darkroom
view.
</para>
<para>
To begin, open an image in darkroom mode by double clicking an image thumbnail on the
lighttable. The darkroom mode is where the actual adjustments for an image are made,
where an arsenal of modules are at hand to help you reach your goal.
</para>
<para>
Each change made on a module while developing an image is turned into a
<link linkend="history"><emphasis>history stack</emphasis></link> item. The history is
stored in a database and in an XMP sidecar file for the specific image.
</para>
<para>
All changes are stored automatically when you switch images or go from one darktable
view to another. You can safely leave darkroom mode or quit darktable at any time and
come back later to continue your work. That said darktable does not need a
<quote>save</quote> button and it does not have one.
<indexterm>
<primary>save button</primary>
</indexterm>
</para>
<para>
On the left panel in darkroom mode is the <link linkend="history"><emphasis>history
stack</emphasis></link>, 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. The 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, just compress the history stack.
</para>
<para>
darktable ships with a number of modules, arranged into groups. These module groups
are accessed via toggle buttons in the right panel, just under the histogram. There
are also two special module groups named <quote>active</quote> and
<quote>favorites</quote>, which only show modules enabled in the history for the
current image, and modules selected as a favorite, respectively. Marking a module as a
favorite is done in the <emphasis>more modules</emphasis> dialog
(<xref linkend="more_modules"/>), at the bottom of the right panel, by clicking a
module until a star is displayed in front of the icon.
</para>
</sect3>
<sect3 status="final">
<title>White balance</title>
<para>
The <link linkend="whitebalance"><emphasis>white balance</emphasis></link> module
controls the white balance or color temperature of the image. It's always enabled and
reads its default values from camera metadata embedded in the image. The most common
change is fine-tuning the white balance, which is done using the
<quote>temperature</quote> slider. Moving this slider left will make the color balance
cooler, and moving it right will make it warmer.
</para>
</sect3>
<sect3 status="final">
<title>Exposure correction</title>
<para>
The <link linkend="exposure"><emphasis>exposure</emphasis></link> 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
<link linkend="histogram"><emphasis>histogram</emphasis></link>. You can also boost
the black level to enhance contrast; but be careful: use small amounts, like steps of
0.005. There is also an auto-correct feature.
</para>
</sect3>
<sect3 status="final">
<title>Noise reduction</title>
<para>
The best starting point for noise reduction is
<link linkend="denoise_profiled"><emphasis>profiled denoise</emphasis></link>. This
module offers an almost <quote>single-click</quote> solution to fight noise. From a
user perspective the effect only depends on camera type and ISO value, both derived
from Exif data. All other settings are taken from a database of noise profiles that
the darktable team has collected – now covering well above 200 popular
camera models. In addition you have several other options in darktable to reduce
noise. There is <link linkend="raw_denoise"><emphasis>raw denoise</emphasis></link>,
<link linkend="denoise_bilateral"><emphasis>denoising based on bilateral
filter</emphasis></link>, <link linkend="denoise_non_local_means"> <emphasis>denoising
based on non-local means</emphasis></link>, and
<link linkend="equalizer"><emphasis>equalizer</emphasis></link>, which is based on
wavelets. If your camera is not yet supported by
<link linkend="denoise_profiled"><emphasis>profiled denoise</emphasis></link>,
<link linkend="denoise_non_local_means"><emphasis>denoising based on non-local
means</emphasis></link> is probably the most convenient, as it allows you to treat
color and luminance noise separately.
</para>
</sect3>
<sect3 status="final">
<title>Fixing spots</title>
<para>
Sometimes you will need to remove spots caused by sensor dirt. The
<link linkend="spot_removal"><emphasis>spot removal</emphasis></link> module is at
hand and can also correct other disturbing elements like skin blemishes. If your
camera has stuck pixels or tends to produce hot pixels at high ISO values or longer
exposure times, have a look at the <link linkend="hotpixels"><emphasis>hot
pixels</emphasis></link> module for automatic correction.
</para>
</sect3>
<sect3 status="final">
<title>Geometrical corrections</title>
<para>
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. In other cases, the horizon
in the image may need levelling, or there are perspective distortions. All this can be
corrected with full manual control in the
<link linkend="crop_and_rotate"><emphasis>crop and rotate</emphasis></link> module.
For a fully automatic correction of perspective distortions you may alternatively
visit the <link linkend="perspective_correction"><emphasis>perspective
correction</emphasis></link> module. If you need to correct typical camera lens flaws
like cushion distortion, transversal chromatic aberrations or vignetting, there is a
<link linkend="lens_correction"><emphasis>lens correction</emphasis></link> module.
</para>
</sect3>
<sect3 status="final">
<title>Bringing back detail</title>
<para>
Digital raw images often contain more information than you can see at first sight.
Especially in the shadows of an image, there are lots of hidden details. The
<link linkend="shadows_and_highlights"><emphasis>shadows and
highlights</emphasis></link> 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. However, you can correct unfavorable color casts in
these areas with the <link linkend="highlight_reconstruction"><emphasis>highlight
reconstruction</emphasis></link> module. Additionally the
<link linkend="color_reconstruction"><emphasis>color reconstruction</emphasis></link>
module is able to fill overexposed areas with suitable colors based on their
surroundings.
</para>
</sect3>
<sect3 status="final">
<title>Adjusting tonal values</title>
<para>
Almost every workflow is likely to include adjusting the image's tonal range.
darktable offers several alternative modules to take care of that. The most basic one
is the <link linkend="contrast_brightness_saturation"><emphasis>contrast brightness
saturation</emphasis></link> module. In the <link linkend="tone_curve"><emphasis>tone
curve</emphasis></link> module, tonal values are adjusted by constructing a gradient
curve. The <link linkend="levels"><emphasis>levels</emphasis></link> module offers a
concise interface, with three markers in a histogram. In addition, there is a
<link linkend="zone_system"><emphasis>zone system</emphasis></link> module which
allows control over tonal values by zones, inspired by the work of Ansel Adams.
</para>
</sect3>
<sect3 status="final">
<title>Enhancing local contrast</title>
<para>
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. The <link linkend="local_contrast"><emphasis>local
contrast</emphasis></link> module is easy to handle, with just a few parameters. A
much more versatile, but also more complex, technique is offered by the
<link linkend="equalizer"><emphasis>equalizer</emphasis></link> module. Have a look at
its presets, to get a feeling for how it works. Equalizer is darktable's "Swiss Army
Knife" for many adjustments where spatial dimension plays a role.
</para>
</sect3>
<sect3 status="final">
<title>Color adjustments</title>
<para>
darktable offers many modules for adjusting colors in an image. A very straightforward
technique is implemented in the <link linkend="color_correction"><emphasis>color
correction</emphasis></link> module. Use it to give an image an overall tint or to
adjust overall color saturation. The <link linkend="color_zones"><emphasis>color
zones</emphasis></link> module offers a much finer control to adjust saturation, or
lightness, and even hue, in user defined zones. darktable's
<link linkend="tone_curve"><emphasis>tone curve</emphasis></link> module –
in addition to the classical adjustment 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
<link linkend="monochrome"><emphasis>monochrome</emphasis></link> module.
Alternatively, you might consider using darktable's
<link linkend="channel_mixer"><emphasis>channel mixer</emphasis></link>.
</para>
</sect3>
<sect3 status="final">
<title>Sharpening</title>
<para>
If you start your workflow from a raw image, you will need to have your final output
sharpened. The <link linkend="sharpen"><emphasis>sharpen</emphasis></link> 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 <link linkend="highpass"><emphasis>highpass</emphasis></link> module,
in combination with darktable's rich set of blending operators.
</para>
</sect3>
<sect3 status="final">
<title>Artistic effects</title>
<para>
darktable comes with a rich set of artistic effect modules. To name just a few: with
the <link linkend="watermark"><emphasis>watermark</emphasis></link> module you add an
individual watermark to your image. The
<link linkend="grain"><emphasis>grain</emphasis></link> module simulates the typical
noise of classical analogue footage. Use the
<link linkend="color_mapping"><emphasis>color mapping</emphasis></link> module to
transfer the look and feel of one color image onto another. darktable's
<link linkend="low_light"><emphasis>low light</emphasis></link> module allows to
simulate human vision to make lowlight pictures look closer to reality. The
<link linkend="graduated_density"><emphasis>graduated density</emphasis></link> filter
adds a neutral or colored gradient to your image for exposure and color correction.
</para>
</sect3>
</sect2>
<sect2 status="final" id="exporting_images">
<title>Exporting images</title>
<para>
Changes to an image are not saved as in a regular image editor. darktable is a
non-destructive editor, which means all changes are stored in a database, and the
original image is untouched. Therefore, you need to export images to bake the processing
options into an output file that can be distributed outside of darktable.
</para>
<para>
Images are exported from the lighttable view, using the <emphasis>export
selected</emphasis> dialog in the right panel (<xref linkend="export_selected"/>). In
general, export means: save my developed raw image as a JPEG.
</para>
<para>
The export is modularized into <emphasis>storage</emphasis> and
<emphasis>format</emphasis>. darktable ships with several storage modules such as
<emphasis>save on disk</emphasis>, various webalbums, a LaTeX photo book template and
more. Format modules are the actual image formats such as JPEG, PNG, TIFF, OpenEXR and
more.
</para>
<para>
Select images on the lighttable, choose the target storage and format, and set the
maximum width and height image restraints. This 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.
</para>
</sect2>
</sect1>
</chapter>
