Project

General

Profile

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 environement:
darktable = require "darktable"

All functions and data are accessed through the darktable module.

This documentation for API version 2.0.0-dev.

This documentation was generated with darktable version 1.5+2099~gf477271.

darktable

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

print

type : function( message : string )

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

message

type : string

The string to display which should be a single line.

print_error

type : 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

type : string

The string to display.

register_event

type : 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

type : string

The name of the event to register to.

callback

type : function

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

...

type : variable

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

register_storage

type : function( plugin_name : string, name : string, [ store : function], [ finalize : function], [ supported : function], [ initialize : function] )

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

type : string

A Unique name for the plugin.

name

type : string

A human readable name for the plugin.

store

type : 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

type : types.dt_imageio_module_storage_t

The storage object used for the export.

image

type : types.dt_lua_image_t

The exported image object.

format

type : types.dt_imageio_module_format_t

The format object used for the export.

filename

type : string

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

number

type : integer

The number of the image out of the export series.

total

type : integer

The total number of images in the export series.

high_quality

type : boolean

True if the export is high quality.

extra_data

type : 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

type : 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

type : types.dt_imageio_module_storage_t

The storage object used for the export.

image_table

type : table

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

extra_data

type : 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

type : 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

type : types.dt_imageio_module_storage_t

The storage object tested.

format

type : types.dt_imageio_module_format_t

The format object to report about.

return

type : boolean

True if the corresponding format is supported.

initialize

type : 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

type : types.dt_imageio_module_storage_t

The storage object tested.

format

type : types.dt_imageio_module_format_t

The format object to report about.

images

type : table of types.dt_lua_image_t

A table containing images to be exported.

high_quality

type : boolean

True if the export is high quality.

extra_data

type : 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

type : 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

films

A table containing all the film objects in the database.

#

type : types.dt_lua_film_t

Each film has a numeric entry in the database.

new

type : 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

type : string

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

return

type : types.dt_lua_film_t

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

delete

see types.dt_lua_film_t.delete

new_format

type : function( type : string ) : types.dt_imageio_module_format_t

Creates a new format object to export images

type

type : string

The type of format object to create, one of :

  • copy
  • exr
  • j2k
  • jpeg
  • pfm
  • png
  • ppm
  • tiff
  • webp

return

type : types.dt_imageio_module_format_t

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

new_storage

type : function( type : string ) : types.dt_imageio_module_storage_t

Creates a new storage object to export images

type

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

type : types.dt_imageio_module_storage_t

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

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).

action_images

type : 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.

hovered

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

selection

type : 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 : implicit_yield

selection

type : 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

type : table of types.dt_lua_image_t

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

current_view

type : function( [ view : types.dt_view_t] ) : types.dt_view_t

Allows to change the current view.

view

type : types.dt_view_t

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

return

type : types.dt_view_t

the current view

create_job

type : 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

type : string

The text to display in the job entry

percentage

type : boolean

Should a progress bar be displayed

cancel_callback

type : 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

job

type : types.dt_lua_backgroundjob_t

The job who is being cancelded

return

type : types.dt_lua_backgroundjob_t

The newly created job object

views

The different views in darktable

map

The map view
parent : types.dt_view_t

Attributes : has_tostring
latitude
type : number

The latitude of the center of the map
Attributes : write

longitude
type : number

The longitude of the center of the map
Attributes : write

zoom
type : number

The current zoom level of the map
Attributes : write

darkroom

The darkroom view
parent : types.dt_view_t

Attributes : has_tostring

lighttable

The lighttable view
parent : types.dt_view_t

Attributes : has_tostring

tethering

The tethering view
parent : types.dt_view_t

Attributes : has_tostring

slideshow

The slideshow view
parent : types.dt_view_t

Attributes : has_tostring

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

snapshots

The UI element that manipulates snapshots in darkroom
container : DT_UI_CONTAINER_PANEL_LEFT_CENTER

parent : types.dt_lib_module_t
position : 1000
views :
ratio
type : number

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

direction
type : types.snapshot_direction_t

The direction of the snapshot overlay
Attributes : write

#
type : types.dt_lua_snapshot_t

The different snapshots for the image

selected

The currently selected snapshot

take_snapshot
type : 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

max_snapshot
type : number

The maximum number of snapshots

styles

The style selection menu
container : DT_UI_CONTAINER_PANEL_RIGHT_CENTER

parent : types.dt_lib_module_t
position : 599
views :

metadata_view

The widget displaying metadata about the current image
container : DT_UI_CONTAINER_PANEL_LEFT_CENTER

parent : types.dt_lib_module_t
position : 299
views :

metadata

The widget allowing modification of metadata fields on the current image
container : DT_UI_CONTAINER_PANEL_RIGHT_CENTER

parent : types.dt_lib_module_t
position : 510
views :

hinter

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

parent : types.dt_lib_module_t
position : 1
views :

modulelist

The window allowing to set modules as visible/hidden/favorite
container : DT_UI_CONTAINER_PANEL_RIGHT_BOTTOM

parent : types.dt_lib_module_t
position : 1
views :

filmstrip

The filmstrip at the bottom of some views
container : DT_UI_CONTAINER_PANEL_BOTTOM

parent : types.dt_lib_module_t
position : 1001
views :

viewswitcher

The labels allowing to switch view
container : DT_UI_CONTAINER_PANEL_TOP_RIGHT

parent : types.dt_lib_module_t
position : 1001
views :

darktable_label

The darktable logo in the upper left corner
container : DT_UI_CONTAINER_PANEL_TOP_LEFT

parent : types.dt_lib_module_t
position : 1001
views :

tagging

The tag manipulation UI
container : DT_UI_CONTAINER_PANEL_RIGHT_CENTER

parent : types.dt_lib_module_t
position : 500
views :

geotagging

The geotagging time synchronisation UI
container : DT_UI_CONTAINER_PANEL_RIGHT_CENTER

parent : types.dt_lib_module_t
position : 450
views :

recentcollect

The recent collection UI element
container : DT_UI_CONTAINER_PANEL_LEFT_CENTER

parent : types.dt_lib_module_t
position : 350
views :

global_toolbox

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

parent : types.dt_lib_module_t
position : 1001
views :
grouping
type : boolean

The current status of the image grouping option
Attributes : write

show_overlays
type : boolean

the current status of the image overlays option
Attributes : write

filter

The image-filter menus at the top of the UI
container : DT_UI_CONTAINER_PANEL_CENTER_TOP_CENTER

parent : types.dt_lib_module_t
position : 1001
views :

import

The buttons to start importing images
container : DT_UI_CONTAINER_PANEL_LEFT_CENTER

parent : types.dt_lib_module_t
position : 999
views :

ratings

The starts to set the rating of an image
container : DT_UI_CONTAINER_PANEL_CENTER_BOTTOM_LEFT

parent : types.dt_lib_module_t
position : 1002
views :

select

The buttons that allow to quickly change the selection
container : DT_UI_CONTAINER_PANEL_RIGHT_CENTER

parent : types.dt_lib_module_t
position : 800
views :

collect

The collection UI element that allows to filter images by collection
container : DT_UI_CONTAINER_PANEL_LEFT_CENTER

parent : types.dt_lib_module_t
position : 400
views :

colorlabels

The color buttons that allow to set labels on an image
container : DT_UI_CONTAINER_PANEL_CENTER_BOTTOM_LEFT

parent : types.dt_lib_module_t
position : 1001
views :

lighttable_mode

The navigation and zoom level UI in lighttable
container : DT_UI_CONTAINER_PANEL_CENTER_BOTTOM_CENTER

parent : types.dt_lib_module_t
position : 1001
views :

copy_history

The UI element that manipulates history
container : DT_UI_CONTAINER_PANEL_RIGHT_CENTER

parent : types.dt_lib_module_t
position : 600
views :

image

The UI element that manipulates the current image
container : DT_UI_CONTAINER_PANEL_RIGHT_CENTER

parent : types.dt_lib_module_t
position : 700
views :

modulegroups

The icons describing the different iop groups
container : DT_UI_CONTAINER_PANEL_RIGHT_TOP

parent : types.dt_lib_module_t
position : 999
views :

module_toolbox

The tools on the bottom line of the UI (overexposure)
container : DT_UI_CONTAINER_PANEL_CENTER_BOTTOM_RIGHT

parent : types.dt_lib_module_t
position : 100
views :

session

The session UI when tethering
container : DT_UI_CONTAINER_PANEL_RIGHT_CENTER

parent : types.dt_lib_module_t
position : 999
views :

histogram

The histogram widget
container : DT_UI_CONTAINER_PANEL_RIGHT_TOP

parent : types.dt_lib_module_t
position : 1001
views :

export

The export menu
container : DT_UI_CONTAINER_PANEL_RIGHT_CENTER

parent : types.dt_lib_module_t
position : 0
views :

history

The history manipulation menu
container : DT_UI_CONTAINER_PANEL_LEFT_CENTER

parent : types.dt_lib_module_t
position : 900
views :

colorpicker

The colorpicker menu
container : DT_UI_CONTAINER_PANEL_LEFT_CENTER

parent : types.dt_lib_module_t
position : 800
views :

navigation

The full image preview to allow navigation
container : DT_UI_CONTAINER_PANEL_LEFT_TOP

parent : types.dt_lib_module_t
position : 1001
views :

masks

The masks window
container : DT_UI_CONTAINER_PANEL_LEFT_CENTER

parent : types.dt_lib_module_t
position : 10
views :

view_toolbox

container : DT_UI_CONTAINER_PANEL_CENTER_BOTTOM_LEFT
parent : types.dt_lib_module_t
position : 100
views :

live_view

The liveview window
container : DT_UI_CONTAINER_PANEL_RIGHT_CENTER

parent : types.dt_lib_module_t
position : 998
views :

map_settings

The map setting window
container : DT_UI_CONTAINER_PANEL_RIGHT_CENTER

parent : types.dt_lib_module_t
position : 990
views :

camera

The camera selection UI
container : DT_UI_CONTAINER_PANEL_RIGHT_CENTER

parent : types.dt_lib_module_t
position : 997
views :

location

The location ui
container : DT_UI_CONTAINER_PANEL_RIGHT_CENTER

parent : types.dt_lib_module_t
position : 999
views :

backgroundjobs

The window displaying the currently running jobs
container : DT_UI_CONTAINER_PANEL_LEFT_BOTTOM

parent : types.dt_lib_module_t
position : 1
views :

tags

Allows access to all existing tags.

#

type : types.dt_lua_tag_t

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

create

type : function( name : string )

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

name

type : string

The name of the new tag.

find

type : function( name : string ) : types.dt_lua_tag_t

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

name

type : string

The name of the tag to find.

return

type : types.dt_lua_tag_t

The tag object or nil.

delete

type : function( tag : types.dt_lua_tag_t )

Deletes the tag object, detaching it from all images.

tag

type : types.dt_lua_tag_t

The tag to be deleted.

attach

type : 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

type : types.dt_lua_tag_t

The tag to be attached.

image

type : types.dt_lua_image_t

The image to attach the tag to.

detach

type : 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

type : types.dt_lua_tag_t

The tag to be detached.

image

type : types.dt_lua_image_t

The image to detach the tag from.

get_tags

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

Gets all tags attached to an image.

image

type : types.dt_lua_image_t

The image to get the tags from.

return

type : table of types.dt_lua_tag_t

A table of tags that are attached to the image.

configuration

type : table

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

version

type : string

The version number of darktable.

has_gui

type : boolean

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

verbose

type : boolean

True if the Lua logdomain is enabled.

tmp_dir

type : string

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

config_dir

type : string

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

cache_dir

type : string

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

api_version_major

type : number

The major version number of the lua API.

api_version_minor

type : number

The minor version number of the lua API.

api_version_patch

type : number

The patch version number of the lua API.

api_version_suffix

type : string

The version suffix of the lua API.

api_version_string

type : string

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

check_version

type : 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

type : string

The name of the module to report on error

...

type : table...

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

preferences

type : table

Lua allows you do 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

register

type : 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

type : string

Invisible prefix to guarantee unicity of preferences.

name

type : string

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

type

type : types.lua_pref_type

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

label

type : string

The label displayed in the preference screen.

tooltip

type : string

The tooltip to display in the preference menue.

default

type : 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

type : int or float

Minimum value (integer and float preferences only).

max

type : int or float

Maximum value (integer and float preferences only).

step

type : float

Step of the spinner (float preferences only).

values

type : string...

Other allowed values (enum preferences only)

read

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

Reads a value from a Lua preference.

script

type : string

Invisible prefix to guarantee unicity of preferences.

name

type : string

The name of the preference displayed in the preference screen.

type

type : types.lua_pref_type

The type of the preference.

return

type : depends on type

The value of the preference.

write

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

Writes a value to a Lua preference.

script

type : string

Invisible prefix to guarantee unicity of preferences.

name

type : string

The name of the preference displayed in the preference screen.

type

type : types.lua_pref_type

The type of the preference.

value

type : depends on type

The value to set the preference to.

styles

This pseudo table allows you to access and manipulate styles.

#

type : types.dt_style_t

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

create

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

Create a new style based on an image.

image

type : types.dt_lua_image_t

The image to create the style from.

name

type : string

The name to give to the new style.

description

type : string

The description of the new style.

return

type : types.dt_style_t

The new style object.

delete

type : function( style : types.dt_style_t )

Deletes an existing style.

style

type : types.dt_style_t

the style to delete

duplicate

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

Create a new style based on an existing style.

style

type : types.dt_style_t

The style to base the new style on.

name

type : string

The new style's name.

description

type : string

The new style's description.

return

type : types.dt_style_t

The new style object.

apply

type : 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

type : types.dt_style_t

The style to use.

image

type : types.dt_lua_image_t

The image to apply the style to.

import

type : function( filename : string )

Import a style from an external .dtstyle file

filename

type : string

The file to import

export

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

Export a style to an external .dtstyle file

style

type : types.dt_style_t

The style to export

directory

type : string

The directory to export to

overwrite

type : boolean

Is overwriting an existing file allowed

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...).

#

type : types.dt_lua_image_t

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

duplicate

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

Creates a duplicate of an image and returns it.

image

type : types.dt_lua_image_t

the image to duplicate

return

type : types.dt_lua_image_t

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

import

type : function( location : string )

Imports new images into the database.

location

type : 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.

move_image

type : 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

type : types.dt_lua_image_t

The image to move

film

type : types.dt_lua_film_t

The film to move to

copy_image

type : 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 wil create a duplicate from that file instead

Note that the parameter order is not relevant.

image

type : types.dt_lua_image_t

The image to copy

film

type : types.dt_lua_film_t

The film to copy to

return

type : types.dt_lua_image_t

The new image

delete

see types.dt_lua_image_t.delete

debug

type : table

This section must be activated separately by calling

require "darktable.debug"

dump

type : 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

type : anything

The object to dump.

name

type : string

A name to use for the object.

known

type : 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

type : string

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

debug

type : boolean

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

max_depth

type : number

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

known

type : table

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

type

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

type : anything

The object whos type must be reported.

return

type : string

A string describing the type of the object.

types

This section documents types that are specific to darktable's Lua API.

dt_lua_image_t

type : dt_type

Image objects represent an image in the database. This is slightly different from a file on disk since a file can have multiple developements.

Note that this is the real image object; changing the value of a field will immediately change it in darktable and will be reflected on any copy of that image object you may have kept.
Attributes : has_tostring

attach_tag

see darktable.tags.attach

detach_tag

see darktable.tags.detach

get_tags

see darktable.tags.get_tags

create_style

see darktable.styles.create

apply_style

see darktable.styles.apply

duplicate

see darktable.database.duplicate

move

see darktable.database.move_image

copy

see darktable.database.copy_image

id

type : number

A unique id identifying the image in the database.

path

type : string

The file the directory containing the image.

film

type : types.dt_lua_film_t

The film object that contains this image.

filename

type : string

The filename of the image.

duplicate_index

type : number

If there are multiple images based on a same file, each will have a unique number, starting from 0.

publisher

type : string

The publisher field of the image.
Attributes : write

title

type : string

The title field of the image.
Attributes : write

creator

type : string

The creator field of the image.
Attributes : write

rights

type : string

The rights field of the image.
Attributes : write

description

type : string

The description field for the image.
Attributes : write

exif_maker

type : string

The maker exif data.
Attributes : write

exif_model

type : string

The camera model used.
Attributes : write

exif_lens

type : string

The id string of the lens used.
Attributes : write

exif_aperture

type : number

The aperture saved in the exif data.
Attributes : write

exif_exposure

type : number

The exposure time of the image.
Attributes : write

exif_focal_length

type : number

The focal length of the image.
Attributes : write

exif_iso

type : number

The iso used on the image.
Attributes : write

exif_datetime_taken

type : string

The date and time of the image.
Attributes : write

exif_focus_distance

type : number

The distance of the subject.
Attributes : write

exif_crop

type : number

The exif crop data.
Attributes : write

latitude

GPS latitude data of the image, nil if not set.
Attributes : write

longitude

GPS longitude data of the image, nil if not set.
Attributes : write

is_raw

type : boolean

True if the image is a RAW file.

is_ldr

type : boolean

True if the image is a ldr image.

is_hdr

type : boolean

True if the image is a hdr image.

width

type : number

The width of the image.

height

type : number

The height of the image.

rating

type : number

The rating of the image (-1 for rejected).
Attributes : write

red

type : boolean

True if the image has the corresponding colorlabel.
Attributes : write

blue

see types.dt_lua_image_t.red

green

see types.dt_lua_image_t.red

yellow

see types.dt_lua_image_t.red

purple

see types.dt_lua_image_t.red

reset

type : self:function(  )

Removes all processing from the image, reseting it back to its original state

self

type : types.dt_lua_image_t

The image whose history will be deleted

delete

type : self:function(  )

Removes an image from the database

self

type : types.dt_lua_image_t

The image to remove

group_with

type : self:function( [ image : types.dt_lua_image_t] )

Puts the first image in the same group as the second image. If no second image is provided the image will be in its own group.

self

type : types.dt_lua_image_t

The image whose group must be changed.

image

type : types.dt_lua_image_t

The image we want to group with.

make_group_leader

type : self:function(  )

Makes the image the leader of its group.

self

type : types.dt_lua_image_t

The image we want as the leader.

get_group_members

type : self:function(  ) : table of types.dt_lua_image_t

Returns a table containing all types.dt_lua_image_t of the group. The group leader is both at a numeric key and at the "leader" special key (so you probably want to use ipairs to iterate through that table).

self

type : types.dt_lua_image_t

The image whose group we are querying.

return

type : table of types.dt_lua_image_t

A table of image objects containing all images that are in the same group as the image.

group_leader

type : types.dt_lua_image_t

The image which is the leader of the group this image is a member of.

local_copy

type : boolean

True if the image has a copy in the local cache
Attributes : write

drop_cache

type : self:function(  )

drops the cached version of this image.

This function should be called if an image is modified out of darktable to force DT to regenerate the thumbnail

Darktable will regenerate the thumbnail by itself when it is needed

self

type : types.dt_lua_image_t

The image whose cache must be droped.

dt_imageio_module_format_t

type : dt_type

A virtual type representing all format types.

plugin_name

type : string

A unique name for the plugin.

name

type : string

A human readable name for the plugin.

extension

type : string

The typical filename extension for that format.

mime

type : string

The mime type associated with the format.

max_width

type : number

The max width allowed for the format (0 = unlimited).
Attributes : write

max_height

type : number

The max height allowed for the format (0 = unlimited).
Attributes : write

write_image

type : self:function( image : types.dt_lua_image_t, filename : string ) : boolean

Exports an image to a file. This is a blocking operation that will not return until the image is exported.
Attributes : implicit_yield

self

type : types.dt_imageio_module_format_t

The format that will be used to export.

image

type : types.dt_lua_image_t

The image object to export.

filename

type : string

The filename to export to.

return

type : boolean

Returns true on success.

dt_imageio_module_format_data_png

type : dt_type

Type object describing parameters to export to png.
parent : types.dt_imageio_module_format_t

bpp

type : number

The bpp parameter to use when exporting.
Attributes : write

dt_imageio_module_format_data_tiff

type : dt_type

Type object describing parameters to export to tiff.
parent : types.dt_imageio_module_format_t

bpp

type : number

The bpp parameter to use when exporting.
Attributes : write

dt_imageio_module_format_data_exr

type : dt_type

Type object describing parameters to export to exr.
parent : types.dt_imageio_module_format_t

compression

type : string

The compression parameter to use when exporting.
Attributes : write

dt_imageio_module_format_data_copy

type : dt_type

Type object describing parameters to export to copy.
parent : types.dt_imageio_module_format_t

dt_imageio_module_format_data_pfm

type : dt_type

Type object describing parameters to export to pfm.
parent : types.dt_imageio_module_format_t

dt_imageio_module_format_data_jpeg

type : dt_type

Type object describing parameters to export to jpeg.
parent : types.dt_imageio_module_format_t

quality

type : number

The quality to use at export time.
Attributes : write

dt_imageio_module_format_data_ppm

type : dt_type

Type object describing parameters to export to ppm.
parent : types.dt_imageio_module_format_t

dt_imageio_module_format_data_webp

type : dt_type

Type object describing parameters to export to webp.
parent : types.dt_imageio_module_format_t

quality

type : number

The quality to use at export time.
Attributes : write

comp_type

type : types.comp_type_t

The overall quality to use; can be one of "webp_lossy" or "webp_lossless".
Attributes : write

hint

type : types.hint_t

A hint on the overall content of the image.
Attributes : write

dt_imageio_module_format_data_j2k

type : dt_type

Type object describing parameters to export to jpeg2000.
parent : types.dt_imageio_module_format_t

quality

type : number

The quality to use at export time.
Attributes : write

bpp

type : number

The bpp parameter to use when exporting.
Attributes : write

format

type : types.dt_imageio_j2k_format_t

The format to use.
Attributes : write

preset

type : types.dt_imageio_j2k_preset_t

The preset to use.
Attributes : write

dt_imageio_module_storage_t

type : dt_type

A virtual type representing all storage types.

plugin_name

type : string

A unique name for the plugin.
Attributes : write

name

type : string

A human readable name for the plugin.
Attributes : write

width

type : number

The currently selected width for the plugin.
Attributes : write

height

type : number

The currently selected height for the plugin.
Attributes : write

recommended_width

type : number

The recommended width for the plugin.
Attributes : write

recommended_height

type : number

The recommended height for the plugin.
Attributes : write

supports_format

type : self:function( format : types.dt_imageio_module_format_t ) : boolean

Checks if a format is supported by this storage.

self

type : types.dt_imageio_module_storage_t

The storage type to check against.

format

type : types.dt_imageio_module_format_t

The format type to check.

return

type : boolean

True if the format is supported by the storage.

dt_imageio_module_storage_data_email

type : dt_type

An object containing parameters to export to email.
parent : types.dt_imageio_module_storage_t

dt_imageio_module_storage_data_flickr

type : dt_type

An object containing parameters to export to flickr.
parent : types.dt_imageio_module_storage_t

dt_imageio_module_storage_data_facebook

type : dt_type

An object containing parameters to export to facebook.
parent : types.dt_imageio_module_storage_t

dt_imageio_module_storage_data_latex

type : dt_type

An object containing parameters to export to latex.
parent : types.dt_imageio_module_storage_t

filename

type : string

The filename to export to.
Attributes : write

title

type : string

The title to use for export.
Attributes : write

dt_imageio_module_storage_data_picasa

type : dt_type

An object containing parameters to export to picasa.
parent : types.dt_imageio_module_storage_t

type : dt_type

An object containing parameters to export to gallery.
parent : types.dt_imageio_module_storage_t

filename

type : string

The filename to export to.
Attributes : write

title

type : string

The title to use for export.
Attributes : write

dt_imageio_module_storage_data_disk

type : dt_type

An object containing parameters to export to disk.
parent : types.dt_imageio_module_storage_t

filename

type : string

The filename to export to.
Attributes : write

dt_lua_film_t

type : dt_type

A film in darktable; this represents a directory containing imported images.
Attributes : has_tostring

move_image

see darktable.database.move_image

copy_image

see darktable.database.copy_image

#

type : types.dt_lua_image_t

The different images within the film.

id

type : number

A unique numeric id used by this film.
Attributes : write

path

type : string

The path represented by this film.
Attributes : write

delete

type : self:function( [ force : Boolean] )

Removes the film from the database.

self

type : types.dt_lua_film_t

The film to remove.

force

type : Boolean

Force removal, even if the film is not empty.

dt_style_t

type : dt_type

A style that can be applied to an image.
Attributes : has_tostring

delete

see darktable.styles.delete

duplicate

see darktable.styles.duplicate

apply

see darktable.styles.apply

export

see darktable.styles.export

name

type : string

The name of the style.

description

type : string

The description of the style.

#

type : types.dt_style_item_t

The different items that make the style.

dt_style_item_t

type : dt_type

An element that is part of a style.
Attributes : has_tostring

name

type : string

The name of the style item.

num

type : number

The position of the style item within its style.

dt_lua_tag_t

type : dt_type

A tag that can be attached to an image.
Attributes : has_tostring

delete

see darktable.tags.delete

attach

see darktable.tags.attach

detach

see darktable.tags.detach

name

type : string

The name of the tag.

#

type : types.dt_lua_image_t

The images that have that tag attached to them.

dt_lib_module_t

type : dt_type

The type of a UI lib

id

type : string

A unit string identifying the lib

name

type : string

The translated title of the UI element

version

type : number

The version of the internal data of this lib

visible

type : boolean

Allow to make a lib module completely invisible to the user.

Note that if the module is invisible the user will have no way to restore it without lua
Attributes : implicit_yield write

container

type : types.dt_ui_container_t

The location of the lib in the darktable UI

expandable

type : boolean

True if the lib can be expanded/retracted

expanded

type : boolean

True if the lib is expanded
Attributes : write

position

type : number

A value deciding the position of the lib within its container

views

type : table

A table of all the views that display this widget

reset

type : self:function(  )

A function to reset the lib to its default values

This function will do nothing if the lib is not visible or can't be reset

self

type : types.dt_lib_module_t

The lib to reset

on_screen

type : boolean

True if the lib is currently visible on the screen

dt_view_t

type : dt_type

A darktable view

id

type : string

A unique string identifying the view

name

type : string

The name of the view

dt_lua_backgroundjob_t

type : dt_type

A lua-managed entry in the backgroundjob lib

percent

type : number

The value of the progress bar, between 0 and 1. will return nil if there is no progress bar, will raise an error if read or written on an invalid job
Attributes : write

valid

type : boolean

True if the job is displayed, set it to false to destroy the entry

An invalid job cannot be made valid again
Attributes : write

dt_lua_snapshot_t

type : dt_type

The description of a snapshot in the snapshot lib
Attributes : has_tostring

filename

type : string

The filename of an image containing the snapshot

select

type : self:function(  )

Activates this snapshot on the display. To deactivate all snapshot you need to call this function on the active snapshot

self

type : types.dt_lua_snapshot_t

The snapshot to activate

name

type : string

The name of the snapshot, as seen in the UI

hint_t

type : enum

a hint on the way to encode a webp image
values :

  • hint_default
  • hint_picture
  • hint_photo
  • hint_graphic

dt_ui_container_t

type : enum

A place in the darktable UI where a lib can be placed
values :

  • DT_UI_CONTAINER_PANEL_LEFT_TOP
  • DT_UI_CONTAINER_PANEL_LEFT_CENTER
  • DT_UI_CONTAINER_PANEL_LEFT_BOTTOM
  • DT_UI_CONTAINER_PANEL_RIGHT_TOP
  • DT_UI_CONTAINER_PANEL_RIGHT_CENTER
  • DT_UI_CONTAINER_PANEL_RIGHT_BOTTOM
  • DT_UI_CONTAINER_PANEL_TOP_LEFT
  • DT_UI_CONTAINER_PANEL_TOP_CENTER
  • DT_UI_CONTAINER_PANEL_TOP_RIGHT
  • DT_UI_CONTAINER_PANEL_CENTER_TOP_LEFT
  • DT_UI_CONTAINER_PANEL_CENTER_TOP_CENTER
  • DT_UI_CONTAINER_PANEL_CENTER_TOP_RIGHT
  • DT_UI_CONTAINER_PANEL_CENTER_BOTTOM_LEFT
  • DT_UI_CONTAINER_PANEL_CENTER_BOTTOM_CENTER
  • DT_UI_CONTAINER_PANEL_CENTER_BOTTOM_RIGHT
  • DT_UI_CONTAINER_PANEL_BOTTOM

snapshot_direction_t

type : enum

Which part of the main window is occupied by a snapshot
values :

  • left
  • right
  • top
  • bottom

dt_imageio_j2k_format_t

type : enum

J2K format type
values :

  • j2k
  • jp2

dt_imageio_j2k_preset_t

type : enum

J2K preset type
values :

  • off
  • cinema2k_24
  • cinema2k_48
  • cinema4k_24

yield_type

type : enum

What type of event to wait for
values :

  • WAIT_MS
  • FILE_READABLE
  • RUN_COMMAND

comp_type_t

type : enum

Type of compression for webp
values :

  • webp_lossy
  • webp_lossless

lua_pref_type

type : enum

The type of value to save in a preference
values :

  • string
  • bool
  • integer
  • float
  • file
  • directory
  • enum

dt_imageio_exr_compression_t

type : enum

undocumented types.dt_imageio_exr_compression_t
values :

  • off
  • rle
  • zips
  • zip
  • piz
  • pxr24
  • b44
  • b44a

events

This section documents events that can be used to trigger Lua callbacks.

intermediate-export-image

type : event

This event is called each time an image is exported, once for each image after the image has been processed to an image format but before the storage has moved the image to its final destination.

callback

type : function( event : string, image : types.dt_lua_image_t, filename : string, format : types.dt_imageio_module_format_t, storage : types.dt_imageio_module_storage_t )

event

type : string

The name of the event that triggered the callback.

image

type : types.dt_lua_image_t

The image object that has been exported.

filename

type : string

The name of the file that is the result of the image being processed.

format

type : types.dt_imageio_module_format_t

The format used to export the image.

storage

type : types.dt_imageio_module_storage_t

The storage used to export the image (can be nil).

extra_registration_parameters

This event has no extra registration parameters.

post-import-image

type : event

This event is triggered whenever a new image is imported into the database.

This event can be registered multiple times, all callbacks will be called.

callback

type : function( event : string, image : types.dt_lua_image_t )

event

type : string

The name of the event that triggered the callback.

image

type : types.dt_lua_image_t

The image object that has been exported.

extra_registration_parameters

This event has no extra registration parameters.

shortcut

type : event

This event registers a new keyboad shortcut. The shortcut isn't bound to any key until the users does so in the preference panel.

The event is triggered whenever the shortcut is triggered.
This event can only be registered once per value of shortcut.

callback

type : function( event : string, shortcut : string )

event

type : string

The name of the event that triggered the callback.

shortcut

type : string

The tooltip string that was given at registration time.

extra_registration_parameters

tooltip

type : string

The string that will be displayed on the shortcut preference panel describing the shortcut.

post-import-film

type : event

This event is triggered when an film import is finished (all post-import-image callbacks have already been triggered). This event can be registered multiple times.

callback

type : function( event : string, film : types.dt_lua_film_t )

event

type : string

The name of the event that triggered the callback.

film

type : types.dt_lua_film_t

The new film that has been added. If multiple films were added recursively only the top level film is reported.

extra_registration_parameters

This event has no extra registration parameters.

view-changed

type : event

This event is triggered after the user changed the active view

callback

type : function( old_view : types.dt_view_t, new_view : types.dt_view_t )

old_view

type : types.dt_view_t

The view that we just left

new_view

type : types.dt_view_t

The view we are now in

extra_registration_parameters

This event has no extra registration parameters.

global_toolbox-grouping_toggle

type : event

This event is triggered after the user toggled the grouping button.

callback

type : function( toggle : boolean )

toggle

type : boolean

the new grouping status.

extra_registration_parameters

This event has no extra registration parameters.

global_toolbox-overlay_toggle

type : event

This event is triggered after the user toggled the overlay button.

callback

type : function( toggle : boolean )

toggle

type : boolean

the new overlay status.

extra_registration_parameters

This event has no extra registration parameters.

attributes

This section documents various attributes used throughout the documentation.

write

This object is a variable that can be written to.

has_tostring

This object has a specific reimplementation of the "tostring" method that allows pretty-printing it.

implicit_yield

This call will release the Lua lock while executing, thus allowing other Lua callbacks to run.

parent

This object inherits some methods from another object. You can call the methods from the parent on the child object

system

This section documents changes to system functions.

coroutine

yield

type : function( type : types.yield_type, extra : variable ) : variable

Lua functions can yield at any point. The parameters and return types depend on why we want to yield.

A callback that is yielding allows other Lua code to run.

  • wait_ms: one extra parameter; the execution will pause for that many miliseconds; yield returns nothing;
  • file_readable: an opened file from a call to the OS library; will return when the file is readable; returns nothing;
  • * run_command: a command to be run by "sh -c"; will return when the command terminates; returns the return code of the execution.

type

type : types.yield_type

The type of yield.

extra

type : variable

An extra parameter: integer for "wait_ms", open file for "file_readable", string for "run_command".

return

type : variable

Nothing for "wait_ms" and "file_readable"; the returned code of the command for "run_command".

Also available in: PDF HTML TXT

Go to top