Lua API


Table of Contents

1. darktable
1.1. darktable.print
1.2. darktable.print_error
1.3. darktable.register_event
1.4. darktable.register_storage
1.5. darktable.register_lib
1.6. darktable.films
1.7. darktable.new_format
1.8. darktable.new_storage
1.9. darktable.new_widget
1.10. darktable.gui
1.11. darktable.guides
1.12. darktable.tags
1.13. darktable.configuration
1.14. darktable.preferences
1.15. darktable.styles
1.16. darktable.database
1.17. darktable.collection
1.18. darktable.control
1.19. darktable.gettext
1.20. darktable.debug
2. types
2.1. types.dt_lua_image_t
2.2. types.dt_imageio_module_format_t
2.3. types.dt_imageio_module_format_data_png
2.4. types.dt_imageio_module_format_data_tiff
2.5. types.dt_imageio_module_format_data_exr
2.6. types.dt_imageio_module_format_data_copy
2.7. types.dt_imageio_module_format_data_pfm
2.8. types.dt_imageio_module_format_data_jpeg
2.9. types.dt_imageio_module_format_data_ppm
2.10. types.dt_imageio_module_format_data_webp
2.11. types.dt_imageio_module_format_data_j2k
2.12. types.dt_imageio_module_format_data_pdf
2.13. types._pdf_mode_t
2.14. types._pdf_pages_t
2.15. types.dt_pdf_stream_encoder_t
2.16. types.dt_imageio_module_storage_t
2.17. types.dt_imageio_module_storage_data_email
2.18. types.dt_imageio_module_storage_data_flickr
2.19. types.dt_imageio_module_storage_data_facebook
2.20. types.dt_imageio_module_storage_data_latex
2.21. types.dt_imageio_module_storage_data_picasa
2.22. types.dt_imageio_module_storage_data_gallery
2.23. types.dt_imageio_module_storage_data_disk
2.24. types.dt_lua_film_t
2.25. types.dt_style_t
2.26. types.dt_style_item_t
2.27. types.dt_lua_tag_t
2.28. types.dt_lua_lib_t
2.29. types.dt_lua_view_t
2.30. types.dt_lua_backgroundjob_t
2.31. types.dt_lua_snapshot_t
2.32. types.hint_t
2.33. types.dt_ui_container_t
2.34. types.snapshot_direction_t
2.35. types.dt_imageio_j2k_format_t
2.36. types.dt_imageio_j2k_preset_t
2.37. types.yield_type
2.38. types.comp_type_t
2.39. types.lua_pref_type
2.40. types.dt_imageio_exr_compression_t
2.41. types.dt_lib_collect_params_rule_t
2.42. types.dt_lib_collect_mode_t
2.43. types.dt_collection_properties_t
2.44. types.dt_lua_orientation_t
2.45. types.dt_lua_align_t
2.46. types.dt_lua_ellipsize_mode_t
2.47. types.dt_lua_cairo_t
2.48. types.lua_widget
2.49. types.lua_container
2.50. types.lua_check_button
2.51. types.lua_label
2.52. types.lua_button
2.53. types.lua_box
2.54. types.lua_entry
2.55. types.lua_separator
2.56. types.lua_combobox
2.57. types.lua_file_chooser_button
2.58. types.lua_stack
2.59. types.lua_slider
3. events
3.1. events.intermediate-export-image
3.2. events.post-import-image
3.3. events.shortcut
3.4. events.post-import-film
3.5. events.view-changed
3.6. events.global_toolbox-grouping_toggle
3.7. events.global_toolbox-overlay_toggle
3.8. events.mouse-over-image-changed
3.9. events.exit
3.10. events.pre-import
4. attributes
4.1. attributes.write
4.2. attributes.has_tostring
4.3. attributes.implicit_yield
4.4. attributes.parent
5. system
5.1. system.coroutine

This documentation is for the *developement* version of darktable. for the stable version, please visit the user manual

To access the darktable specific functions you must load the darktable environment:

darktable = require "darktable"

All functions and data are accessed through the darktable module.

This documentation for API version 3.0.0.

1. darktable

The darktable library is the main entry point for all access to the darktable internals.

1.1. darktable.print

function( 
	message : string
)

Will print a string to the darktable control log (the long overlayed window that appears over the main panel).

message
string

The string to display which should be a single line.

