@photivra/engine 2.11.1 → 2.13.0

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

@@ -1,5 +1,6 @@
 import type { EvidenceProvenance } from "../core/evidence-provenance.js";
 import { type GenericEquipmentTier, type GenericEquipmentTierPreset } from "../equipment/generic-tier-assets.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";
@@ -27,6 +28,95 @@ import { type ChartSizeOption, type CaptureIlluminant, type CallerMaterialScene,
 /** Version of how the facade builds requests. It changes whenever the same input would build a different request. */
 export declare const SIMULATE_CAPTURE_FACADE_VERSION: "1.0.0";
 export type SimulateCaptureExposureMode = "manual" | "aperture-priority" | "shutter-priority" | "program";
+/**
+ * #516: what aperture priority does with Auto ISO once the ISO reaches the body's Auto ISO maximum and the exposure is
+ * still under the meter target: `"allow-slower-shutter"` lengthens the shutter past the slowest preferred shutter to reach
+ * the target; `"hold-preferred-shutter"` keeps the preferred shutter and leaves the exposure under target.
+ */
+export type SimulateCaptureAutoIsoAfterMaximum = "allow-slower-shutter" | "hold-preferred-shutter";
+/**
+ * #516: how Auto ISO chose the ISO (`exposure.iso: "auto"`), reported in the result's `exposure.autoIso`. The full
+ * resolver output stays in the capture's `exposure.resolution`.
+ */
+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 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 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, 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" | {
     kelvin: number;
@@ -191,8 +281,38 @@ export interface SimulateCaptureOptions {
     exposure?: {
         /** Default "manual". */
         mode?: SimulateCaptureExposureMode;
-        /** Default 100. */
-        iso?: number;
+        /**
+         * Default 100. #516: `"auto"` lets the body's Auto ISO choose the ISO from the meter target, within its Auto ISO range
+         * (the tiers: ISO 100 to their maximum), in every mode: manual keeps the aperture and shutter; aperture priority keeps the
+         * aperture and follows `autoIso`; shutter priority picks the aperture at the lowest Auto ISO (no wider than the target
+         * needs, so at most the widest) and raises the ISO for the rest; program picks the program line at the lowest Auto ISO and
+         * raises the ISO beyond the line's end. The result reports the ISO in `exposure.settings.iso` and how it was chosen in
+         * `exposure.autoIso`.
+         */
+        iso?: number | "auto";
+        /**
+         * 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 | "auto";
+            afterMaximumIso?: SimulateCaptureAutoIsoAfterMaximum;
+            limits?: AutoIsoLimits;
+            automaticSlowestShutter?: SimulateCaptureAutomaticSlowestShutterOptions;
+        };
         /** Shutter for manual and shutter-priority modes. Default 1/125 s. */
         shutterSeconds?: number;
         /** Exposure compensation applied to the meter target, in stops. Default 0. */
@@ -430,7 +550,25 @@ export interface SimulateCaptureResult {
         };
         /** Exposure value at ISO 100 of the settings, log2(N²/t). */
         ev100: number;
+        /** #516: `"automatic"` when the request asked for `iso: "auto"`, else `"manual"`. */
+        isoControl: "manual" | "automatic";
+        /** #516: present with `iso: "auto"`: how Auto ISO chose `settings.iso` and what limited it. */
+        autoIso?: SimulateCaptureAutoIsoReport;
         meteredSceneLuminanceCdPerSquareMeter: number;
+        /**
+         * #515: deviation, in stops, of the exposure used from the CIPA DC-004-2020 standard exposure for the metered luminance L:
+         * log2(N²/t) − log2(0.65·L·S/10). Positive is darker than the standard exposure (under), negative brighter (over). In an
+         * automatic mode it is the compensation with the opposite sign plus any step or limit the resolver hit. Finite, or null when
+         * 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;
     };
@@ -619,6 +757,9 @@ export interface IdealReferenceResult {
             iso: number;
         };
         ev100: number;
+        /** #516: as in the capture result. */
+        isoControl: "manual" | "automatic";
+        autoIso?: SimulateCaptureAutoIsoReport;
     };
     scene: SimulateCaptureResult["scene"];
     region?: {
@@ -699,7 +840,7 @@ export interface DisplayViewResult {
             height: number;
         };
     };
-    /** The resolved exposure of the capture this view shows. */
+    /** The resolved exposure of the capture this view shows; `standardExposureDeviationStops` and `standardExposureIlluminanceLux` as in {@link SimulateCaptureResult}. */
     exposure: {
         mode: SimulateCaptureExposureMode;
         settings: {
@@ -708,6 +849,12 @@ export interface DisplayViewResult {
             iso: number;
         };
         ev100: number;
+        standardExposureDeviationStops: number | null;
+        /** As in the capture result. */
+        standardExposureIlluminanceLux: number | null;
+        /** #516: as in the capture result. */
+        isoControl: "manual" | "automatic";
+        autoIso?: SimulateCaptureAutoIsoReport;
     };
     scene: SimulateCaptureResult["scene"];
     /**
@@ -809,6 +956,15 @@ export interface DisplayViewRunContext {
         regimeId: string;
     }>;
     resolvedIso: number;
+    /** #516: how the ISO was chosen, reported in the view's `exposure`. */
+    isoReport: {
+        isoControl: "manual" | "automatic";
+        autoIso?: SimulateCaptureAutoIsoReport;
+    };
+    /** #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

@@ -30,6 +30,7 @@
  */
 import { markInternalNativeTileReader, markInternalSceneRadianceEvaluator, registerInternalRadianceAccess } from "../core/internal-radiance-evaluator.js";
 import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { InvalidScientificResultError } from "../core/validation.js";
 import { requireInputObject } from "../core/record-validation.js";
 import { ENGINE_API_VERSION } from "../core/version.js";
 import { GENERIC_TIER_ASSETS } from "../equipment/generic-tier-assets.js";
@@ -39,7 +40,8 @@ import { resolveGenericEquipmentExposureCapabilities } from "../equipment/exposu
 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, resolveShutterPriorityExposureMode, resolveProgramAutoExposureMode } from "../exposure/exposure-mode-resolver.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";
@@ -121,6 +123,36 @@ const GREY_CARD_REFLECTANCE = 0.18;
 function sosReferenceLuminance(fNumber, shutterSeconds, iso) {
     return SOS_REFERENCE_EXPOSURE_NUMERATOR_LUX_SECONDS * fNumber ** 2 / (CAMERA_EQUATION_CONSTANT * shutterSeconds * iso);
 }
+/**
+ * #515: deviation, in stops, of the exposure the settings give from the CIPA DC-004-2020 standard exposure for the metered
+ * luminance L: Δ = log2(N²/t) − log2(0.65·L·S/10) = log2(L_ref(N, t, S) / L), with L_ref the luminance that the settings
+ * expose at H = 10/S (S = 10/H, §3.2; H = 0.65·L·t/N², §5.5 (4)). Positive is darker than the standard exposure (under).
+ * A scene with no metered luminance (L = 0, which manual mode still captures) has no standard exposure: null, never ±Infinity.
+ */
+function standardExposureDeviationStops(fNumber, shutterSeconds, iso, meteredLuminance) {
+    if (!(meteredLuminance > 0))
+        return null;
+    const deviation = Math.log2(sosReferenceLuminance(fNumber, shutterSeconds, iso) / meteredLuminance);
+    if (!Number.isFinite(deviation))
+        throw new InvalidScientificResultError("exposure.standardExposureDeviationStops is not finite (metered scene luminance " +
+            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:
@@ -392,6 +424,92 @@ export function bilinearPhaseProfiles() {
             kernels: CHANNELS.map((c) => ({ outputChannelId: c, contributions: kernels[px + "," + py][c] })), evidence: FACADE_EVIDENCE,
             limitations: ["Bilinear interpolation of the RGGB mosaic; no edge-directed demosaic, false-colour suppression or calibration."] } }));
 }
