GUI toolboxes

Write per-image notes that live next to your files and render as Markdown. Such notes can be to-do lists, memos, contacts of the persons in the image, tips or instructions for collaborators, etc.

The module opens in preview by default; switch to edit to change the source text. The Markdown parsing needs Ansel to be build with CMark , which is optional. If Ansel was not built with this library, it will be rendered as plain text.

Highlight areas of the image that may exhibit luminance or gamut clipping.

When an image is sent to a display device, each pixel is normally represented as a set of 3 numbers, representing the intensity of the red, green and blue primary colors in the output color space. Because the output color space is usually closely related to hardware with physical limations, there is a maximum permitted value for the [R,G,B] channels, representing the maximum available intensity for that color space. Similarly, there is also a minimum value below which pixel values will be mapped to zero. When we try to convert from a larger color space to the final output color space, any values exceeding this maximum will be clamped to the maximum value, and any values below the minimum will be clamped to zero. This process is called “clipping” and it will lead to lost detail, or “incorrect” colors for any pixels with clipped channels.

Assess colors and brightness in your image using ISO 12646:2008 recommended viewing conditions.

When developing an image, the way we perceive brightness, contrast and saturation is influenced by the surrounding ambient conditions. If an image is displayed against a dark background, this can have a number of adverse effects on our perception of that image:

• Exaggeration of the perceived exposure makes the image seems brighter than it really is. This is nicely illustrated by the Adelson checkerboard shadow effect .
• A decrease in the perceived saturation in the image makes the colors seem less rich than they really are (the Hunt effect).
• A decrease in the perceived contrast in the image makes the tones seem flatter than they really are (Bartleson-Breneman effect 3)

The end result is that the final image can end up being too dark and overly-processed in terms of contrast and color saturation. To avoid this, the “ISO 12646:2008” standard makes some recommendations about the conditions under which the colors of an image should be assessed. The color assessment module in the darkroom places a frame around the image to help the user better assess the colors in the image, along the lines of those recommendations.

Display information embedded within an image’s Exif data as well as a number of additional data fields defined by Ansel.

When hovering with the mouse over image thumbnails, the displayed data is automatically updated to show information about the image currently under the mouse cursor.

When several images are selected and the focus is not on a single image, the module only displays information that is the same for all images. If any fields differ between the images, the text “<various values>” is displayed instead.

View and create multiple versions of the current image. Each version can be edited independently without affecting other versions – all versions use the same underlying image file, but the editing history of each version is stored in its own independent XMP sidecar file.

The duplicate manager lists each version of the current darkroom image along with its preview thumbnail. Hold down the left mouse button on a thumbnail to temporarily show that version in the center view. Double-click to switch to that version and edit it.

Export selected images.

Files can be exported to a file on disk, email, various online storage locations, a web album, or a book template.

The filmstrip can be used to quickly switch between images. The images shown are the same as those displayed in the lighttable view and are defined by the currently-selected collection.

Search for a location on the map. You must be connected to the internet to use this feature.

To use this module, type in a place name or address, press Enter and a list of results will be shown. Click on an item in the list and the map will zoom to that location. An outline covering that location or a pin pointing at the location will be displayed.

An outline (polygon) can be used to create a user location. Check the max polygon points parameter in the map settings module to ensure that sufficient points are available for a polygon to be displayed.

Identify which parts of the image contain high-contrast details, like edges and textures, which usually indicates that those areas are in focus.

Activate the module by clicking on the

Focus peaking works by filtering out most of the image noise, measuring the intensity gradients in the image and calculating average and standard deviation statistics. When the gradient of an edge differs significantly from the mean, the associated pixels are marked with a “heat map” indicating how sharp the edge is.

Highlight areas of the image that may exhibit gamut clipping.

Click the

Right-click on the icon to open a dialog with configuration parameters – these are the same as for the soft proof option.

You might also like to consider using the clipping warning, which also provides under- and over-exposure warnings as well as a gamut check similar to that offered by this module.

Import and apply GPX track data to a selection of images.

This module is common to the lighttable and map views. The map view provides an enhanced mode that allows you to preview the position of the images along the GPS tracks while adjusting the images’ date/time offset and time zone.

Take color samples from the current darkroom image, display their values in multiple ways and compare colors from different locations.

The color picker is activated by pressing the color picker icon. The module’s parameters will remain in effect until you leave the darkroom mode.

Besides the global color picker described here, many Ansel modules (e.g. RGB curve) also contain local color pickers which are used to set individual module parameters. You should be aware that these two forms of color picker do not always work in the same color space. The global color picker works in the histogram color space and takes its samples after the complete pixelpipe has been processed. Local color pickers run in the color space of the module in which they are activated and reflect the input or output data of that module within the pixelpipe.