1.2. darktable.print_error

function( 
	message : string
)

This function will print its parameter if the Lua logdomain is activated. Start darktable with the "-d lua" command line option to enable the Lua logdomain.

message
string

The string to display.

1.3. darktable.register_event

function( 
	event_type : string, 
	callback : function, 
	... : variable
)

This function registers a callback to be called when a given event happens.

Events are documented in the event section.

event_type
string

The name of the event to register to.

callback
function

The function to call on event. The signature of the function depends on the type of event.

...
variable

Some events need extra parameters at registration time; these must be specified here.

1.4. darktable.register_storage

function( 
	plugin_name : string, 
	name : string, 
	[store : function], 
	[finalize : function], 
	[supported : function], 
	[initialize : function], 
	[widget : types.lua_widget]
)

This function will add a new storage implemented in Lua.

A storage is a module that is responsible for handling images once they have been generated during export. Examples of core storages include filesystem, e-mail, facebook...

plugin_name
string

A Unique name for the plugin.

name
string

A human readable name for the plugin.

[store]
function( 
	storage : types.dt_imageio_module_storage_t, 
	image : types.dt_lua_image_t, 
	format : types.dt_imageio_module_format_t, 
	filename : string, 
	number : integer, 
	total : integer, 
	high_quality : boolean, 
	extra_data : table
)

This function is called once for each exported image. Images can be exported in parallel but the calls to this function will be serialized.

storage
types.dt_imageio_module_storage_t

The storage object used for the export.

image
types.dt_lua_image_t

The exported image object.

format
types.dt_imageio_module_format_t

The format object used for the export.

filename
string

The name of a temporary file where the processed image is stored.

number
integer

The number of the image out of the export series.

total
integer

The total number of images in the export series.

high_quality
boolean

True if the export is high quality.

extra_data
table

An empty Lua table to take extra data. This table is common to the initialize, store and finalize calls in an export serie.

[finalize]
function( 
	storage : types.dt_imageio_module_storage_t, 
	image_table : table, 
	extra_data : table
)

This function is called once all images are processed and all store calls are finished.

storage
types.dt_imageio_module_storage_t

The storage object used for the export.

image_table
table

A table keyed by the exported image objects and valued with the corresponding temporary export filename.

extra_data
table

An empty Lua table to store extra data. This table is common to all calls to store and the call to finalize in a given export series.

[supported]
function( 
	storage : types.dt_imageio_module_storage_t, 
	format : types.dt_imageio_module_format_t
) : boolean

A function called to check if a given image format is supported by the Lua storage; this is used to build the dropdown format list for the GUI.

Note that the parameters in the format are the ones currently set in the GUI; the user might change them before export.

storage
types.dt_imageio_module_storage_t

The storage object tested.

format
types.dt_imageio_module_format_t

The format object to report about.

return
boolean

True if the corresponding format is supported.

[initialize]
function( 
	storage : types.dt_imageio_module_storage_t, 
	format : types.dt_imageio_module_format_t, 
	images : table of types.dt_lua_image_t, 
	high_quality : boolean, 
	extra_data : table
) : table or nil

A function called before storage happens

This function can change the list of exported functions

storage
types.dt_imageio_module_storage_t

The storage object tested.

format
types.dt_imageio_module_format_t

The format object to report about.

images
table of types.dt_lua_image_t

A table containing images to be exported.

high_quality
boolean

True if the export is high quality.

extra_data
table

An empty Lua table to take extra data. This table is common to the initialize, store and finalize calls in an export serie.

return
table or nil

The modified table of images to export or nil

If nil (or nothing) is returned, the original list of images will be exported

If a table of images is returned, that table will be used instead. The table can be empty. The images parameter can be modified and returned

[widget]
types.lua_widget

A widget to display in the export section of darktable's UI

1.5. darktable.register_lib

function( 
	plugin_name : string, 
	name : string, 
	expandable : boolean, 
	resetable : boolean, 
	containers : table of types.dt_lua_view_t => [ types.dt_ui_container_t, int ], 
	widget : types.lua_widget, 
	view_enter : function, 
	view_leave : function
)

Register a new lib object. A lib is a graphical element of darktable's user interface

plugin_name
string

A unique name for your library

name
string

A user-visible name for your library

expandable
boolean

whether this lib should be expandable or not

