@photivra/engine 2.20.0 → 2.21.0

package/docs/api/facade-representative-light-sources.md

@@ -0,0 +1,131 @@
+# facade/representative-light-sources.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.
+
+## createRepresentativeLightSourceIlluminant
+
+A capture illuminant for a source: `{ kind: "spectrum", spectrum, label }` with the spectrum of
+{@link createRepresentativeLightSourceSpectrum} and the label "<name> (representative, not a named product)".
+
+```ts
+export function createRepresentativeLightSourceIlluminant(input: { sourceId: RepresentativeLightSourceId }): Extract<CaptureIlluminant, { kind: "spectrum" }>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createRepresentativeLightSourceSpectrum
+
+A source's relative spectral power distribution S(λ) = b + Σ aₖ·exp(−½((λ − μₖ)/σₖ)²) as a function spectrum on
+360–830 nm (relative units; values memoized per wavelength). Pass it to a capture as
+`illuminant: { kind: "spectrum", spectrum }`; for color work use `sensor.spectralStepNanometers: 5` or finer
+(docs/LIGHT_SOURCES.md, "Quadrature"). Throws `InvalidScientificInputError` outside 360–830 nm.
+
+```ts
+export function createRepresentativeLightSourceSpectrum(input: { sourceId: RepresentativeLightSourceId }): ColorimetricSpectrum;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## getRepresentativeLightSourceSet
+
+The built-in representative light sources: Photivra's own parametric spectra of a tri-phosphor fluorescent tube and
+three white LEDs (low and high color rendering at 4000 K, warm at 2700 K). A static, deeply frozen engine contract.
+Each is "representative, not a named product"; docs/LIGHT_SOURCES.md gives every formula and the reasons for it.
+
+```ts
+export function getRepresentativeLightSourceSet(): RepresentativeLightSourceSet;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## REPRESENTATIVE_LIGHT_SOURCE_IDS
+
+The source ids, in set order.
+
+```ts
+REPRESENTATIVE_LIGHT_SOURCE_IDS = Object.freeze([
+  "tri-phosphor-fluorescent-4000k", "white-led-low-rendering-4000k", "white-led-high-rendering-4000k", "warm-white-led-2700k"
+] as const)
+```
+
+## REPRESENTATIVE_LIGHT_SOURCE_SET_ID
+
+Identity of the built-in light-source set.
+
+```ts
+REPRESENTATIVE_LIGHT_SOURCE_SET_ID = "photivra-representative-light-sources"
+```
+
+## REPRESENTATIVE_LIGHT_SOURCE_SET_VERSION
+
+Version of the set's spectra; a change to any spectrum changes it.
+
+```ts
+REPRESENTATIVE_LIGHT_SOURCE_SET_VERSION = "1.0.0"
+```
+
+## REPRESENTATIVE_LIGHT_SOURCE_WAVELENGTH_RANGE_NANOMETERS
+
+Domain of every spectrum, nm (the CIE 1931 observer's domain; the capture facade uses 380–780 nm of it).
+
+```ts
+REPRESENTATIVE_LIGHT_SOURCE_WAVELENGTH_RANGE_NANOMETERS = Object.freeze({ minimum: 360, maximum: 830 })
+```
+
+## RepresentativeLightSource
+
+One built-in source: its id, name, design reason and spectrum definition.
+
+```ts
+export interface RepresentativeLightSource {
+  sourceId: RepresentativeLightSourceId;
+  /** Photivra's descriptive name, for example "White LED, high color rendering, 4000 K". */
+  name: string;
+  family: "fluorescent" | "led";
+  /** The CCT the spectrum was designed for, K (its computed CCT is within 1 K of it, Duv within 0.0001; docs/LIGHT_SOURCES.md). */
+  nominalCorrelatedColorTemperatureKelvin: number;
+  /** Always "representative, not a named product". */
+  label: "representative, not a named product";
+  /** One sentence: what the source represents and why it is built this way. */
+  reason: string;
+  /** The constant b (a low continuum), relative units. */
+  base: number;
+  bands: readonly RepresentativeLightSourceBand[];
+}
+```
+
+## RepresentativeLightSourceBand
+
+One Gaussian band a·exp(−½((λ − μ)/σ)²) of a source spectrum.
+
+```ts
+export interface RepresentativeLightSourceBand {
+  kind: "gaussian";
+  /** What the band represents, for example "blue pump" or "green phosphor line". */
+  role: string;
+  amplitude: number;
+  centerNanometers: number;
+  standardDeviationNanometers: number;
+}
+```
+
+## RepresentativeLightSourceId
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type RepresentativeLightSourceId = (typeof REPRESENTATIVE_LIGHT_SOURCE_IDS)[number];
+```
+
+## RepresentativeLightSourceSet
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface RepresentativeLightSourceSet {
+  setId: typeof REPRESENTATIVE_LIGHT_SOURCE_SET_ID;
+  setVersion: typeof REPRESENTATIVE_LIGHT_SOURCE_SET_VERSION;
+  wavelengthRangeNanometers: { readonly minimum: number; readonly maximum: number };
+  sources: readonly RepresentativeLightSource[];
+}
+```

package/docs/api/facade-scene-radiance.md

@@ -91,7 +91,8 @@ provider `providerProfileId`.
 
 ```ts
 export function createPlanarSceneRadianceProvider(input: {
-  scene: ChartScene | ChartMaterialLayerScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene;
+  /** An `image-plane` scene (#581) is refused: it is taken by the facade's capture and display-view functions, which load its module. */
+  scene: ChartScene | ChartMaterialLayerScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene | ImagePlaneScene;
   illuminant: CaptureIlluminant;
   illuminanceLux: number;
   distanceM: number;
@@ -110,6 +111,47 @@ export function createPlanarSceneRadianceProvider(input: {
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## ImagePlaneImage
+
+2.21 (#581): an image the caller supplies, for an {@link ImagePlaneScene}. `data` holds `width × height` pixels row by row
+from the top, `channels` (3: RGB, 4: RGBA) samples each, in the encoding's type: `srgb-8` Uint8Array or Uint8ClampedArray
+(canvas `ImageData.data`), `srgb-16` Uint16Array, `linear-srgb` Float32Array. sRGB primaries and white (IEC 61966-2-1) in
+every encoding; `srgb-8` and `srgb-16` are decoded with the sRGB transfer function, `linear-srgb` is already linear and is
+clipped to [0, 1] (the clipped samples are counted). Alpha is linear coverage over the paper. The array is read, never
+changed or kept beyond the call.
+
+```ts
+export interface ImagePlaneImage {
+  width: number;
+  height: number;
+  channels: 3 | 4;
+  encoding: "srgb-8" | "srgb-16" | "linear-srgb";
+  data: Uint8Array | Uint8ClampedArray | Uint16Array | Float32Array;
+}
+```
+
+## ImagePlaneScene
+
+2.21 (#581): a photo as a flat matte print on the scene plane, lit by the request's illuminant like a chart. Each pixel's
+color becomes a reflectance spectrum through the engine's print reflectance lattice (docs/IMAGE_PLANE.md): an
+approximation, a print of an image that was already processed, clipped and blurred by the camera that took it. The print's
+physical size is `chartSize` (its height defaults to the image's aspect); without it the print is fitted inside the frame,
+centered, on the 18 % surround.
+
+```ts
+export interface ImagePlaneScene {
+  kind: "image-plane";
+  sceneId: string;
+  image: ImagePlaneImage;
+  /** The paper and the deepest ink: reflectances of sRGB white and black, 0 ≤ black < white ≤ 1. Defaults 0.90 and 0.01. */
+  paper?: { whiteReflectance?: number; blackReflectance?: number };
+  /** How the print is reconstructed between pixel centers. Default `bilinear` (the pixels' spectra, bilinearly weighted). */
+  interpolation?: "bilinear" | "nearest";
+  /** Opt-in raised pixel limit: an integer up to the full-resolution ceiling. Default 24 000 000 pixels. */
+  maximumPixels?: number;
+}
+```
+
 ## PHOTOPIC_MAXIMUM_LUMINOUS_EFFICACY_LM_PER_W
 
 CIE maximum luminous efficacy for photopic vision, lm/W.
@@ -128,8 +170,11 @@ export interface PlanarSceneRadianceProvider {
   providerProfileId: string;
   evaluateRadiance(request: Readonly<SceneRadianceEvaluationRequest>): SceneRadianceEvaluationResult;
   evaluateApertureRadiance(request: Readonly<SceneRadianceEvaluationRequest>, ray: Readonly<SensorApertureRay>): SceneRadianceEvaluationResult;
-  /** Spectral radiance at a plane point (frame units), the same value the callbacks return. */
-  radianceAt(u: number, v: number, wavelengthNanometers: number): number;
+  /**
+   * Spectral radiance at a plane point (frame units), the same value the callbacks return. #551: a moving subject's provider
+   * reads it at time `t` (seconds from the first opening, default 0); a still scene ignores it.
+   */
+  radianceAt(u: number, v: number, wavelengthNanometers: number, t?: number): number;
   /**
    * 2.3, chart scenes only: the chart material at a plane point (frame units), or `materials.length` for the
    * surround of a fixed-size chart; `materialRadiance` gives that material's spectral radiance, the same value
@@ -137,6 +182,12 @@ export interface PlanarSceneRadianceProvider {
    */
   chartMaterialAt?(u: number, v: number): number;
   materialRadiance?(material: number, wavelengthNanometers: number): number;
+  /**
+   * 2.21 (#581), image-plane scenes only: the tabulated expected signal's scene at these spectral nodes and channel responses, its
+   * radiance per node and, for the direct path, Σ_n A_c(λ_n)·L(λ_n) integrated from each pixel's reconstructed spectrum
+   * (`ResolvedImagePlaneScene.pixelSignals`, the surround's reflectance times the neutral signal outside the print).
+   */
+  imageSignalScene?(wavelengths: readonly number[], perNode: readonly Float64Array[]): ImagePlaneSignalScene;
 }
 ```
 

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

@@ -144,7 +144,7 @@ a capture does. `motion.rotation` is a non-zero angular velocity; `sensor.tempor
 
 ```ts
 SIMULATE_CAPTURE_COST_OPTIONS = Object.freeze(["lens.pupilSampling", "lens.projection", "lens.distortion", "lens.vignetting", "lens.psf",
-  "lens.diffraction", "lens.defocus", "lens.catalogue", "sensor.antiAliasing", "sensor.pixelAperture.box", "sensor.temporalSampleCount", "motion.rotation", "motion.shutter.rolling", "output.borderHandling.mirror", "output.region",
+  "lens.diffraction", "lens.defocus", "lens.catalogue", "sensor.antiAliasing", "sensor.pixelAperture.box", "sensor.temporalSampleCount", "motion.rotation", "motion.subject", "motion.shutter.rolling", "output.borderHandling.mirror", "output.region",
   "output.whiteBalance.auto", "output.demosaic.ahd", "output.highlightMode.reconstruct", "output.colorEncoding.wide-gamut", "output.gamutMapping.perceptual",
   "output.diffractionCorrection", "output.sharpening", "output.lensCorrections", "output.format.jpeg", "output.format.png", "output.format.dng"] as const)
 ```
@@ -175,7 +175,7 @@ the record form with `fast` and is reported in `diagnostics.fast.applied` when i
 whether or not it has a fast method yet; one without runs exact and reports `false`.
 
 ```ts
-SIMULATE_CAPTURE_FAST_OPTIONS = Object.freeze(["lens.diffraction", "lens.catalogue", "sensor.antiAliasing", "sensor.pixelAperture.box", "output.demosaic.ahd"] as const)
+SIMULATE_CAPTURE_FAST_OPTIONS = Object.freeze(["lens.diffraction", "lens.catalogue", "sensor.antiAliasing", "sensor.pixelAperture.box", "output.demosaic.ahd", "motion.subject"] as const)
 ```
 
 ## SIMULATE_CAPTURE_METERING_MODES
@@ -473,8 +473,9 @@ export interface SimulateCaptureFastReport {
 
 `lens.catalogue` as a record (#568): the lens id as `kind` and the `fast` override (see {@link SimulateCaptureOptions.fast}).
 Fast: the tabulated fast method (#568), and with `lens.defocus` the lens's bokeh without its cat's eye (#567; fast wides and
-normals only), whose field-varying PSF needs a finer fast grid (measured 2.2–3.4× slower). Exact: the per-site PSF with the
-cat's eye. Blades and spherical aberration always apply (they cost nothing).
+normals only), whose field-varying PSF needs a finer fast grid (measured 2.2–3.4× slower); with camera rotation under
+`motion.shutter: "rolling"`, the per-tap PSF points instead of the lattice reading (#588). Exact: the per-site PSF with the
+cat's eye, read on the lattice. Blades and spherical aberration always apply (they cost nothing).
 
 ```ts
 export interface SimulateCaptureLensCatalogueRecord { kind: string; fast?: boolean }
@@ -529,6 +530,11 @@ export interface SimulateCaptureMotion {
   shutter?: "global" | "rolling";
   /** Rolling shutter only: time from the first to the last line over the simulated frame, in s. Default: the body's declared readout skew. */
   rollingShutterSkewSeconds?: number;
+  /**
+   * #551: a moving subject: the whole scene, or one rectangle of it over a still background, translating on the scene plane
+   * (and optionally rotating about the optical axis) during the exposure. Off by default (a still scene).
+   */
+  subject?: SimulateCaptureSubjectMotion;
 }
 ```
 
@@ -672,9 +678,10 @@ export interface SimulateCaptureOptions {
   /**
    * Required: an engine chart (for example `{ preset: "uniform" }`, an 18 % grey card), a declared `material-layers` scene (#491:
    * a chart under shape-mask layers, as `resolveChartMaterialLayers` takes it; the capture is that of its `callerScene`, byte for
-   * byte, and the display view can render it on the GPU), or a caller reflectance, radiance or material function.
+   * byte, and the display view can render it on the GPU), a caller reflectance, radiance or material function, or (2.21, #581) an
+   * `image-plane` scene: a photo as a flat print (docs/IMAGE_PLANE.md).
    */
-  scene: ChartScene | ChartMaterialLayerScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene;
+  scene: ChartScene | ChartMaterialLayerScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene | ImagePlaneScene;
   /** Distance from the camera to the scene plane in metres. Default 5. */
   subjectDistanceM?: number;
   /**
@@ -689,6 +696,12 @@ export interface SimulateCaptureOptions {
   illuminant?: CaptureIlluminant;
   /** Illuminance on the scene plane, lux. Default about 21 481 lux (see `SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX` and the assumptions). */
   illuminanceLux?: number;
+  /**
+   * 2.22 (#550), opt-in mixed lighting: two or more sources blended across the chart (docs/MIXED_ILLUMINATION.md), instead of
+   * `illuminant` and `illuminanceLux`. The frame center's light sets the grey-card meter and the standard-exposure figures, and
+   * its strongest source the "scene-illuminant" white balance; both are reported in `assumptions`.
+   */
+  illumination?: MixedIllumination;
   output?: {
     /** Output pixels; the native sensor raster adds a one-site demosaic border on each side. Defaults 64 × 64. */
     width?: number;
@@ -788,6 +801,13 @@ export interface SimulateCaptureOptions {
   motion?: SimulateCaptureMotion;
   /** #555: plus the sensor characteristics ({@link SimulateCaptureSensorCharacteristics}), each off by default. */
   sensor?: SimulateCaptureSensorCharacteristics & {
+    /**
+     * #554: a sensor profile record (`SENSOR_PROFILES`, or `resolveSensorProfile(id)`), checked strictly. It replaces the body's ISO range, readout regimes
+     * (full well, read noise of each conversion gain, the dual-gain switch, high-gain storage, ADC bit depth), readout time and
+     * fixed-pattern noise, and sets the default pixel pitch and peak QE; explicit fields here still override it one at a time.
+     * Default: none (the body's own sensor). See docs/SENSOR_PROFILES.md.
+     */
+    profile?: SensorProfile;
     /**
      * Pixel pitch in micrometres, 0.5–1000. Default 6. The simulated sensor is output width × pitch wide. 2.5: above 100 µm the
      * capture is a downsized view of a whole frame (for example 36 mm / 48 pixels = 750 µm), recorded in the assumption

package/docs/api/motion-subject-motion.md

@@ -0,0 +1,23 @@
+# motion/subject-motion.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.
+
+## SimulateCaptureSubjectMotion
+
+`motion.subject` of `simulateCapture`: a moving subject on the scene plane (#551).
+
+```ts
+export interface SimulateCaptureSubjectMotion {
+  /** Velocity on the scene plane, m/s: +x right, +y up as seen from the camera. Missing components are 0. */
+  velocityMPerSec?: { x?: number; y?: number };
+  /** Rotation about the optical axis direction, rad/s, counter-clockwise as seen from the camera (+x toward +y). Default 0. */
+  angularVelocityRadPerSec?: number;
+  /**
+   * The moving part: a rectangle on the scene plane at rest (at the first opening reference), its centre and size in metres
+   * (+x right, +y up from the optical axis). Omitted: the whole scene moves.
+   */
+  region?: { centerXM: number; centerYM: number; widthM: number; heightM: number };
+  /** Exact or fast (2.20.0 convention): fast takes fewer temporal midpoints when the subject's streak is short (see the docs). */
+  fast?: boolean;
+}
+```

package/docs/api/optics-generic-lens-lateral-color.md

@@ -0,0 +1,79 @@
+# optics/generic-lens-lateral-color.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.
+
+## calculateLateralColorFringe
+
+The red–blue image displacement of a catalogue lens at a field position on a sensor, in micrometres and pixels, from the
+lens's own lateral-colour model Δr(λ) = L·R·H·D(λ) at the lens corrections' channel wavelengths (610 and 465 nm), or at the
+given `channelDispersion`. Exact for the model (no fast mode); an approximation of a generic lens, not a measured product.
+
+```ts
+export function calculateLateralColorFringe(input: CalculateLateralColorFringeInput): CalculationResult<LateralColorFringe>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateLateralColorFringeInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateLateralColorFringeInput {
+  /** A catalogue id (`GENERIC_LENS_IDS`). */
+  lensId: string;
+  /** The sensor's active capture area, mm (the lens is scaled to it as in `resolveGenericLens`). */
+  activeImagingArea: { widthMm: number; heightMm: number };
+  /** The sensor's pixel pitch, µm. */
+  pixelPitchMicrometers: number;
+  /**
+   * The field position as fractions of the frame's half-width (x, +right) and half-height (y, +up) from the optical axis, each
+   * in [−1, 1]. Default `{ x: 1, y: 1 }`: the top-right corner.
+   */
+  fieldPosition?: { x: number; y: number };
+  /**
+   * 2.21.0: each channel's effective dispersion (`calculateChannelEffectiveDispersion` for the camera's channels and the light;
+   * only `red` and `blue` are read). Default: D at the single wavelengths 610 and 465 nm.
+   */
+  channelDispersion?: ChannelDispersion;
+}
+```
+
+## LateralColorDisplacement
+
+A signed displacement of the blue image from the red one: radial (positive: blue farther from the axis) and its x and y parts.
+
+```ts
+export interface LateralColorDisplacement {
+  radial: number;
+  x: number;
+  y: number;
+}
+```
+
+## LateralColorFringe
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LateralColorFringe {
+  lensId: string;
+  /** The image-plane point, mm from the optical axis (+x right, +y up). */
+  imagePointMm: { x: number; y: number };
+  /** Field height H: the point's distance from the axis as a fraction of the half-diagonal (1 at the corner). */
+  fieldHeight: number;
+  /** The channel wavelengths the displacement is taken at, nm; null with a given `channelDispersion`. */
+  channelWavelengthsNm: { red: number; blue: number } | null;
+  /** The red and blue dispersions D used (normalized: 0 at the d line, F minus C = 1). */
+  channelDispersion: { red: number; blue: number };
+  /** Blue-minus-red image displacement, µm. */
+  blueMinusRedMicrometers: LateralColorDisplacement;
+  /** The same in pixels of the given pitch. */
+  blueMinusRedPixels: LateralColorDisplacement;
+  /** The fringe width: |radial| displacement, µm and pixels. */
+  fringeWidthMicrometers: number;
+  fringeWidthPixels: number;
+  /** The lens's own F-to-C (486 to 656 nm) displacement at this point, L·R·H, µm. */
+  fToCMicrometers: number;
+}
+```

package/docs/api/output-developed-lens-corrections.md

@@ -2,10 +2,19 @@
 
 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.
 
+## ChannelDispersion
+
+A normalized dispersion per channel (`genericLensDispersion` units: 0 at the d line, F minus C = 1).
+
+```ts
+export type ChannelDispersion = Readonly<Record<LensCorrectionChannel, number>>;
+```
+
 ## GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM
 
 Effective wavelengths of the red, green and blue channels for the lateral-colour map, nm: a generic approximation of where
-a camera's channel responses peak, not a measured camera.
+a camera's channel responses peak, not a measured camera. The default of `createGenericLensCorrectionProfile` without a
+`channelDispersion`; `simulateCapture`'s `output.lensCorrections` uses the capture's own channels instead (#589).
 
 ```ts
 GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM: Readonly<Record<LensCorrectionChannel, number>> = Object.freeze({ red: 610, green: 540, blue: 465 })

package/docs/api/output-generic-lens-corrections.md

@@ -2,13 +2,44 @@
 
 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.
 
+## calculateChannelEffectiveDispersion
+
+#589: each channel's effective dispersion for the catalogue lenses' lateral colour, D̄_c = Σ w·D(λ) / Σ w with
+w = response_c(λ)·illuminant(λ) at the nodes and D the normalised Cauchy dispersion (`genericLensDispersion`: 0 at the
+Fraunhofer d line, F minus C = 1). Under lateral colour L·r·D(λ) a neutral surface's image in channel c moves by L·r·D̄_c, so
+blue minus red is L·r·(D̄_blue − D̄_red). Pass the result as `channelDispersion` to `createGenericLensCorrectionProfile`.
+`simulateCapture`'s `output.lensCorrections` computes it from the capture's own channels and reports it in its assumption.
+An approximation: a weighted mean over a neutral surface; a colored surface weights the band differently.
+
+```ts
+export function calculateChannelEffectiveDispersion(input: CalculateChannelEffectiveDispersionInput): CalculationResult<ChannelDispersion>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateChannelEffectiveDispersionInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateChannelEffectiveDispersionInput {
+  /** Spectral nodes, nm, strictly increasing, within 300–1100 nm. */
+  wavelengthsNm: readonly number[];
+  /** Each channel's response at the nodes (any common linear unit, ≥ 0; for example electrons per unit spectral radiance). */
+  channelResponse: { red: readonly number[]; green: readonly number[]; blue: readonly number[] };
+  /** The illuminant's relative spectral power at the nodes (≥ 0; the scale cancels). */
+  illuminant: readonly number[];
+}
+```
+
 ## createGenericLensCorrectionProfile
 
 Builds the catalogue lens's generic correction profile for one camera state: a radial distortion map (the lens's own
-r_d = r(1 + k1ρ²), read at each ideal destination point), per-channel lateral-colour scales 1 + L·D(λ_channel), and the
-relative-illumination gain at the state's aperture (strength 1). From profile version 1.1.0 (#584) the vignetting component
-(version 1.1.0) carries the distortion's area factor (`distortionAreaFactor`): its gain is det J(ρ_i)/E(ρ_s) at the capture's
-sensor point, so it flattens a flat-field capture. The result passes `parseGenericLensCorrectionProfile`.
+r_d = r(1 + k1ρ²), read at each ideal destination point), per-channel lateral-colour scales 1 + L·D̄_channel (`channelDispersion`,
+by default D at the generic channel wavelengths), and the relative-illumination gain at the state's aperture (strength 1). From
+profile version 1.1.0 (#584) the vignetting component (version 1.1.0) carries the distortion's area factor
+(`distortionAreaFactor`): its gain is det J(ρ_i)/E(ρ_s) at the capture's sensor point, so it flattens a flat-field capture. The
+result passes `parseGenericLensCorrectionProfile`.
 
 ```ts
 export function createGenericLensCorrectionProfile(input: CreateGenericLensCorrectionProfileInput): GenericLensCorrectionProfile;
@@ -28,5 +59,10 @@ export interface CreateGenericLensCorrectionProfileInput {
   activeImagingArea: { widthMm: number; heightMm: number };
   /** The exact camera state the profile applies to: its focal length must be the lens's on this sensor, its aperture in range. */
   state: OpticalProfileState;
+  /**
+   * #589: each channel's effective dispersion (`calculateChannelEffectiveDispersion` for the camera's channels and the light).
+   * Default: D at {@link GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM} (610, 540 and 465 nm), a generic approximation.
+   */
+  channelDispersion?: ChannelDispersion;
 }
 ```

package/docs/api/output-print-plan.md

@@ -42,14 +42,44 @@ export function parsePrintPlanInput(value: unknown): PrintPlanInput;
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## PrintContainLayout
+
+The layout of a `contain` fit, in millimetres. The printed image itself is the plan's `printedImageMm`.
+
+```ts
+export interface PrintContainLayout {
+  /** The paper as placed: after the quarter turn when `paperRotated`. */
+  paperMm: { width: number; height: number };
+  paperRotated: boolean;
+  /** Unprinted border on each side of the centered image; zero when the paper has the image's aspect ratio. */
+  bordersMm: { left: number; right: number; top: number; bottom: number };
+}
+```
+
 ## PrintedImageSize
 
 The flat printed image area. It excludes paper margins, borders and canvas wraps.
+With a `contain` fit it is instead the paper, or the printable area of it, that the image is fitted inside.
 
 ```ts
 export interface PrintedImageSize { width: number; height: number; unit: PrintLength["unit"] }
 ```
 
+## PrintFit
+
+How the printed image relates to `printedImage`.
+- `confirmed-native-aspect`: `printedImage` is the printed image itself and must already have the native aspect ratio,
+ within the stated relative error.
+- `contain`: `printedImage` is the paper. The image keeps the native aspect ratio and is scaled to the largest size that
+ fits inside it, centered; the rest is unprinted border. `match-image` turns the paper a quarter turn when its
+ orientation (portrait or landscape) differs from the image's; `as-given` keeps it. Layout only: nothing is cropped or resampled.
+
+```ts
+export type PrintFit =
+  | { kind: "confirmed-native-aspect"; maximumRelativeAspectError: number }
+  | { kind: "contain"; paperOrientation: "as-given" | "match-image" };
+```
+
 ## PrintLength
 
 A physical length. Not to be confused with image pixels or printer dots.
@@ -90,6 +120,8 @@ export interface PrintPlan {
   alternatives: { maximumImageMmAtCurrentDistance: { width: number; height: number }; minimumViewingDistanceMmAtCurrentSize: number | null } | null;
   capturedDetailAssessment: "unassessed";
   deliveryAssessment: "unassessed";
+  /** Present only with a `contain` fit; null when the native raster is unknown. */
+  contain?: PrintContainLayout | null;
 }
 ```
 
@@ -103,7 +135,7 @@ export interface PrintPlanInput {
   printedImage: PrintedImageSize;
   viewingDistance: PrintLength;
   sampling: PrintSamplingCriterion;
-  fit: { kind: "confirmed-native-aspect"; maximumRelativeAspectError: number };
+  fit: PrintFit;
   provider?: PrintProviderConstraints;
 }
 ```
@@ -156,6 +188,8 @@ export interface PrintSizeLimit {
   maximumImageMm: { width: number; height: number } | null;
   reasons: string[];
   referencePlan: PrintPlan;
+  /** Present only with a `contain` fit: the paper that holds `maximumImageMm` with the same layout (borders scale with it). */
+  maximumPaperMm?: { width: number; height: number } | null;
 }
 ```
 

package/llms.txt

@@ -7,6 +7,8 @@
 - [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
+- [Image-plane scene](https://github.com/Photivra/photivra/blob/main/docs/IMAGE_PLANE.md): a photo as a flat print in front of the camera (`{ kind: "image-plane" }`), its input, placement, print reflectance lattice and accuracy
+- [Light sources](https://github.com/Photivra/photivra/blob/main/docs/LIGHT_SOURCES.md): representative fluorescent and LED spectra designed by Photivra (`createRepresentativeLightSourceIlluminant`), their CCT and color rendering
 - [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.20.0",
+  "version": "2.21.0",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",