Index by title

Append presets from one darktable installation to another

I built the following script to migrate my presets from one darktable installation to another.
Script is "quick and dirty", but should work.
Please read the script main note for usage information.

Save the following script to file, name it append_presets.py and run it using python 2.7

"""Append presets from one darktable installation to another

Before run:
  1. backup! both db files.
  2. Make sure darktable is not running
  3. It is advised to copy the destination db to something like dest_library.db
     once append finished, you can switch between the newly modified file and the original one.

Usage: 
  python append_presets.py src.db dest.db 
  ex: python append_presets.py .config/darktable/src_library.db .config/darktable/dest_library.db
  Both source and destination DBs must be an existing valid darktable DBs!

Background:
  darktable store all presets in the ~/.config/darktable/library.db file.
  This is a sqlite3 database.
  Problems? yes! darktable store the pictures repository and much more data on the same DB.
  Which make it a bad idea to copy the DB between your laptop and desktop.
  (or just to copy your presets around)

  presets saved into the "presets" table with a unique id for each preset.
  (ID is based on preset name, operation and operation_id)
  two important columns are the op_params and the blendop_params. Both of type BLOB which make it harder to play with.

Logic:
  open the source DB and copy all the presets to memory
  open destination DB and insert all presets from the source DB
     if insert succeed, commit the insert.
     else, this preset (probably) already exist in the destination   

Script works for me (appending my presets from darktable 1.2.3 on fedora to 1.4.1 on mint)
But never tested in a professional way.
Code is "quick and dirty" as I wrote it for a one time migration.
No responsibilities assumed.

2014-04-16, izack@varsanno.com
""" 
import sys
import sqlite3 

def getParameters():
    numOfParms =  len(sys.argv)
    srcDB = "src_library.db" 
    destDB = "dest_library.db" 
    if numOfParms > 1:
        srcDB = sys.argv[1]
    if numOfParms == 3:
        destDB = sys.argv[2]
    return srcDB, destDB

def readDB (dbFile):
    conn = sqlite3.connect(dbFile)
    with conn:    
        c = conn.cursor()    
        c.execute("SELECT * FROM presets")
        rows = c.fetchall()
        return rows

def appendAll(rows, destDB):
    conn = sqlite3.connect(destDB)
    sql = 'insert into presets values(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?);'
    c = conn.cursor()
    for row in rows:
        try:
            c.execute(sql,row)
            conn.commit()
        except:
            print "can't append:", row[0]+"("+row[2]+")" 
        else:
            print row[0]+"("+row[2]+")", "Appended" 

def main():
    srcDB, destDB = getParameters()
    rows = readDB(srcDB)
    appendAll(rows, destDB)

main()


Conventions et règles de traduction

Cette page décrit les conventions et règles qui doivent être utilisés dans la traduction française de darktable. Ces règles s'appliquent aussi bien au manuel utilisateur qu'au logiciel lui même.

Règles

Il faut assurer la cohérence entre le nom des modules dans darktable et dans le manuel utilisateur.

http://sourceforge.net/mailarchive/forum.php?thread_name=201312052250.41669.sersch%40gmail.com&forum_name=darktable-users

Conventions

Voici une liste des traductions admises comme correctes :