+/**
+ * #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, 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,
+        ...(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
     // it first opens the aperture toward f/4, then lengthens the shutter. For more light it first closes toward
@@ -1186,11 +1304,18 @@ export async function runCapture(options, run, viewOption, renderView) {
         registerInternalRadianceAccess(provider.evaluateRadiance, { keyOfDirection: materialOfDirection, radianceOfKey: provider.materialRadiance, tabulated: true });
     assume("model.scene-radiometry", "model", "lambertian-plane", "Radiance = reflectance × irradiance / π on one plane; illuminance from K_m = 683 lm/W and the engine's analytic CIE 1931 ȳ fit.");
     // Metering (CIPA DC-004 standard output sensitivity and camera equation) and exposure-mode resolution
-    const exposureOptions = allowKeys(top.exposure, "exposure", ["mode", "iso", "shutterSeconds", "compensationStops"]);
+    const exposureOptions = allowKeys(top.exposure, "exposure", ["mode", "iso", "shutterSeconds", "compensationStops", "autoIso"]);
     const mode = pick(exposureOptions, "mode", "exposure.mode", "manual", "Manual exposure.");
     if (!["manual", "aperture-priority", "shutter-priority", "program"].includes(mode))
         fail("Unknown exposure mode.");
-    const iso = positive(pick(exposureOptions, "iso", "exposure.iso", DEFAULTS.iso, "ISO 100, the tiers' base ISO."), "exposure.iso");
+    const isoOption = pick(exposureOptions, "iso", "exposure.iso", DEFAULTS.iso, "ISO 100, the tiers' base ISO.");
+    // #516: "auto" resolves the ISO with the mode's Auto ISO resolver; NaN marks the ISO as not yet known.
+    const automaticIso = isoOption === "auto";
+    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)
+        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.");
@@ -1238,9 +1363,68 @@ export async function runCapture(options, run, viewOption, renderView) {
             fail("exposure.shutterSeconds is resolved automatically in " + mode + " mode; omit it.");
         shutterSeconds = NaN;
     }
+    // #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 + ".");
+        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, 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".');
+        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: { 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, ...limitsPolicy } });
     }
     else if (mode === "aperture-priority") {
         resolution = resolveAperturePriorityExposureMode({ target, capabilities, referenceExposure: reference, manualAperture: fNumber, manualIso: iso,
@@ -1248,17 +1432,25 @@ export async function runCapture(options, run, viewOption, renderView) {
     }
     else if (mode === "shutter-priority") {
         resolution = resolveShutterPriorityExposureMode({ target, capabilities, referenceExposure: reference, manualShutterSeconds: shutterSeconds,
-            isoControl: { kind: "manual", iso, apertureQuantizationPolicy: "nearest-log2-narrower-on-tie" } });
+            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: { kind: "manual", iso } });
+        resolution = resolveProgramAutoExposureMode({ target, capabilities, referenceExposure: reference, programLine: defaultProgramLine(),
+            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.");
     fNumber = resolution.resolvedSettings.aperture ?? fNumber;
     shutterSeconds = resolution.resolvedSettings.shutterSeconds ?? shutterSeconds;
     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, 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.
@@ -1699,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, 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();
@@ -1772,7 +1964,7 @@ export async function runCapture(options, run, viewOption, renderView) {
             "Each pixel samples the scene at its centre, like the capture's default point aperture; use sensor.pixelAperture \"box\" for photosite-averaged pixels.");
         return Object.freeze({ kind: "ideal-reference", label: "Ideal reference (no camera effects); not a capture.", facadeVersion: SIMULATE_CAPTURE_FACADE_VERSION, engineApiVersion: ENGINE_API_VERSION,
             image: { width: outputWidth, height: outputHeight, format, samples, ...(png ? { png, colorEncoding: colorEncoding } : {}) },
-            exposure: { mode, settings: { fNumber, shutterSeconds, iso: resolvedIso }, ev100: Math.log2(fNumber ** 2 / shutterSeconds) },
+            exposure: { mode, settings: { fNumber, shutterSeconds, iso: resolvedIso }, ev100: Math.log2(fNumber ** 2 / shutterSeconds), ...isoReport },
             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 },
@@ -2062,8 +2254,9 @@ export async function runCapture(options, run, viewOption, renderView) {
         ...(region && regionNative ? { region: { ...region, frameWidth: width, frameHeight: height, nativeRect: { ...regionNative } } } : {}),
         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),
-            meteredSceneLuminanceCdPerSquareMeter: meteredLuminance, resolution },
+        exposure: { mode, settings: { fNumber, shutterSeconds, iso: resolvedIso }, ev100: Math.log2(fNumber ** 2 / shutterSeconds), ...isoReport,
+            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 },