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 5.0.0.
The darktable library is the main entry point for all access to the darktable internals.
function(
message : string
)
Will print a string to the darktable control log (the long overlaid window that appears over the main panel).
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.
function(
message : string
)
This function is similar todarktable.print_log but adds an ERROR prefix for clarity.
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.
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...
string
A Unique name for the plugin.
string
A human readable name for the plugin.
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.
types.dt_imageio_module_storage_t
The storage object used for the export.
types.dt_lua_image_t
The exported image object.
types.dt_imageio_module_format_t
The format object used for the export.
string
The name of a temporary file where the processed image is stored.
integer
The number of the image out of the export series.
integer
The total number of images in the export series.
boolean
True if the export is high quality.
table
An empty Lua table to take extra data. This table is common to the initialize, store and finalize calls in an export series.
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.
types.dt_imageio_module_storage_t
The storage object used for the export.
table
A table keyed by the exported image objects and valued with the corresponding temporary export filename.
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.
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.
types.dt_imageio_module_storage_t
The storage object tested.
types.dt_imageio_module_format_t
The format object to report about.
boolean
True if the corresponding format is supported.
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
types.dt_imageio_module_storage_t
The storage object tested.
types.dt_imageio_module_format_t
The format object to report about.
table of types.dt_lua_image_t
A table containing images to be exported.
boolean
True if the export is high quality.
table
An empty Lua table to take extra data. This table is common to the initialize, store and finalize calls in an export series.
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
types.lua_widget
A widget to display in the export section of darktable's UI
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
string
A unique name for your library
string
A user-visible name for your library
boolean
whether this lib should be expandable or not
boolean
whether this lib has a reset button or not
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
types.lua_widget
The widget to display in the lib
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
types.dt_lua_lib_t
The lib on which the callback is called
types.dt_lua_view_t
The view that we are leaving
types.dt_lua_view_t
The view that we are entering
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
types.dt_lua_lib_t
The lib on which the callback is called
types.dt_lua_view_t
The view that we are leaving
types.dt_lua_view_t
The view that we are entering
A table containing all the film objects in the database.
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
string
The directory that the new film will represent. The directory must exist
types.dt_lua_film_t
The newly created film, or the existing film if the directory is already imported
function( type : string ) : types.dt_imageio_module_format_t
Creates a new format object to export images
string
The type of format object to create, one of :
copy
exr
j2k
jpeg
pfm
png
ppm
tiff
webp
types.dt_imageio_module_format_t
The newly created object. Exact type depends on the type passed
function( type : string ) : types.dt_imageio_module_storage_t
Creates a new storage object to export images
string
The type of storage object to create, one of :
disk
flickr
gallery
latex
picasa
(Other, lua-defined, storage types may appear.)
types.dt_imageio_module_storage_t
The newly created object. Exact type depends on the type passed
function( type : string, ... : variable ) : types.lua_widget
Creates a new widget object to display in the UI
string
The type of storage object to create, one of :
box
button
check_button
combobox
container
entry
file_chooser_button
label
section_label
separator
slider
stack
text_view
variable
Extra parameters, exact value are documented with each type
types.lua_widget
The newly created object. Exact type depends on the type passed
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 darktable-cli instead of darktable).
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 consistent with darktable's GUI.
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: |
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.
table of types.dt_lua_image_t
A table containing the selection as it was before the function was called.
function( [view : types.dt_lua_view_t] ) : types.dt_lua_view_t
Allows to change the current view.
types.dt_lua_view_t
The view to switch to. If empty the current view is unchanged
types.dt_lua_view_t
the current view
function( text : string, [percentage : boolean], [cancel_callback : function] ) : types.dt_lua_backgroundjob_t
Create a new progress_bar displayed in darktable.gui.libs.backgroundjobs
string
The text to display in the job entry
boolean
Should a progress bar be displayed
function( job : types.dt_lua_backgroundjob_t )
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
types.dt_lua_backgroundjob_t
The job who is being cancelled
types.dt_lua_backgroundjob_t
The newly created job object
The different views in darktable
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
The UI element that manipulates snapshots in darkroom
Attributes: |
number
The place in the screen where the line separating the snapshot is. Between 0 and 1
Attributes: |
The collection UI element that allows to filter images by collection
Attributes: |
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: |
array oftypes.dt_lib_collect_params_rule_t
A table of rules describing the filter. These rules will be applied after this call
array oftypes.dt_lib_collect_params_rule_t
The rules that were applied before this call.
function( ) : types.dt_lib_collect_params_rule_t
Returns a newly created rule object
types.dt_lib_collect_params_rule_t
The newly created rule
The buttons to start importing images
Attributes: |
function( widget : types.lua_widget )
Add a widget in the option expander of the import dialog
types.lua_widget
The widget to add to the dialog. The reset callback of the widget will be called whenever the dialog is opened
The widget displaying metadata about the current image
Attributes: |
function( name : string, callback : function )
Register a function providing extra info to display in the widget
string
The name displayed for the new information
function( image : types.dt_lua_image_t ) : string
The function providing the info
types.dt_lua_image_t
The image to analyze
string
The extra information to display
The common tools to all view (settings, grouping...)
Attributes: |
The buttons that allow to quickly change the selection
Attributes: |
function( label : string, callback : function, [tooltip : string] )
Add a new button and call a callback when it is clicked
string
The label to display on the button
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
string
The name of the button that was pressed
table oftypes.dt_lua_image_t
The images in the current collection. This is the same content asdarktable.collection
table oftypes.dt_lua_image_t
The images to set the selection to
string
The tooltip to use on the new button
The UI element that manipulates the current images
Attributes: |
function( label : string, callback : function, [tooltip : string] )
Add a new button and call a callback when it is clicked
string
The label to display on the button
function( event : string, images : table oftypes.dt_lua_image_t )
The function to call when the button is pressed
string
The name of the button that was pressed
table oftypes.dt_lua_image_t
The images to act on when the button was clicked
string
The tooltip to use on the new button
table
Guide lines to overlay over an image in crop and rotate.
All guides are clipped to the drawing area.
function( name : string, draw_callback : function, [gui_callback : function] )
Register a new guide.
string
The name of the guide to show in the GUI.
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!
types.dt_lua_cairo_t
The cairo object used for drawing.
float
The x coordinate of the top left corner of the drawing area.
float
The y coordinate of the top left corner of the drawing area.
float
The width of the drawing area.
float
The height of the drawing area.
float
The current zoom_scale. Only needed when setting the line thickness.
function
A function returning a widget to show when the guide is selected. It takes no arguments.
Allows access to all existing tags.
types.dt_lua_tag_t
Each existing tag has a numeric entry in the tags table - use ipairs to iterate over them.
function(
name : string
)
Creates a new tag and return it. If the tag exists return the existing tag.
function( name : string ) : types.dt_lua_tag_t
Returns the tag object or nil if the tag doesn't exist.
string
The name of the tag to find.
types.dt_lua_tag_t
The tag object or nil.
function( tag : types.dt_lua_tag_t )
Deletes the tag object, detaching it from all images.
types.dt_lua_tag_t
The tag to be deleted.
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.
types.dt_lua_tag_t
The tag to be attached.
types.dt_lua_image_t
The image to attach the tag to.
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.
types.dt_lua_tag_t
The tag to be detached.
types.dt_lua_image_t
The image to detach the tag from.
function( image : types.dt_lua_image_t ) : table of types.dt_lua_tag_t
Gets all tags attached to an image.
types.dt_lua_image_t
The image to get the tags from.
table of types.dt_lua_tag_t
A table of tags that are attached to the image.
table
This table regroups values that describe details of the configuration of darktable.
boolean
True if darktable has a GUI (launched through the main darktable command, not darktable-cli).
string
The name of the directory where darktable will find its global configuration objects (modules).
string
The version description of the lua API. This is a string compatible with the semantic versioning convention
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 development version
(the ... here will automatically expand to your module name if used at the top of your script
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, lua 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
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...], [wiget : types.lua_widget], [set_callback : function] )
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).
string
Invisible prefix to guarantee unicity of preferences.
string
A unique name used with the script part to identify the preference.
types.lua_pref_type
The type of the preference - one of the string values described above.
string
The label displayed in the preference screen.
string
The tooltip to display in the preference menu.
depends on type
Default value to use when not set explicitly or by the user.
For the enum type of pref, this is mandatory
int or float
Minimum value (integer and float preferences only).
int or float
Maximum value (integer and float preferences only).
float
Step of the spinner (float preferences only).
string...
Other allowed values (enum preferences only)
types.lua_widget
The widget to use in preference(lua preferences only)
function( widget : types.lua_widget )
A function called when the widget needs to be updated from the preference
types.lua_widget
The widget to update
function( script : string, name : string, type : types.lua_pref_type ) : depends on type
Reads a value from a Lua preference.
string
Invisible prefix to guarantee unicity of preferences.
string
The name of the preference displayed in the preference screen.
types.lua_pref_type
The type of the preference.
depends on type
The value of the preference.
function( script : string, name : string, type : types.lua_pref_type, value : depends on type )
Writes a value to a Lua preference.
string
Invisible prefix to guarantee unicity of preferences.
string
The name of the preference displayed in the preference screen.
types.lua_pref_type
The type of the preference.
depends on type
The value to set the preference to.
This pseudo table allows you to access and manipulate styles.
function( image : types.dt_lua_image_t, name : string, description : string ) : types.dt_style_t
Create a new style based on an image.
types.dt_lua_image_t
The image to create the style from.
string
The name to give to the new style.
string
The description of the new style.
types.dt_style_t
The new style object.
function( style : types.dt_style_t )
Deletes an existing style.
types.dt_style_t
the style to delete
function( style : types.dt_style_t, name : string, description : string ) : types.dt_style_t
Create a new style based on an existing style.
types.dt_style_t
The style to base the new style on.
string
The new style's name.
string
The new style's description.
types.dt_style_t
The new style object.
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.
types.dt_style_t
The style to use.
types.dt_lua_image_t
The image to apply the style to.
function( style : types.dt_style_t, directory : string, overwrite : boolean )
Export a style to an external .dtstyle file
types.dt_style_t
The style to export
string
The directory to export to
boolean
Is overwriting an existing file allowed
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...).
types.dt_lua_image_t
Each image in the database appears with a numerical index; you can iterate them using ipairs.
function( image : types.dt_lua_image_t ) : types.dt_lua_image_t
Creates a duplicate of an image and returns it.
types.dt_lua_image_t
the image to duplicate
types.dt_lua_image_t
The new image object.
function( location : string ) : types.dt_lua_image_t
Imports new images into the database.
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.
types.dt_lua_image_t
The created image if an image is imported or the toplevel film object if a film was imported.
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.
types.dt_lua_image_t
The image to move
types.dt_lua_film_t
The film to move to
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.
types.dt_lua_image_t
The image to copy
types.dt_lua_film_t
The film to copy to
types.dt_lua_image_t
The new image
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.
types.dt_lua_image_t
Each image in the collection appears with a numerical index; you can iterate them using ipairs.
This table contain function to manipulate the control flow of lua programs. It provides ways to do background jobs and other related functions
boolean
TRUE when darktable is terminating
Use this variable to detect when you should finish long running jobs
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(
file : file
)
Block until a file is readable while not blocking darktable
This function is not available on Windows builds
table
This table contains functions related to translating lua scripts
function( domainname : string, msgid : string ) : string
Translate a string using the specified textdomain
function( msgid : string, msgid_plural : string, n : int ) : string
Translate a string depending on the number of objects using the darktable textdomain
function( domainname : string, msgid : string, msgid_plural : string, n : int ) : string
Translate a string depending on the number of objects using the specified textdomain
function( domainname : string, dirname : string )
Tell gettext where to find the .mo file translating messages for a particular domain
table
This section must be activated separately by calling require "darktable.debug"
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.
anything
The object to dump.
string
A name to use for the object.
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
string
A string containing a text description of the object - can be very long.
function(
object : anything
) : string
Similar to the system function type() but it will return the real type instead of "userdata" for darktable specific objects.