A number of commonly-used compositional guides can be overlaid on your image while you are editing. These can be enabled either globally (all the time) or locally (when certain modules are active).

Other darkroom functionality also draws colored overlay lines on the image (for example, drawn masks). An option is also provided to change the color of those overlays (see below).

global guides

Left-click the

icon in the bottom bar to globally display guide overlays. The overlays will remain switched on until you click the button a second time to switch them off.

View and modify the history stack of the current darkroom image.

This module lists every change of state (activate/de-activate/move/change parameters) for all processing modules that have been modified for the current image. Select a point in the stack to return to that point in the development history of the image. Shift+click an item in the history stack to expand that module in the right-hand module panel without changing the current edit.

Filter the images shown in the lighttable view and filmstrip panel using image attributes. This set of filtered images is known as a collection.

Importing images into Ansel stores information about them (filename, path, Exif data, data from XMP sidecar files etc.) in Ansel’s library database. A collection may be defined by applying filtering rules to these attributes, thus creating a subset of images to display in the lighttable view and the filmstrip module.

Create areas or locations and organize them as hierarchical tags.

A location is shown as a shape on the map when selected. Initially each location is represented as a square or circle and can be changed to a rectangle or ellipse by adjusting the shape’s width and/or height.

A location can also be created from an OpenStreetMap region (city/country) polygon. To achieve this, first make sure the max polygon points parameter is large enough (some country polygons use more than 150,000 points). Then select the desired location in the find location module. When the corresponding region shape is displayed, a polygon symbol becomes available in the “shape” control (see below). Select it to create the new location.

This module provides an interface for installing darktable lua scripts. The first time it is run, instructions are displayed in the module.

It can be disabled with an option in preferences > lua options.

Select preferred map data from various providers. Some will provide additional layers (satellite view etc.) which you can toggle.

Manage all masks and shapes for the current image.

This module can be used to create, rename, edit and delete shapes. You can add shapes to and remove shapes from a mask, group shapes together, and combine them using set operators.

The top line of the mask manager panel contains buttons that can be used to create new shapes. These are the same as in the drawn mask interface of in processing modules.

Edit the metadata of selected images.

Metadata is freeformat text (title, description, creator, publisher, rights etc.) that describes your images.

When several images are selected having different values for a given metadata field, the module displays for that field – if you choose to apply changes, these fields will not be changed. If you right-click on the field the different values are listed at the end of the contextual menu. Select one of the values in the menu to apply that value to all of the selected images – the change will be saved once you press the “apply” button or the Enter/Tab key.

Change the order of the processing modules in the darkroom using presets.

When processing an image, the active modules are applied in a specific order, which is shown in the right-hand panel of the darkroom view. This module provides information about the current ordering of the processing modules in the pixelpipe. The name of the currently-selected preset is shown in the module header (or “custom” if the user has manually modified the order). The following presets are available for selection.

Zoom and pan the current image.

On the top left hand side of the darkroom, the navigation panel displays a full preview of the current image with a rectangle showing the area that is currently visible in the central panel. Drag the rectangle around to pan the zoomed-in view. The 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.

Manage settings for the print view and initiate printing.

Highlight areas of the image where color channels of the raw input file are clipped.

Clipped color channels imply an overexposed image with loss of information in the affected areas. Some of this information may be recoverable using the highlight reconstruction, color reconstruction or filmic rgb modules.

Click on the

This module provides various graphical depictions of the developed image’s light levels or chromaticity.

Move the mouse over the panel to show buttons that allow you to adjust the display. The leftmost button cycles the mode between histogram, waveform scope, RGB parade scope, and vectorscope. The remaining buttons control how the plot for the current scope is drawn.

Store development snapshots and compare with the current edit.

A snapshot is a stored bitmap of the center image in the darkroom view. Snapshots can be taken at any point in the development process and later overlaid onto the current center view. This allows you to undertake a side by side comparison (by default left=snapshot, right=active edit) while you are tuning parameters of a module. This can also be combined with the history stack module to compare a snapshot against different stages of development.

View your image rendered using a selected color profile.

Click the

Create named styles from selected images’ history stacks and apply styles to selected images.

Styles can either be created within this panel or in the history stack module in the darkroom.

A list of all available styles is displayed in the module. A search field above the list allows you to locate a style by name or description. This module also allows styles to be edited and deleted.

Double-click on a style name to apply that style to all selected images. A style may also be applied to all selected images by pressing a shortcut key assigned to it (see preferences > shortcuts) while in the lighttable or darkroom view.

Manage tags attached to images.

Tags provide a means of adding information to images using a keyword dictionary. You can also manage tags as a hierarchical tree, which can be useful when their number becomes large.

Tags are physically stored in XMP sidecar files as well as in Ansel’s library database and can be included in exported images.