Special Topics on darktable 5.6 user manual

memory & performance tuning

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

🔗memory requirements

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

variables

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

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

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

🔗available variables

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

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

🔗metadata

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

darktable's color pipeline

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

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

midi device support

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

🔗introduction

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