resetable
boolean

whether this lib has a reset button or not

containers
table of types.dt_lua_view_t => [ types.dt_ui_container_t, int ]

A table associating to each view containing the lib the corresponding container and position

widget
types.lua_widget

The widget to display in the lib

view_enter
self:function( 
	old_view : types.dt_lua_view_t, 
	new_view : types.dt_lua_view_t
)

A callback called when a view displaying the lib is entered

self
types.dt_lua_lib_t

The lib on which the callback is called

old_view
types.dt_lua_view_t

The view that we are leaving

new_view
types.dt_lua_view_t

The view that we are entering

view_leave
self:function( 
	old_view : types.dt_lua_view_t, 
	new_view : types.dt_lua_view_t
)

A callback called when leaving a view displaying the lib

self
types.dt_lua_lib_t

The lib on which the callback is called

old_view
types.dt_lua_view_t

The view that we are leaving

new_view
types.dt_lua_view_t

The view that we are entering

1.6. darktable.films

A table containing all the film objects in the database.

1.6.1. darktable.films.#

types.dt_lua_film_t

Each film has a numeric entry in the database.

1.6.2. darktable.films.new

function( 
	directory : string
) : types.dt_lua_film_t

Creates a new empty film

see darktable.database.import to import a directory with all its images and to add images to a film

directory
string

The directory that the new film will represent. The directory must exist

return
types.dt_lua_film_t

The newly created film, or the existing film if the directory is already imported

1.6.3. darktable.films.delete

see types.dt_lua_film_t.delete

1.7. darktable.new_format

function( 
	type : string
) : types.dt_imageio_module_format_t

Creates a new format object to export images

type
string

The type of format object to create, one of :

  • copy

  • exr

  • j2k

  • jpeg

  • pdf

  • pfm

  • png

  • ppm

  • tiff

  • webp

return
types.dt_imageio_module_format_t

The newly created object. Exact type depends on the type passed

1.8. darktable.new_storage

function( 
	type : string
) : types.dt_imageio_module_storage_t

Creates a new storage object to export images

type
string

The type of storage object to create, one of :

  • disk

  • email

  • facebook

  • flickr

  • gallery

  • latex

  • picasa

(Other, lua-defined, storage types may appear.)

return
types.dt_imageio_module_storage_t

The newly created object. Exact type depends on the type passed

1.9. darktable.new_widget

function( 
	type : string
) : types.lua_widget

Creates a new widget object to display in the UI

type
string

The type of storage object to create, one of :

  • box

  • button

  • check_button

  • combobox

  • container

  • entry

  • file_chooser_button

  • label

  • separator

  • slider

  • stack

return
types.lua_widget

The newly created object. Exact type depends on the type passed

1.10. darktable.gui

This subtable contains function and data to manipulate the darktable user interface with Lua.

Most of these function won't do anything if the GUI is not enabled (i.e you are using the command line version darktabl-cli instead of darktable).

1.10.1. darktable.gui.action_images

table

A table of types.dt_lua_image_t on which the user expects UI actions to happen.

It is based on both the hovered image and the selection and is consistent with the way darktable works.

It is recommended to use this table to implement Lua actions rather than darktable.gui.hovered or darktable.gui.selection to be consistant with darktable's GUI.

1.10.2. darktable.gui.hovered

types.dt_lua_image_t

The image under the cursor or nil if no image is hovered.

1.10.3. darktable.gui.selection

function( 
	[selection : table of types.dt_lua_image_t]
) : table of types.dt_lua_image_t

Allows to change the set of selected images.

Attributes:
[selection]
table of types.dt_lua_image_t

A table of images which will define the selected images. If this parameter is not given the selection will be untouched. If an empty table is given the selection will be emptied.

return
table of types.dt_lua_image_t

A table containing the selection as it was before the function was called.

1.10.4. darktable.gui.current_view

function( 
	[view : types.dt_lua_view_t]
) : types.dt_lua_view_t

Allows to change the current view.

[view]
types.dt_lua_view_t

The view to switch to. If empty the current view is unchanged

return
types.dt_lua_view_t

the current view

1.10.5. darktable.gui.create_job

function( 
	text : string, 
	[percentage : boolean], 
	[cancel_callback : function]
) : types.dt_lua_backgroundjob_t

