@photivra/engine 2.12.0 → 2.14.0

package/docs/api/facade-color-patches.md

@@ -0,0 +1,150 @@
+# facade/color-patches.ts public contracts
+
+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.
+
+## COLOR_PATCH_IDS
+
+The ids of the built-in patches, in the order of the `color-patches` chart (row-major, six per row).
+
+```ts
+COLOR_PATCH_IDS = Object.freeze([
+  "neutral-1", "neutral-2", "neutral-3", "neutral-4", "neutral-5", "neutral-6",
+  "red", "yellow", "green", "cyan", "blue", "magenta",
+  "red-soft", "yellow-soft", "green-soft", "cyan-soft", "blue-soft", "magenta-soft",
+  "skin-pale", "skin-medium", "skin-tan", "skin-deep", "sky-blue", "foliage-green",
+  "brick-red", "sand", "teal", "lavender", "deep-orange", "deep-violet"
+] as const)
+```
+
+## COLOR_PATCH_SET_ID
+
+Identity of the built-in patch set.
+
+```ts
+COLOR_PATCH_SET_ID = "photivra-color-patches"
+```
+
+## COLOR_PATCH_SET_VERSION
+
+Version of the patch set's spectra and reference values; a change to any spectrum changes it.
+
+```ts
+COLOR_PATCH_SET_VERSION = "1.0.0"
+```
+
+## COLOR_PATCH_WAVELENGTH_RANGE_NANOMETERS
+
+Wavelengths on which every patch spectrum is defined, nanometers, inclusive.
+
+```ts
+COLOR_PATCH_WAVELENGTH_RANGE_NANOMETERS = Object.freeze({ minimum: 360, maximum: 830 })
+```
+
+## ColorPatch
+
+One built-in patch: its id, short code, name, reason for being on the chart, spectrum definition and reference
+colorimetry.
+
+```ts
+export interface ColorPatch {
+  /** Stable API id, e.g. `"skin-medium"`. */
+  patchId: ColorPatchId;
+  /**
+   * Stable short code for labels and printed charts: `PV-` and a group letter and number, e.g. `"PV-N4"`. The letters are
+   * N neutral, S strong, T soft (tint), P skin (portrait), M memory and G gamut-edge, numbered in chart order.
+   */
+  code: string;
+  /** Photivra's own descriptive name, in US English, e.g. `"Studio Gray 4"`; not a third-party color name. */
+  name: string;
+  group: ColorPatchGroup;
+  /** One sentence: why the patch is on the chart. */
+  reason: string;
+  /** The constant b of the formula. */
+  base: number;
+  terms: readonly ColorPatchSpectralTerm[];
+  /**
+   * Reference colorimetry of the reflectance (not of a rendered capture): CIELAB under CIE illuminant D65 with the CIE
+   * 1931 2° observer, the CIE tables at 1 nm over 360–830 nm, white = the perfect diffuser under D65 (Y = 100); and the
+   * sRGB color of that XYZ (CSS Color 4 matrix, after XYZ scaling of the D65 table white to the sRGB white),
+   * 8-bit hex. Rounded for publication: L*, a*, b* to 0.01.
+   */
+  reference: { cielabD65: readonly [number, number, number]; srgbHex: string; inSrgbGamut: boolean };
+}
+```
+
+## ColorPatchGroup
+
+Groups of the patch set, in chart order.
+
+```ts
+export type ColorPatchGroup = "neutral" | "strong" | "soft" | "skin" | "memory" | "gamut-edge";
+```
+
+## ColorPatchId
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ColorPatchId = (typeof COLOR_PATCH_IDS)[number];
+```
+
+## ColorPatchSet
+
+The built-in patch set (see {@link getColorPatchSet}).
+
+```ts
+export interface ColorPatchSet {
+  setId: typeof COLOR_PATCH_SET_ID;
+  version: typeof COLOR_PATCH_SET_VERSION;
+  wavelengthRangeNanometers: { minimum: number; maximum: number };
+  /** Patches per row of the `color-patches` chart's default layout. */
+  columns: number;
+  patches: readonly ColorPatch[];
+}
+```
+
+## ColorPatchSpectralTerm
+
+One term of a patch spectrum (see the module formula).
+
+```ts
+export type ColorPatchSpectralTerm =
+  | { kind: "gaussian"; amplitude: number; centerNanometers: number; standardDeviationNanometers: number }
+  | { kind: "logistic-rise" | "logistic-fall"; amplitude: number; midpointNanometers: number; scaleNanometers: number };
+```
+
+## evaluateColorPatchReflectance
+
+The reflectance (dimensionless, in [0, 1]) of a built-in color patch at one wavelength, from its analytic formula.
+Labeled `approximation`: the spectra are Photivra's own smooth designs, not measurements of a physical sample.
+
+```ts
+export function evaluateColorPatchReflectance(input: EvaluateColorPatchReflectanceInput): CalculationResult<{ reflectance: number }>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## EvaluateColorPatchReflectanceInput
+
+Input of {@link evaluateColorPatchReflectance}.
+
+```ts
+export interface EvaluateColorPatchReflectanceInput {
+  patchId: ColorPatchId;
+  /** Vacuum wavelength, nanometers, in 360–830. */
+  wavelengthNanometers: number;
+}
+```
+
+## getColorPatchSet
+
+The built-in Photivra color-patch set: every patch's id, code, name, group, reason, spectrum parameters and reference CIELAB (D65,
+CIE 1931 2°) and sRGB values. A static, deeply frozen engine contract. Pass a patch to a chart as
+`{ kind: "color-patch", patchId }` wherever a chart reflectance is accepted, or draw the whole set with the
+`color-patches` chart preset.
+
+```ts
+export function getColorPatchSet(): ColorPatchSet;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

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

@@ -21,8 +21,17 @@ 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; `standardExposureDeviationStops` as in {@link SimulateCaptureResult}. */
+  /**
+   * The resolved exposure of the capture this view shows; `standardExposureDeviationStops`, `standardExposureIlluminanceLux`
+   * and `greyCardDeviationStops` 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;
+    /** 2.14: as in the capture result. */
+    greyCardDeviationStops: number | null;
+    /** 2.14: as in the capture result. */
+    metering: SimulateCaptureMetering;
     /** #516: as in the capture result. */
     isoControl: "manual" | "automatic"; autoIso?: SimulateCaptureAutoIsoReport };
   scene: SimulateCaptureResult["scene"];
@@ -134,6 +143,14 @@ whether or not it has a fast method yet; one without runs exact and reports `fal
 SIMULATE_CAPTURE_FAST_OPTIONS = Object.freeze(["lens.diffraction", "sensor.antiAliasing", "sensor.pixelAperture.box", "output.demosaic.ahd"] as const)
 ```
 
+## SIMULATE_CAPTURE_METERING_MODES
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+SIMULATE_CAPTURE_METERING_MODES: readonly SimulateCaptureMetering[] = Object.freeze(["scene-average", "grey-card"] as const)
+```
+
 ## SIMULATE_DISPLAY_VIEW_DEFAULT_SAMPLES_PER_AXIS
 
 Default stratified samples per axis of a display view (`view.samplesPerAxis`): 16 × 16 sampled real pixels per display pixel with detail, 4 × 4 where it is uniform.
