@pired/lightroom-mcp 3.1.0

package/dist/LightroomMCP.lrplugin/HandlerAIMasks.lua

@@ -0,0 +1,549 @@
+local LrApplication = import 'LrApplication'
+local LrTasks = import 'LrTasks'
+local LrApplicationView = import 'LrApplicationView'
+local LrDevelopController = import 'LrDevelopController'
+
+local PhotoLookup = require 'PhotoLookup'
+local Log = require 'Log'
+
+local AIMaskHandler = {}
+
+-- =====================================================================
+-- add_ai_mask — AI subject/sky/background selection masks
+-- =====================================================================
+--
+-- Lightroom Classic's AI masking (Select Subject / Select Sky / ...) is
+-- exposed to the SDK through LrDevelopController:
+--
+--   maskId = LrDevelopController.createNewMask("aiSelection", subtype)
+--
+-- Unlike the catalog write APIs used by most handlers, LrDevelopController
+-- drives the Develop module of the running Lightroom UI: the target photo
+-- must be selected in the filmstrip and the Develop module active, and the
+-- AI computation itself runs inside Lightroom (seconds on fast machines).
+-- The handler therefore, per photo:
+--
+--   1. selects the photo (outside any catalog gate — it yields, #134/#124);
+--   2. switches to the Develop module (once, before the batch);
+--   3. engages the masking tool if another tool is active;
+--   4. creates the AI selection mask;
+--   5. applies the requested adjustment sliders to the new mask.
+--
+-- Everything is pcall-wrapped and reported honestly per photo: if a
+-- particular subtype is unavailable in the installed Lightroom version,
+-- or the photo has no detectable subject, the error surfaces in that
+-- photo's entry instead of failing the whole call.
+--
+-- Best verified visually afterwards with get_photo_preview.
+
+-- Subtypes accepted by createNewMask("aiSelection", ...). Availability of
+-- people/objects/landscape depends on the Lightroom Classic version.
+local SELECTION_TYPES = {
+    subject = true,
+    sky = true,
+    background = true,
+    objects = true,
+    people = true,
+    landscape = true,
+}
+
+-- Friendly arg name -> LrDevelopController setValue param + valid range.
+-- Temperature/Tint are deliberately NOT offered here: in the masking
+-- context those sliders are relative (-100..100) while the global Develop
+-- parameters are Kelvin/-150..150, and the SDK docs do not pin down which
+-- one setValue targets while a mask is active. Rather than risk silently
+-- overwriting the global white balance, local color work goes through
+-- add_local_adjustment (LocalTemperature2012/LocalTint2012, verified).
+local ADJUSTMENTS = {
+    exposure = { key = "Exposure2012", min = -5, max = 5 },
+    contrast = { key = "Contrast2012", min = -100, max = 100 },
+    highlights = { key = "Highlights2012", min = -100, max = 100 },
+    shadows = { key = "Shadows2012", min = -100, max = 100 },
+    whites = { key = "Whites2012", min = -100, max = 100 },
+    blacks = { key = "Blacks2012", min = -100, max = 100 },
+    texture = { key = "Texture", min = -100, max = 100 },
+    clarity = { key = "Clarity2012", min = -100, max = 100 },
+    dehaze = { key = "Dehaze", min = -100, max = 100 },
+    vibrance = { key = "Vibrance", min = -100, max = 100 },
+    saturation = { key = "Saturation", min = -100, max = 100 },
+    sharpness = { key = "Sharpness", min = 0, max = 150 },
+}
+
+local SUPPORTED_ADJUSTMENT_NAMES = (function()
+    local names = {}
+    for k in pairs(ADJUSTMENTS) do table.insert(names, k) end
+    table.sort(names)
+    return table.concat(names, ", ")
+end)()
+
+-- Named adjustment recipes for AI/range masks (ported from lightroom-cli's
+-- presets.py, minus 'warm-skin': it relies on Temp/Tint, which this handler
+-- deliberately does not expose — see the ADJUSTMENTS note above).
+local ADJUSTMENT_PRESETS = {
+    darken_sky = { exposure = -0.7, highlights = -30, saturation = 15 },
+    brighten_subject = { exposure = 0.5, shadows = 20, clarity = 10 },
+    blur_background = { sharpness = -80, clarity = -40 },
+    enhance_landscape = { clarity = 30, vibrance = 25, dehaze = 15 },
+}
+
+local SETTLE_AFTER_MODULE_SWITCH_S = 0.5
+local SETTLE_BETWEEN_PHOTOS_S = 0.3
+
+local function buildAdjustments(input)
+    if input == nil then return {} end
+    if type(input) ~= "table" then
+        error("adjustments must be an object")
+    end
+    local out = {}
+    for name, value in pairs(input) do
+        local spec = ADJUSTMENTS[name]
+        if not spec then
+            error("unknown adjustment '" .. tostring(name)
+                .. "' (supported: " .. SUPPORTED_ADJUSTMENT_NAMES .. ")")
+        end
+        if type(value) ~= "number" then
+            error("adjustment '" .. tostring(name) .. "' must be a number")
+        end
+        if value < spec.min or value > spec.max then
+            error(string.format("adjustment '%s' must be between %s and %s",
+                name, tostring(spec.min), tostring(spec.max)))
+        end
+        table.insert(out, { name = name, key = spec.key, value = value })
+    end
+    return out
+end
+
+local function resolveAdjustments(args)
+    if args.adjustments ~= nil and args.adjustment_preset ~= nil then
+        error("pass either adjustments or adjustment_preset, not both")
+    end
+    if args.adjustment_preset ~= nil then
+        local preset = ADJUSTMENT_PRESETS[args.adjustment_preset]
+        if not preset then
+            error("adjustment_preset must be one of: darken_sky, brighten_subject, blur_background, enhance_landscape")
+        end
+        return buildAdjustments(preset), args.adjustment_preset
+    end
+    return buildAdjustments(args.adjustments), nil
+end
+
+-- Shared per-photo batch loop: selects each photo in Develop, engages the
+-- masking tool if needed, creates the mask through `createMask()`, then
+-- applies the requested adjustment sliders. Returns (results, succeeded).
+local function runMaskCreationBatch(catalog, photos, createMask, adjustments)
+    local results = {}
+    local succeeded = 0
+    local failed = 0
+
+    for i, photo in ipairs(photos) do
+        if i > 1 then LrTasks.sleep(SETTLE_BETWEEN_PHOTOS_S) end
+
+        local entry = {
+            photo = {
+                id = photo.localIdentifier,
+                path = photo:getRawMetadata('path'),
+                filename = photo:getFormattedMetadata('fileName'),
+            },
+        }
+        table.insert(results, entry)
+
+        local ok = pcall(function()
+            catalog:setSelectedPhotos(photo, { photo })
+        end)
+        if not ok then
+            entry.error = "could not select the photo in Lightroom"
+            failed = failed + 1
+        else
+            -- Engage the masking tool only if another tool is active; a
+            -- fresh createNewMask usually does this itself, but the guard
+            -- mirrors how the Develop UI behaves when a tool is stuck open.
+            local currentToolOk, currentTool = pcall(function()
+                return LrDevelopController.getSelectedTool()
+            end)
+            if currentToolOk and currentTool ~= "masking" then
+                pcall(function() LrDevelopController.selectTool("masking") end)
+            end
+
+            local maskOk, maskId = pcall(createMask)
+            if not maskOk or maskId == nil then
+                entry.error = "createNewMask failed: " .. tostring(maskId)
+                failed = failed + 1
+            else
+                entry.mask_id = maskId
+                entry.applied = {}
+                entry.adjustment_errors = {}
+
+                for _, adj in ipairs(adjustments) do
+                    local applied, err = pcall(function()
+                        LrDevelopController.setValue(adj.key, adj.value)
+                    end)
+                    if applied then
+                        entry.applied[adj.name] = adj.value
+                    else
+                        entry.adjustment_errors[adj.name] = tostring(err)
+                    end
+                end
+                if next(entry.adjustment_errors) == nil then
+                    entry.adjustment_errors = nil
+                end
+                succeeded = succeeded + 1
+            end
+        end
+    end
+
+    return results, succeeded, failed
+end
+
+local function resolveSinglePhoto(catalog, photoId)
+    local photo = nil
+    catalog:withReadAccessDo(function()
+        local resolved = PhotoLookup.resolveMany(catalog, { photoId })
+        if resolved[1] and resolved[1].photo then
+            photo = resolved[1].photo
+        end
+    end)
+    return photo
+end
+
+local function switchToDevelopAndSelect(catalog, photo)
+    -- switchToModule and setSelectedPhotos both yield to the UI thread, so
+    -- they must run OUTSIDE any catalog access gate (#134/#124).
+    local switchOk, switchErr = pcall(function()
+        LrApplicationView.switchToModule("develop")
+    end)
+    if not switchOk then
+        error("could not switch Lightroom to the Develop module: "
+            .. tostring(switchErr))
+    end
+    LrTasks.sleep(SETTLE_AFTER_MODULE_SWITCH_S)
+
+    local selectOk = pcall(function()
+        catalog:setSelectedPhotos(photo, { photo })
+    end)
+    if not selectOk then
+        error("could not select the photo in Lightroom")
+    end
+    LrTasks.sleep(SETTLE_BETWEEN_PHOTOS_S)
+end
+
+function AIMaskHandler.addAIMask(args)
+    args = args or {}
+    if not args.photo_ids or #args.photo_ids == 0 then
+        error("photo_ids is required")
+    end
+
+    local selectionType = args.selection_type or "subject"
+    if not SELECTION_TYPES[selectionType] then
+        error("selection_type must be one of: subject, sky, background, objects, people, landscape")
+    end
+
+    local adjustments, presetName = resolveAdjustments(args)
+
+    local catalog = LrApplication.activeCatalog()
+
+    local photos = {}
+    catalog:withReadAccessDo(function()
+        local resolved = PhotoLookup.resolveMany(catalog, args.photo_ids)
+        for _, entry in ipairs(resolved) do
+            if entry.photo then table.insert(photos, entry.photo) end
+        end
+    end)
+
+    if #photos == 0 then
+        error("No photos matched photo_ids")
+    end
+
+    -- switchToModule and setSelectedPhotos both yield to the UI thread, so
+    -- they must run OUTSIDE any catalog access gate (#134/#124).
+    local switchOk, switchErr = pcall(function()
+        LrApplicationView.switchToModule("develop")
+    end)
+    if not switchOk then
+        error("could not switch Lightroom to the Develop module: "
+            .. tostring(switchErr))
+    end
+    LrTasks.sleep(SETTLE_AFTER_MODULE_SWITCH_S)
+
+    local results, succeeded, failed = runMaskCreationBatch(catalog, photos, function()
+        return LrDevelopController.createNewMask("aiSelection", selectionType)
+    end, adjustments)
+
+    Log.info(string.format("addAIMask('%s'): %d/%d photos",
+        selectionType, succeeded, #photos))
+
+    local result = {
+        success = failed == 0,
+        selection_type = selectionType,
+        requested = #photos,
+        succeeded = succeeded,
+        failed = failed,
+        results = results,
+        method = "LrDevelopController.createNewMask('aiSelection')",
+        message = string.format("AI '%s' mask applied to %d of %d photos",
+            selectionType, succeeded, #photos),
+    }
+    if presetName then
+        result.adjustment_preset = presetName
+    end
+    if failed > 0 then
+        result.message = result.message
+            .. ". Check each photo's 'error' entry; verify masks visually with get_photo_preview."
+    end
+    return result
+end
+
+-- =====================================================================
+-- add_range_mask — luminance / color / depth range masks
+-- =====================================================================
+--
+-- LrDevelopController.createNewMask("rangeMask", "luminance"|"color"|"depth")
+-- creates a range mask on the photo loaded in Develop, then setValue
+-- applies the adjustment sliders to it (same flow as the AI masks).
+-- HONEST LIMITATION (also present in lightroom-cli): the SDK cannot set
+-- the range bounds or sample points, so a fresh range mask covers the
+-- full range — refine the bounds in the Lightroom UI afterwards, or use
+-- the adjustment sliders from here. 'depth' requires a photo that has
+-- depth data (iPhone portrait etc.).
+
+local RANGE_TYPES = {
+    luminance = true,
+    color = true,
+    depth = true,
+}
+
+function AIMaskHandler.addRangeMask(args)
+    args = args or {}
+    if not args.photo_ids or #args.photo_ids == 0 then
+        error("photo_ids is required")
+    end
+
+    local rangeType = args.range_type or "luminance"
+    if not RANGE_TYPES[rangeType] then
+        error("range_type must be one of: luminance, color, depth")
+    end
+
+    local adjustments, presetName = resolveAdjustments(args)
+
+    local catalog = LrApplication.activeCatalog()
+
+    local photos = {}
+    catalog:withReadAccessDo(function()
+        local resolved = PhotoLookup.resolveMany(catalog, args.photo_ids)
+        for _, entry in ipairs(resolved) do
+            if entry.photo then table.insert(photos, entry.photo) end
+        end
+    end)
+
+    if #photos == 0 then
+        error("No photos matched photo_ids")
+    end
+
+    local switchOk, switchErr = pcall(function()
+        LrApplicationView.switchToModule("develop")
+    end)
+    if not switchOk then
+        error("could not switch Lightroom to the Develop module: "
+            .. tostring(switchErr))
+    end
+    LrTasks.sleep(SETTLE_AFTER_MODULE_SWITCH_S)
+
+    local results, succeeded, failed = runMaskCreationBatch(catalog, photos, function()
+        return LrDevelopController.createNewMask("rangeMask", rangeType)
+    end, adjustments)
+
+    Log.info(string.format("addRangeMask('%s'): %d/%d photos",
+        rangeType, succeeded, #photos))
+
+    local result = {
+        success = failed == 0,
+        range_type = rangeType,
+        requested = #photos,
+        succeeded = succeeded,
+        failed = failed,
+        results = results,
+        method = "LrDevelopController.createNewMask('rangeMask')",
+        message = string.format("Range '%s' mask applied to %d of %d photos",
+            rangeType, succeeded, #photos),
+        note = "The SDK cannot set range bounds or sample points: the mask "
+            .. "covers the full range. Refine the bounds in Lightroom's UI, or "
+            .. "drive the look through the adjustment sliders.",
+    }
+    if presetName then
+        result.adjustment_preset = presetName
+    end
+    if failed > 0 then
+        result.message = result.message
+            .. ". Check each photo's 'error' entry."
+    end
+    return result
+end
+
+-- =====================================================================
+-- toggle_mask_overlay — show/hide mask overlays in the Develop UI
+-- =====================================================================
+--
+-- LrDevelopController.toggleOverlay() flips the red mask overlay in the
+-- Develop module, the fastest way for a human to eyeball what add_ai_mask /
+-- add_local_adjustment actually selected. Acts on the photo loaded in
+-- Develop; this handler selects the requested photo first so the overlay
+-- belongs to it deterministically.
+
+function AIMaskHandler.toggleMaskOverlay(args)
+    if args.photo_id == nil or args.photo_id == "" then
+        error("photo_id is required")
+    end
+
+    local catalog = LrApplication.activeCatalog()
+    local photo = resolveSinglePhoto(catalog, args.photo_id)
+    if not photo then
+        error("No photo matched photo_id")
+    end
+
+    switchToDevelopAndSelect(catalog, photo)
+
+    local ok, err = pcall(function()
+        LrDevelopController.toggleOverlay()
+    end)
+    if not ok then
+        error("toggleOverlay failed: " .. tostring(err)
+            .. " (requires the Develop module to be showing this photo)")
+    end
+
+    Log.info(string.format("toggleMaskOverlay: photo %s", tostring(photo.localIdentifier)))
+
+    return {
+        success = true,
+        photo = {
+            id = photo.localIdentifier,
+            path = photo:getRawMetadata('path'),
+        },
+        message = "Mask overlay toggled — check the Lightroom Develop view "
+            .. "(red overlay shows what is masked).",
+    }
+end
+
+-- =====================================================================
+-- list_masks / remove_mask — mask inventory management
+-- =====================================================================
+--
+-- LrDevelopController.getAllMasks() returns the masks of the photo loaded
+-- in the Develop module. The exact per-entry shape varies between Lightroom
+-- versions (name/id fields), so entries are passed through verbatim — pair
+-- list_masks with read_local_adjustments for the full stored structure.
+-- removeMask verifies through the mask count before/after, which is stable
+-- regardless of entry shape.
+
+local function currentMaskCount()
+    local ok, masks = pcall(function()
+        return LrDevelopController.getAllMasks()
+    end)
+    if not ok or type(masks) ~= "table" then return -1 end
+    return #masks
+end
+
+function AIMaskHandler.listMasks(args)
+    if args.photo_id == nil or args.photo_id == "" then
+        error("photo_id is required")
+    end
+
+    local catalog = LrApplication.activeCatalog()
+    local photo = resolveSinglePhoto(catalog, args.photo_id)
+    if not photo then
+        error("No photo matched photo_id")
+    end
+
+    switchToDevelopAndSelect(catalog, photo)
+
+    local masksOk, masks = pcall(function()
+        return LrDevelopController.getAllMasks()
+    end)
+    if not masksOk then
+        error("getAllMasks() failed: " .. tostring(masks))
+    end
+    masks = masks or {}
+
+    Log.info(string.format("listMasks: %d mask(s)", #masks))
+
+    return {
+        success = true,
+        photo = {
+            id = photo.localIdentifier,
+            path = photo:getRawMetadata('path'),
+        },
+        masks = masks,
+        count = #masks,
+        message = string.format("Photo has %d mask(s)", #masks),
+    }
+end
+
+function AIMaskHandler.removeMask(args)
+    if args.photo_id == nil or args.photo_id == "" then
+        error("photo_id is required")
+    end
+
+    local removeAll = args.remove_all == true
+
+    if not removeAll and args.mask_id == nil then
+        error("mask_id is required (or pass remove_all=true to clear every mask)")
+    end
+    if removeAll and args.confirm ~= true then
+        error("remove_all strips every mask from the photo: pass confirm=true to proceed")
+    end
+
+    local catalog = LrApplication.activeCatalog()
+    local photo = resolveSinglePhoto(catalog, args.photo_id)
+    if not photo then
+        error("No photo matched photo_id")
+    end
+
+    switchToDevelopAndSelect(catalog, photo)
+
+    local beforeCount = currentMaskCount()
+
+    if removeAll then
+        -- resetMasking() is the engine's "remove all masks" command
+        -- (lightroom-cli's `ai reset`).
+        local resetOk, resetErr = pcall(function()
+            LrDevelopController.resetMasking()
+        end)
+        if not resetOk then
+            error("resetMasking failed: " .. tostring(resetErr))
+        end
+    else
+        local delOk, delErr = pcall(function()
+            LrDevelopController.deleteMask(args.mask_id)
+        end)
+        if not delOk then
+            error("deleteMask failed: " .. tostring(delErr)
+                .. " (the mask id must belong to the current photo — check list_masks)")
+        end
+    end
+
+    -- Give the Develop module a beat to commit the deletion, then verify
+    -- through the mask count: the per-entry shape of getAllMasks() varies
+    -- between Lightroom versions, but a decrease is unambiguous.
+    LrTasks.sleep(SETTLE_BETWEEN_PHOTOS_S)
+    local afterCount = currentMaskCount()
+    local verified = beforeCount >= 0 and afterCount >= 0 and afterCount < beforeCount
+
+    Log.info(string.format("removeMask(%s): %d -> %d masks",
+        removeAll and "all" or tostring(args.mask_id), beforeCount, afterCount))
+
+    local result = {
+        success = true,
+        remove_all = removeAll,
+        masks_before = beforeCount,
+        masks_after = afterCount,
+        verified = verified,
+        message = string.format("%s (masks %d -> %d)",
+            removeAll and "Removed all masks" or ("Removed mask '" .. tostring(args.mask_id) .. "'"),
+            beforeCount, afterCount),
+    }
+    if not verified then
+        result.warning = "Mask count did not decrease — the photo may have "
+            .. "had no masks, or the id did not match. Run list_masks to inspect."
+    end
+    return result
+end
+
+return AIMaskHandler