Сценарії за допомогою Lua on darktable 5.6 user manual

Огляд

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

Сценарії Lua можуть бути використані для визначення дій для Darktable, які слід виконувати при активації події. Одним з прикладів може бути виклик зовнішньої програми під час експорту файлу, щоб застосувати додаткові кроки обробки за межами Darktable.

Lua – це незалежний проєкт, заснований у 1993 році, що забезпечує потужну, швидку, легку та вбудовувану мову сценаріїв. Lua широко використовується багатьма програмами з відкритим кодом, у комерційних програмах та для програмування ігор. Darktable використовує Lua версії 5.4. Опис принципів та синтаксису Lua виходить за рамки цього посібника. Для детального ознайомлення див. Довідковий посібник з Lua.

Сценарії в Darktable

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

🔗Від 5.6 і далі

Колекція сценаріїв включена до комплекту Darktable. Їх можна вимкнути в Налаштування > Опції Lua.

Починаючи з Darktable 5.6, Lua-сценарії включені до релізу, тому їх більше не потрібно встановлювати окремо.

Див. основні принципи для пояснення того, як Darktable завантажує Lua-сценарії.

Документація щодо сценаріїв у Darktable доступна в Документації Lua.

🔗До 5.6

До версії 5.6 сценарії не були включені до комплекту та їх потрібно було встановлювати, дотримуючись наступних інструкцій.

🔗Завантаження та встановлення

Колекція сценаріїв доступна в репозиторії lua-scripts. Це також включає менеджер сценаріїв, який спрощує вмикання або вимикання окремих сценаріїв з графічного інтерфейсу. Документація для цих сценаріїв Lua міститься в документації Lua.

Основні принципи

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

Сценарії можуть реєструвати зворотні виклики для виконання дій при настанні різних подій. Цей механізм зворотного виклику є основним методом активації дій Lua.

Центральним оркестратором для Lua-сценаріїв є менеджер сценаріїв, який запускає сервісний модуль Сценарії у режимі Світлого стола та завантажує сценарії, що входять до комплекту Darktable.

Сценарії Lua можна вимкнути в Налаштування > Опції Lua.

🔗Як Darktable завантажує сценарії (і менеджер сценаріїв)

Darktable по-різному обробляє два типи розташування: файли, які виконуються як код Lua, та каталоги, які скануються на наявність сценаріїв:

Простий приклад Lua

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

Почнемо з простого прикладу, який надрукує якийсь код на консолі. Створіть файл з назвою luarc у каталозі конфігурації Darktable і додайте до нього такий рядок:

print("Hello World !")

Запустіть Darktable з консолі, і ви побачите на консолі надруковану фразу “Hello World !”. Нічого вигадливого, але це початок.

На цей момент у сценарії немає нічого специфічного для Darktable. Ми просто використовуємо стандартну функцію друку Lua для друку рядка. Це приємно і все таке, але ми можемо зробити й краще. Для доступу до API Darktable вам спочатку потрібно “вимагати” його (require) та зберегти повернутий об’єкт у змінну. Після цього ви зможете отримати доступ до API Darktable як підполя поверненого об’єкта. Все це задокументовано в довідковому посібнику Lua API від Darktable.

Друк зображень із міткою

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

Перший приклад показав нам самі основи Lua і дозволив перевірити, чи все працює належним чином. А тепер зробімо щось дещо складніше. Спробуємо надрукувати список зображень, до яких прикріплена “червона” позначка. Але перш за все, що таке зображення?

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

Запуск наведеного вище коду дасть багато результату на виході. Ми розглянемо це за мить, але спочатку розглянемо сам код.

Ми знаємо про require darktable. Тут нам потрібно окремо require darktable.debug, що є необов’язковим розділом API, який надає допоміжні функції для допомоги у налагодженні сценаріїв Lua.

Додавання простого прискорювача

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

Поки що всі наші сценарії робили щось під час запуску. Це має обмежену користь і не дозволяє нам реагувати на реальні дії користувача. Щоб зробити більш просунуті речі, нам потрібно зареєструвати функцію, яка буде викликана при настанні певної події. Найпоширеніша подія, на яку слід реагувати, – це клавіатурний прискорювач.

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