@@ -186,23 +203,84 @@ 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 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;
+  /** 2.14: present when `exposure.autoIso.isoSteps` is given: the ISO steps Auto ISO chose from. */
+  isoSteps?: "whole-stop" | "third-stop";
+}
+```
+
+## 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;
 }
 ```
 
@@ -308,6 +386,17 @@ export type SimulateCaptureLensDistortion =
   | { kind: "brown-conrady"; profile: BrownConradyDistortionProfile };
 ```
 
+## SimulateCaptureMetering
+
+2.14: what the meter reads. `scene-average` (the default): the body's 16 × 16-zone meter reads the scene's luminance.
+`grey-card`: incident metering; every zone reads the luminance 0.18·E/π of an 18 % Lambertian grey card under the
+request's illuminance E, so the automatic modes choose settings whose `greyCardDeviationStops` is 0 (up to their steps
+and limits), whatever the scene's reflectances.
+
+```ts
+export type SimulateCaptureMetering = "scene-average" | "grey-card";
+```
+
 ## SimulateCaptureMotion
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -391,15 +480,37 @@ 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"`.
+     * - `isoSteps` (2.14): `"whole-stop"` (default) lets Auto ISO choose only the whole-stop ISOs of the body's grid
+     *   (100, 200, 400 …), as before the generic bodies gained third-stop settings (preset 2.1.0); `"third-stop"` lets it
+     *   choose every setting (100, 125, 160 …). Manual ISO always takes any setting of the grid. Limits must lie on the
+     *   grid Auto ISO uses.
      */
