@photivra/engine 2.12.0 → 2.13.0

package/dist/exposure/exposure-mode-resolver.js

@@ -17,7 +17,7 @@
 import { InvalidScientificInputError } from "../core/validation.js";
 import { EXPOSURE_METER_TARGET_SCHEMA_VERSION } from "./metering-target.js";
 import { parseExposureProgramLineProfile } from "./program-line.js";
-import { requireInputKeys } from "../core/record-validation.js";
+import { rejectUnknownFields, requireInputKeys } from "../core/record-validation.js";
 import { InvalidConfigurationError } from "../core/configuration-error.js";
 export const EXPOSURE_MODE_RESOLVER_VERSION = "0.5.0";
 function requireRecord(value, path) {
@@ -328,7 +328,7 @@ function nearestDiscreteIso(idealIso, values) {
             : "none"
     };
 }
-function autoIsoBounds(capabilities) {
+function bodyAutoIsoBounds(capabilities) {
     return {
         minimum: capabilities.iso
             .autoIsoMinimum ??
@@ -338,9 +338,75 @@ function autoIsoBounds(capabilities) {
             capabilities.iso.maximum
     };
 }
-function resolveAutomaticIso(idealIso, capabilities) {
+/**
+ * #505: the Auto ISO range a resolver chooses in: the body's Auto ISO range, narrowed by the
+ * photographer's validated limits when given. A limit outside the body's range, or off a discrete
+ * ISO grid, fails; it is never clipped.
+ */
+function autoIsoBounds(capabilities, limits, path = "autoIsoLimits") {
+    const body = bodyAutoIsoBounds(capabilities);
+    if (limits === undefined) {
+        return {
+            ...body,
+            minimumConstraint: "iso-minimum",
+            maximumConstraint: "iso-maximum"
+        };
+    }
+    const record = requireRecord(limits, path);
+    rejectUnknownFields(record, ["maximum", "minimum"], path);
+    const check = (value, field) => {
+        const iso = requirePositiveFinite(value, path + "." + field);
+        if (iso < body.minimum ||
+            iso > body.maximum) {
+            throw new InvalidScientificInputError(path +
+                "." +
+                field +
+                " (ISO " +
+                iso +
+                ") lies outside the body's Auto ISO range, ISO " +
+                body.minimum +
+                " to " +
+                body.maximum +
+                ".");
+        }
+        const grid = capabilities.iso.settingGrid;
+        if (grid.kind ===
+            "discrete-values" &&
+            !grid.values.some((candidate) => settingEquals(candidate, iso))) {
+            throw new InvalidScientificInputError(path +
+                "." +
+                field +
+                " (ISO " +
+                iso +
+                ") is not a selectable ISO of the resolved discrete ISO grid.");
+        }
+        return iso;
+    };
+    const maximum = check(record.maximum, "maximum");
+    const minimum = record.minimum === undefined
+        ? body.minimum
+        : check(record.minimum, "minimum");
+    if (minimum > maximum) {
+        throw new InvalidScientificInputError(path +
+            ".minimum must not exceed " +
+            path +
+            ".maximum.");
+    }
+    return {
+        minimum,
+        maximum,
+        minimumConstraint: minimum > body.minimum &&
+            !settingEquals(minimum, body.minimum)
+            ? "user-iso-minimum"
+            : "iso-minimum",
+        maximumConstraint: maximum < body.maximum &&
+            !settingEquals(maximum, body.maximum)
+            ? "user-iso-maximum"
+            : "iso-maximum"
+    };
+}
+function resolveAutomaticIso(idealIso, capabilities, bounds) {
     const grid = capabilities.iso.settingGrid;
-    const bounds = autoIsoBounds(capabilities);
     if (grid.kind ===
         "discrete-values") {
         const autoValues = grid.values.filter((value) => value >= bounds.minimum &&
@@ -351,6 +417,13 @@ function resolveAutomaticIso(idealIso, capabilities) {
         const discrete = nearestDiscreteIso(idealIso, autoValues);
         return {
             ...discrete,
+            limitingConstraint: discrete.clamped ===
+                "minimum"
+                ? bounds.minimumConstraint
+                : discrete.clamped ===
+                    "maximum"
+                    ? bounds.maximumConstraint
+                    : discrete.limitingConstraint,
             kind: "discrete"
         };
     }
@@ -361,7 +434,7 @@ function resolveAutomaticIso(idealIso, capabilities) {
             kind: "continuous",
             quantized: false,
             clamped: "minimum",
-            limitingConstraint: "iso-minimum"
+            limitingConstraint: bounds.minimumConstraint
         };
     }
     if (idealIso >
@@ -371,7 +444,7 @@ function resolveAutomaticIso(idealIso, capabilities) {
             kind: "continuous",
             quantized: false,
             clamped: "maximum",
-            limitingConstraint: "iso-maximum"
+            limitingConstraint: bounds.maximumConstraint
         };
     }
     return {
@@ -471,9 +544,8 @@ function resolveAutomaticShutter(idealShutterSeconds, capabilities) {
         limitingConstraint: "none"
     };
 }
-function minimumSelectableIso(capabilities) {
+function minimumSelectableIso(capabilities, bounds) {
     const grid = capabilities.iso.settingGrid;
-    const bounds = autoIsoBounds(capabilities);
     if (grid.kind ===
         "continuous-within-range") {
         return bounds.minimum;
@@ -978,6 +1050,11 @@ export function resolveManualExposureMode(input) {
             "nearest-log2-lower-on-tie") {
         throw new InvalidConfigurationError('isoControl.quantizationPolicy must be "nearest-log2-lower-on-tie".');
     }
+    const autoBounds = input.isoControl.kind ===
+        "automatic"
+        ? autoIsoBounds(input.capabilities, input.isoControl
+            .autoIsoLimits, "isoControl.autoIsoLimits")
+        : undefined;
     if (input.isoControl.kind ===
         "manual") {
         const manualIso = requirePositiveFinite(input.isoControl.iso, "isoControl.iso");
@@ -1052,7 +1129,7 @@ export function resolveManualExposureMode(input) {
         idealIso <= 0) {
         throw new InvalidScientificInputError("Ideal Auto ISO must remain finite and greater than zero.");
     }
-    const automatic = resolveAutomaticIso(idealIso, input.capabilities);
+    const automatic = resolveAutomaticIso(idealIso, input.capabilities, autoBounds);
     const achievedScale = opticalFactor *
         (automatic.iso /
             referenceExposure.iso);
@@ -1265,6 +1342,7 @@ export function resolveAperturePriorityAutoIsoExposureMode(input) {
                 .maximumSeconds) {
         throw new InvalidScientificInputError("policy.slowestPreferredShutterSeconds lies outside the resolved shutter capability range.");
     }
+    const autoBounds = autoIsoBounds(input.capabilities, policy.autoIsoLimits, "policy.autoIsoLimits");
     const availability = validateAutoIsoAvailability(input.capabilities);
     const commonBlocked = (blocker) => {
         const raw = buildPriorityAutoIsoBlocked("aperture-priority", target, referenceExposure, blocker, { aperture: manualAperture });
@@ -1292,7 +1370,7 @@ export function resolveAperturePriorityAutoIsoExposureMode(input) {
     if (target.status === "no-signal") {
         return commonBlocked("target-no-signal");
     }
-    const baselineIso = minimumSelectableIso(input.capabilities);
+    const baselineIso = minimumSelectableIso(input.capabilities, autoBounds);
     const factorAtReferenceShutter = opticalExposureFactor(manualAperture, referenceExposure
         .shutterSeconds, referenceExposure) *
         (baselineIso /
@@ -1316,7 +1394,13 @@ export function resolveAperturePriorityAutoIsoExposureMode(input) {
         manualShutterSeconds: shutter.shutterSeconds,
         isoControl: {
             kind: "automatic",
-            quantizationPolicy: policy.isoQuantizationPolicy
+            quantizationPolicy: policy.isoQuantizationPolicy,
+            ...(policy.autoIsoLimits ===
+                undefined
+                ? {}
+                : {
+                    autoIsoLimits: policy.autoIsoLimits
+                })
         }
     });
     if (isoPass.status !== "resolved" ||
@@ -1547,6 +1631,7 @@ export function resolveShutterPriorityExposureMode(input) {
             "not-wider-than-target") {
         throw new InvalidConfigurationError("Shutter Priority Auto ISO policy is invalid.");
     }
+    const autoBounds = autoIsoBounds(input.capabilities, policy.autoIsoLimits, "isoControl.policy.autoIsoLimits");
     const availability = validateAutoIsoAvailability(input.capabilities);
     if (availability !== "supported") {
         const raw = buildPriorityAutoIsoBlocked("shutter-priority", target, referenceExposure, availability === "unknown"
@@ -1586,7 +1671,7 @@ export function resolveShutterPriorityExposureMode(input) {
             }
         };
     }
-    const baselineIso = minimumSelectableIso(input.capabilities);
+    const baselineIso = minimumSelectableIso(input.capabilities, autoBounds);
     const idealAtBaseline = idealApertureForTarget(target
         .requiredExposureScaleToTarget, manualShutterSeconds, baselineIso, referenceExposure);
     const aperture = selectApertureNotWiderThanTarget(idealAtBaseline, input.capabilities);
@@ -1598,7 +1683,13 @@ export function resolveShutterPriorityExposureMode(input) {
         manualShutterSeconds,
         isoControl: {
             kind: "automatic",
-            quantizationPolicy: policy.isoQuantizationPolicy
+            quantizationPolicy: policy.isoQuantizationPolicy,
+            ...(policy.autoIsoLimits ===
+                undefined
+                ? {}
+                : {
+                    autoIsoLimits: policy.autoIsoLimits
+                })
         }
     });
     if (isoPass.status !== "resolved" ||
@@ -1738,6 +1829,10 @@ export function resolveProgramAutoExposureMode(input) {
             "nearest-log2-lower-on-tie") {
         throw new InvalidConfigurationError("Program Auto ISO policy is invalid.");
     }
+    const autoBounds = autoIsoBounds(input.capabilities, input.isoControl
+        .autoIsoLimits, "isoControl.autoIsoLimits");
+    const holdPolicy = validateProgramSlowestPreferredShutter(input.isoControl
+        .slowestPreferredShutter, input.capabilities);
     const availability = validateAutoIsoAvailability(input.capabilities);
     if (availability !== "supported") {
         return {
@@ -1767,28 +1862,94 @@ export function resolveProgramAutoExposureMode(input) {
             safetyShiftApplied: false
         };
     }
-    const baselineIso = minimumSelectableIso(input.capabilities);
+    const baselineIso = minimumSelectableIso(input.capabilities, autoBounds);
     const requestedOpticalStops = target
         .exposureOffsetStopsToTarget -
         Math.log2(baselineIso /
             referenceExposure.iso);
     const selection = selectProgramLineSettings(requestedOpticalStops, programLine, input.capabilities);
-    const isoPass = resolveManualExposureMode({
-        target,
-        capabilities: input.capabilities,
-        referenceExposure,
-        manualAperture: selection.resolvedAperture,
-        manualShutterSeconds: selection
-            .resolvedShutterSeconds,
-        isoControl: {
-            kind: "automatic",
-            quantizationPolicy: input.isoControl
-                .isoQuantizationPolicy
+    const isoControl = input.isoControl;
+    const autoIsoPass = (shutterSeconds) => {
+        const pass = resolveManualExposureMode({
+            target,
+            capabilities: input.capabilities,
+            referenceExposure,
+            manualAperture: selection.resolvedAperture,
+            manualShutterSeconds: shutterSeconds,
+            isoControl: {
+                kind: "automatic",
+                quantizationPolicy: isoControl
+                    .isoQuantizationPolicy,
+                ...(isoControl
+                    .autoIsoLimits ===
+                    undefined
+                    ? {}
+                    : {
+                        autoIsoLimits: isoControl
+                            .autoIsoLimits
+                    })
+            }
+        });
+        if (pass.status !== "resolved" ||
+            pass.isoControl !== "automatic") {
+            throw new InvalidScientificInputError("Program Auto could not resolve its Auto ISO pass.");
         }
-    });
-    if (isoPass.status !== "resolved" ||
-        isoPass.isoControl !== "automatic") {
-        throw new InvalidScientificInputError("Program Auto could not resolve its Auto ISO pass.");
+        return pass;
+    };
+    // #504: hold the line's shutter at or faster than the slowest preferred shutter before the ISO rises.
+    const lineShutterSeconds = selection
+        .resolvedShutterSeconds;
+    const holdApplied = holdPolicy !== undefined &&
+        lineShutterSeconds >
+            holdPolicy
+                .slowestPreferredShutterSeconds &&
+        !settingEquals(lineShutterSeconds, holdPolicy
+            .slowestPreferredShutterSeconds);
+    const heldShutterSeconds = holdApplied
+        ? selectShutterNotLongerThanTarget(holdPolicy
+            .slowestPreferredShutterSeconds, input.capabilities).shutterSeconds
+        : lineShutterSeconds;
+    const isoPass = autoIsoPass(heldShutterSeconds);
+    let resolvedSettings = isoPass.resolvedSettings;
+    let residual = isoPass.targetResidual;
+    let fallbackUsed = false;
+    if (holdApplied &&
+        holdPolicy.afterMaximumIso ===
+            "allow-slower-shutter" &&
+        isoPass.isoResolution.clamped ===
+            "maximum" &&
+        isoPass.targetResidual.state ===
+            "under-target") {
+        // At the Auto ISO maximum the shutter may lengthen toward the target, but not past the line's own shutter.
+        const maxIso = isoPass.resolvedSettings.iso;
+        const atReference = opticalExposureFactor(selection.resolvedAperture, referenceExposure
+            .shutterSeconds, referenceExposure) *
+            (maxIso /
+                referenceExposure.iso);
+        const idealShutter = referenceExposure
+            .shutterSeconds *
+            (target
+                .requiredExposureScaleToTarget /
+                atReference);
+        const beyondLine = idealShutter >=
+            lineShutterSeconds;
+        const shutter = beyondLine
+            ? {
+                shutterSeconds: lineShutterSeconds,
+                limitingConstraint: isoPass.targetResidual
+                    .limitingConstraint
+            }
+            : resolveAutomaticShutter(idealShutter, input.capabilities);
+        fallbackUsed = true;
+        resolvedSettings = {
+            aperture: selection.resolvedAperture,
+            shutterSeconds: shutter.shutterSeconds,
+            iso: maxIso
+        };
+        residual =
+            targetResidual(target, opticalExposureFactor(selection.resolvedAperture, shutter.shutterSeconds, referenceExposure) *
+                (maxIso /
+                    referenceExposure.iso), shutter.limitingConstraint);
     }
     return {
         resolverVersion: EXPOSURE_MODE_RESOLVER_VERSION,
@@ -1814,8 +1975,43 @@ export function resolveProgramAutoExposureMode(input) {
         idealIsoBeforeConstraints: isoPass
             .idealIsoBeforeConstraints,
         isoResolution: isoPass.isoResolution,
-        resolvedSettings: isoPass.resolvedSettings,
-        targetResidual: isoPass.targetResidual
+        resolvedSettings,
+        targetResidual: residual,
+        ...(holdPolicy === undefined
+            ? {}
+            : {
+                slowestPreferredShutter: {
+                    ...holdPolicy,
+                    applied: holdApplied,
+                    afterMaximumIsoFallbackUsed: fallbackUsed
+                }
+            })
+    };
+}
+function validateProgramSlowestPreferredShutter(value, capabilities) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const record = requireRecord(value, "isoControl.slowestPreferredShutter");
+    rejectUnknownFields(record, ["slowestPreferredShutterSeconds", "afterMaximumIso"], "isoControl.slowestPreferredShutter");
+    if (record.afterMaximumIso !==
+        "allow-slower-shutter" &&
+        record.afterMaximumIso !==
+            "hold-preferred-shutter") {
+        throw new InvalidConfigurationError('isoControl.slowestPreferredShutter.afterMaximumIso must be "allow-slower-shutter" or "hold-preferred-shutter".');
+    }
+    const seconds = requirePositiveFinite(record.slowestPreferredShutterSeconds, "isoControl.slowestPreferredShutter.slowestPreferredShutterSeconds");
+    if (seconds <
+        capabilities.shutter
+            .minimumSeconds ||
+        seconds >
+            capabilities.shutter
+                .maximumSeconds) {
+        throw new InvalidScientificInputError("isoControl.slowestPreferredShutter.slowestPreferredShutterSeconds lies outside the resolved shutter capability range.");
+    }
+    return {
+        slowestPreferredShutterSeconds: seconds,
+        afterMaximumIso: record.afterMaximumIso
     };
 }
 /**
@@ -1847,6 +2043,7 @@ export function resolveFullAutoExposureMode(input) {
             "nearest-log2-lower-on-tie") {
         throw new InvalidConfigurationError("Full Auto exposure policy is invalid.");
     }
+    const autoBounds = autoIsoBounds(input.capabilities, input.policy.autoIsoLimits, "policy.autoIsoLimits");
     const programLine = validateProgramLineForResolution(input.policy.programLine, referenceExposure, input.capabilities);
     const blocked = (blocker) => ({
         resolverVersion: EXPOSURE_MODE_RESOLVER_VERSION,
@@ -1890,7 +2087,7 @@ export function resolveFullAutoExposureMode(input) {
             ? "auto-iso-unknown"
             : "auto-iso-unsupported");
     }
-    const baselineIso = minimumSelectableIso(input.capabilities);
+    const baselineIso = minimumSelectableIso(input.capabilities, autoBounds);
     const requestedOpticalStops = target
         .exposureOffsetStopsToTarget -
         Math.log2(baselineIso /
@@ -1906,7 +2103,15 @@ export function resolveFullAutoExposureMode(input) {
         isoControl: {
             kind: "automatic",
             quantizationPolicy: input.policy
-                .isoQuantizationPolicy
+                .isoQuantizationPolicy,
+            ...(input.policy
+                .autoIsoLimits ===
+                undefined
+                ? {}
+                : {
+                    autoIsoLimits: input.policy
+                        .autoIsoLimits
+                })
         }
     });
     if (isoPass.status !== "resolved" ||