@photivra/engine 2.12.0 → 2.14.0

package/dist/exposure/exposure-mode-resolver.d.ts

@@ -7,12 +7,34 @@ export interface RelativeExposureControlAnchor {
     shutterSeconds: number;
     iso: number;
 }
+/**
+ * #505: the photographer's Auto ISO limits, a policy choice kept separate from what the body allows
+ * (`capabilities.iso.autoIsoMinimum`/`autoIsoMaximum`, else the ISO range). Cameras let the
+ * photographer cap Auto ISO, and some also raise its floor (for example the Nikon D850's "maximum
+ * sensitivity", Fujifilm's per-preset default and maximum sensitivity, and Panasonic's separate upper
+ * and lower Auto ISO limits; makers' manuals, see docs/USAGE.md).
+ *
+ * Both values are ISO settings: inside the body's Auto ISO range and, on a discrete ISO grid, one of
+ * its values, with `minimum` at most `maximum`. Anything else fails with
+ * `InvalidScientificInputError`; the engine never clips a limit silently. When a limit is strictly
+ * inside the body's range and the ISO is held there, the limiting constraint is `user-iso-maximum` or
+ * `user-iso-minimum`; a limit equal to the body's bound adds nothing, and the body's `iso-maximum` or
+ * `iso-minimum` is reported.
+ */
+export interface AutoIsoLimits {
+    /** The highest ISO Auto ISO may choose. */
+    maximum: number;
+    /** The lowest ISO Auto ISO may choose, and so its baseline. Default: the body's Auto ISO minimum. */
+    minimum?: number;
+}
 export type ManualIsoControl = {
     kind: "manual";
     iso: number;
 } | {
     kind: "automatic";
     quantizationPolicy: "nearest-log2-lower-on-tie";
+    /** #505: optional photographer-set Auto ISO limits inside the body's Auto ISO range. */
+    autoIsoLimits?: AutoIsoLimits;
 };
 export interface ResolveManualExposureModeInput {
     target: ExposureMeterTarget;
@@ -31,7 +53,7 @@ export interface ResolveAperturePriorityExposureModeInput {
     shutterQuantizationPolicy: "nearest-log2-shorter-on-tie";
 }
 export type ExposureTargetResidualState = "matched" | "under-target" | "over-target" | "target-unresolved";
-export type ExposureResolutionConstraint = "none" | "iso-minimum" | "iso-maximum" | "iso-grid-quantization" | "shutter-minimum" | "shutter-maximum" | "shutter-grid-quantization" | "aperture-widest" | "aperture-narrowest" | "aperture-grid-quantization";
+export type ExposureResolutionConstraint = "none" | "iso-minimum" | "iso-maximum" | "user-iso-minimum" | "user-iso-maximum" | "iso-grid-quantization" | "shutter-minimum" | "shutter-maximum" | "shutter-grid-quantization" | "aperture-widest" | "aperture-narrowest" | "aperture-grid-quantization";
 export type ExposureTargetResidual = {
     status: "resolved";
     state: "matched" | "under-target" | "over-target";
@@ -193,6 +215,8 @@ export type AperturePriorityExposureModeResolution = (AperturePriorityExposureRe
 export interface AutoIsoBaselinePolicy {
     isoBaseline: "minimum-selectable";
     isoQuantizationPolicy: "nearest-log2-lower-on-tie";
+    /** #505: optional photographer-set Auto ISO limits inside the body's Auto ISO range. */
+    autoIsoLimits?: AutoIsoLimits;
 }
 export interface AperturePriorityAutoIsoPolicy extends AutoIsoBaselinePolicy {
     kind: "minimum-iso-until-slowest-preferred-shutter";
@@ -394,7 +418,27 @@ export type ProgramAutoIsoControl = {
     kind: "automatic";
     isoBaseline: "minimum-selectable";
     isoQuantizationPolicy: "nearest-log2-lower-on-tie";
+    /** #505: optional photographer-set Auto ISO limits inside the body's Auto ISO range. */
+    autoIsoLimits?: AutoIsoLimits;
+    /**
+     * #504: optionally hold the program line's shutter at or faster than a slowest preferred shutter
+     * before the ISO rises (for example from `estimateAutoIsoSlowestShutter()`). Absent, the program line
+     * is followed as before.
+     */
+    slowestPreferredShutter?: ProgramSlowestPreferredShutterPolicy;
 };
+/**
+ * #504: Program + Auto ISO's slowest preferred shutter, the two-axis policy of Aperture Priority + Auto
+ * ISO applied to the program line. When the line asks for a longer shutter than
+ * `slowestPreferredShutterSeconds`, the shutter is held there (snapped, never longer) with the line's
+ * aperture, and Auto ISO makes up the rest. At the Auto ISO maximum, `afterMaximumIso` decides:
+ * `"allow-slower-shutter"` lengthens the shutter toward the target, but never past the program line's
+ * own shutter; `"hold-preferred-shutter"` keeps it and leaves the exposure under target.
+ */
+export interface ProgramSlowestPreferredShutterPolicy {
+    slowestPreferredShutterSeconds: number;
+    afterMaximumIso: "allow-slower-shutter" | "hold-preferred-shutter";
+}
 export interface ResolveProgramAutoExposureModeInput {
     target: ExposureMeterTarget;
     capabilities: ResolvedGenericEquipmentExposureCapabilities;
@@ -407,6 +451,8 @@ export interface FullAutoExposurePolicy {
     programLine: ExposureProgramLineProfile;
     isoBaseline: "minimum-selectable";
     isoQuantizationPolicy: "nearest-log2-lower-on-tie";
+    /** #505: optional photographer-set Auto ISO limits inside the body's Auto ISO range. */
+    autoIsoLimits?: AutoIsoLimits;
 }
 export interface ResolveFullAutoExposureModeInput {
     target: ExposureMeterTarget;
@@ -481,6 +527,16 @@ export type ProgramAutoExposureModeResolution = (ProgramExposureResolutionBase &
     targetResidual: Extract<ExposureTargetResidual, {
         status: "resolved";
     }>;
+    /**
+     * #504: present only with `isoControl.slowestPreferredShutter`. `applied` is true when the line's
+     * shutter was longer than the slowest preferred shutter and was held; `afterMaximumIsoFallbackUsed`
+     * when the slower-shutter fallback ran at the Auto ISO maximum. `programLineSelection` stays the
+     * line's own selection.
+     */
+    slowestPreferredShutter?: ProgramSlowestPreferredShutterPolicy & {
+        applied: boolean;
+        afterMaximumIsoFallbackUsed: boolean;
+    };
 }) | {
     resolverVersion: typeof EXPOSURE_MODE_RESOLVER_VERSION;
     mode: "program-auto";

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