banding raies de couleur / effet de bandes
brightness luminosité
color break rupture de dégradé / transitions en escalier
color cast dominante de couleur
color label label de couleur
combobox zone de liste déroulante
deflicker Ne pas traduire et préciser "anti-scintillement"
dialog [box] boîte de dialogue
duplicate cloner (traduit ainsi dans l'interface)
duplicate clone
filmstrip bandeau
form forme
HDR grande plage dynamique ou grande gamme dynamique
LDR plage ou gamme dynamique standard ou ordinaire
lightness clarté
luminance luminance (en photométrie)
mask masque
RGB RGB (dans tous les acronymes comportant RGB)
shape forme
sidecar fichier lié
slider curseur
tethering prise de vue connectée ("capture" dans l'interface de darktable)
thumbnail miniature
raw, RAW RAW (toujours en majuscules)
wavelets ondelettes (en théorie du signal)

CropAndRotatePlugIn

Introduction

The CropAndRotatePlugIn plug-in forms part of the "basic" plug-in group and is used to crop, rotate, flip and do keystone distortion. It can also display various kinds of guides while doing so. It is generally used as part of the Darkroom process of darktable's workflow.

This page is correct for the following stable versions of darktable

Reasons for use

The CropAndRotatePlugIn plug-in is used to manipulate the perspective and crop of your photos. The keystone distortion can correct images of tall buildings to make their edges appear parallel again, like a tilt-shift lens.

What this plug-in actually does

This plug-in affects the displayed pixels of a photograph and can cut away unneeded portions. Also it can distort the pixels, potentially losing some resolution. Keystone always distorts the whole image, regardless of crop.

Parameters that can be changed

The following parameters can be changed within this plug-in and can be found in the right-hand panel of the Darkroom view:

flip

Settings are 'horizontal' and 'vertical' flip to reverse the image along the selected axis.

angle

Settings range from -180 to 180 degrees where the negative range rotates the whole image clockwise. Also the image is automatically cropped, so no empty areas are part of the result.
There is a more easy way to align edges in the image to be either horizontal or vertical. Right-click in the image area, and drag a line along an edge to be aligned. Darktable will automatically set the needed angle to make that edge either horizontal or vertical, whichever is closer.

keystone h

Settings range from -1 to 1 where -1 shrinks the left half and where 1 shrinks the right part of the image, while expanding the other half.

keystone v

Settings range from -1 to 1 where -1 shrinks the lower half and where 1 shrinks the upper part of the image, while expanding the other half.

aspect

Choose frome various kinds of aspect ratios for your image.

guides display

Various kinds of grids can be displayed as guides to help alignment.

Example usage

Example 1

The CropAndRotatePlugIn plug-in allows you to reduce perspective distortion when shooting tall buildings for example.

You can see how the CropAndRotatePlugIn plug-in makes the walls of the building parallel again. The following photo was taken with a short telephoto 90mm equivalent lens from the ground. It shows a small amount of perspective distortion.

Only a small amount of keystone is needed. I found it easiest to first rotate some edge near the middle of the image, then apply keystone. Repeat again until it is OK.

Caveats

Some plugins like the graduated neutral density filter [http://darktable.org/redmine/projects/users/wiki/GNDPlugIn?parent=Plug-ins_Wiki_Pages] still use the whole image area regardless of crop.

See also

darktable's online manual http://www.darktable.org/usermanual/ch03s04s32.html.php

Source code

darktable:source:src/iop/clipping.c


Demosaic plug-in

Introduction

The Demosaic plug-in forms part of the basic plug-in group and is used to transform the RAW file (CFA pattern, bayer for example) into an RGB image.

It is activated in the Darkroom only when zoom is greater than 50%, and it is also used when exporting an image.

TODO: Screenshot of the plug-in - insert screenshot here [use a close-up, showing all parameters of the relevant plug-in, but no items from other plug-ins - to avoid confusion]

This page is correct for the following stable versions of Darktable

What this plug-in actually does

This plug-in determines the demosaicing algorith to use and its parameters, if one is used indeed.

Demosaicing is used if there's a need to compute an image with more than 50% magnification (on display or on export). Alternatively bilateral downsampling is used (it uses 2x2 blocks as single RGB pixels with some corrections for clipped pixels).

If High Quality resampling is activated then DT applies demosaicing, then the pixel pipeline at full resolution, then downscales the result as needed.

If High Quality resampling is not activated then DT applies bilateral downsampling or demosaicing depending on the situation (see avobe), then applies the pixel pipeline.

Parameters and settings that can be changed

The following parameters and settings can be changed within this plug-in:

method

This parameter determines the method to use: PPG or AMaZE

edge threshold

This parameter sets the threshold for the median pass.

Possible values range from 0 to 1 in steps of 0.001

color smoothing

This parameter determines the number of passes for color smoothing.

Possible values range from 1 to 5 in steps of 1

match greens

This parameter sets the green correction, which is useful for some specific cameras.

Possible values are:

Generally recommended settings for this plug-in

(TODO)

Whilst users may choose any settings they wish to create the look that they desire, the following settings are generally recommended for this plug-in.

Parameter method

Useful settings generally range from [25 to 75]. Lower values can lead to... and higher values will lead to....

Parameter edge threshold

Useful settings generally range from [25 to 75]. Lower values can lead to... and higher values will lead to....

Parameter color smoothing

Useful settings generally range from [25 to 75]. Lower values can lead to... and higher values will lead to....

Parameter match greens

Useful settings generally range from [25 to 75]. Lower values can lead to... and higher values will lead to....

[Other general comments about the parameters and their use (either alone, or in combination with one another)]

Example usage

(TODO)

Example 1

The [NAME] plug-in allows you to [manipulate/adjust/enhance/reduce/maximise/minimise/remove - delete as appropriate] VVVVVVVVVV to ....

In this example, you can see how the [NAME] plug-in [manipulates/adjusts/enhances/reduces/maximises/minimises/removes] ZZZZZZZZ and allows ....

Before photo screenshot - insert screenshot here
[Explanation of the original photo and what is hoped to improve/change]

Parameters used/suggested screenshot - insert screenshot here
[Explanation of the parameters used, and why - focusing on the reasons for using the values that you did.]

After photo screenshot to show changes - insert screenshot here
[Explanation of the photo following plug-in improvements and what has improved/changed]

NB.[Important to ensure that the before and after screenshots show only the effect of this plug-in, not a combination of other unspecified plug-ins or a stack of other adjustments. This example should focus on just the changes and improvements that can be achieved through the use of this plug-in. DELETE THIS TEXT ONCE THE EXAMPLE IS CREATED]

Example 2

The [NAME] plug-in allows you to [manipulate/adjust/enhance/reduce/maximise/minimise/remove - delete as appropriate] VVVVVVVVVV to ....

In this example, you can see how the [NAME] plug-in [manipulates/adjusts/enhances/reduces/maximises/minimises/removes] ZZZZZZZZ and allows ....

Before photo screenshot - insert screenshot here
[Explanation of the original photo and what is hoped to improve/change]

Parameters used/suggested screenshot - insert screenshot here
[Explanation of the parameters used, and why - focusing on the reasons for using the values that you did.]

After photo screenshot to show changes - insert screenshot here
[Explanation of the photo following plug-in improvements and what has improved/changed]

NB.[Important to ensure that the before and after screenshots show only the effect of this plug-in, not a combination of other unspecified plug-ins or a stack of other adjustments. This example should focus on just the changes and improvements that can be achieved through the use of this plug-in. DELETE THIS TEXT ONCE THE EXAMPLE IS CREATED]

[Insert other examples as required]

Caveats

The AMaZE method sometimes has trouble when crop/rotate or opencl are switched on.

See also

Darktable's online manual - 4.7 Demosaic

Relevant Blog entries concerning this plugin Online tutorials showing how to use this plug-in Online videos showing this plug-in in action

Wikipedia: Color Filter Array

Wikipedia: Demosaicing

Source code


GeoTagging plug-in

Introduction

The geotagging plug-in is part of the lighttable view and is used to add geographical coordinates to the EXIF data of selected photos from a gpx file.

This page is correct for the following stable versions of darktable

Reasons for use

You are recording your movements during outdoor photo activities with a GPS device and like to add the geo coordinates of the location to the EXIF information of your photos. You don't need this plug-in if your camera has a build in GPS receiver. The GPS device records all your movements in a track file with precise time tags added to each location.
The geotagging plug-in is used to add geographical coordinates to the EXIF data of selected photos from a gpx file. My Garmin devices (Forerunner 305, Forerunner 310XT and GPSmaps 60csx) stores for each track point following data:

Start tag </trkpt>
Position in latitude/longitude <trkpt lat="47.7150476" lon="11.7259344">
Elevation in meters <ele>731.4000000</ele>
Time in UTC ( Zulu time) <time>2013-01-27T08:56:37Z</time>
End tag </trkpt>

Every few seconds a new track point is added to the track file (gpx file). A gpx file of an one hour photo tour contains some hundreds to even more than thousands track points.

What this plug-in actually does

This plug-in adds the position information recorded in the gpx file to the EXIF data of your photo. Accurate geotagging requires that the time setting of your camera is fully synchronized with the GPS time. The GPS time is extracted from the satellite signal with a high precision. The time of your camera is far less precise and will deviate from the GPS time in the magnitude of seconds or even minutes.

The geotagging plug-in support you in following tasks:

Calculate time offset

Check the time setting of your camera before starting your outdoor photo tour. If you like, set camera time to UTC (Universal Time Coordinated). Not all cameras record the time zone or darktable (exiv2) may not be able to read the time zone correctly from your pictures. Setting the camera time to UTC will avoid this pitfall.
Set the camera time with a precision of a few minutes.
Before or after your outdoor photo tour take a calibration picture of a precise clock showing the time in seconds. If your GPS receiver shows the time take a picture of the display. I used a radio controlled clock (DCF 77).

Import the calibration photo into darktable. The precise time is visible on the photo (usually in local time; in my case UTC +1h). The time recorded by your camera is shown by darktable in the lighttable view in the image information plug-in (“datetime”). In this example the camera time was set to local time. As expected there is a difference.

Apply the time offset to selected photos

Apply the position from the gpx file to the photos

Parameters that can be changed

Not applicable

Generally recommended settings

Set camera time to UTC to simplify offset calculation

Example usage

See section “what this plug-in actually does" above

Caveats

None

See also

darktable online user manual chapter 2.11
Geotagging in darktable

Source code

Ups -where to find?


HighlightReconstruction PlugIn

Introduction

The HighlightReconstruction plug-in is part of the basic group. By default it is switched on and there is no reason to change settings or to switch it off.

This page is correct for the following stable versions of darktable

Reasons for use

Your camera uses a Bayer pattern to make the camera chip sensitive to color. The Bayer pattern consists of red, green and blue filters in front of the sensor to generate pictures with RGB components. For technical reasons the green filters put the lowest attenuation to the light compared to red and blue channels. A white light results on a (much) higher signal of the green channel than the red and blue channel. The white balance plug-in takes care that the picture you take will show the right colors finally. It does this by amplification of the red and blue signals at the output in order to balance the resulting sensitivity of all three color components to the same sensitivity. To verify this, go to the white balance plug-in and set the preset to passthrough. Red, green and blue channel are set to 1.000 and the picture shows a green mask. Setting the preset to camera white balance the green channel remains at 1.000 and the red channel (e.g. 2.300) and the blue channel (e.g. 1.500) are amplified to balance the colors.

The output signal of the RGB channels increases with increasing brightness. The green channel will reach saturation before the red and blue channel. At this point clipping of the highlights starts in the green channel. Following scenario visualize the effect of clipping in the green channel. Basis is a medium grey (HMTL notification in hex 96-96-96 or in dec 150-150-150). Increasing the brightness in all three channels (HTML notification in hex to dc-dc-dc or in dec 220-220-220) results in a lighter grey. Let us assume that clipping in the green channel starts at hex value 96 (dec 150). Increasing the brightness will result to magenta color (HTML notification in hex dc-96-dc or in dec 220-150-220). The simulation with the gimp color chooser shows the resulting colors.

The effect of magenta highlights can be verified also in darktable. The following pictures were taken on a river in winter showing some ice and the moving water around. The two photos on the left are overexposed by mistake by one f-stop. In darktable the exposure was reduced by -1 EV. The Highlight Reconstruction is on for the first picture. The 2nd picture is a duplicate of the 1st picture with the Highlight Reconstruction switched off. The highlights on the ice changes into magenta.

The 3rd picture shows the same scene with correct exposure already in the camera. The 4th photo is a duplicate of the 3rd photo with Highlight Reconstruction switched off. The 4th photo shows no magenta because of the reduced brightness at correct exposure level the green channel didn't reach the clipping value.

What this plug-in actually does

When mode “clipping highlights” is selected the plug-in avoids that the value of the red and blue channel increase when the green channel is already saturated and started clipping. In reality the algorithm analyses highlights if at least one channels is clipped and limit the other channels accordingly.

The mode “reconstruct in LCh” analyses each pixel having at least one channel clipped and transforms the information in LCh color space to linearly mix the channels.

Parameters that can be changed

Within the plug-in you have the choice to to select between two methods:

A preference for one or the other methods can not be given. I didn't not observed visible differences in both methods up to now.

The tool tip for the clipping threshold recommends “manually adjust the clipping threshold against magenta highlights (you shouldn't ever need to touch this)”. This confirms that the clipping is closely linked to the physical characteristics of the sensor and the Bayer pattern.

If no channels are clipped there is no negative impact on your picture if the Highlight Reconstruction plug-in is switched on. There is no reason to switch it off.

Example usage

See section reason for usage above.

Caveats

None

See also

darktable online user manual chapter 4.5.6
darktable blog magenta highlights

Source code

darktable/src/iop /highlights.c


TODO: proper format for this wikipage

Sharpening with the High Pass:

The filter creates a mask of the fine detail, sharpness defining how fine that detail is. Then contrast boost defines how much the mask is highlighted (meaning, how much details are highlighted).


Import from other software

This page aims to share documentation on how to import your images from other software into shotwell.

Shotwell

Shotwell generally behaves pretty well with metadata, although it has a few issues:

Other important notes:

So to import your files from Shotwell to Darktable is fairly easy: just import the Photo folder directly into Darktable, using the Import > Folder tool on the top left. Make sure you associated a tag to those images as this will be useful later to tell those images apart, say shotwell-YYYYMMDD. All the images will be imported swiftly, but Darktable will also work on generating thumbnails for all those pictures, which will take a much longer time. Those thumbnails are generated on the fly so you may want to spend some time scrolling by hand through your collection to generate them all once.

Also, in my case Darktable crashed during the import. Fortunately, you can just restart the import without ill effects. I had to do this 3 times for a 10k image collection.

As mentionned above, metadata from JPG files gets imported without problems and neatly shows up in Darktable. This includes tags, ratings and so on. However, RAW files don't get the same privilege: no metadata gets imported at all because well, there is no metadata from shotwell in those files. It is only in the database.

After messing around with a bunch of python for an hour or two, I wrote a rather convoluted script that will extract some data from Shotwell. I asked for the tool to be included in the darktable distribution, but you can already get it from issue #9461.

In my case, it reported:

1221/1496 images found, 41 found with metadata, 41 changed

... in other words, only 1221 of the images lacking metadata were found in shotwell, and of those, only 41 had tags! Ouch! Well, it's still useful enough for me - i got some data out of there. I filed the helper script in issue #9461 for others to use, but it would need some improvements to be completely useful. It also still relies on an original import and so on.

Make sure you stop darktable before running the script.


InputColorProfilePlugIn

To add your own color profiles to Darktable's input color profile plugin copy your color profile file (in .icc format) into the folder:

~/.config/darktable/color/in/

Once copied they should be selectable in the profile drop down box.


Manual export-import of styles, presets and masks

Page written after chat on IRC on 2014-11-02.

As of 2014, darktable stores styles, presets and masks in a sqlite3 database.

It is useful sometimes to delete the database to fix some problems.

But user may want to keep their styles, presets and/or masks through the database purge.

Default location of database is ~/.config/darktable/library.db but user can choose any other location with the --library command line argument.

Alternate solution: keep original database intact, use an alternate location to import, then replace main database only after confirming everything is okay in the alternate location.

Steps below are not official, use and adapt at your own risks.

Warning

cp ~/.config/darktable/library.db  ~/.config/darktable/library.db_manualbackup_2014-11-03

Check if backup is okay

darktable --library ~/.config/darktable/library.db_manualbackup_2014-11-03

Check how it works, then quit, wait until the process has actually exited.

Exporting elements

sqlite3 ~/.config/darktable/library.db
.output presets.backup
.dump presets
.output styles.backup
.dump styles
.output style_items.backup
.dump style_items
.output masks.backup
.dump masks
.quit

Purging database

Dangerous! Make sure you still have your backup.

rm ~/.config/darktable/library.db

Run darktable once to recreate an empty database, then quit.

Importing elements

Don't reimport everything, only what you actually need. If the problem is in those settings, reimporting them will bring the problem back.

sqlite3 ~/.config/darktable/library.db <presets.backup

sqlite3 ~/.config/darktable/library.db <styles.backup
sqlite3 ~/.config/darktable/library.db <style_items.backup

sqlite3 ~/.config/darktable/library.db <masks.backup

Import only once or you'll end up with duplicates.

Rolling back

If something is wrong, you can put things back in order from your backup

cp  ~/.config/darktable/library.db_manualbackup_2014-11-03  ~/.config/darktable/library.db

Monochrome

(TODO description of the plugin)

Other effects

The main function of the Monochrome module is to, well, change the image to monochrome, but there are some interesting effects that can be achieved with blending:

Center the circle on an orange similar to skin tones, let's call it "skin orange", and try:

skin organe, Overlay blending at 50%
skin orange, Average blending at 30%


[NAME] plug-in

Introduction

The [NAME] plug-in forms part of the YYYYYYYYYYYY plug-in group and is used to [make ZZZZZZZZZZ changes to a photograph]. It is generally used as part of the [Import/Lighttable/Darkroom/Export - delete as appropriate] process of darktable's workflow.

Screenshot of the plug-in - insert screenshot here [use a close-up, showing all parameters of the relevant plug-in, but no items from other plug-ins - to avoid confusion]

This page is correct for the following stable versions of darktable

Reasons for use

The [NAME] plug-in is used to ... [manipulate/adjust/enhance/reduce/maximise/minimise/remove - delete as appropriate] the XXXXXXXXX aspect of your photos. [Expand further here to either give more detail on generic reasons for use, or to explain other reasons for use.]

What this plug-in actually does

This plug-in affects the [contrast/highlights/underexposed/overexposed] aspects of a photograph and .... [insert a '''''slightly technical''''' explanation of what the plug-in does - since this allows people to learn the underlying theory behind any manipulations and improve their knowledge over time. Please note - this is not the place for a full technical thesis, but more a very simple explanation of how the plug-in achieves its effect]

Parameters that can be changed

The following [parameters/settings] can be changed within this plug-in:

AAAAAAAA

This parameter is represented by a [slider/graphics box/whatever....] and can be found in the [right/left]-hand panel of the [import/Lighttable/Darkroom/export - delete as appropriate] view.
Settings range from [0 to 100] where 0 shows/changes .... and where 100 shows/changes...

BBBBBBBB

This parameter is represented by a [slider/graphics box/whatever....] and can be found in the [right/left]-hand panel of the [import/Lighttable/Darkroom/export - delete as appropriate] view.
Settings range from [0 to 100] where 0 shows/changes .... and where 100 shows/changes...

CCCCCCCC

This parameter is represented by a [slider/graphics box/whatever....] and can be found in the [right/left]-hand panel of the [import/Lighttable/Darkroom/export - delete as appropriate] view.
Settings range from [0 to 100] where 0 shows/changes .... and where 100 shows/changes...

DDDDDDDD

This parameter is represented by a [slider/graphics box/whatever....] and can be found in the [right/left]-hand panel of the [import/Lighttable/Darkroom/export - delete as appropriate] view.
Settings range from [0 to 100] where 0 shows/changes .... and where 100 shows/changes...

Generally recommended settings

Whilst users may choose any settings they wish to create the look that they desire, the following settings are generally recommended for this plug-in.

Parameter AAAAAAAA

Useful settings generally range from [25 to 75]. Lower values can lead to... and higher values will lead to....

Parameter BBBBBBBB

Useful settings generally range from [25 to 75]. Lower values can lead to... and higher values will lead to....

Parameter CCCCCCCC

Useful settings generally range from [25 to 75]. Lower values can lead to... and higher values will lead to....

Parameter DDDDDDDD

Useful settings generally range from [25 to 75]. Lower values can lead to... and higher values will lead to....

[Other general comments about the parameters and their use (either alone, or in combination with one another)]

Example usage

Example 1

The [NAME] plug-in allows you to [manipulate/adjust/enhance/reduce/maximise/minimise/remove - delete as appropriate] VVVVVVVVVV to ....

In this example, you can see how the [NAME] plug-in [manipulates/adjusts/enhances/reduces/maximises/minimises/removes] ZZZZZZZZ and allows ....

Before photo screenshot - insert screenshot here
[Explanation of the original photo and what is hoped to improve/change]

Parameters used/suggested screenshot - insert screenshot here
[Explanation of the parameters used, and why - focusing on the reasons for using the values that you did.]

After photo screenshot to show changes - insert screenshot here
[Explanation of the photo following plug-in improvements and what has improved/changed]

NB.[Important to ensure that the before and after screenshots show only the effect of this plug-in, not a combination of other unspecified plug-ins or a stack of other adjustments. This example should focus on just the changes and improvements that can be achieved through the use of this plug-in. DELETE THIS TEXT ONCE THE EXAMPLE IS CREATED]

Example 2

The [NAME] plug-in allows you to [manipulate/adjust/enhance/reduce/maximise/minimise/remove - delete as appropriate] VVVVVVVVVV to ....

In this example, you can see how the [NAME] plug-in [manipulates/adjusts/enhances/reduces/maximises/minimises/removes] ZZZZZZZZ and allows ....

Before photo screenshot - insert screenshot here
[Explanation of the original photo and what is hoped to improve/change]

Parameters used/suggested screenshot - insert screenshot here
[Explanation of the parameters used, and why - focusing on the reasons for using the values that you did.]

After photo screenshot to show changes - insert screenshot here
[Explanation of the photo following plug-in improvements and what has improved/changed]

NB.[Important to ensure that the before and after screenshots show only the effect of this plug-in, not a combination of other unspecified plug-ins or a stack of other adjustments. This example should focus on just the changes and improvements that can be achieved through the use of this plug-in. DELETE THIS TEXT ONCE THE EXAMPLE IS CREATED]

[Insert other examples as required]

Caveats

[Input any warnings about using this plug-in in conjunction with others that may negatively affect it, or where you should choose to use either this plug-in or another, but not both - or delete this line.]

[Input any details about how extreme settings may affect the photos - or delete this line.]

[None]

See also

The darktable book [link to static generic 'current version' page]

darktable's online manual [link to front page] - [PLUG-IN NAME - link to exact relevant page]

Relevant Blog entries concerning this plugin * [None currently available/Insert links here]

Online tutorials showing how to use this plug-in * [None currently available/Insert links here]

Online videos showing this plug-in in action * None currently available/Insert links here]

Source code

darktable:source:src/iop/clipping.c


[NAME] plug-in

Introduction

The [NAME] plug-in forms part of the YYYYYYYYYYYY plug-in group and is used to [make ZZZZZZZZZZ changes to a photograph]. It is generally used as part of the [Import/Lighttable/Darkroom/Export - delete as appropriate] process of darktable's workflow.

Screenshot of the plug-in - insert screenshot here [use a close-up, showing all parameters of the relevant plug-in, but no items from other plug-ins - to avoid confusion]

This page is correct for the following stable versions of darktable

Reasons for use

The [NAME] plug-in is used to ... [manipulate/adjust/enhance/reduce/maximise/minimise/remove - delete as appropriate] the XXXXXXXXX aspect of your photos. [Expand further here to either give more detail on generic reasons for use, or to explain other reasons for use.]

What this plug-in actually does

This plug-in affects the [contrast/highlights/underexposed/overexposed] aspects of a photograph and .... [insert a '''''slightly technical''''' explanation of what the plug-in does - since this allows people to learn the underlying theory behind any manipulations and improve their knowledge over time. Please note - this is not the place for a full technical thesis, but more a very simple explanation of how the plug-in achieves its effect]

Parameters that can be changed

The following [parameters/settings] can be changed within this plug-in:

AAAAAAAA

This parameter is represented by a [slider/graphics box/whatever....] and can be found in the [right/left]-hand panel of the [import/Lighttable/Darkroom/export - delete as appropriate] view.
Settings range from [0 to 100] where 0 shows/changes .... and where 100 shows/changes...

BBBBBBBB

This parameter is represented by a [slider/graphics box/whatever....] and can be found in the [right/left]-hand panel of the [import/Lighttable/Darkroom/export - delete as appropriate] view.
Settings range from [0 to 100] where 0 shows/changes .... and where 100 shows/changes...

CCCCCCCC

This parameter is represented by a [slider/graphics box/whatever....] and can be found in the [right/left]-hand panel of the [import/Lighttable/Darkroom/export - delete as appropriate] view.
Settings range from [0 to 100] where 0 shows/changes .... and where 100 shows/changes...

DDDDDDDD

This parameter is represented by a [slider/graphics box/whatever....] and can be found in the [right/left]-hand panel of the [import/Lighttable/Darkroom/export - delete as appropriate] view.
Settings range from [0 to 100] where 0 shows/changes .... and where 100 shows/changes...

Generally recommended settings

Whilst users may choose any settings they wish to create the look that they desire, the following settings are generally recommended for this plug-in.

Parameter AAAAAAAA

Useful settings generally range from [25 to 75]. Lower values can lead to... and higher values will lead to....

Parameter BBBBBBBB

Useful settings generally range from [25 to 75]. Lower values can lead to... and higher values will lead to....

Parameter CCCCCCCC

Useful settings generally range from [25 to 75]. Lower values can lead to... and higher values will lead to....

Parameter DDDDDDDD

Useful settings generally range from [25 to 75]. Lower values can lead to... and higher values will lead to....

[Other general comments about the parameters and their use (either alone, or in combination with one another)]

Example usage

Example 1

The [NAME] plug-in allows you to [manipulate/adjust/enhance/reduce/maximise/minimise/remove - delete as appropriate] VVVVVVVVVV to ....

In this example, you can see how the [NAME] plug-in [manipulates/adjusts/enhances/reduces/maximises/minimises/removes] ZZZZZZZZ and allows ....

Before photo screenshot - insert screenshot here
[Explanation of the original photo and what is hoped to improve/change]

Parameters used/suggested screenshot - insert screenshot here
[Explanation of the parameters used, and why - focusing on the reasons for using the values that you did.]

After photo screenshot to show changes - insert screenshot here
[Explanation of the photo following plug-in improvements and what has improved/changed]

NB.[Important to ensure that the before and after screenshots show only the effect of this plug-in, not a combination of other unspecified plug-ins or a stack of other adjustments. This example should focus on just the changes and improvements that can be achieved through the use of this plug-in. DELETE THIS TEXT ONCE THE EXAMPLE IS CREATED]

Example 2

The [NAME] plug-in allows you to [manipulate/adjust/enhance/reduce/maximise/minimise/remove - delete as appropriate] VVVVVVVVVV to ....

In this example, you can see how the [NAME] plug-in [manipulates/adjusts/enhances/reduces/maximises/minimises/removes] ZZZZZZZZ and allows ....

Before photo screenshot - insert screenshot here
[Explanation of the original photo and what is hoped to improve/change]

Parameters used/suggested screenshot - insert screenshot here
[Explanation of the parameters used, and why - focusing on the reasons for using the values that you did.]

After photo screenshot to show changes - insert screenshot here
[Explanation of the photo following plug-in improvements and what has improved/changed]

NB.[Important to ensure that the before and after screenshots show only the effect of this plug-in, not a combination of other unspecified plug-ins or a stack of other adjustments. This example should focus on just the changes and improvements that can be achieved through the use of this plug-in. DELETE THIS TEXT ONCE THE EXAMPLE IS CREATED]

[Insert other examples as required]

Caveats

[Input any warnings about using this plug-in in conjunction with others that may negatively affect it, or where you should choose to use either this plug-in or another, but not both - or delete this line.]

[Input any details about how extreme settings may affect the photos - or delete this line.]

[None]

See also

The darktable book [link to static generic 'current version' page]

darktable's online manual [link to front page] - [PLUG-IN NAME - link to exact relevant page]

Relevant Blog entries concerning this plugin * [None currently available/Insert links here]

Online tutorials showing how to use this plug-in * [None currently available/Insert links here]

Online videos showing this plug-in in action * None currently available/Insert links here]

Source code

darktable:source:src/iop/clipping.c


Plug-ins Wiki Page

General Information

A Plug-In's place in the pipeline is fixed, history stack is irrelevant in that matter.

If you click on a category twice everything ungroups and you can see the exact order everything is applied from bottom to top

Shift+click on a plugin header it will unfold that one and fold all the others.

Relevant source files are located here: darktable:source:/

lighttable

geotagging

darkroom - Basic Group

Crop and rotate

Base curve

Orientation

Exposure

Highlight reconstruction

Demosaic

White Balance

Invert

darkroom - Tone Group

Fill-light

Levels

Tone curve

Zone system

Tone Mapping

darkroom - Color Group

Overexposed

Velvia

Channel mixer

Output Color profile

Color contrast

Color correction

Color zones

Color transfer

Vibrance

Input color profile

Unbreak input profile

darkroom - Corection Group

Sharpen

Equalizer

Denoise (non-local means)

Denoise (bilateral filter)

Lens correction

Spot removal

denoise (profiled)

Chromatic aberrations

Raw Denoise

Hot Pixels

darkroom - Effect Group

Watermark

Framing

Split toning

Vignetting

Soften

Grain

High pass

Low pass

Monochrome

Low light

Shadows and Highlights

Bloom

Colorize

Graduated Neutral Density

Others

Local contrast 2: No longer built, should be taken out of the user manual link


Preparation for offset printing - converting to CMYK

For commercial printing, you may need to provide an image in the CMYK color format, which describes the image in terms of Cyan, Magenta, Yellow and blacK ink, instead of the Red, Green and Blue pixels of computer screens and digital cameras. For inkjet printing at home you should not need this, even if similar colors are used.

Darktable doesn't offer a conversion to CMYK in itself. But free software provides a working solution by using the ImageMagick toolkit. A recipe for this:

1. Ask your printer for the color profile you should use for printing, and for the minimum highlight values and maximum ink coverage he recommends. In doubt, get a standard safe profile like ISO Coated v2 300% which is available for download at the ECI, and use a minimum of 5% for Cyan, Magenta and Yellow, a maximum of 85% for blacK, and don't exceed a maximum ink coverage of 300% in total.

2. You need to export the image from darktable. Choose "Adobe RGB compatible" as an output color profile, since that can transport some printable colors that are outside of the standard sRGB range. And use a lossless format like TIFF.

3. Convert the image to CMYK using convert from ImageMagick. Use the -profile option to specify the color profile that applies to your print job:

convert image-rgb.tif -profile ISOcoated_v2_300_eci.icc image-cmyk.tif

4. Use identify from ImageMagick with the -verbose option to check if your conversion is within the limits recommended by your printer. identify specifies the values twice, once in a range between 0 and 255 and second, in (), as a value between 0 and 1. Multiply this second value by 100 and you get a percent value as used in printing:

identify -verbose image-cmyk.tif

Image: image-cmyk.tif
...
  Channel statistics:
    Pixels: 10182900
    Cyan:
      min: 0 (0)
      max: 224 (0.878431)
      mean: 71.7436 (0.281348)
      standard deviation: 41.0453 (0.160962)
      kurtosis: -1.15845
      skewness: 0.351658
    Magenta:
      min: 0 (0)
      max: 255 (1)
      mean: 67.8804 (0.266198)
      standard deviation: 57.9146 (0.227116)
      kurtosis: -0.168102
      skewness: 0.765279
    Yellow:
      min: 0 (0)
      max: 255 (1)
      mean: 109.522 (0.4295)
      standard deviation: 72.0618 (0.282595)
      kurtosis: -1.47142
      skewness: -0.175285
    Black:
      min: 0 (0)
      max: 242 (0.94902)
      mean: 53.808 (0.211012)
      standard deviation: 50.9582 (0.199836)
      kurtosis: -0.845476
      skewness: 0.468255
  Image statistics:
    Overall:
      min: 0 (0)
      max: 255 (1)
      mean: 75.7386 (0.297014)
      standard deviation: 56.6314 (0.222084)
      kurtosis: -0.0961796
      skewness: 0.623551
  Total ink density: 300%

5. Correct the color levels as needed using convert. Use the -channel option to specify the color channel you wish to change and the options -evaluate Add and -evaluate Remove to modify. For Cyan, Magenta, Yellow, you need to apply all corrections similarly to all three channels to avoid color casts. In our example, we want to increase the minimum value for Cyan, Magenta and Yellow by 5%-points and decrease the maximum value for blacK by 10%-points. Be aware that the percent values are relating to the full color, not to the value already there: adding 10% to a value of 10% results in 20%, not 11%.

convert image-cmyk.tif -channel CMY -evaluate Add 5% -channel K -evaluate Subtract 10% image-cmyk-corrected.tif

6. Check your result visually: Loading the image into scribus is probably the most accurate preview available in free software.


denoise profiled plug-in

Introduction

The denoise (profiled) plug-in forms part of the correction plug-in group and is used to denoise images, using a camera-specific noise calibration.

Blog-post describing the details behind the plug-in: http://www.darktable.org/2012/12/profiling-sensor-and-photon-noise/

todo: screenshot

This page is correct for the following stable versions of darktable

Reasons for use

The plug-in is used to denoise images.

What this plug-in actually does

See the blog post referenced above.

Parameters that can be changed

The following [parameters/settings] can be changed within this plug-in:

profile

todo

mode

Method used in the denoising core. Non-local means works best for 'lightness' blending, wavelets work best for 'color' blending.

patch size

todo

strength

todo

blend mode

Standard blend mode is available for this module.

Generally recommended settings

The modules produces good results out of the box, possibly with a reduced strength or blend mode normal with reduced opacity.

A usual trick is to reduce chroma noise, while applying less denoise to luma (lightness), to avoid losing too much detail. Create two instances of the module, one with blend mode color and another with blend mode normal or lightness. Adjust the strength or opacity of the modules to taste.

Example usage

Example 1

TODO

Example 2

The [NAME] plug-in allows you to [manipulate/adjust/enhance/reduce/maximise/minimise/remove - delete as appropriate] VVVVVVVVVV to ....

In this example, you can see how the [NAME] plug-in [manipulates/adjusts/enhances/reduces/maximises/minimises/removes] ZZZZZZZZ and allows ....

Before photo screenshot - insert screenshot here
[Explanation of the original photo and what is hoped to improve/change]

Parameters used/suggested screenshot - insert screenshot here
[Explanation of the parameters used, and why - focusing on the reasons for using the values that you did.]

After photo screenshot to show changes - insert screenshot here
[Explanation of the photo following plug-in improvements and what has improved/changed]

NB.[Important to ensure that the before and after screenshots show only the effect of this plug-in, not a combination of other unspecified plug-ins or a stack of other adjustments. This example should focus on just the changes and improvements that can be achieved through the use of this plug-in. DELETE THIS TEXT ONCE THE EXAMPLE IS CREATED]

[Insert other examples as required]

Caveats

This module requires a noise profile to have been generated for the specific sensor or camera.

The blog post referenced above contains a description on how to perform such a calibration.

See also

http://www.darktable.org/2012/12/profiling-sensor-and-photon-noise/

Source code

darktable:source:src/iop/denoiseprofile.c


Sharpen plug-in

This is a standard Unsharp Mask tool for sharpening the details of an image.

screenshot goes here

This page is correct for the following stable versions of Darktable

Reasons for use

The Sharpen plug-in is used to raise the apparent sharpness of your photos.

What this plug-in actually does

An unsharp mask raises the contrast of the fine details in the image and thus sharpens it.

With specific settings an unsharp mask can also be used to enhance local contrast, but losing it's sharpening qualities # . DT has other tools designed to enhance local contrast, like the Equalizer Plug-in.

Parameters and settings that can be changed

(TODO)

The following [parameters/settings] can be changed within this plug-in:

AAAAAAAA

This parameter is represented by a [slider/graphics box/whatever....] and can be found in the [right/left]-hand panel of the [import/Lighttable/Darkroom/export - delete as appropriate] view.
Settings range from [0 to 100] where 0 shows/changes .... and where 100 shows/changes...

BBBBBBBB

This parameter is represented by a [slider/graphics box/whatever....] and can be found in the [right/left]-hand panel of the [import/Lighttable/Darkroom/export - delete as appropriate] view.
Settings range from [0 to 100] where 0 shows/changes .... and where 100 shows/changes...

CCCCCCCC

This parameter is represented by a [slider/graphics box/whatever....] and can be found in the [right/left]-hand panel of the [import/Lighttable/Darkroom/export - delete as appropriate] view.
Settings range from [0 to 100] where 0 shows/changes .... and where 100 shows/changes...

DDDDDDDD

This parameter is represented by a [slider/graphics box/whatever....] and can be found in the [right/left]-hand panel of the [import/Lighttable/Darkroom/export - delete as appropriate] view.
Settings range from [0 to 100] where 0 shows/changes .... and where 100 shows/changes...

Generally recommended settings for this plug-in

(TODO)

Whilst users may choose any settings they wish to create the look that they desire, the following settings are generally recommended for this plug-in.

Parameter AAAAAAAA

Useful settings generally range from [25 to 75]. Lower values can lead to... and higher values will lead to....

Parameter BBBBBBBB

Useful settings generally range from [25 to 75]. Lower values can lead to... and higher values will lead to....

Parameter CCCCCCCC

Useful settings generally range from [25 to 75]. Lower values can lead to... and higher values will lead to....

Parameter DDDDDDDD

Useful settings generally range from [25 to 75]. Lower values can lead to... and higher values will lead to....

[Other general comments about the parameters and their use (either alone, or in combination with one another)]

Example usage

(TODO)

Example 1

The Sharpen plug-in allows you to [manipulate/adjust/enhance/reduce/maximise/minimise/remove - delete as appropriate] VVVVVVVVVV to ....

In this example, you can see how the Sharpen plug-in [manipulates/adjusts/enhances/reduces/maximises/minimises/removes] ZZZZZZZZ and allows ....

Before photo screenshot - insert screenshot here
[Explanation of the original photo and what is hoped to improve/change]

Parameters used/suggested screenshot - insert screenshot here
[Explanation of the parameters used, and why - focusing on the reasons for using the values that you did.]

After photo screenshot to show changes - insert screenshot here
[Explanation of the photo following plug-in improvements and what has improved/changed]

NB.[Important to ensure that the before and after screenshots show only the effect of this plug-in, not a combination of other unspecified plug-ins or a stack of other adjustments. This example should focus on just the changes and improvements that can be achieved through the use of this plug-in. DELETE THIS TEXT ONCE THE EXAMPLE IS CREATED]

Example 2

The Sharpen plug-in allows you to [manipulate/adjust/enhance/reduce/maximise/minimise/remove - delete as appropriate] VVVVVVVVVV to ....

In this example, you can see how the Sharpen plug-in [manipulates/adjusts/enhances/reduces/maximises/minimises/removes] ZZZZZZZZ and allows ....

Before photo screenshot - insert screenshot here
[Explanation of the original photo and what is hoped to improve/change]

Parameters used/suggested screenshot - insert screenshot here
[Explanation of the parameters used, and why - focusing on the reasons for using the values that you did.]

After photo screenshot to show changes - insert screenshot here
[Explanation of the photo following plug-in improvements and what has improved/changed]

NB.[Important to ensure that the before and after screenshots show only the effect of this plug-in, not a combination of other unspecified plug-ins or a stack of other adjustments. This example should focus on just the changes and improvements that can be achieved through the use of this plug-in. DELETE THIS TEXT ONCE THE EXAMPLE IS CREATED]

[Insert other examples as required]

Caveats

(TODO)

[Input any warnings about using this plug-in in conjunction with others that may negatively affect it, or where you should choose to use either this plug-in or another, but not both - or delete this line.]

[Input any details about how extreme settings may affect the photos - or delete this line.]

[None]

See also

Darktable book [link to static generic 'current version' page]

Darktable's online manual - Sharpen

Relevant Blog entries concerning this plugin Online tutorials showing how to use this plug-in Online videos showing this plug-in in action

Wikipedia: Unsharp Mask

Source code


Supported cameras

Darktable uses libgphoto2 for tethering, you can find a list of by libgphoto supported cameras here.

Tested and fully functional cameras

Here follows a complete list of verified and supported cameras for tethering with Darktable...

Model/Driver libgphoto2 version
Canon EOS 40D (PTP mode) 2.4.10
Canon EOS 400D (PTP mode) 2.4.8
Canon EOS 100D (PTP mode) 2.5.4
Nikon DSC D60 (PTP mode) 2.4.8
Nikon DSC D90 (PTP mode) 2.4.8
Nikon DSC D3100 (PTP mode) Basic Shooting, but no Live View 2.5.1
Nikon DSC D300s (PTP mode) 2.5.2
Nikon DSC D3 (PTP mode) 2.4.14

Verify support for your camera

Your camera must be fully supported by gphoto2 and before reporting any problems about
camera tethering, the following steps must be successfully performed.

First of all be sure to have gphoto2 tools installed, then connect your camera to
your computer using the usb cable...

1. Verify that camera is detected

The following command will provide which cameras are detected and connected
to the computer, find your camera port name and use it in the tests below ( mostly port usb: will be enough )...

  env LANG=C gphoto2 --auto-detect

2. Verify camera driver abilities

Execute the following command and verify that the "Capture choices" ability supports Image and "Configuration support" is yes.
These two abilities is checked and decides if "tethered shoot" button should be shown or not in Darktable.

  env LANG=C gphoto2 --port usb: --abilities

3.a Verify camera remote capture

This step should capture an image and download it to your computer.

  env LANG=C gphoto2 --port usb: --capture-image-and-download

3.b Verify camera tethered capture

And last this step waits for you to push the shutter on the camera when the images should be downloaded to your computer.

  env LANG=C gphoto2 --port usb: --capture-tethered

What if this didn't work?

Contact the gphoto2 team to find out if or how your camera is or can be supported.

Soo now what?

If you successfully went through all the tests above your camera will likely be supported
by darktable and tethering, if you still stumble over a problem in darktable please
file a bug @ http://darktable.org/redmine/projects/darktable/issues/new and attach the respective output of the 2 steps above
and the log of:

darktable -d camctl 2>1 >camctl.log

If any of the steps above failed, then there is a problem with your specific camera and driver.
Please report the issue to the gphoto2 mailing list for further help. Include these
flags to the command above that failed to attach to the mail for better support:

--debug --debug-file gphoto2_debug.log


Translating the usermanual

Some information is already provided by doc/usermanual/README. This wiki page just tries to make it easier and visible to regular users who might want to contribute some translation.

Packages required to build the documentation (tested on debian):

sudo apt-get install doxygen gnome-doc-utils libsaxon-java fop

Download the darktable source code and run the build:

git clone https://github.com/darktable-org/darktable.git
cd darktable
./build.sh

build.sh will return some warning in case other packages are missing (tip: these warnings are at the beginning of the long terminal output; run the script twice to see just the relevant information).

First, you must add your language to the file doc/usermanual/po/LINGUAS (e.g.: fr for the french language).
Then run the build.sh script and create the po file for your language:

./build.sh
cd build
make update-usermanual-XX

where XX is your language code. A new file will be generated in the root of the git repository: doc/usermanual/po/XX.po. Go ahead and translate it.
To compile the translated manual (PDF export only):

./build.sh
cd build
make darktable-usermanual-XX

A PDF file will be generated and saved in build/doc/usermanual/.
HTML export for translated documentation is not currently supported.

Beware that after each chapter title there is usually a string used for the index of the manual. You should use the main word as first word, regardless of the grammar, to put it in the right letter of the index.
For example, module usage can be translated as "uso dei moduli" (in italian); but I prefer using "moduli, uso" to index it at the M, where the user can easily find it.

If the compilation of the manual doesn't work, it's likely that there's some XML error. You should parse the XML file generated by make with:

xmllint --noout --postvalid --dtdvalid http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd build/doc/usermanual/darktable_single-XX.xml

(See issue #9755#note-14)


User interface tweaks

This page was created in order to workaround the problem shown here: https://www.darktable.org/2015/12/darktable-2-0-released/comment-page-4/#comment-48666.

The user interface can be tweaked by editing darktablerc configuration file.


WatermarkPlugIn

Variables

This is the list of variables that darktable expands in watermarks and example values:

Note: some cameras write user-specified text at shoot time to exif field 0x9286 a.k.a. 37510 or "User Comment" ("Exif.Photo.UserComment" as per exif2). At image import time, darktable copies content from that field to Xmp.dc.description, so use $(Xmp.dc.description) in your watermark text (svg or text input box) to render that text in the watermark.


User's wiki

Darktable Help

Please see our online user manual

Supported cameras for tethering.

Plug-ins Wiki Pages

Import from other software

Translating the usermanual

Conventions et règles de traduction

Manual export/import of styles, presets and masks

Preparation for offset printing - converting to CMYK

Scripts: Append presets from one darktable installation to another

See this if you think editing the original raw files is a good idea: http://article.gmane.org/gmane.comp.graphics.darktable.user/7002/

child pages: