Scripting with Lua on darktable 5.6 user manual

overview

Mon, 01 Jan 0001 00:00:00 +0000

Lua scripts can be used to define actions for darktable to perform when an event is triggered. One example might be calling an external application during file export in order to apply additional processing steps outside of darktable.

Lua is an independent project founded in 1993, providing a powerful, fast, lightweight, embeddable scripting language. Lua is widely used by many open source applications, in commercial programs, and for games programming. darktable uses Lua version 5.4. Describing the principles and syntax of Lua is beyond the scope of this manual. For a detailed introduction see the Lua reference manual.

darktable's scripts

Mon, 01 Jan 0001 00:00:00 +0000

🔗from 5.6 onward

A collection of scripts is included with darktable. They can be disabled in preferences > lua.

Starting with darktable 5.6, the lua-scripts are included with the release, so they no longer have to installed separately.

See basic principles for an explanation of how darktable loads Lua scripts.

Documentation for darktable’s scripts is available in the lua docs.

🔗pre 5.6

Pre 5.6 the scripts were not bundled and had to be installed using the following instructions.

basic principles

Mon, 01 Jan 0001 00:00:00 +0000

Scripts can register callbacks to perform actions on various darktable events. This callback mechanism is the primary method of triggering lua actions.

The central orchestrator for lua scripts is the script manager, which spawns the utility module scripts in the lighttable and loads darktable’s bundled scripts.

Lua scripts can be disabled in preferences/lua options.

🔗how darktable loads scripts (and the script manager)

darktable treats two kinds of location differently: Files that are executed as Lua code, and directories that are scanned for scripts:

a simple lua example

Mon, 01 Jan 0001 00:00:00 +0000

Let’s start with a simple example that will print some code on the console. Create a file called luarc in darktable’s configuration directory and add the following line to it:

print("Hello World !")

Start darktable from the console and you will see the sentence “Hello World !” printed on the console. Nothing fancy but it’s a start.

At this point, there is nothing darktable-specific in the script. We simply use Lua’s standard print function to print a string. That’s nice and all, but we can do better than that. To access the darktable API you first need to require it and save the returned object in a variable. Once this is done you can access the darktable API as subfields of the returned object. All of this is documented in darktable’s Lua API reference manual.

printing labeled images

Mon, 01 Jan 0001 00:00:00 +0000

The first example showed us the very basics of lua and allowed us to check that everything was working properly. Now let’s do something a little bit more complex. Let’s try to print a list of images that have a “red” label attached to them. But first of all, what is an image?

local darktable = require "darktable"
local debug = require "darktable.debug"
print(darktable.debug.dump(darktable.database[1]))

Running the code above will produce a lot of output. We will look at it in a moment, but first let’s look at the code itself.

adding a simple shortcut

Mon, 01 Jan 0001 00:00:00 +0000

So far, all our scripts have done things during startup. This is of limited use and doesn’t allow us to react to real user actions. To do more advanced things we need to register a function that will be called on a given event. The most common event to react to is a keyboard shortcut.

darktable = require "darktable"

local function hello_shortcut(event, shortcut)
darktable.print("Hello, I just received '"..event..
       "' with parameter '"..shortcut.."'")
end

darktable.register_event("hello shortcut",
       "shortcut",hello_shortcut,
       "A shortcut that prints its parameters")

Now start darktable, go to “preferences > shortcuts > lua > A shortcut that prints its parameters”, assign a shortcut and try it. You should see a nice message printed on the screen.

exporting images with lua

Mon, 01 Jan 0001 00:00:00 +0000

So far we have learned to use lua to adapt darktable to our particular workflow. Let’s look now at how to use lua to easily export images to an online service. If you are able to upload an image to a service via the command line then you can use lua to integrate this into darktable’s user interface.

In this next example we will use lua to export via scp. A new storage type will appear in darktable’s UI that will export images to a remote target via the copy mechanism in ssh.

building user interface elements

Mon, 01 Jan 0001 00:00:00 +0000

Our previous example was a bit limited. In particular the use of a preference for the export path wasn’t very nice. We can do better than that by adding elements to the user interface in the export dialog.

UI elements are created via the darktable.new_widget function. This function takes a type of widget as a parameter and returns a new object corresponding to that widget. You can then set various fields in that widget to set its parameters. You will then use that object as a parameter to various functions that will add it to the darktable UI. The following simple example adds a lib in the lighttable view with a simple label:

sharing scripts

Mon, 01 Jan 0001 00:00:00 +0000

So far, all of our lua code has been in luarc. That’s a good way to develop your script but not very practical for distribution. We need to make this into a proper lua module. To do that, we save the code in a separate file (scp-storage.lua in this case):

--[[
SCP STORAGE
a simple storage to export images via scp

AUTHOR
Jérémy Rosen (jeremy.rosen@enst-bretagne.fr)

INSTALLATION
* copy this file in $CONFIGDIR/lua/
* add the following line in the file $CONFIGDIR/luarc
  require "scp-storage"

USAGE
* select "Export via SCP" in the storage selection menu
* set the target directory 
* export your images

LICENSE
GPLv2

]]

darktable = require "darktable"
dtutils = require "lib/dtutils"

dtutils.check_min_api_version("7.0.0", ...)

local scp_path = darktable.new_widget("entry"){
  tooltip = "Complete path to copy to. Can include user and hostname",
  text = "",
  reset_callback = function(self) self.text = "" end
}

darktable.register_storage("scp_export","Export via scp",
  function( storage, image, format, filename,
     number, total, high_quality, extra_data)
    if not darktable.control.execute("scp "..filename.." "..
      scp_path.text
    ) then
      darktable.print_error("scp failed for "..tostring(image))
    end
  end,
  nil, --finalize
  nil, --supported
  nil, --initialize
  darktable.new_widget("box") {
    orientation = "horizontal",
    darktable.new_widget("label"){ label = "target SCP PATH " },
    scp_path,
})

darktable will look for scripts (following the normal lua rules) in the standard directories plus $CONFIGDIR/lua/*.lua. So our script can be called by simply adding require "scp-storage" in the luarc file. A couple of extra notes…

calling lua from dbus

Mon, 01 Jan 0001 00:00:00 +0000

It is possible to send a lua command to darktable via its DBus interface. The method org.darktable.service.Remote.Lua takes a single string parameter which is interpreted as a lua command. The command will be executed in the current lua context and should return either nil or a string. The result will be passed back as the result of the DBus method.

If the Lua call results in an error, the DBus method call will return an error org.darktable.Error.LuaError with the lua error message as the message attached to the DBus error.

using darktable from a lua script

Mon, 01 Jan 0001 00:00:00 +0000

Warning: This feature is very experimental. It is known that several elements don’t yet work in library mode. Careful testing is highly recommended.

The lua interface allows you to use darktable from any lua script. This will load darktable as a library and provide you with most of the lua API (darktable is configured headless, so the functions relating to the user interface are not available).

As an example, the following program will print the list of all images in your library:

lua API

Mon, 01 Jan 0001 00:00:00 +0000

darktable’s Lua API is documented in its own manual with a detailed description of all data structures and functions. You can download the API manual from here.