-    autoIso?: { slowestPreferredShutterSeconds: number; afterMaximumIso?: SimulateCaptureAutoIsoAfterMaximum };
+    autoIso?: { slowestPreferredShutterSeconds?: number | "auto"; afterMaximumIso?: SimulateCaptureAutoIsoAfterMaximum; limits?: AutoIsoLimits;
+      automaticSlowestShutter?: SimulateCaptureAutomaticSlowestShutterOptions; isoSteps?: "whole-stop" | "third-stop" };
     /** Shutter for manual and shutter-priority modes. Default 1/125 s. */
     shutterSeconds?: number;
     /** Exposure compensation applied to the meter target, in stops. Default 0. */
     compensationStops?: number;
+    /**
+     * 2.14: `"scene-average"` (default) or `"grey-card"` (incident metering, see {@link SimulateCaptureMetering}). Manual
+     * exposure does not use the meter's reading, so the setting changes only the automatic modes and Auto ISO.
+     */
+    metering?: SimulateCaptureMetering;
   };
   /**
    * Required: an engine chart (for example `{ preset: "uniform" }`, an 18 % grey card), a declared `material-layers` scene (#491:
@@ -608,6 +719,9 @@ export interface SimulateCaptureResult {
     isoControl: "manual" | "automatic";
     /** #516: present with `iso: "auto"`: how Auto ISO chose `settings.iso` and what limited it. */
     autoIso?: SimulateCaptureAutoIsoReport;
+    /** 2.14: the metering the exposure used (`exposure.metering`; `"scene-average"` when omitted). */
+    metering: SimulateCaptureMetering;
+    /** The scene's average luminance on the meter's zones, cd/m², with either metering. */
     meteredSceneLuminanceCdPerSquareMeter: number;
     /**
      * #515: deviation, in stops, of the exposure used from the CIPA DC-004-2020 standard exposure for the metered luminance L:
@@ -616,6 +730,23 @@ 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;
+    /**
+     * 2.14: deviation, in stops, of the exposure used from the CIPA DC-004-2020 standard exposure of an 18 % Lambertian grey
+     * card under the request's illuminance E (incident metering: the light falling on the scene, as a grey card or a
+     * hand-held incident meter reads it): log2(L_ref(N, t, S) / (0.18·E/π)), with L_ref = 10·N²/(0.65·t·S). Same sign as
+     * `standardExposureDeviationStops` (positive is darker, under). It does not depend on the scene's reflectances; with the
+     * default settings and illuminance it is exactly 0. The exposure modes still meter the scene (`meteredSceneLuminanceCdPerSquareMeter`);
+     * this only reports where the settings used sit against the grey card. Null for a radiance-function scene, whose radiance
+     * does not depend on the illuminance.
+     */
+    greyCardDeviationStops: 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/llms.txt

@@ -6,6 +6,7 @@
 
 - [Agent guide](https://github.com/Photivra/photivra/blob/main/docs/AGENT_GUIDE.md): which function to call, units, reading results, errors and limits
 - [Quick start](https://github.com/Photivra/photivra/blob/main/docs/QUICK_START.md): `simulateCapture()` inputs, defaults, chart presets and output formats
+- [Color patches](https://github.com/Photivra/photivra/blob/main/docs/COLOR_PATCHES.md): the built-in color chart patches (`color-patches` preset, `{ kind: "color-patch", patchId }`), their spectra and CIELAB
 - [Usage guide](https://github.com/Photivra/photivra/blob/main/docs/USAGE.md): worked examples for every public area
 - [API reference](https://github.com/Photivra/photivra/blob/main/docs/API_REFERENCE.md): every root export, with a task-to-function index
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photivra/engine",
-  "version": "2.12.0",
+  "version": "2.14.0",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",
@@ -73,7 +73,7 @@
     "node": ">=22.13.0"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && node scripts/minify-wgsl-dist.mjs",
     "hooks:install": "node scripts/install-git-hooks.mjs",
     "prepush": "node scripts/prepush.mjs",
     "check:static": "eslint . && tsc --noEmit && npm run check:licenses && npm run check:license-headers && npm run check:identity && npm run check:browser-surface",