Create a new progress_bar displayed in darktable.gui.libs.backgroundjobs

text
string

The text to display in the job entry

[percentage]
boolean

Should a progress bar be displayed

[cancel_callback]
function( 
	job : types.dt_lua_backgroundjob_t, 
	image : types.dt_lua_image_t
) : string

A function called when the cancel button for that job is pressed

note that the job won't be destroyed automatically. You need to set types.dt_lua_backgroundjob_t.valid to false for that

job
types.dt_lua_backgroundjob_t

The job who is being cancelded

image
types.dt_lua_image_t

The image to analyze

return
string

The extra information to display

return
types.dt_lua_backgroundjob_t

The newly created job object

1.10.6. darktable.gui.views

The different views in darktable

darktable.gui.views.map

The map view

darktable.gui.views.map.latitude
number

The latitude of the center of the map

Attributes:
darktable.gui.views.map.longitude
number

The longitude of the center of the map

Attributes:
darktable.gui.views.map.zoom
number

The current zoom level of the map

Attributes:
darktable.gui.views.darkroom

The darkroom view

darktable.gui.views.lighttable

The lighttable view

darktable.gui.views.tethering

The tethering view

darktable.gui.views.slideshow

The slideshow view

darktable.gui.views.print

The print view

1.10.7. darktable.gui.libs

This table allows to reference all lib objects

lib are the graphical blocks within each view.

To quickly figure out what lib is what, you can use the following code which will make a given lib blink.

local tested_module="global_toolbox"
dt.gui.libs[tested_module].visible=false
coroutine.yield("WAIT_MS",2000)
while true do
	dt.gui.libs[tested_module].visible = not dt.gui.libs[tested_module].visible
	coroutine.yield("WAIT_MS",2000)
end

darktable.gui.libs.snapshots

The UI element that manipulates snapshots in darkroom

darktable.gui.libs.snapshots.ratio
number

The place in the screen where the line separating the snapshot is. Between 0 and 1

Attributes:
darktable.gui.libs.snapshots.direction
types.snapshot_direction_t

The direction of the snapshot overlay

Attributes:
darktable.gui.libs.snapshots.#
types.dt_lua_snapshot_t

The different snapshots for the image

darktable.gui.libs.snapshots.selected
types.dt_lua_snapshot_t

The currently selected snapshot

darktable.gui.libs.snapshots.take_snapshot
function( 
)

Take a snapshot of the current image and add it to the UI

The snapshot file will be generated at the next redraw of the main window

darktable.gui.libs.snapshots.max_snapshot
number

The maximum number of snapshots

darktable.gui.libs.collect

The collection UI element that allows to filter images by collection

darktable.gui.libs.collect.filter
function( 
	[rules : array oftypes.dt_lib_collect_params_rule_t]
) : array oftypes.dt_lib_collect_params_rule_t

Allows to get or change the list of visible images

Attributes:
[rules]
array oftypes.dt_lib_collect_params_rule_t

A table of rules describing the filter. These rules will be applied after this call

return
array oftypes.dt_lib_collect_params_rule_t

The rules that were applied before this call.

darktable.gui.libs.collect.new_rule
function( 
) : types.dt_lib_collect_params_rule_t

Returns a newly created rule object

return
types.dt_lib_collect_params_rule_t

The newly created rule

darktable.gui.libs.import

The buttons to start importing images

darktable.gui.libs.import.register_widget
function( 
	widget : types.lua_widget
)

Add a widget in the option expander of the import dialog

widget
types.lua_widget

The widget to add to the dialog. The reset callback of the widget will be called whenever the dialog is opened

darktable.gui.libs.styles

The style selection menu

darktable.gui.libs.metadata_view

The widget displaying metadata about the current image

darktable.gui.libs.metadata

The widget allowing modification of metadata fields on the current image

darktable.gui.libs.hinter

The small line of text at the top of the UI showing the number of selected images

darktable.gui.libs.modulelist

The window allowing to set modules as visible/hidden/favorite

darktable.gui.libs.filmstrip

The filmstrip at the bottom of some views

darktable.gui.libs.viewswitcher

The labels allowing to switch view

darktable.gui.libs.darktable_label

The darktable logo in the upper left corner

darktable.gui.libs.tagging

The tag manipulation UI

darktable.gui.libs.geotagging

The geotagging time synchronisation UI

