@photivra/engine 2.11.1 → 2.13.0

package/docs/api/exposure-exposure-mode-resolver.md

@@ -198,6 +198,32 @@ 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;
+}
+```
+
+## AutoIsoLimits
+
+#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.
+
+```ts
+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;
 }
 ```
 
@@ -219,6 +245,8 @@ export type ExposureResolutionConstraint =
   | "none"
   | "iso-minimum"
   | "iso-maximum"
+  | "user-iso-minimum"
+  | "user-iso-maximum"
   | "iso-grid-quantization"
   | "shutter-minimum"
   | "shutter-maximum"
@@ -366,6 +394,8 @@ export interface FullAutoExposurePolicy {
     "minimum-selectable";
   isoQuantizationPolicy:
     "nearest-log2-lower-on-tie";
+  /** #505: optional photographer-set Auto ISO limits inside the body's Auto ISO range. */
+  autoIsoLimits?: AutoIsoLimits;
 }
 ```
 
@@ -467,6 +497,8 @@ export type ManualIsoControl =
       kind: "automatic";
       quantizationPolicy:
         "nearest-log2-lower-on-tie";
+      /** #505: optional photographer-set Auto ISO limits inside the body's Auto ISO range. */
+      autoIsoLimits?: AutoIsoLimits;
     };
 ```
 
@@ -521,6 +553,16 @@ export type ProgramAutoExposureModeResolution =
           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:
@@ -573,6 +615,14 @@ export type ProgramAutoIsoControl =
         "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;
     };
 ```
 
@@ -611,6 +661,24 @@ export interface ProgramLineSelectionDiagnostics {
 }
 ```
 
+## 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.
+
+```ts
+export interface ProgramSlowestPreferredShutterPolicy {
+  slowestPreferredShutterSeconds: number;
+  afterMaximumIso:
+    | "allow-slower-shutter"
+    | "hold-preferred-shutter";
+}
+```
+
 ## RelativeExposureControlAnchor
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.

package/docs/api/facade-simulate-capture.md

@@ -21,8 +21,12 @@ export interface DisplayViewResult {
    */
   view: { width: number; height: number; frameWidth: number; frameHeight: number; scaleX: number; scaleY: number; samplesPerAxis: number;
     region?: { x: number; y: number; width: number; height: number } };
-  /** The resolved exposure of the capture this view shows. */
-  exposure: { mode: SimulateCaptureExposureMode; settings: { fNumber: number; shutterSeconds: number; iso: number }; ev100: number };
+  /** The resolved exposure of the capture this view shows; `standardExposureDeviationStops` and `standardExposureIlluminanceLux` as in {@link SimulateCaptureResult}. */
+  exposure: { mode: SimulateCaptureExposureMode; settings: { fNumber: number; shutterSeconds: number; 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"];
   /**
    * Work done: real pixels sampled, real-site expectations evaluated, scene queries, display pixels sampled in full (detail) or with
@@ -53,7 +57,9 @@ export interface IdealReferenceResult {
   engineApiVersion: string;
   image: { width: number; height: number; format: SimulateCaptureOutputFormat; samples: Uint8Array | Uint16Array; png?: Uint8Array; colorEncoding?: SimulateCaptureColorEncoding };
   /** The resolved exposure of the capture this reference matches. */
-  exposure: { mode: SimulateCaptureExposureMode; settings: { fNumber: number; shutterSeconds: number; iso: number }; ev100: number };
+  exposure: { mode: SimulateCaptureExposureMode; settings: { fNumber: number; shutterSeconds: number; iso: number }; ev100: number;
+    /** #516: as in the capture result. */
+    isoControl: "manual" | "automatic"; autoIso?: SimulateCaptureAutoIsoReport };
   scene: SimulateCaptureResult["scene"];
   region?: { x: number; y: number; width: number; height: number; frameWidth: number; frameHeight: number };
   diagnostics: { sampleCount: number; timingsMs: { reference: number; total: number } };
@@ -163,6 +169,104 @@ export interface SimulateCaptureAssumption {
 }
 ```
 
+## SimulateCaptureAutoIsoAfterMaximum
+
+#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.
+
+```ts
+export type SimulateCaptureAutoIsoAfterMaximum = "allow-slower-shutter" | "hold-preferred-shutter";
+```
+
+## SimulateCaptureAutoIsoReport
+
+#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`.
+
+```ts
+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;
+}
+```
+
+## SimulateCaptureAutomaticSlowestShutterOptions
+
+#504: the settings of `exposure.autoIso.slowestPreferredShutterSeconds: "auto"`. Every field is optional; the defaults are
+labelled generic values, recorded as `default` assumptions.
+
+```ts
+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;
+}
+```
+
+## SimulateCaptureAutomaticSlowestShutterReport
+
+#504: the automatic slowest preferred shutter in the Auto ISO report.
+
+```ts
+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;
+}
+```
+
 ## SimulateCaptureBorderHandling
 
 `margin` renders extra native sites around the output, as far as the kernel reaches. `mirror` renders
@@ -338,8 +442,34 @@ 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. */
@@ -548,7 +678,25 @@ export interface SimulateCaptureResult {
     settings: { fNumber: number; shutterSeconds: number; iso: number };
     /** 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;
   };

package/docs/api/output-text-metadata.md

@@ -2,6 +2,40 @@
 
 The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
+## addJpegTextMetadata
+
+Returns a copy of a baseline JPEG with the text fields added: merged into its XMP APP1 packet (or a new packet
+after the last leading APPn segment when it has none), plus a COM segment for `comment`. Every other byte,
+including the entropy-coded data, is unchanged. Reads marker segments only up to SOS. The engine's own
+`output.metadata` path calls this function, so for the same JPEG and text the bytes are the same.
+
+Root export (#388). `metadata` is checked as `output.metadata` is (see the module notes); a JPEG without SOI,
+a malformed or truncated segment before SOS, an XMP APP1 segment after a non-APPn segment, an XMP packet that is
+not UTF-8 or has no `rdf:RDF`, or text that makes the packet larger than one APP1 segment fails with
+`InvalidConfigurationError`. The input is not changed.
+
+```ts
+export function addJpegTextMetadata(jpeg: Uint8Array, metadata: Readonly<OutputTextMetadata>): Uint8Array;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## addPngTextMetadata
+
+Returns a copy of a PNG with one text chunk per field inserted before the first IDAT chunk. Other chunks are
+unchanged. The engine's own `output.metadata` path calls this function, so for the same PNG and text the bytes
+are the same.
+
+Root export (#388). `metadata` is checked as `output.metadata` is (see the module notes); a file without the PNG
+signature, or without an IDAT chunk inside its bytes, fails with `InvalidConfigurationError`. Chunk CRCs before
+IDAT are not checked. The input is not changed.
+
+```ts
+export function addPngTextMetadata(png: Uint8Array, metadata: Readonly<OutputTextMetadata>): Uint8Array;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
 ## OutputTextMetadata
 
 Caller-supplied text written into JPEG, PNG and DNG outputs. Every field is optional; at least one must be set.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photivra/engine",
-  "version": "2.11.1",
+  "version": "2.13.0",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",