@photivra/engine 2.12.0 → 2.13.0

package/dist/facade/simulate-capture.d.ts

@@ -1,6 +1,6 @@
 import type { EvidenceProvenance } from "../core/evidence-provenance.js";
 import { type GenericEquipmentTier, type GenericEquipmentTierPreset } from "../equipment/generic-tier-assets.js";
-import { type ExposureResolutionConstraint } from "../exposure/exposure-mode-resolver.js";
+import { type AutoIsoLimits, type ExposureResolutionConstraint } from "../exposure/exposure-mode-resolver.js";
 import { resolveColorTemperatureWhiteBalance, type ResolvedWhiteBalanceState } from "../color/white-balance.js";
 import { type CaptureWhiteBalanceIntent } from "../capture/simulated-capture.js";
 import { type NativeRawOutput, type NativeRawPlan } from "../capture/native-raw.js";
@@ -41,23 +41,81 @@ export type SimulateCaptureAutoIsoAfterMaximum = "allow-slower-shutter" | "hold-
 export interface SimulateCaptureAutoIsoReport {
     /** The ISO the meter target asked for at the resolved aperture and shutter, before the Auto ISO range and the ISO grid. */
     idealIsoBeforeConstraints: number;
-    /** The Auto ISO range the ISO was chosen in: the body's Auto ISO bounds, or its ISO range when it declares none (the tiers: ISO 100 to their maximum). */
+    /**
+     * The body's Auto ISO range: its Auto ISO bounds, or its ISO range when it declares none (the tiers: ISO 100 to their
+     * maximum). Without `limits` the ISO was chosen in this range.
+     */
     autoIsoMinimum: number;
     autoIsoMaximum: number;
+    /**
+     * #505: present only with `exposure.autoIso.limits`: the photographer's Auto ISO range the ISO was chosen in, inside the
+     * body's (`minimum` is the body's Auto ISO minimum when the option omits it).
+     */
+    limits?: {
+        minimum: number;
+        maximum: number;
+    };
     /** Whether the ISO was held at an end of the Auto ISO range. */
     clamped: false | "minimum" | "maximum";
     /**
      * The constraint that limited the resolved exposure: the resolver's `targetResidual.limitingConstraint`, for example
-     * `"iso-maximum"` (the exposure stays under target at the Auto ISO maximum), `"iso-grid-quantization"` (the nearest
-     * selectable ISO) or `"none"` (on target).
+     * `"iso-maximum"` (the exposure stays under target at the body's Auto ISO maximum), `"user-iso-maximum"` (#505: at the
+     * photographer's `limits.maximum`, below the body's), `"iso-grid-quantization"` (the nearest selectable ISO) or `"none"`
+     * (on target).
      */
     limitingConstraint: ExposureResolutionConstraint;
     /** The resolver's residual, log2(target / achieved exposure), in stops: positive when the exposure is under the meter target, negative when over it. */
     residualStops: number;
-    /** Aperture priority only: the policy and slowest preferred shutter used, and whether the slower-shutter fallback ran. */
+    /**
+     * Aperture priority, and program with a slowest preferred shutter (#504): the policy and slowest preferred shutter used,
+     * and whether the slower-shutter fallback ran.
+     */
     afterMaximumIso?: SimulateCaptureAutoIsoAfterMaximum;
     slowestPreferredShutterSeconds?: number;
     afterMaximumIsoFallbackUsed?: boolean;
+    /** #504, program only: whether the program line's shutter was longer than the slowest preferred shutter and was held. */
+    slowestPreferredShutterApplied?: boolean;
+    /** #504: present only with `slowestPreferredShutterSeconds: "auto"`: how the engine derived it (`estimateAutoIsoSlowestShutter`). */
+    automaticSlowestShutter?: SimulateCaptureAutomaticSlowestShutterReport;
+}
+/**
+ * #504: the settings of `exposure.autoIso.slowestPreferredShutterSeconds: "auto"`. Every field is optional; the defaults are
+ * labelled generic values, recorded as `default` assumptions.
+ */
+export interface SimulateCaptureAutomaticSlowestShutterOptions {
+    /** The bias in whole stops, as cameras' Auto minimum-shutter settings offer: +1 one stop faster, −1 one stop slower; −2 to +2. Default 0. */
+    fasterByStops?: number;
+    /** The shake blur allowed, in sensor pixels of `sensor.pixelPitchMicrometers`. Default 1 (a generic pixel-level budget). */
+    blurBudgetPixels?: number;
+    /**
+     * The hand's constant angular velocity, rad/s (signs as in `motion.angularVelocityRadPerSec`; only the magnitude matters).
+     * Default `GENERIC_HANDHELD_ANGULAR_VELOCITY_RAD_PER_SEC`: 4.39 °/s on yaw, a cited generic value for a 100 g phone held in
+     * two hands (Xiao et al., Proc. SPIE 7250, 2009), not a measurement of you or of this camera.
+     */
+    angularVelocityRadPerSec?: {
+        yaw: number;
+        pitch: number;
+    };
+    /** Stabilization in equivalent stops (≥ 0, at most 10), scaling the motion by 2^−stops. Default 0: the tiers declare no stabilization. */
+    stabilizationStopsEquivalent?: number;
+}
+/** #504: the automatic slowest preferred shutter in the Auto ISO report. */
+export interface SimulateCaptureAutomaticSlowestShutterReport {
+    /** The exposure time whose camera-shake blur equals the budget (`estimateCameraShakeBlur`), before the bias and the grid. */
+    derivedShutterSeconds: number;
+    fasterByStops: number;
+    /** derivedShutterSeconds · 2^−fasterByStops. */
+    biasedShutterSeconds: number;
+    /** The slowest preferred shutter used: the biased time within the body's shutter range. */
+    shutterSeconds: number;
+    blurBudgetPixels: number;
+    /** The shake blur at `shutterSeconds`, in pixels. */
+    blurAtShutterPixels: number;
+    angularVelocityRadPerSec: {
+        yaw: number;
+        pitch: number;
+    };
+    stabilizationStopsEquivalent: number;
 }
 export type SimulateCaptureOutputFormat = "srgb-8" | "srgb-16" | "jpeg" | "png" | "dng";
 export type SimulateCaptureWhiteBalance = "scene-illuminant" | "auto" | "none" | {
@@ -233,13 +291,27 @@ export interface SimulateCaptureOptions {
          */
         iso?: number | "auto";
         /**
-         * #516: aperture priority with `iso: "auto"` only (required there). The shutter gets as long as
-         * `slowestPreferredShutterSeconds` (seconds, within the body's shutter range) at the lowest Auto ISO; beyond it the ISO
-         * rises; at the Auto ISO maximum `afterMaximumIso` decides (default `"allow-slower-shutter"`).
+         * Auto ISO settings, with `iso: "auto"` only.
+         *
+         * - `slowestPreferredShutterSeconds` and `afterMaximumIso` (#516): aperture priority, where the slowest shutter is
+         *   required, and (#504) program, where it is optional. The shutter gets as long as `slowestPreferredShutterSeconds`
+         *   (seconds, within the body's shutter range) at the lowest Auto ISO; beyond it the ISO rises; at the Auto ISO maximum
+         *   `afterMaximumIso` decides (default `"allow-slower-shutter"`; in program the shutter then never gets longer than the
+         *   program line's own). Without it, program follows its line as before.
+         * - `slowestPreferredShutterSeconds: "auto"` (#504): the engine derives it from the focal length, the pixel pitch and a
+         *   hand-shake profile with `estimateAutoIsoSlowestShutter` (the camera-shake model, not the 1/focal-length rule of
+         *   thumb); `automaticSlowestShutter` sets the bias, the blur budget, the shake and the stabilization.
+         * - `limits` (#505): every mode. The photographer's Auto ISO range `{ maximum, minimum? }`, a choice kept apart from
+         *   the body's Auto ISO capability: both are selectable ISOs inside the body's Auto ISO range, `minimum` at most
+         *   `maximum` (default: the body's minimum). Outside the body's range or off its ISO grid the request fails; the
+         *   engine never clips a limit. When the ISO stops at a limit strictly inside the body's range, the report's
+         *   `limitingConstraint` is `"user-iso-maximum"` or `"user-iso-minimum"`.
          */
         autoIso?: {
-            slowestPreferredShutterSeconds: number;
+            slowestPreferredShutterSeconds?: number | "auto";
             afterMaximumIso?: SimulateCaptureAutoIsoAfterMaximum;
+            limits?: AutoIsoLimits;
+            automaticSlowestShutter?: SimulateCaptureAutomaticSlowestShutterOptions;
         };
         /** Shutter for manual and shutter-priority modes. Default 1/125 s. */
         shutterSeconds?: number;
@@ -490,6 +562,13 @@ export interface SimulateCaptureResult {
          * the metered luminance is 0 (a black scene has no standard exposure).
          */
         standardExposureDeviationStops: number | null;
+        /**
+         * The illuminance, lux, at which the settings used give the standard exposure: E·L_ref(N, t, S)/L = E·2^Δ, with E the
+         * request's `illuminanceLux`. Exact for a reflective scene (a chart, a reflectance function or a material scene), whose
+         * metered luminance is proportional to E. Null for a black scene (L = 0) and for a radiance-function scene, whose
+         * radiance does not depend on the illuminance. It may exceed the 1e7 lux that `illuminanceLux` accepts.
+         */
+        standardExposureIlluminanceLux: number | null;
         /** Full output of the existing exposure-mode resolver. */
         resolution: unknown;
     };
@@ -761,7 +840,7 @@ export interface DisplayViewResult {
             height: number;
         };
     };
-    /** The resolved exposure of the capture this view shows; `standardExposureDeviationStops` as in {@link SimulateCaptureResult}. */
+    /** The resolved exposure of the capture this view shows; `standardExposureDeviationStops` and `standardExposureIlluminanceLux` as in {@link SimulateCaptureResult}. */
     exposure: {
         mode: SimulateCaptureExposureMode;
         settings: {
@@ -771,6 +850,8 @@ export interface DisplayViewResult {
         };
         ev100: number;
         standardExposureDeviationStops: number | null;
+        /** As in the capture result. */
+        standardExposureIlluminanceLux: number | null;
         /** #516: as in the capture result. */
         isoControl: "manual" | "automatic";
         autoIso?: SimulateCaptureAutoIsoReport;
@@ -882,6 +963,8 @@ export interface DisplayViewRunContext {
     };
     /** #515: the capture's `exposure.standardExposureDeviationStops`. */
     standardExposureDeviationStops: number | null;
+    /** The capture's `exposure.standardExposureIlluminanceLux`. */
+    standardExposureIlluminanceLux: number | null;
     sceneOption: unknown;
     scenePreset: "composite" | "uniform" | "patches" | "slanted-edge" | "siemens-star" | "step-wedge" | "grey-ramp" | "checkerboard" | "point-grid" | "dead-leaves" | "bar-groups" | "hyperbolic-wedge" | "zone-plate" | "slanted-squares" | "line-grid" | "fiducial" | "reflectance-function" | "radiance-function" | "material-function";
     shutterSeconds: number;

package/dist/facade/simulate-capture.js

@@ -41,6 +41,7 @@ import { resolveGenericIsoSignalChain } from "../sensor/iso-signal-chain.js";
 import { meterRelativeExposure } from "../exposure/metering.js";
 import { createExposureMeterTargetFromMeteringResult, setExposureCompensationOnMeterTarget } from "../exposure/metering-target.js";
 import { resolveManualExposureMode, resolveAperturePriorityExposureMode, resolveAperturePriorityAutoIsoExposureMode, resolveShutterPriorityExposureMode, resolveProgramAutoExposureMode } from "../exposure/exposure-mode-resolver.js";
+import { estimateAutoIsoSlowestShutter, GENERIC_HANDHELD_ANGULAR_VELOCITY_RAD_PER_SEC } from "../exposure/auto-iso-slowest-shutter.js";
 import { parseExposureProgramLineProfile } from "../exposure/program-line.js";
 import { resolveCaptureGeometry } from "../output/capture-geometry.js";
 import { estimateCie1931ColorMatchingFunctions } from "../color/color-matching-functions.js";
@@ -137,6 +138,21 @@ function standardExposureDeviationStops(fNumber, shutterSeconds, iso, meteredLum
             meteredLuminance + " cd/m²).");
     return deviation;
 }
+/**
+ * The illuminance at which the settings give the standard exposure, E·L_ref/L (= E·2^Δ). A reflective scene's radiance is
+ * reflectance × k(E)·S(λ)/π with k linear in E (calculateIlluminantIrradianceScale), so the metered L is proportional to E
+ * and re-metering at this illuminance gives Δ = 0 up to rounding. A radiance-function scene ignores E, and a black scene
+ * has no standard exposure: null.
+ */
+function standardExposureIlluminanceLux(fNumber, shutterSeconds, iso, meteredLuminance, illuminanceLux, radianceScalesWithIlluminance) {
+    if (!radianceScalesWithIlluminance || !(meteredLuminance > 0))
+        return null;
+    const lux = illuminanceLux * sosReferenceLuminance(fNumber, shutterSeconds, iso) / meteredLuminance;
+    if (!Number.isFinite(lux))
+        throw new InvalidScientificResultError("exposure.standardExposureIlluminanceLux is not finite (metered scene luminance " +
+            meteredLuminance + " cd/m²).");
+    return lux;
+}
 /**
  * Default illuminance, lux: an 18 % Lambertian grey card (L = 0.18·E/π) then gets exactly the CIPA DC-004 standard
  * output sensitivity reference exposure H = 10/S at f/8, 1/125 s, ISO 100:
@@ -412,16 +428,87 @@ export function bilinearPhaseProfiles() {
  * #516: the result's Auto ISO report, read from a resolved Auto ISO resolution (every mode's resolved Auto ISO branch carries
  * `idealIsoBeforeConstraints`, `isoResolution` and a resolved `targetResidual`; aperture priority adds its fallback flag).
  */
-function autoIsoReport(resolution, iso, aperturePriority) {
+function autoIsoReport(resolution, iso, shutterPolicy, limits, automatic) {
     const r = resolution;
+    // Program reports its hold under slowestPreferredShutter (#504); aperture priority at the top level.
+    const program = r.slowestPreferredShutter;
     const ideal = r.idealIsoBeforeConstraints, residual = r.targetResidual?.residualStops, clamped = r.isoResolution?.clamped;
     if (typeof ideal !== "number" || !Number.isFinite(ideal) || typeof residual !== "number" || !Number.isFinite(residual) || r.targetResidual?.status !== "resolved" ||
         (clamped !== false && clamped !== "minimum" && clamped !== "maximum"))
         throw new InvalidScientificResultError("Auto ISO resolution did not report a finite ideal ISO and residual.");
     // The resolvers' Auto ISO range: the body's Auto ISO bounds, else its ISO range.
     return { idealIsoBeforeConstraints: ideal, autoIsoMinimum: iso.autoIsoMinimum ?? iso.minimum, autoIsoMaximum: iso.autoIsoMaximum ?? iso.maximum, clamped,
-        limitingConstraint: r.targetResidual.limitingConstraint, residualStops: residual,
-        ...(aperturePriority ? { ...aperturePriority, afterMaximumIsoFallbackUsed: r.afterMaximumIsoFallbackUsed === true } : {}) };
+        ...(limits ? { limits: { ...limits } } : {}), limitingConstraint: r.targetResidual.limitingConstraint, residualStops: residual,
+        ...(shutterPolicy ? { ...shutterPolicy, afterMaximumIsoFallbackUsed: (program ? program.afterMaximumIsoFallbackUsed : r.afterMaximumIsoFallbackUsed) === true } : {}),
+        ...(program ? { slowestPreferredShutterApplied: program.applied === true } : {}),
+        ...(automatic ? { automaticSlowestShutter: automatic } : {}) };
+}
+/**
+ * #505: `exposure.autoIso.limits`, the photographer's Auto ISO range. Both limits are selectable ISOs inside the body's
+ * Auto ISO range, `minimum` at most `maximum`; anything else fails (the resolvers check the same, but an option defect
+ * is a configuration error here). `minimum` defaults to the body's Auto ISO minimum.
+ */
+function parseAutoIsoLimitsOption(value, iso) {
+    const record = allowKeys(value, "exposure.autoIso.limits", ["maximum", "minimum"]);
+    if (record.maximum === undefined)
+        fail("exposure.autoIso.limits.maximum is required: the highest ISO Auto ISO may choose.");
+    const bodyMinimum = iso.autoIsoMinimum ?? iso.minimum, bodyMaximum = iso.autoIsoMaximum ?? iso.maximum;
+    const limit = (field) => {
+        const v = positive(record[field], "exposure.autoIso.limits." + field);
+        if (v < bodyMinimum || v > bodyMaximum)
+            fail("exposure.autoIso.limits." + field + " (ISO " + v + ") must be within the body's Auto ISO range, ISO " + bodyMinimum + " to " + bodyMaximum + ".");
+        if (iso.settingGrid.kind === "discrete-values" && !iso.settingGrid.values.includes(v))
+            fail("exposure.autoIso.limits." + field + " (ISO " + v + ") must be a selectable ISO of the body: " + iso.settingGrid.values.join(", ") + ".");
+        return v;
+    };
+    const maximum = limit("maximum"), minimum = record.minimum === undefined ? bodyMinimum : limit("minimum");
+    if (minimum > maximum)
+        fail("exposure.autoIso.limits.minimum (ISO " + minimum + ") must not exceed exposure.autoIso.limits.maximum (ISO " + maximum + ").");
+    return { minimum, maximum };
+}
+/**
+ * #504: `exposure.autoIso.slowestPreferredShutterSeconds: "auto"`: the slowest preferred shutter from the camera-shake model
+ * (`estimateAutoIsoSlowestShutter`) for this lens, focus and pixel pitch, within the body's shutter range. Option defects are
+ * configuration errors; the defaults are recorded as `default` assumptions and the derivation as a `model` assumption.
+ */
+function resolveAutomaticSlowestShutterOption(value, context) {
+    const path = "exposure.autoIso.automaticSlowestShutter";
+    const record = allowKeys(value, path, ["fasterByStops", "blurBudgetPixels", "angularVelocityRadPerSec", "stabilizationStopsEquivalent"]);
+    const fasterByStops = context.pick(record, "fasterByStops", path + ".fasterByStops", 0, "No bias: the derived slowest shutter is used as is.");
+    if (typeof fasterByStops !== "number" || !Number.isInteger(fasterByStops) || Math.abs(fasterByStops) > 2)
+        fail(path + ".fasterByStops must be a whole number of stops from -2 to +2.");
+    const blurBudgetPixels = positive(context.pick(record, "blurBudgetPixels", path + ".blurBudgetPixels", 1, "A generic pixel-level blur budget: the shake trace during the exposure may be one pixel long. A choice, not a measured threshold."), path + ".blurBudgetPixels");
+    const angularOption = context.pick(record, "angularVelocityRadPerSec", path + ".angularVelocityRadPerSec", { ...GENERIC_HANDHELD_ANGULAR_VELOCITY_RAD_PER_SEC }, "Generic hand shake: 4.39 °/s (0.0766 rad/s) on yaw, the linear camera-motion rate Xiao, Farrell, Catrysse and Wandell (Proc. SPIE 7250, 2009) use for an average user " +
+        "holding a 100 g mobile handset with two hands. A labelled generic default, not a measurement of this photographer or camera.");
+    const angular = allowKeys(angularOption, path + ".angularVelocityRadPerSec", ["yaw", "pitch"]);
+    for (const axis of ["yaw", "pitch"]) {
+        const v = angular[axis];
+        if (typeof v !== "number" || !Number.isFinite(v) || Math.abs(v) > 100)
+            fail(path + ".angularVelocityRadPerSec." + axis + " must be a finite number within ±100 rad/s.");
+    }
+    const angularVelocityRadPerSec = { yaw: angular.yaw, pitch: angular.pitch };
+    if (angularVelocityRadPerSec.yaw === 0 && angularVelocityRadPerSec.pitch === 0)
+        fail(path + ".angularVelocityRadPerSec must be non-zero on at least one axis: without shake no slowest shutter follows.");
+    const stabilizationStopsEquivalent = context.pick(record, "stabilizationStopsEquivalent", path + ".stabilizationStopsEquivalent", 0, "No stabilization: the generic tiers declare none.");
+    if (typeof stabilizationStopsEquivalent !== "number" || !Number.isFinite(stabilizationStopsEquivalent) || stabilizationStopsEquivalent < 0 || stabilizationStopsEquivalent > 10)
+        fail(path + ".stabilizationStopsEquivalent must be a number of stops from 0 to 10.");
+    let estimate;
+    try {
+        estimate = estimateAutoIsoSlowestShutter({ focalLengthMm: context.focalLengthMm, focusDistanceM: context.focusDistanceM, angularVelocityRadPerSec,
+            stabilizationStopsEquivalent, blurBudget: { kind: "pixels", pixels: blurBudgetPixels, pixelPitchMicrometers: context.pitch }, fasterByStops,
+            shutterCapability: context.shutter }).value;
+    }
+    catch (error) {
+        fail(path + ": " + (error instanceof Error ? error.message : String(error)));
+    }
+    const report = { derivedShutterSeconds: estimate.derivedShutterSeconds, fasterByStops,
+        biasedShutterSeconds: estimate.biasedShutterSeconds, shutterSeconds: estimate.shutterSeconds, blurBudgetPixels, blurAtShutterPixels: estimate.blurAtShutterPixels,
+        angularVelocityRadPerSec, stabilizationStopsEquivalent };
+    context.assume("exposure.autoIso.automaticSlowestShutter", "model", { ...report, angularVelocityRadPerSec: { ...angularVelocityRadPerSec },
+        focalLengthMm: context.focalLengthMm, focusDistanceM: context.focusDistanceM, pixelPitchMicrometers: context.pitch }, "Automatic slowest shutter (#504): the exposure time at which estimateCameraShakeBlur()'s on-axis blur (constant angular velocity, thin-lens projection at the focus " +
+        "distance, stabilization as 2^-stops) equals the blur budget, times 2^-fasterByStops, held within the body's shutter range. An approximation; the 1/focal-length " +
+        "reciprocal rule is a rule of thumb and is not used.");
+    return report;
 }
 function defaultProgramLine() {
     // Generic educational program line written for the engine, relative to the f/8, 1/125 s reference. For less light
@@ -1227,8 +1314,8 @@ export async function runCapture(options, run, viewOption, renderView) {
     if (typeof isoOption === "string" && !automaticIso)
         fail('exposure.iso must be a positive finite number or "auto".');
     const iso = automaticIso ? NaN : positive(isoOption, "exposure.iso");
-    if (exposureOptions.autoIso !== undefined && !(automaticIso && mode === "aperture-priority"))
-        fail('exposure.autoIso applies only to exposure.mode "aperture-priority" with exposure.iso "auto"; omit it.');
+    if (exposureOptions.autoIso !== undefined && !automaticIso)
+        fail('exposure.autoIso applies only with exposure.iso "auto"; omit it.');
     const compensation = exposureOptions.compensationStops === undefined ? DEFAULTS.compensationStops : exposureOptions.compensationStops;
     if (typeof compensation !== "number" || !Number.isFinite(compensation) || Math.abs(compensation) > 10)
         fail("exposure.compensationStops must be within ±10.");
@@ -1279,31 +1366,65 @@ export async function runCapture(options, run, viewOption, renderView) {
     // #516: the resolvers' Auto ISO policies; their baseline is the lowest selectable ISO in the body's Auto ISO range.
     const autoIsoBaseline = { isoBaseline: "minimum-selectable", isoQuantizationPolicy: "nearest-log2-lower-on-tie" };
     let autoIsoAperturePriority;
+    // #505: the photographer's Auto ISO limits, validated against the body's Auto ISO range; absent unless given.
+    let autoIsoOptions = {};
+    let autoIsoLimits;
+    // #504: the slowest preferred shutter (aperture priority; optional in program) and, with "auto", how it was derived.
+    let autoIsoShutterPolicy;
+    let automaticSlowestShutter;
     if (automaticIso) {
         if (capabilities.iso.autoIsoAvailability !== "supported")
             fail('exposure.iso "auto" needs a body with Auto ISO; this camera\'s Auto ISO is ' + capabilities.iso.autoIsoAvailability + ".");
-        assume("exposure.autoIso", "model", { minimum: capabilities.iso.autoIsoMinimum ?? capabilities.iso.minimum, maximum: capabilities.iso.autoIsoMaximum ?? capabilities.iso.maximum, ...autoIsoBaseline }, "Auto ISO: the engine's exposure-mode resolver chooses the ISO from the meter target, starting from the lowest selectable ISO in the body's Auto ISO range and " +
-            "snapping to the nearest selectable ISO in log2 (the lower on a tie), held at the range's ends. A generic policy, not a manufacturer's Auto ISO.");
-    }
-    if (automaticIso && mode === "aperture-priority") {
-        const autoIsoOptions = allowKeys(exposureOptions.autoIso, "exposure.autoIso", ["slowestPreferredShutterSeconds", "afterMaximumIso"]);
+        autoIsoOptions = allowKeys(exposureOptions.autoIso, "exposure.autoIso", ["slowestPreferredShutterSeconds", "afterMaximumIso", "limits", "automaticSlowestShutter"]);
+        if (mode !== "aperture-priority" && mode !== "program")
+            for (const key of ["slowestPreferredShutterSeconds", "afterMaximumIso", "automaticSlowestShutter"])
+                if (autoIsoOptions[key] !== undefined)
+                    fail("exposure.autoIso." + key + ' applies only to exposure.mode "aperture-priority" or "program"; omit it.');
+        if (autoIsoOptions.limits !== undefined)
+            autoIsoLimits = parseAutoIsoLimitsOption(autoIsoOptions.limits, capabilities.iso);
+        assume("exposure.autoIso", "model", { minimum: capabilities.iso.autoIsoMinimum ?? capabilities.iso.minimum, maximum: capabilities.iso.autoIsoMaximum ?? capabilities.iso.maximum,
+            ...(autoIsoLimits ? { limits: { ...autoIsoLimits } } : {}), ...autoIsoBaseline }, "Auto ISO: the engine's exposure-mode resolver chooses the ISO from the meter target, starting from the lowest selectable ISO in the body's Auto ISO range and " +
+            "snapping to the nearest selectable ISO in log2 (the lower on a tie), held at the range's ends. A generic policy, not a manufacturer's Auto ISO." +
+            (autoIsoLimits ? " The photographer's limits (exposure.autoIso.limits, #505) narrow that range to ISO " + autoIsoLimits.minimum + " to " + autoIsoLimits.maximum + "." : ""));
+    }
+    if (automaticIso && mode === "program" && autoIsoOptions.slowestPreferredShutterSeconds === undefined) {
+        for (const key of ["afterMaximumIso", "automaticSlowestShutter"])
+            if (autoIsoOptions[key] !== undefined)
+                fail("exposure.autoIso." + key + ' in program needs exposure.autoIso.slowestPreferredShutterSeconds; omit it or set the slowest shutter.');
+    }
+    if (automaticIso && (mode === "aperture-priority" || (mode === "program" && autoIsoOptions.slowestPreferredShutterSeconds !== undefined))) {
         if (autoIsoOptions.slowestPreferredShutterSeconds === undefined)
-            fail('exposure.autoIso.slowestPreferredShutterSeconds is required with exposure.mode "aperture-priority" and exposure.iso "auto": the slowest shutter, in seconds, before Auto ISO raises the ISO.');
-        const slowestPreferredShutterSeconds = positive(autoIsoOptions.slowestPreferredShutterSeconds, "exposure.autoIso.slowestPreferredShutterSeconds");
-        if (slowestPreferredShutterSeconds < capabilities.shutter.minimumSeconds || slowestPreferredShutterSeconds > capabilities.shutter.maximumSeconds)
-            fail("exposure.autoIso.slowestPreferredShutterSeconds must be within the body's shutter range, " + capabilities.shutter.minimumSeconds + " s to " + capabilities.shutter.maximumSeconds + " s.");
+            fail('exposure.autoIso.slowestPreferredShutterSeconds is required with exposure.mode "aperture-priority" and exposure.iso "auto": the slowest shutter, in seconds, before Auto ISO raises the ISO, or "auto".');
+        if (autoIsoOptions.automaticSlowestShutter !== undefined && autoIsoOptions.slowestPreferredShutterSeconds !== "auto")
+            fail('exposure.autoIso.automaticSlowestShutter applies only with exposure.autoIso.slowestPreferredShutterSeconds "auto"; omit it.');
+        let slowestPreferredShutterSeconds;
+        if (autoIsoOptions.slowestPreferredShutterSeconds === "auto") {
+            automaticSlowestShutter = resolveAutomaticSlowestShutterOption(autoIsoOptions.automaticSlowestShutter, { focalLengthMm, focusDistanceM, pitch,
+                shutter: capabilities.shutter, assume, pick });
+            slowestPreferredShutterSeconds = automaticSlowestShutter.shutterSeconds;
+        }
+        else {
+            if (typeof autoIsoOptions.slowestPreferredShutterSeconds === "string")
+                fail('exposure.autoIso.slowestPreferredShutterSeconds must be a positive number of seconds or "auto".');
+            slowestPreferredShutterSeconds = positive(autoIsoOptions.slowestPreferredShutterSeconds, "exposure.autoIso.slowestPreferredShutterSeconds");
+            if (slowestPreferredShutterSeconds < capabilities.shutter.minimumSeconds || slowestPreferredShutterSeconds > capabilities.shutter.maximumSeconds)
+                fail("exposure.autoIso.slowestPreferredShutterSeconds must be within the body's shutter range, " + capabilities.shutter.minimumSeconds + " s to " + capabilities.shutter.maximumSeconds + " s.");
+        }
         const afterMaximumIso = pick(autoIsoOptions, "afterMaximumIso", "exposure.autoIso.afterMaximumIso", "allow-slower-shutter", "At the Auto ISO maximum, the shutter may get slower than the slowest preferred shutter to reach the meter target.");
         if (afterMaximumIso !== "allow-slower-shutter" && afterMaximumIso !== "hold-preferred-shutter")
             fail('exposure.autoIso.afterMaximumIso must be "allow-slower-shutter" or "hold-preferred-shutter".');
-        autoIsoAperturePriority = { slowestPreferredShutterSeconds, afterMaximumIso };
+        autoIsoShutterPolicy = { slowestPreferredShutterSeconds, afterMaximumIso };
+        if (mode === "aperture-priority")
+            autoIsoAperturePriority = autoIsoShutterPolicy;
     }
+    const limitsPolicy = autoIsoLimits ? { autoIsoLimits: { ...autoIsoLimits } } : {};
     if (mode === "manual") {
         resolution = resolveManualExposureMode({ target, capabilities, referenceExposure: reference, manualAperture: fNumber, manualShutterSeconds: shutterSeconds,
-            isoControl: automaticIso ? { kind: "automatic", quantizationPolicy: autoIsoBaseline.isoQuantizationPolicy } : { kind: "manual", iso } });
+            isoControl: automaticIso ? { kind: "automatic", quantizationPolicy: autoIsoBaseline.isoQuantizationPolicy, ...limitsPolicy } : { kind: "manual", iso } });
     }
     else if (autoIsoAperturePriority) {
         resolution = resolveAperturePriorityAutoIsoExposureMode({ target, capabilities, referenceExposure: reference, manualAperture: fNumber,
-            policy: { kind: "minimum-iso-until-slowest-preferred-shutter", ...autoIsoBaseline, shutterSelectionPolicy: "not-longer-than-target", ...autoIsoAperturePriority } });
+            policy: { kind: "minimum-iso-until-slowest-preferred-shutter", ...autoIsoBaseline, shutterSelectionPolicy: "not-longer-than-target", ...autoIsoAperturePriority, ...limitsPolicy } });
     }
     else if (mode === "aperture-priority") {
         resolution = resolveAperturePriorityExposureMode({ target, capabilities, referenceExposure: reference, manualAperture: fNumber, manualIso: iso,
@@ -1311,13 +1432,14 @@ export async function runCapture(options, run, viewOption, renderView) {
     }
     else if (mode === "shutter-priority") {
         resolution = resolveShutterPriorityExposureMode({ target, capabilities, referenceExposure: reference, manualShutterSeconds: shutterSeconds,
-            isoControl: automaticIso ? { kind: "automatic", policy: { kind: "minimum-iso-aperture-first", apertureSelectionPolicy: "not-wider-than-target", ...autoIsoBaseline } } :
+            isoControl: automaticIso ? { kind: "automatic", policy: { kind: "minimum-iso-aperture-first", apertureSelectionPolicy: "not-wider-than-target", ...autoIsoBaseline, ...limitsPolicy } } :
                 { kind: "manual", iso, apertureQuantizationPolicy: "nearest-log2-narrower-on-tie" } });
     }
     else {
         assume("exposure.programLine", "model", "facade-generic-program-line", "Engine-authored generic program line (f/16 1/2000 s … f/8 1/125 s … f/4 1.024 s); not a manufacturer program.");
         resolution = resolveProgramAutoExposureMode({ target, capabilities, referenceExposure: reference, programLine: defaultProgramLine(),
-            isoControl: automaticIso ? { kind: "automatic", ...autoIsoBaseline } : { kind: "manual", iso } });
+            isoControl: automaticIso ? { kind: "automatic", ...autoIsoBaseline, ...limitsPolicy, ...(autoIsoShutterPolicy ? { slowestPreferredShutter: { ...autoIsoShutterPolicy } } : {}) } :
+                { kind: "manual", iso } });
     }
     if (resolution.status !== "resolved" || !resolution.resolvedSettings)
         fail("Exposure could not be resolved (" + resolution.status + "); the scene may have no signal.");
@@ -1326,8 +1448,9 @@ export async function runCapture(options, run, viewOption, renderView) {
     const resolvedIso = resolution.resolvedSettings.iso ?? iso;
     if (!Number.isFinite(resolvedIso) || resolvedIso <= 0)
         fail("Exposure could not be resolved: the resolved ISO is not a positive finite number.");
-    const isoReport = automaticIso ? { isoControl: "automatic", autoIso: autoIsoReport(resolution, capabilities.iso, autoIsoAperturePriority) } : { isoControl: "manual" };
+    const isoReport = automaticIso ? { isoControl: "automatic", autoIso: autoIsoReport(resolution, capabilities.iso, autoIsoShutterPolicy, autoIsoLimits, automaticSlowestShutter) } : { isoControl: "manual" };
     const exposureDeviationStops = standardExposureDeviationStops(fNumber, shutterSeconds, resolvedIso, meteredLuminance);
+    const exposureIlluminanceLux = standardExposureIlluminanceLux(fNumber, shutterSeconds, resolvedIso, meteredLuminance, illuminanceLux, callerScene?.kind !== "radiance-function");
     const defocusDisc = defocusModel === undefined ? undefined :
         resolveDefocusOption({ run, assume, focalLengthMm, fNumber, focusDistanceM, subjectDistanceM, pitch, diffraction: diffractionRadiusOption !== undefined });
     // #492: the capture applies the disc as an object-space convolution, which needs every disc point a site sees to be another site's scene point.
@@ -1768,7 +1891,7 @@ export async function runCapture(options, run, viewOption, renderView) {
     // Display view: the renderer that simulate-display-view.ts passes in reads this request's resolved state, so a bundle
     // that only captures does not contain the display view.
     if (displayView)
-        return await renderView({ ahd, fastReport, antiAliasing, aspect, assume, assumptions, axisChannelResponse, boxSamples, buildProvider, callerScene, chart, materialLayers, chartReport, chartSize, diffraction, defocus: displayViewDefocus, diffractionPsf, fNumber, focalLengthMm, focusDistanceM, height, highlightMode, illuminanceLux, illuminant, illuminantOption, imagingArea, intentOf, metresPerFrameUnit, noiseSeed, outputOptions, parsedView, pitch, preset, provider, regimeByChannel, resolvedIso, isoReport, standardExposureDeviationStops: exposureDeviationStops, sceneOption, scenePreset, shutterSeconds, started, subjectDistanceM, toneCurve, whiteBalanceOption, whiteBalanceState, width, checkAbort, margin, mode, nativeHeight, nativeWidth, sourceSha256, yieldControl, kelvinWhiteBalanceInput });
+        return await renderView({ ahd, fastReport, antiAliasing, aspect, assume, assumptions, axisChannelResponse, boxSamples, buildProvider, callerScene, chart, materialLayers, chartReport, chartSize, diffraction, defocus: displayViewDefocus, diffractionPsf, fNumber, focalLengthMm, focusDistanceM, height, highlightMode, illuminanceLux, illuminant, illuminantOption, imagingArea, intentOf, metresPerFrameUnit, noiseSeed, outputOptions, parsedView, pitch, preset, provider, regimeByChannel, resolvedIso, isoReport, standardExposureDeviationStops: exposureDeviationStops, standardExposureIlluminanceLux: exposureIlluminanceLux, sceneOption, scenePreset, shutterSeconds, started, subjectDistanceM, toneCurve, whiteBalanceOption, whiteBalanceState, width, checkAbort, margin, mode, nativeHeight, nativeWidth, sourceSha256, yieldControl, kelvinWhiteBalanceInput });
     // Ideal reference (2.3): the scene without camera effects, at the capture's own exposure, white balance and encoding.
     if (idealReference) {
         const referenceStarted = clockMs();
@@ -2132,7 +2255,8 @@ export async function runCapture(options, run, viewOption, renderView) {
         request: { environmentRaw: finalRawInput, siteInput, development, whiteBalanceState,
             ...(diffraction ? { diffraction: { profile: diffraction, psf: diffractionPsf, execution: diffractionObjectSpace ? "object-space-convolution" : "environment-psf-quadrature" } } : {}) },
         exposure: { mode, settings: { fNumber, shutterSeconds, iso: resolvedIso }, ev100: Math.log2(fNumber ** 2 / shutterSeconds), ...isoReport,
-            meteredSceneLuminanceCdPerSquareMeter: meteredLuminance, standardExposureDeviationStops: exposureDeviationStops, resolution },
+            meteredSceneLuminanceCdPerSquareMeter: meteredLuminance, standardExposureDeviationStops: exposureDeviationStops,
+            standardExposureIlluminanceLux: exposureIlluminanceLux, resolution },
         scene: { sceneId: chart ? "chart:" + chart.preset : callerScene.sceneId, preset: scenePreset, parameters: chart ? chart.parameters : {},
             illuminant: { id: illuminant.id, description: illuminant.description, illuminanceLux }, distanceM: subjectDistanceM,
             framedWidthM: 2 * metresPerFrameUnit, framedHeightM: 2 * metresPerFrameUnit * aspect, ...(chartReport ? { chart: chartReport } : {}), sourceSha256 },