darktable.gui.libs.recentcollect

The recent collection UI element

darktable.gui.libs.global_toolbox

The common tools to all view (settings, grouping...)

darktable.gui.libs.global_toolbox.grouping
boolean

The current status of the image grouping option

Attributes:
darktable.gui.libs.global_toolbox.show_overlays
boolean

the current status of the image overlays option

Attributes:
darktable.gui.libs.filter

The image-filter menus at the top of the UI

darktable.gui.libs.ratings

The starts to set the rating of an image

darktable.gui.libs.select

The buttons that allow to quickly change the selection

darktable.gui.libs.select.register_selection
function( 
	label : string, 
	callback : function, 
	[tooltip : string]
)

Add a new button and call a callback when it is clicked

label
string

The label to display on the button

callback
function( 
	event : string, 
	images : table oftypes.dt_lua_image_t
) : table oftypes.dt_lua_image_t

The function to call when the button is pressed

event
string

The name of the button that was pressed

images
table oftypes.dt_lua_image_t

The images in the current collection. This is the same content asdarktable.collection

return
table oftypes.dt_lua_image_t

The images to set the selection to

[tooltip]
string

The tooltip to use on the new button

darktable.gui.libs.colorlabels

The color buttons that allow to set labels on an image

darktable.gui.libs.lighttable_mode

The navigation and zoom level UI in lighttable

darktable.gui.libs.copy_history

The UI element that manipulates history

darktable.gui.libs.image

The UI element that manipulates the current images

darktable.gui.libs.image.register_action
function( 
	label : string, 
	callback : function, 
	[tooltip : string]
)

Add a new button and call a callback when it is clicked

label
string

The label to display on the button

callback
function( 
	event : string, 
	images : table oftypes.dt_lua_image_t
)

The function to call when the button is pressed

event
string

The name of the button that was pressed

images
table oftypes.dt_lua_image_t

The images to act on when the button was clicked

[tooltip]
string

The tooltip to use on the new button

darktable.gui.libs.modulegroups

The icons describing the different iop groups

darktable.gui.libs.module_toolbox

The tools on the bottom line of the UI (overexposure)

darktable.gui.libs.session

The session UI when tethering

darktable.gui.libs.histogram

The histogram widget

darktable.gui.libs.export

The export menu

darktable.gui.libs.history

The history manipulation menu

darktable.gui.libs.colorpicker

The colorpicker menu

darktable.gui.libs.navigation

The full image preview to allow navigation

darktable.gui.libs.masks

The masks window

darktable.gui.libs.view_toolbox

darktable.gui.libs.live_view

The liveview window

darktable.gui.libs.map_settings

The map setting window

darktable.gui.libs.camera

The camera selection UI

darktable.gui.libs.location

The location ui

darktable.gui.libs.backgroundjobs

The window displaying the currently running jobs

darktable.gui.libs.print_settings

The settings window in the print view

1.11. darktable.guides

table

Guide lines to overlay over an image in crop and rotate.

All guides are clipped to the drawing area.

1.11.1. darktable.guides.register_guide

function( 
	name : string, 
	draw_callback : function, 
	[gui_callback : function]
)

Register a new guide.

name
string

The name of the guide to show in the GUI.

draw_callback
function( 
	cr : types.dt_lua_cairo_t, 
	x : float, 
	y : float, 
	width : float, 
	height : float, 
	zoom_scale : float
)

The function to call to draw the guide lines. The drawn lines will be stroked by darktable.

THIS IS RUNNING IN THE GUI THREAD AND HAS TO BE FAST!

cr
types.dt_lua_cairo_t

The cairo object used for drawing.

x
float

The x coordinate of the top left corner of the drawing area.

y
float

The y coordinate of the top left corner of the drawing area.

width
float

The width of the drawing area.

height
float

The height of the drawing area.

zoom_scale
float

The current zoom_scale. Only needed when setting the line thickness.

[gui_callback]
function

A function returning a widget to show when the guide is selected. It takes no arguments.

1.12. darktable.tags

Allows access to all existing tags.

1.12.1. darktable.tags.#

types.dt_lua_tag_t

Each existing tag has a numeric entry in the tags table - use ipairs to iterate over them.

1.12.2. darktable.tags.create

function( 
	name : string
)

Creates a new tag and return it. If the tag exists return the existing tag.

