@photivra/engine 2.2.1 → 2.3.0

package/docs/api/facade-chart-scenes.md

@@ -2,6 +2,37 @@
 
 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.
 
+## BarGroupsChartScene
+
+2.3: groups of three dark bars on a light plate (the three-bar concept of the US Air Force 1951 target,
+a US-government publication, in the engine's own arrangement): one group per frequency, vertical bars (horizontal resolution)
+in the upper row and horizontal bars (vertical resolution) below, optionally labelled with engine-drawn
+seven-segment numerals. Frequencies are line widths per picture height (LW/PH, as in ISO 12233), where
+the picture height is the chart's height: one bar is PH/LW wide.
+
+```ts
+export interface BarGroupsChartScene {
+  preset: "bar-groups";
+  /** One group per entry, left to right: integers 1..100000. Default [100, 200, 400, 800]. 1..32 entries. */
+  lineWidthsPerPictureHeight?: readonly number[];
+  /** Draw each group's LW/PH value below it. Default true. */
+  numerals?: boolean;
+  darkReflectance?: number;
+  lightReflectance?: number;
+}
+```
+
+## calculateBarGroupTargets
+
+The bar groups of a `bar-groups` chart, or of every `bar-groups` element of a composite, in the chart's
+frame units (2.3). `aspect` is the chart's height / width, as for {@link resolveChartScene}.
+
+```ts
+export function calculateBarGroupTargets(input: { scene: ChartScene; aspect: number }): ChartBarGroupTarget[];
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
 ## calculatePointGridCenters
 
 Centres (frame units) of a point grid: one disk centred in each of columns × rows equal cells, row-major from the top-left.
@@ -12,6 +43,18 @@ export function calculatePointGridCenters(input: { columns: number; rows: number
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## calculateSlantedSquareEdges
+
+Squares and edges of a `slanted-squares` chart, or of every `slanted-squares` element of a composite, in
+the chart's frame units (2.3), for slanted-edge regions of interest (Burns, PICS 2000). Directions are unit
+vectors along each edge (u right, v up).
+
+```ts
+export function calculateSlantedSquareEdges(input: { scene: ChartScene; aspect: number }): ChartSlantedSquare[];
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
 ## calculateStepWedgeReflectances
 
 Step reflectances of a step wedge. `equal-density` spaces optical density D = -log10(R) evenly, which
@@ -24,6 +67,14 @@ export function calculateStepWedgeReflectances(input: { steps: number; minimumRe
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## CHART_CONTINUOUS_LEVELS
+
+Neutral levels that represent a continuous pattern (grey ramp; 2.3 sine star, zone plate and dead-leaves greys).
+
+```ts
+CHART_CONTINUOUS_LEVELS = 1024
+```
+
 ## CHART_SCENE_DEFAULTS
 
 Engine-chosen chart parameters, each reported when the caller omitted it.
@@ -37,7 +88,16 @@ CHART_SCENE_DEFAULTS = Object.freeze({
   "grey-ramp": Object.freeze({ minimumReflectance: 0.03, maximumReflectance: 0.9 }),
   checkerboard: Object.freeze({ squaresAcross: 8, darkReflectance: 0.05, lightReflectance: 0.8 }),
   "point-grid": Object.freeze({ columns: 5, rows: 3, radius: 0.01, pointReflectance: 0.9, backgroundReflectance: 0.02 }),
-  patches: Object.freeze({ gapFraction: 0.1, backgroundReflectance: 0.18 })
+  patches: Object.freeze({ gapFraction: 0.1, backgroundReflectance: 0.18 }),
+  "dead-leaves": Object.freeze({ radiusMinimum: 0.01, radiusMaximum: 0.5, minimumReflectance: 0.2, maximumReflectance: 0.6, seed: 1 }),
+  "bar-groups": Object.freeze({ lineWidthsPerPictureHeight: Object.freeze([100, 200, 400, 800]), numerals: true, darkReflectance: 0.05, lightReflectance: 0.8 }),
+  "hyperbolic-wedge": Object.freeze({ orientation: "horizontal" as const, lineCount: 5, minimumLineWidthsPerPictureHeight: 100,
+    maximumLineWidthsPerPictureHeight: 1000, darkReflectance: 0.05, lightReflectance: 0.8 }),
+  "zone-plate": Object.freeze({ radiusFraction: 0.9, maximumCyclesPerPictureHeight: 200, darkReflectance: 0.1, lightReflectance: 0.7, backgroundReflectance: 0.18 }),
+  "slanted-squares": Object.freeze({ columns: 3, rows: 2, sizeFraction: 0.5, angleDegrees: 5, darkReflectance: 0.15, lightReflectance: 0.6 }),
+  "line-grid": Object.freeze({ spacing: 1 / 3, lineWidth: 0.01, lineReflectance: 0.42, backgroundReflectance: 0.6 }),
+  fiducial: Object.freeze({ radiusFraction: 0.8, ringFraction: 0.18, inverted: false, darkReflectance: 0.05, lightReflectance: 0.8, backgroundReflectance: 0.18 }),
+  composite: Object.freeze({ background: Object.freeze({ preset: "uniform" as const, reflectance: 0.18 }) })
 })
 ```
 
@@ -47,7 +107,8 @@ The exact contract is declared below; use the domain guide for assumptions and s
 
 ```ts
 CHART_SCENE_PRESETS: readonly ChartScenePresetId[] = Object.freeze(["uniform", "slanted-edge", "siemens-star",
-  "step-wedge", "grey-ramp", "checkerboard", "point-grid", "patches"] as const)
+  "step-wedge", "grey-ramp", "checkerboard", "point-grid", "patches", "dead-leaves", "bar-groups", "hyperbolic-wedge", "zone-plate",
+  "slanted-squares", "line-grid", "fiducial", "composite"] as const)
 ```
 
 ## CHART_SPECTRAL_RANGE_NANOMETERS
@@ -58,6 +119,43 @@ Wavelength range every chart spectrum must cover (the facade's sensor quadrature
 CHART_SPECTRAL_RANGE_NANOMETERS = Object.freeze({ minimum: 380, maximum: 780 })
 ```
 
+## ChartBarGroupTarget
+
+One bar group of a `bar-groups` chart or composite element, in the chart's frame units.
+
+```ts
+export interface ChartBarGroupTarget {
+  /** Composite element index, or null for a plain `bar-groups` chart. */
+  elementIndex: number | null;
+  lineWidthsPerPictureHeight: number;
+  /** Line pairs (cycles) per picture height: LW/PH ÷ 2. */
+  cyclesPerPictureHeight: number;
+  /** Width of one bar, frame units. */
+  lineWidth: number;
+  /** The three vertical bars (horizontal resolution) and the three horizontal bars (vertical resolution). */
+  verticalBars: ChartRectangle;
+  horizontalBars: ChartRectangle;
+}
+```
+
+## ChartElementScene
+
+Any chart preset except `composite`: a composite's background or element.
+
+```ts
+export type ChartElementScene = UniformChartScene | SlantedEdgeChartScene | SiemensStarChartScene | StepWedgeChartScene | GreyRampChartScene |
+  CheckerboardChartScene | PointGridChartScene | PatchChartScene | DeadLeavesChartScene | BarGroupsChartScene | HyperbolicWedgeChartScene |
+  ZonePlateChartScene | SlantedSquaresChartScene | LineGridChartScene | FiducialChartScene;
+```
+
+## ChartRectangle
+
+An axis-aligned rectangle in chart frame units: u0 ≤ u ≤ u1, v0 ≤ v ≤ v1.
+
+```ts
+export interface ChartRectangle { u0: number; v0: number; u1: number; v1: number }
+```
+
 ## ChartReflectance
 
 A neutral (spectrally flat) reflectance in [0, 1], or a caller reflectance spectrum (values in [0, 1]).
@@ -71,8 +169,7 @@ export type ChartReflectance = number | ColorimetricSpectrum;
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
 
 ```ts
-export type ChartScene = UniformChartScene | SlantedEdgeChartScene | SiemensStarChartScene | StepWedgeChartScene |
-  GreyRampChartScene | CheckerboardChartScene | PointGridChartScene | PatchChartScene;
+export type ChartScene = ChartElementScene | CompositeChartScene;
 ```
 
 ## ChartScenePresetId
@@ -83,6 +180,25 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export type ChartScenePresetId = ChartScene["preset"];
 ```
 
+## ChartSlantedSquare
+
+One square of a `slanted-squares` chart and its four edges, in the chart's frame units.
+
+```ts
+export interface ChartSlantedSquare {
+  elementIndex: number | null;
+  center: { u: number; v: number };
+  /** Side length, frame units. */
+  side: number;
+  /** Clockwise rotation, degrees. */
+  angleDegrees: number;
+  darkReflectance: number;
+  lightReflectance: number;
+  /** `left`/`right` edges are near-vertical (horizontal MTF), `top`/`bottom` near-horizontal (vertical MTF). */
+  edges: { side: "left" | "right" | "top" | "bottom"; midpoint: { u: number; v: number }; direction: { u: number; v: number }; length: number }[];
+}
+```
+
 ## CheckerboardChartScene
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -97,6 +213,82 @@ export interface CheckerboardChartScene {
 }
 ```
 
+## CompositeChartElement
+
+One element of a composite chart: a preset drawn inside its placement rectangle (frame units of the
+composite). The element sees its own frame: u = ±1 at the rectangle's left and right edges, aspect =
+height / width, and LW/PH frequencies still refer to the composite's picture height.
+
+```ts
+export interface CompositeChartElement {
+  scene: ChartElementScene;
+  centerU: number;
+  centerV: number;
+  width: number;
+  height: number;
+  /** `rectangle` (default) or `ellipse` inscribed in the rectangle; outside it, earlier elements or the background show. */
+  mask?: "rectangle" | "ellipse";
+}
+```
+
+## CompositeChartScene
+
+2.3: an ordered list of elements over a background. Later elements cover earlier ones. The engine
+provides only the generic parts; a branded or product-specific layout stays in the application.
+
+```ts
+export interface CompositeChartScene {
+  preset: "composite";
+  /** Fills the whole composite frame. Default `{ preset: "uniform", reflectance: 0.18 }`. */
+  background?: ChartElementScene;
+  /** 1..256 elements, drawn in order. */
+  elements: readonly CompositeChartElement[];
+}
+```
+
+## DeadLeavesChartScene
+
+2.3: seeded dead-leaves texture (Matheron's random closed set model, in the scale-invariant form used for
+camera texture measurement by Cao, Guichard and Hornung): opaque disks with Poisson-distributed centres,
+radius density ∝ r⁻³ on [radiusMinimum, radiusMaximum] and a grey drawn uniformly in [minimum, maximum]
+reflectance. Disks are drawn in order with earlier disks on top until every point of the chart (plus 0.1
+frame units around it) is covered, which samples the stationary dead-leaves image exactly (Kendall and
+Thönnes' backward "perfect simulation"). Radii are in frame units (fraction of the frame half-width).
+
+```ts
+export interface DeadLeavesChartScene {
+  preset: "dead-leaves";
+  /** Smallest disk radius, frame units, [0.002, radiusMaximum). Default 0.01. */
+  radiusMinimum?: number;
+  /** Largest disk radius, frame units, (radiusMinimum, 2]. Default 0.5. */
+  radiusMaximum?: number;
+  /** Grey range (neutral reflectances). Defaults 0.2 and 0.6. */
+  minimumReflectance?: number;
+  maximumReflectance?: number;
+  /** Random seed (uint32); the same seed gives the same disks on every platform. Default 1. */
+  seed?: number;
+}
+```
+
+## FiducialChartScene
+
+2.3: registration fiducial: a 2 × 2 checker disk inside a dark ring; `inverted` swaps the checker phase (an orientation cue).
+
+```ts
+export interface FiducialChartScene {
+  preset: "fiducial";
+  /** Disk radius as a fraction of the frame half-height, (0, 1]. Default 0.8. */
+  radiusFraction?: number;
+  /** Ring width as a fraction of the radius, (0, 1). Default 0.18. */
+  ringFraction?: number;
+  /** Default false: the upper-right and lower-left quadrants are dark. */
+  inverted?: boolean;
+  darkReflectance?: number;
+  lightReflectance?: number;
+  backgroundReflectance?: number;
+}
+```
+
 ## GreyRampChartScene
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -110,6 +302,43 @@ export interface GreyRampChartScene {
 }
 ```
 
+## HyperbolicWedgeChartScene
+
+2.3: hyperbolic wedge: `lineCount` dark lines separated by light gaps of the same width, whose width
+shrinks along the wedge axis so that the frequency rises linearly from the minimum to the maximum LW/PH.
+The line edges are hyperbolas. `horizontal`: the axis runs left to right and the lines are nearly
+horizontal (vertical resolution); `vertical`: the axis runs bottom to top (horizontal resolution).
+
+```ts
+export interface HyperbolicWedgeChartScene {
+  preset: "hyperbolic-wedge";
+  orientation?: "horizontal" | "vertical";
+  /** Dark lines, 1..50. Default 5. */
+  lineCount?: number;
+  /** LW/PH at the start and end of the axis. Defaults 100 and 1000. */
+  minimumLineWidthsPerPictureHeight?: number;
+  maximumLineWidthsPerPictureHeight?: number;
+  darkReflectance?: number;
+  lightReflectance?: number;
+}
+```
+
+## LineGridChartScene
+
+2.3: straight lines at every multiple of `spacing` from the centre in u and v (a distortion and registration grid).
+
+```ts
+export interface LineGridChartScene {
+  preset: "line-grid";
+  /** Distance between lines, frame units, (0, 2]. Default 1/3 (six cells across). */
+  spacing?: number;
+  /** Line width, frame units, (0, spacing). Default 0.01. */
+  lineWidth?: number;
+  lineReflectance?: number;
+  backgroundReflectance?: number;
+}
+```
+
 ## PatchChartScene
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -196,6 +425,13 @@ export interface SiemensStarChartScene {
   lightReflectance?: number;
   /** Reflectance outside the star. Default 0.18. */
   backgroundReflectance?: number;
+  /**
+   * 2.3: angular reflectance profile. `bar` (default): square-wave sectors. `sine`: a sinusoidal star,
+   * R(θ) = mid + amp·sin(2π·cycles·(θ/2π + ½)) between the dark and light reflectances, zero crossings at
+   * the bar star's sector edges, quantized to {@link CHART_CONTINUOUS_LEVELS} levels. Reported in the
+   * parameters only when given, so 2.2 scene digests are unchanged.
+   */
+  profile?: "bar" | "sine";
 }
 ```
 
@@ -215,6 +451,27 @@ export interface SlantedEdgeChartScene {
 }
 ```
 
+## SlantedSquaresChartScene
+
+2.3: a field of dark squares rotated clockwise by `angleDegrees` on a light background, one centred in
+each of columns × rows equal cells: every square gives two near-vertical and two near-horizontal slanted
+edges (Burns, PICS 2000). See {@link calculateSlantedSquareEdges}.
+
+```ts
+export interface SlantedSquaresChartScene {
+  preset: "slanted-squares";
+  columns?: number;
+  rows?: number;
+  /** Square side as a fraction of the smaller cell side, (0, 1); the rotated square must stay in its cell. Default 0.5. */
+  sizeFraction?: number;
+  /** Clockwise rotation, degrees, in (-45, 45). Default 5. */
+  angleDegrees?: number;
+  /** Square (dark) and background (light) reflectances. Defaults 0.15 and 0.6 (4:1). */
+  darkReflectance?: number;
+  lightReflectance?: number;
+}
+```
+
 ## StepWedgeChartScene
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -238,3 +495,22 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface UniformChartScene { preset: "uniform"; reflectance?: ChartReflectance }
 ```
+
+## ZonePlateChartScene
+
+2.3: circular zone plate R(r) = mid + amp·cos(π·k·r²): the local frequency k·r rises linearly from 0 at
+the centre to `maximumCyclesPerPictureHeight` at the rim (the quadratic-phase chirp of a Fresnel zone
+plate). Quantized to {@link CHART_CONTINUOUS_LEVELS} levels.
+
+```ts
+export interface ZonePlateChartScene {
+  preset: "zone-plate";
+  /** Plate radius as a fraction of the frame half-height, (0, 1]. Default 0.9. */
+  radiusFraction?: number;
+  /** Frequency at the rim, cycles per picture height. Default 200. */
+  maximumCyclesPerPictureHeight?: number;
+  darkReflectance?: number;
+  lightReflectance?: number;
+  backgroundReflectance?: number;
+}
+```

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

@@ -32,6 +32,29 @@ export type CaptureIlluminant =
   | { kind: "spectrum"; spectrum: ColorimetricSpectrum; label?: string };
 ```
 
+## CHART_SIZE_DEFAULT_SURROUND_REFLECTANCE
+
+Default surround of a fixed-size chart: an 18 % grey plane.
+
+```ts
+CHART_SIZE_DEFAULT_SURROUND_REFLECTANCE = 0.18
+```
+
+## ChartSizeOption
+
+2.3: a chart's physical size on the scene plane (`simulateCapture` `chartSize`, `createPlanarSceneRadianceProvider` `chartSize`).
+
+```ts
+export interface ChartSizeOption {
+  /** Chart width in metres, (0, 10 000]. */
+  widthM: number;
+  /** Chart height in metres. Default: widthM × the frame aspect (height / width), so the chart has the frame's shape. */
+  heightM?: number;
+  /** Neutral reflectance of the plane around the chart, lit by the same illuminant. Default 0.18. */
+  surroundReflectance?: number;
+}
+```
+
 ## createPlanarSceneRadianceProvider
 
 Public scene-preset provider. Places an engine chart (or a caller reflectance or radiance function) on
@@ -51,6 +74,11 @@ export function createPlanarSceneRadianceProvider(input: {
   aspect: number;
   sceneId: string;
   providerProfileId: string;
+  /**
+   * 2.3, opt-in: place the chart at this physical size, centred, instead of filling the frame; the chart preset
+   * is resolved with aspect heightM / widthM and the rest of the plane is the surround.
+   */
+  chartSize?: ChartSizeOption;
 }): PlanarSceneRadianceProvider & { chart: ResolvedChartScene | null };
 ```
 
@@ -76,6 +104,13 @@ export interface PlanarSceneRadianceProvider {
   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;
+  /**
+   * 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
+   * `radianceAt` returns at its points.
+   */
+  chartMaterialAt?(u: number, v: number): number;
+  materialRadiance?(material: number, wavelengthNanometers: number): number;
 }
 ```
 
@@ -118,5 +153,12 @@ export interface ScenePlanePoint {
   u: number;
   v: number;
   wavelengthNanometers: number;
+  /**
+   * 2.3, only with a fixed-size chart (`chartSize`): the point in chart-local frame units (±1 at the chart's
+   * left/right edges, v up on the same scale, ±chart height/width at its top/bottom). The function is then
+   * called only for points on the chart; the surround is the placement's surround reflectance.
+   */
+  chartU?: number;
+  chartV?: number;
 }
 ```

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

@@ -2,6 +2,38 @@
 
 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.
 
+## IdealReferenceResult
+
+Result of {@link simulateIdealReference}: an ideal reference image, not a capture (no RAW, plan or request).
+
+```ts
+export interface IdealReferenceResult {
+  kind: "ideal-reference";
+  /** Human-readable label for a user interface. */
+  label: string;
+  facadeVersion: typeof SIMULATE_CAPTURE_FACADE_VERSION;
+  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 };
+  scene: SimulateCaptureResult["scene"];
+  region?: { x: number; y: number; width: number; height: number; frameWidth: number; frameHeight: number };
+  diagnostics: { sampleCount: number; timingsMs: { reference: number; total: number } };
+  provenance: { scientificStatus: "approximation"; cameraPresetId: string; cameraPresetVersion: string; evidence: readonly EvidenceProvenance[];
+    composedContracts: readonly string[]; limitations: readonly string[] };
+  /** The capture request's assumptions, then `reference.kind`, `reference.excludes`, `reference.exposure` and `reference.sampling`. */
+  assumptions: readonly SimulateCaptureAssumption[];
+}
+```
+
+## SIMULATE_CAPTURE_BOX_APERTURE_DEFAULT_SAMPLES
+
+Default midpoint samples per axis of `sensor.pixelAperture: "box"`.
+
+```ts
+SIMULATE_CAPTURE_BOX_APERTURE_DEFAULT_SAMPLES = 4
+```
+
 ## SIMULATE_CAPTURE_COST_OPTIONS
 
 Options reported in `diagnostics.options` (2.1), in this order, when they ran: the ones that change how much work
@@ -9,7 +41,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", "sensor.antiAliasing", "sensor.temporalSampleCount", "motion.rotation", "motion.shutter.rolling", "output.borderHandling.mirror",
+  "lens.diffraction", "sensor.antiAliasing", "sensor.pixelAperture.box", "sensor.temporalSampleCount", "motion.rotation", "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.format.jpeg", "output.format.png", "output.format.dng"] as const)
 ```
@@ -144,6 +176,14 @@ export interface SimulateCaptureOptions {
   lens?: {
     /** Must lie in the lens capability (the generic primes are 50 mm). Default: the lens's shortest focal length. */
     focalLengthMm?: number;
+    /**
+     * Opt-in (2.3): a lens of the generic prime family by its full-frame-equivalent focal length
+     * (`GENERIC_PRIME_EQUIVALENT_FOCAL_LENGTHS_MM`). Its physical focal length is the equivalent ÷ the diagonal crop
+     * factor of the simulated frame (output width × height × pixel pitch); it replaces the tier lens's focal length and
+     * f-number range (the tier lens's transmission is kept). An f-number outside the prime's range, or a subject or
+     * focus distance below its minimum focus distance, is rejected. Not combinable with `focalLengthMm`.
+     */
+    prime?: number;
     /** Aperture for manual and aperture-priority modes. Default 8. */
     fNumber?: number;
     /** Focus distance in metres. Default: the subject distance. */
@@ -183,6 +223,14 @@ export interface SimulateCaptureOptions {
   scene: ChartScene | CallerReflectanceScene | CallerRadianceScene;
   /** Distance from the camera to the scene plane in metres. Default 5. */
   subjectDistanceM?: number;
+  /**
+   * Opt-in (2.3) fixed-size chart: place the scene at this physical size on the plane at the subject distance,
+   * centred on the optical axis, instead of sizing it to fill the frame. Outside it the plane is a neutral surround
+   * (default 18 %). Chart presets are resolved in the chart's own frame (aspect heightM / widthM); caller functions
+   * are called only on the chart and receive chart-local `chartU`, `chartV`. `result.scene.chart` reports the
+   * framed width, the fraction of the frame the chart covers and the thin-lens magnification.
+   */
+  chartSize?: ChartSizeOption;
   /** Default: Planckian 6500 K (a blackbody stand-in for daylight; CIE D65 is not bundled). */
   illuminant?: CaptureIlluminant;
   /** Illuminance on the scene plane, lux. Default about 21 481 lux (see `SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX` and the assumptions). */
@@ -225,6 +273,15 @@ export interface SimulateCaptureOptions {
      * memory grow with the pixel count (see "Large images" in the quick start); browsers may fail at large sizes.
      */
     maximumPixels?: number;
+    /**
+     * Opt-in (2.3) region rendering: render only this rectangle, in output-pixel coordinates of the whole frame
+     * `width` × `height` (x right, y down from its top-left). The pixels are byte-identical to the same pixels of
+     * the whole render: framing, metering, exposure, noise seeds (absolute native site indices), rolling-shutter row
+     * timing, diffraction and demosaic all use the whole frame. Use it to tile a large frame across workers or to
+     * render a 100 % crop. `result.image` is the region; `result.region` reports it. Not combinable with
+     * `whiteBalance: "auto"`, whose statistics would come from the region only.
+     */
+    region?: { x: number; y: number; width: number; height: number };
   };
   /** Camera motion and shutter type. Default: still camera, global electronic shutter. */
   motion?: SimulateCaptureMotion;
@@ -242,6 +299,13 @@ export interface SimulateCaptureOptions {
      * Multiplies the scene queries by the number of split points. Default off (the tiers declare no filter).
      */
     antiAliasing?: SimulateCaptureSensorAntiAliasing;
+    /**
+     * Opt-in (2.3) pixel aperture. `"point"` (default): each site samples the irradiance at its centre.
+     * `"box"`: each site integrates the irradiance over its whole square photosite (fill factor 1) with an
+     * N × N midpoint rule, N = `samplesPerAxis` (1–16, default 4), so detail finer than a pixel averages out as
+     * on a real sensor (pixel MTF |sinc(f·p)|) instead of aliasing. Multiplies the scene queries by N².
+     */
+    pixelAperture?: SimulateCapturePixelAperture;
   };
   /** Aborting cancels the running task; the promise rejects with a domain error and returns no partial image. */
   signal?: AbortSignal;
@@ -258,6 +322,14 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export type SimulateCaptureOutputFormat = "srgb-8" | "srgb-16" | "jpeg" | "png" | "dng";
 ```
 