Тепер запустіть Darktable, перейдіть до “Налаштування > Клавіатурні прискорювачі > Lua > A shortcut that prints its parameters”, призначте прискорювач і спробуйте. Ви повинні побачити приємне повідомлення, надруковане на екрані.

Експортування зображень за допомогою Lua

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

Дотепер ми навчилися використовувати Lua для адаптації Darktable до нашого конкретного робочого процесу. Давайте зараз розглянемо, як за допомогою Lua легко експортувати зображення в онлайн-сервіс. Якщо ви можете завантажити зображення в цей сервіс через командний рядок, ви можете використовувати Lua для інтеграції цього в інтерфейс користувача Darktable.

У цьому наступному прикладі ми будемо використовувати Lua для експорту через scp. У інтерфейсі користувача Darktable з’явиться новий тип сховища, який експортуватиме зображення до віддаленої цілі за допомогою механізму копіювання в ssh.

Побудова елементів інтерфейсу користувача

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

Наш попередній приклад був трохи обмеженим. Зокрема, використання налаштувань для шляху експорту було не дуже гарним рішенням. Ми можемо зробити це краще, додавши елементи до інтерфейсу користувача у діалоговому вікні експорту.

Елементи інтерфейсу створюються за допомогою функції darktable.new_widget. Ця функція приймає тип віджета як параметр і повертає новий об’єкт, відповідний цьому віджету. Потім ви можете встановити різні поля у цьому віджеті, щоб встановити його параметри. Потім ви використовуватимете цей об’єкт як параметр для різних функцій, які додадуть його до інтерфейсу Darktable. Наступний простий приклад додає lib у режимі світлого стола з простою міткою:

Обмін сценаріями

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

Наразі весь наш код Lua був у luarc. Це хороший спосіб розробити свій сценарій, але не дуже практичний для розповсюдження. Нам потрібно зробити це належним модулем Lua. Для цього ми зберігаємо код в окремому файлі (в цьому випадку scp-storage.lua):

--[[
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 шукатиме сценарії (дотримуючись звичайних правил Lua) у стандартних каталогах плюс $CONFIGDIR/lua/*.lua. Отже, наш сценарій можна викликати, просто додавши require "scp-storage" у файл luarc. Пара додаткових приміток…

Виклик Lua з D-Bus

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

Можна надіслати команду Lua на Darktable через його інтерфейс D-Bus. Метод org.darktable.service.Remote.Lua приймає один параметр рядка, який інтерпретується як команда Lua. Команда буде виконана в поточному контексті Lua і повинна повернути або нічого, або рядок. Результат буде передано назад як результат методу D-Bus.

Якщо виклик Lua призводить до помилки, виклик методу D-Bus поверне помилку org.darktable.Error.LuaError із повідомленням про помилку Lua як повідомлення, прикріплене до помилки D-Bus.

Використання Darktable зі сценарію Lua

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

Попередження: ця функція дуже експериментальна. Відомо, що кілька елементів ще не працюють у бібліотечному режимі. Настійно рекомендується ретельне тестування.

Інтерфейс Lua дозволяє використовувати Darktable з будь-якого сценарію Lua. Це завантажить Darktable як бібліотеку та надасть вам більшість API Lua (Darktable налаштовано без відображення інтерфейсу, тому функції, що стосуються інтерфейсу користувача, недоступні).

Наприклад, наступна програма надрукує список усіх зображень у вашій бібліотеці:

#!/usr/bin/env lua
package = require "package"
package.cpath=package.cpath..";./lib/darktable/lib?.so"

dt = require("darktable")(
"--library", "./library.db",
"--datadir", "./share/darktable",
"--moduledir", "./lib/darktable",
"--configdir", "./configdir",
"--cachedir","cachedir",
"--g-fatal-warnings")

require("darktable.debug")

for k,v in ipairs(dt.database) do
   print(tostring(v))
end

Зверніть увагу на третій рядок, який вказує на розташування файлу libdarktable.so.

Lua API

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

Lua API Darktable задокументовано у власному посібнику з докладним описом усіх структур даних та функцій. Ви можете завантажити посібник з API з цієї сторінки.