name
string

The name of the new tag.

1.12.3. darktable.tags.find

function( 
	name : string
) : types.dt_lua_tag_t

Returns the tag object or nil if the tag doesn't exist.

name
string

The name of the tag to find.

return
types.dt_lua_tag_t

The tag object or nil.

1.12.4. darktable.tags.delete

function( 
	tag : types.dt_lua_tag_t
)

Deletes the tag object, detaching it from all images.

tag
types.dt_lua_tag_t

The tag to be deleted.

1.12.5. darktable.tags.attach

function( 
	tag : types.dt_lua_tag_t, 
	image : types.dt_lua_image_t
)

Attach a tag to an image; the order of the parameters can be reversed.

tag
types.dt_lua_tag_t

The tag to be attached.

image
types.dt_lua_image_t

The image to attach the tag to.

1.12.6. darktable.tags.detach

function( 
	tag : types.dt_lua_tag_t, 
	image : types.dt_lua_image_t
)

Detach a tag from an image; the order of the parameters can be reversed.

tag
types.dt_lua_tag_t

The tag to be detached.

image
types.dt_lua_image_t

The image to detach the tag from.

1.12.7. darktable.tags.get_tags

function( 
	image : types.dt_lua_image_t
) : table of types.dt_lua_tag_t

Gets all tags attached to an image.

image
types.dt_lua_image_t

The image to get the tags from.

return
table of types.dt_lua_tag_t

A table of tags that are attached to the image.

1.13. darktable.configuration

table

This table regroups values that describe details of the configuration of darktable.

1.13.1. darktable.configuration.version

string

The version number of darktable.

1.13.2. darktable.configuration.has_gui

boolean

True if darktable has a GUI (launched through the main darktable command, not darktable-cli).

1.13.3. darktable.configuration.verbose

boolean

True if the Lua logdomain is enabled.

1.13.4. darktable.configuration.tmp_dir

string

The name of the directory where darktable will store temporary files.

1.13.5. darktable.configuration.config_dir

string

The name of the directory where darktable will find its global configuration objects (modules).

1.13.6. darktable.configuration.cache_dir

string

The name of the directory where darktable will store its mipmaps.

1.13.7. darktable.configuration.api_version_major

number

The major version number of the lua API.

1.13.8. darktable.configuration.api_version_minor

number

The minor version number of the lua API.

1.13.9. darktable.configuration.api_version_patch

number

The patch version number of the lua API.

1.13.10. darktable.configuration.api_version_suffix

string

The version suffix of the lua API.

1.13.11. darktable.configuration.api_version_string

string

The version description of the lua API. This is a string compatible with the semantic versionning convention

1.13.12. darktable.configuration.check_version

function( 
	module_name : string, 
	... : table...
)

Check that a module is compatible with the running version of darktable

Add the following line at the top of your module :

darktable.configuration.check(...,{M,m,p},{M2,m2,p2})

To document that your module has been tested with API version M.m.p and M2.m2.p2.

This will raise an error if the user is running a released version of DT and a warning if he is running a developement version