+## SimulateCapturePixelAperture
+
+Pixel aperture (2.3): centre sampling, or the square photosite integrated with an N × N midpoint rule.
+
+```ts
+export type SimulateCapturePixelAperture = "point" | "box" | { kind: "box"; samplesPerAxis?: number };
+```
+
 ## SimulateCaptureProgress
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -293,9 +365,19 @@ export interface SimulateCaptureResult {
     /** Lossless uncompressed CFA DNG of the packed RAW when format is "dng" (`serializeNativeRawDng`); `samples` are then sRGB 8-bit. */
     dng?: Uint8Array;
   };
-  /** Packed native RAW (codes, black levels, saturation flags) as produced by the native environment RAW task. */
+  /**
+   * Packed native RAW (codes, black levels, saturation flags) as produced by the native environment RAW task. With
+   * `output.region` (2.3): the region's native sites only, with `plan` describing that raster (its active area is the
+   * region); `request.environmentRaw` and `request.siteInput` stay those of the whole frame.
+   */
   raw: NativeRawOutput;
   plan: NativeRawPlan;
+  /**
+   * 2.3, present with `output.region`: the rendered rectangle in output pixels of the whole `frameWidth` × `frameHeight`
+   * frame, and the native sites rendered for it (`nativeRect`, in the whole frame's native raster: the region, the
+   * demosaic reach on each side clipped to the raster, and its origin rounded down to the 2 × 2 CFA repeat).
+   */
+  region?: { x: number; y: number; width: number; height: number; frameWidth: number; frameHeight: number; nativeRect: { x: number; y: number; width: number; height: number } };
   /** The complete underlying request. */
   request: {
     environmentRaw: NativeEnvironmentRawInput;
@@ -330,6 +412,14 @@ export interface SimulateCaptureResult {
     /** Physical size of the framed scene plane, metres. */
     framedWidthM: number;
     framedHeightM: number;
+    /**
+     * 2.3, present with `chartSize`: the chart's physical size and surround, the fraction of the frame width and
+     * height it covers (above 1 when it is larger than the frame and cropped), the thin-lens magnification
+     * v/d (image distance over subject distance, the scale the facade's framing uses) and the chart's size on the
+     * sensor in millimetres and output pixels.
+     */
+    chart?: { widthM: number; heightM: number; surroundReflectance: number; frameWidthFraction: number; frameHeightFraction: number;
+      magnification: number; imageWidthMm: number; imageHeightMm: number; imageWidthPixels: number; imageHeightPixels: number };
     /**
      * SHA-256 of the canonical scene description, recorded as the capture source digest. Caller spectra (a
      * `spectrum` or `daylight` illuminant, chart reflectance spectra) are part of the description: tabulated
@@ -402,3 +492,18 @@ export type SimulateCaptureWhiteBalance =
   | { kelvin: number; tint?: number }
   | { channelGains: { red: number; green: number; blue: number } };
 ```
+
+## simulateIdealReference
+
+The ideal reference of a capture request (2.3): the same scene, framing, chart size, output size, region and pixel
+grid as `simulateCapture(options)` would use, rendered with no camera effects (no lens blur, diffraction, defocus,
+distortion, vignetting, anti-aliasing filter, mosaic or demosaic, noise, dark signal or motion), at the capture's
+own exposure and developed with its white balance, colour matrices, tone curve and encoding (the
+`reference.exposure` assumption). Deterministic and cheap: no RAW is simulated. Formats srgb-8, srgb-16 and png.
+The result is labelled `kind: "ideal-reference"`; it is not a capture.
+
+```ts
+export async function simulateIdealReference(options: SimulateCaptureOptions): Promise<IdealReferenceResult>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.

package/docs/api/facade-subject-framing.md

@@ -0,0 +1,72 @@
+# facade/subject-framing.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.
+
+## calculateSubjectDistanceForFraming
+
+The subject distance that fits a chart of a given physical size to the frame, with magnification, coverage and the minimum-focus check (2.3).
+
+```ts
+export function calculateSubjectDistanceForFraming(input: CalculateSubjectDistanceForFramingInput): SubjectFraming;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSubjectDistanceForFramingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateSubjectDistanceForFramingInput {
+  /** Active sensor (or simulated frame) size, mm. */
+  sensor: { widthMm: number; heightMm: number };
+  /** Physical focal length, mm. Give exactly one of this and `equivalentFocalLengthMm`. */
+  focalLengthMm?: number;
+  /** Full-frame-equivalent focal length (diagonal crop factor); a generic prime's value also reports that lens. */
+  equivalentFocalLengthMm?: number;
+  /** Chart size as for `simulateCapture` `chartSize`: heightM defaults to widthM × the sensor aspect (height / width). */
+  chart: { widthM: number; heightM?: number };
+  fit?: SubjectFramingFit;
+}
+```
+
+## SubjectFraming
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SubjectFraming {
+  /** Distance from the lens to the chart plane, metres: f·(1 + 1/m). */
+  subjectDistanceM: number;
+  /** Image size ÷ object size, f/(d − f). */
+  magnification: number;
+  /** Thin-lens image distance f·(1 + m), mm. */
+  imageDistanceMm: number;
+  focalLengthMm: number;
+  equivalentFocalLengthMm: number;
+  cropFactor35Mm: number;
+  chart: { widthM: number; heightM: number };
+  fit: SubjectFramingFit;
+  /** Plane area the frame covers at that distance, metres. */
+  framedWidthM: number;
+  framedHeightM: number;
+  /** Fraction of the frame width and height the chart covers (1 on the fitted side; above 1 means cropped). */
+  coverage: { frameWidthFraction: number; frameHeightFraction: number };
+  /** The generic prime of this equivalent focal length, when there is one. */
+  prime: GenericPrimeLens | null;
+  /** The generic prime rule max(0.10 m, f·(1 + 1/0.15)) at this focal length (the prime's own value when there is one). */
+  minimumFocusDistanceM: number;
+  /** True when the fit distance is closer than the minimum focus distance: the chart cannot be framed this way. */
+  belowMinimumFocus: boolean;
+  scientificStatus: "approximation";
+  assumptions: readonly SimulateCaptureAssumption[];
+}
+```
+
+## SubjectFramingFit
+
+How the chart fits the frame: `contain` (default; the whole chart is visible and its limiting side touches the frame), `width`, `height` or `cover` (the chart fills the frame and is cropped on its other side).
+
+```ts
+export type SubjectFramingFit = "contain" | "width" | "height" | "cover";
+```