(the ... here will automatically expand to your module name if used at the top of your script

module_name
string

The name of the module to report on error

...
table...

Tables of API versions that are known to work with the script

1.14. darktable.preferences

table

Lua allows you to manipulate preferences. Lua has its own namespace for preferences and you can't access nor write normal darktable preferences.

Preference handling functions take a _script_ parameter. This is a string used to avoid name collision in preferences (i.e namespace). Set it to something unique, usually the name of the script handling the preference.

Preference handling functions can't guess the type of a parameter. You must pass the type of the preference you are handling.

Note that the directory, enum and file type preferences are stored internally as string. The user can only select valid values, but a lua script can set it to any string

1.14.1. darktable.preferences.register

function( 
	script : string, 
	name : string, 
	type : types.lua_pref_type, 
	label : string, 
	tooltip : string, 
	[default : depends on type], 
	[min : int or float], 
	[max : int or float], 
	[step : float], 
	values : string...
)

Creates a new preference entry in the Lua tab of the preference screen. If this function is not called the preference can't be set by the user (you can still read and write invisible preferences).

script
string

Invisible prefix to guarantee unicity of preferences.

name
string

A unique name used with the script part to identify the preference.

type
types.lua_pref_type

The type of the preference - one of the string values described above.

label
string

The label displayed in the preference screen.

tooltip
string

The tooltip to display in the preference menu.

[default]
depends on type

Default value to use when not set explicitely or by the user.

For the enum type of pref, this is mandatory

[min]
int or float

Minimum value (integer and float preferences only).

[max]
int or float

Maximum value (integer and float preferences only).

[step]
float

Step of the spinner (float preferences only).

values
string...

Other allowed values (enum preferences only)

1.14.2. darktable.preferences.read

function( 
	script : string, 
	name : string, 
	type : types.lua_pref_type
) : depends on type

Reads a value from a Lua preference.

script
string

Invisible prefix to guarantee unicity of preferences.

name
string

The name of the preference displayed in the preference screen.

type
types.lua_pref_type

The type of the preference.

return
depends on type

The value of the preference.

1.14.3. darktable.preferences.write

function( 
	script : string, 
	name : string, 
	type : types.lua_pref_type, 
	value : depends on type
)

Writes a value to a Lua preference.

script
string

Invisible prefix to guarantee unicity of preferences.

name
string

The name of the preference displayed in the preference screen.

type
types.lua_pref_type

The type of the preference.

value
depends on type

The value to set the preference to.

1.15. darktable.styles

This pseudo table allows you to access and manipulate styles.

1.15.1. darktable.styles.#

types.dt_style_t

Each existing style has a numeric index; you can iterate them using ipairs.

1.15.2. darktable.styles.create

function( 
	image : types.dt_lua_image_t, 
	name : string, 
	description : string
) : types.dt_style_t

Create a new style based on an image.

image
types.dt_lua_image_t

The image to create the style from.

name
string

The name to give to the new style.

description
string

The description of the new style.

return
types.dt_style_t

The new style object.

1.15.3. darktable.styles.delete

function( 
	style : types.dt_style_t
)

Deletes an existing style.

style
types.dt_style_t

the style to delete

1.15.4. darktable.styles.duplicate

function( 
	style : types.dt_style_t, 
	name : string, 
	description : string
) : types.dt_style_t

Create a new style based on an existing style.

style
types.dt_style_t

The style to base the new style on.

name
string

The new style's name.

description
string

The new style's description.

return
types.dt_style_t

The new style object.

1.15.5. darktable.styles.apply

function( 
	style : types.dt_style_t, 
	image : types.dt_lua_image_t
)

Apply a style to an image. The order of parameters can be inverted.

style
types.dt_style_t

The style to use.

image
types.dt_lua_image_t

The image to apply the style to.

1.15.6. darktable.styles.import

function( 
	filename : string
)

Import a style from an external .dtstyle file

filename
string

The file to import

1.15.7. darktable.styles.export

function( 
	style : types.dt_style_t, 
	directory : string, 
	overwrite : boolean
)

Export a style to an external .dtstyle file

style
types.dt_style_t

The style to export

directory
string

The directory to export to

overwrite
boolean

Is overwriting an existing file allowed

1.16. darktable.database

Allows to access the database of images. Note that duplicate images (images with the same RAW but different XMP) will appear multiple times with different duplicate indexes. Also note that all images are here. This table is not influenced by any GUI filtering (collections, stars etc...).

1.16.1. darktable.database.#

types.dt_lua_image_t

Each image in the database appears with a numerical index; you can interate them using ipairs.

1.16.2. darktable.database.duplicate

function( 
	image : types.dt_lua_image_t
) : types.dt_lua_image_t

Creates a duplicate of an image and returns it.

image
types.dt_lua_image_t

the image to duplicate

return
types.dt_lua_image_t

The new image object.

1.16.3. darktable.database.import

function( 
	location : string
) : types.dt_lua_image_t

Imports new images into the database.

location
string

The filename or directory to import images from. NOTE: If the images are set to be imported recursively in preferences only the toplevel film is returned (the one whose path was given as a parameter). NOTE2: If the parameter is a directory the call is non-blocking; the film object will not have the newly imported images yet. Use a post-import-film filtering on that film to react when images are actually imported.

return
types.dt_lua_image_t

The created image if an image is imported or the toplevel film object if a film was imported.

1.16.4. darktable.database.move_image

function( 
	image : types.dt_lua_image_t, 
	film : types.dt_lua_film_t
)

Physically moves an image (and all its duplicates) to another film.

This will move the image file, the related XMP and all XMP for the duplicates to the directory of the new film

Note that the parameter order is not relevant.

image
types.dt_lua_image_t

The image to move

film
types.dt_lua_film_t

The film to move to

1.16.5. darktable.database.copy_image

function( 
	image : types.dt_lua_image_t, 
	film : types.dt_lua_film_t
) : types.dt_lua_image_t

Physically copies an image to another film.

This will copy the image file and the related XMP to the directory of the new film

If there is already a file with the same name as the image file, it will create a duplicate from that file instead

Note that the parameter order is not relevant.

image
types.dt_lua_image_t

The image to copy

film
types.dt_lua_film_t

The film to copy to

return
types.dt_lua_image_t

The new image

1.16.6. darktable.database.delete

see types.dt_lua_image_t.delete

1.17. darktable.collection

Allows to access the currently worked on images, i.e the ones selected by the collection lib. Filtering (rating etc) does not change that collection.

1.17.1. darktable.collection.#

types.dt_lua_image_t

Each image in the collection appears with a numerical index; you can interate them using ipairs.

1.18. darktable.control

This table contain function to manipulate the control flow of lua programs. It provides ways to do background jobs and other related functions

1.18.1. darktable.control.ending

boolean

TRUE when darktable is terminating

Use this variable to detect when you should finish long running jobs

1.18.2. darktable.control.dispatch

function( 
	function : function, 
	... : anything
)

Runs a function in the background. This function will be run at a later point, after luarc has finished running. If you do a loop in such a function, please check darktable.control.ending in your loop to finish the function when DT exits

function
function

The call to dispatch

...
anything

extra parameters to pass to the function

1.19. darktable.gettext

table

This table contains functions related to translating lua scripts

1.19.1. darktable.gettext.gettext

function( 
	msgid : string
) : string

Translate a string using the darktable textdomain

msgid
string

The string to translate

return
string

The translated string

1.19.2. darktable.gettext.dgettext

function( 
	domainname : string, 
	msgid : string
) : string

Translate a string using the specified textdomain

domainname
string

The domain to use for that translation

msgid
string

The string to translate

return
string

The translated string

1.19.3. darktable.gettext.ngettext

function( 
	msgid : string, 
	msgid_plural : string, 
	n : int
) : string

Translate a string depending on the number of objects using the darktable textdomain

msgid
string

The string to translate

msgid_plural
string

The string to translate in plural form

n
int

The number of objetc

return
string

The translated string

1.19.4. darktable.gettext.dngettext

function( 
	domainname : string, 
	msgid : string, 
	msgid_plural : string, 
	n : int
) : string

Translate a string depending on the number of objects using the specified textdomain

domainname
string

The domain to use for that translation

msgid
string

The string to translate

msgid_plural
string

The string to translate in plural form

n
int

The number of objetc

return
string

The translated string

1.19.5. darktable.gettext.bindtextdomain

function( 
	domainname : string, 
	dirname : string
)

Tell gettext where to find the .mo file translating messages for a particular domain

domainname
string

The domain to use for that translation

dirname
string

The base directory to look for the file. The file should be placed in dirname/locale name/LC_MESSAGES/domain.mo

1.20. darktable.debug

table

This section must be activated separately by calling require "darktable.debug"

1.20.1. darktable.debug.dump

function( 
	object : anything, 
	[name : string], 
	[known : table]
) : string

This will return a string describing everything Lua knows about an object, used to know what an object is. This function is recursion-safe and can be used to dump _G if needed.

object
anything

The object to dump.

[name]
string

A name to use for the object.

[known]
table

A table of object,string pairs. Any object in that table will not be dumped, the string will be printed instead.

defaults to darktable.debug.known if not set

return
string

A string containing a text description of the object - can be very long.

1.20.2. darktable.debug.debug

boolean

Initialized to false; set it to true to also dump information about metatables.

1.20.3. darktable.debug.max_depth

number

Initialized to 10; The maximum depth to recursively dump content.

1.20.4. darktable.debug.known

table

A table containing the default value of darktable.debug.dump.known

1.20.5. darktable.debug.type

function( 
	object : anything
) : string

Similar to the system function type() but it will return the real type instead of "userdata" for darktable specific objects.

object
anything

The object whos type must be reported.

return
string

A string describing the type of the object.