@photivra/engine 0.2.0 → 0.5.0

package/docs/ARCHITECTURE.md

@@ -7,6 +7,7 @@ Photivra separates a reusable scientific core from optional composition and tran
 The browser-safe root package currently owns:
 
 - unit-explicit camera, sensor, lens, exposure, focus, scene, and motion contracts;
+- additive sensor-foundation contracts that separate physical imaging area from native effective image raster;
 - deterministic camera/optics/exposure/crop calculations;
 - the explicitly approximate stabilization-equivalent camera-shake model;
 - sensor signal/noise primitives;
@@ -18,6 +19,179 @@ The root package has no runtime npm dependencies. CI walks the root import graph
 
 Comparison, optimization, real-camera calibration databases, renderer effects, and full optical simulation are **not** current root-package capabilities.
 
+The sensor foundation intentionally keeps physical image-formation geometry separate from digital sampling. `SensorImagingArea` represents the photosensitive imaging dimensions used for image formation; `NativeImageRaster` represents effective image samples and does not imply one image sample equals one physical photodiode. Derived sampling pitch is geometric spacing only, not fill factor or photon-collection area.
+
+Capture geometry builds on that foundation without mutating native sensor identity:
+
+```text
+physical imaging area + native raster
+              ↓
+native active-capture rectangle
+              ↓
+physical camera orientation
+              ↓
+oriented active capture
+              ↓
+digital/output crop
+              ↓
+output raster
+```
+
+Native coordinates use a top-left origin with +X right and +Y down and remain invariant under physical camera rotation. Exact point, vector, and half-open rectangle transforms map between native and oriented capture coordinates for 0°/90°/180°/270° rotations. This keeps later CFA phase, rolling-readout direction, motion-vector transforms, and camera-shake transforms anchored to one stable sensor coordinate system. Display/file transforms remain separate from physical capture orientation.
+
+Active capture retains its physical bounds and center offset relative to the optical axis. Off-center crops therefore use asymmetric angular bounds instead of being silently recentered. Output raster resampling must preserve the output-crop aspect ratio; implicit geometric stretching is rejected.
+
+Equivalent focal length is also layered on top of physical capture geometry rather than stored as lens identity. The engine keeps physical `focalLengthMm` authoritative and derives diagonal-based 35 mm equivalence from the active physical capture area. Focus distance and final digital/output crop do not redefine this conventional capture-equivalent quantity.
+
+Sensor architecture is a separate descriptive layer. Illumination (FSI/BSI), integration/stacking, readout capabilities, and color-sampling family are independent evidence-backed facts. Their presence alone has no image-quality effect in the engine. Evidence origin is modeled independently from reuse rights, scalar facts may cite multiple evidence records, and multi-valued capabilities carry evidence per value. Omitted facts remain unknown rather than being inferred. Capture-mode semantics, readout timing, reconstruction, and calibrated radiometry consume these facts only through later explicit models.
+
+
+## Image-formation ownership and ordering
+
+The root package exports `getImageFormationContract()` as the canonical semantic map for current and future image-formation work.
+
+It defines five scientific domains:
+
+1. scene/ray geometry;
+2. lens mapping plus pupil/throughput;
+3. field- and wavelength-dependent PSF;
+4. time-dependent exposure/readout;
+5. sensor sampling through orientation/output/display.
+
+The graph is a **dependency/ownership graph**, not a literal renderer filter list. Hard upstream dependencies are acyclic; explicit couplings record interactions that must not be split into scientifically independent post-effects.
+
+Important consequences:
+
+- focus breathing is projection/lens mapping;
+- lateral CA is wavelength/channel-dependent field mapping;
+- illumination vignetting is throughput-only;
+- mechanical/pupil vignetting can affect both throughput and PSF/bokeh;
+- diffraction belongs to the pupil/PSF domain;
+- camera rotation should be time-parameterized so global and rolling readout consume one motion model;
+- exposure duration and readout timing remain independent;
+- future sensor ordering is reserved from optical stack/CFA sampling through charge/noise/ADC/reconstruction before oriented/output transforms.
+
+Renderer implementations may optimize or approximate only when they preserve the engine-owned semantics. Geometric warps use inverse destination-to-source sampling, premultiplied alpha, and stable depth/occlusion order.
+
+See `docs/IMAGE_FORMATION.md`.
+
+## Radiometry readiness boundary
+
+Radiometry prerequisites are represented separately from the composed POC and from low-level signal/noise primitives. `parseRadiometryReadinessProfile()` validates declared scene spectral radiance, optical transmission, pupil/vignetting behavior, photosite collection-area semantics, exposure integration, and sensor response together with evidence and uncertainty declarations.
+
+`assessRadiometryReadiness()` distinguishes:
+
+- `not-ready`: one or more required components are absent;
+- `approximate-only`: all required components exist, but one or more are approximate or lack quantified uncertainty;
+- `calibrated-ready`: every required component is declared calibrated and carries quantified uncertainty.
+
+These states describe the declared prerequisite package only. They do **not** prove that cited evidence is scientifically correct, do not derive photon counts, and never enable photon/noise output in `simulatePocCamera()` automatically.
+
+Geometric sample pitch is explicitly insufficient as a photosite photon-collection area. A radiometric profile must supply either an effective collection area or a geometric cell area plus explicit fill factor. Calibration artifacts are identified by stable IDs and SHA-256 checksums rather than being embedded implicitly in geometry metadata.
+
+## Composition boundary at POC API 0.20
+
+The sensor/capture/architecture/radiometry modules are public root-engine foundations. POC simulation API 0.20 composes the geometry foundation through final output/viewing semantics while keeping older callers valid.
+
+The POC now composes:
+
+- physical sensor width/height plus native effective raster dimensions;
+- shared sensor-geometry metrics, including physical crop factor, raster-derived megapixels, and X/Y geometric sampling pitch;
+- the legacy same-aspect centered `crop.factor` path for compatibility;
+- an opt-in staged `capture` path for physical orientation, native active-capture rectangle, oriented digital/output crop, and final output raster;
+- active-capture and final-output FOV, including asymmetric bounds for off-center physical or digital crop;
+- diagonal-based 35 mm-equivalent focal length derived from active physical capture while physical focal length remains authoritative;
+- capture-mode equivalent-viewing CoC based on the final retained physical viewing area rather than output pixel count;
+- orientation-aware post-output subject framing with explicit retained physical bounds/FOV;
+- additive image-plane→native-raster conversion plus oriented-capture and final-output motion/camera-shake vector diagnostics;
+- explicit oriented-capture→output pixel scale for renderer sampling/blur conversion;
+- one representative horizontal-pitch path for existing blur/sampling calculations, with a fail-closed guard for materially non-square sampling;
+- the established projection, DOF/defocus, diffraction, motion, exposure, aperture-shape, and camera-shake models.
+
+Compatibility boundaries remain explicit:
+
+- staged capture geometry cannot be combined with legacy `crop.factor` other than `1`;
+- legacy `subjectCrop` response remains for legacy mode, while staged capture reports post-output framing under `capture.subjectFraming`;
+- explicit physical CoC remains caller-owned; equivalent-viewing CoC is a separately labeled approximation based on final retained physical viewing area;
+- existing legacy motion/camera-shake fields retain their image-plane (+X right, +Y up) meaning rather than being reinterpreted; capture diagnostics explicitly convert to native raster (+Y down) before orientation.
+
+The POC still does **not** consume:
+
+- `SensorArchitectureProfile`;
+- `RadiometryReadinessProfile` or calibrated photon/noise output.
+
+That separation is deliberate. Further foundation APIs should remain independently testable and only enter the POC through explicit contract/version changes and migration review.
+
+## PSF/pupil foundation
+
+The field/wavelength PSF domain now has an explicit public foundation through `getPsfFoundationContract()` and `calculatePsfFoundationComponents()`.
+
+The foundation provides:
+- stable contribution IDs and implementation/reservation status;
+- field/depth/spectral/pupil context;
+- existing geometric-defocus and circular-Airy diagnostics with their original provenance;
+- an explicit `not-composed` policy.
+
+It does not invent a combined PSF, MTF, or lens-sharpness score.
+
+Future non-circular diffraction, mechanical pupil clipping, field curvature, field-dependent aberration, and bokeh models should extend this contribution/context model rather than replacing existing defocus/diffraction APIs.
+
+Preview and reference render paths may use different computational fidelity, but must preserve contribution identities and engine-owned semantics.
+
+## Standalone illumination-throughput foundation
+
+The lens-field/pupil domain now includes generic illumination vignetting as field-dependent linear throughput.
+
+The engine owns:
+- physical field-radius normalization;
+- the declared operating envelope;
+- full-envelope extrema validation;
+- the linear throughput factor and stop-loss diagnostic.
+
+Renderer backends consume that factor in a linear working domain. They must not reinterpret this stage as gamma-space darkening, coordinate warp, or pupil clipping.
+
+Mechanical/pupil vignetting remains part of future pupil/PSF work because it can change both throughput and bokeh/PSF shape.
+
+## Standalone lateral-CA field-mapping foundation
+
+The lens-field domain also exposes generic red/green/blue channel-dependent radial mapping.
+
+The green channel is the reference/common geometric field map. A shared base distortion is combined with explicit red/blue coefficient offsets, so ordinary distortion and chromatic separation remain semantically distinct without requiring two renderer warps.
+
+The engine owns both forward per-channel coordinates and inverse per-channel destination-to-source sampling. Backends should not implement lateral CA as arbitrary finished-image channel offsets or apply the same base distortion twice.
+
+This is deliberately not a spectral/CFA/colorimetric model. Wavelength-dependent optics, longitudinal CA, wavelength-dependent PSFs, and calibrated lens profiles remain separate future work.
+
+## Standalone radial field-mapping foundation
+
+The lens-field/pupil domain now also exposes generic radial distortion through paired forward and inverse mappings.
+
+The engine, rather than a renderer backend, owns:
+- coefficient normalization against a declared physical image-plane radius;
+- the valid maximum normalized field radius;
+- strict monotonicity/invertibility checks;
+- deterministic inverse destination-to-source mapping.
+
+This prevents WebGPU/WebGL2 implementations from inventing separate distortion equations.
+
+The radial-distortion slice is optical-axis-centered only. Tangential/decentered distortion and calibrated lens profiles remain future work. Lateral chromatic aberration and illumination vignetting are implemented as separate standalone foundations and are not part of the radial-distortion model.
+
+## Standalone focus-breathing foundation
+
+The lens-field/pupil domain now has a partial standalone foundation through `calculateFocusBreathingProjection()` and `calculateFocusBreathingFieldOfView()`.
+
+These functions apply an explicit caller-declared scale to the ideal thin-lens projection for one focus state. They do not infer a breathing curve, identify a real lens, or mutate physical focal length.
+
+The model remains standalone and is not composed into `simulatePocCamera()` yet. Generic radial distortion, lateral chromatic aberration, and illumination vignetting are separately implemented standalone foundations and must not be silently coupled into focus breathing. Mechanical/pupil vignetting, pupil/PSF coupling, and calibrated lens profiles remain future work.
+
+## Standalone spatial camera-rotation foundation
+
+The root engine exposes `calculateCameraRotationImageMapping()` as a low-level implementation of the image-formation contract's time-parameterized camera-rotation placement.
+
+It is intentionally **not** composed into `simulatePocCamera()` yet. The existing POC and `estimateCameraShakeBlur()` retain their backwards-compatible global shake approximation.
+
+The new primitive provides deterministic yaw/pitch/roll rotation geometry only. It does not model camera translation, stabilization control laws, rolling-readout scheduling, or scene-depth-dependent parallax.
+
 ## Repository-local Node POC transport
 
 The repository contains a minimal Node-only HTTP transport under `src/api` for contributor integration testing.
@@ -30,7 +204,7 @@ This transport is intentionally **not** part of the public `@photivra/engine` pa
 
 Future capabilities should compose onto the scientific core rather than silently widening unrelated models. Examples include:
 
-- more complete camera-rotation and translation models;
+- composed use of the standalone spatial camera-rotation model plus future depth-aware camera translation;
 - panning and rolling/global shutter;
 - flash;
 - spectral/color modeling;
@@ -49,3 +223,7 @@ Capabilities should remain discoverable and explicitly versioned rather than bei
 This repository contains the Apache-2.0 scientific/business-logic package together with its tests, documentation, schemas, validation, and contributor tooling.
 
 The published npm package intentionally exposes only the browser-safe scientific root surface; repository-local development tooling such as the Node POC transport remains outside the published package.
+
+## Version surfaces
+
+The root library contract and the composed POC simulation contract are versioned independently. `ENGINE_API_VERSION` describes the root browser-safe engine surface. `POC_SIMULATION_API_VERSION` describes the request/response behavior of `simulatePocCamera()` and the repository-local POC HTTP transport. Package versioning remains separate from both.

package/docs/IMAGE_FORMATION.md

@@ -0,0 +1,151 @@
+# Image-Formation Contract
+
+Photivra's image-formation contract defines **scientific ownership, coordinate semantics, and dependency/coupling boundaries** for current and future camera effects.
+
+It is not a claim that every stage is implemented, and it is not a requirement that renderers execute one literal serial filter chain.
+
+Use:
+
+```ts
+import { getImageFormationContract } from "@photivra/engine";
+
+const contract = getImageFormationContract();
+```
+
+## Five scientific domains
+
+The contract groups image formation into five domains:
+
+1. **scene / ray geometry**
+2. **lens mapping + pupil / throughput**
+3. **field- and wavelength-dependent PSF**
+4. **time-dependent exposure / readout**
+5. **native sensor sampling -> orientation -> output / display**
+
+These are scientific ownership domains. Some effects couple more than one domain.
+
+Examples:
+
+- focus breathing changes projection/magnification and therefore couples lens mapping to scene projection;
+- lateral chromatic aberration is wavelength/channel-dependent field mapping and may share wavelength basis with the PSF model;
+- illumination vignetting is throughput-only;
+- mechanical/pupil vignetting can change both throughput and PSF/bokeh shape;
+- diffraction consumes the effective pupil and belongs to the PSF domain;
+- rolling readout couples native sensor timing to temporal integration;
+- camera rotation should be evaluable as a function of physical exposure time so global and rolling readout can consume the same motion model.
+
+## Coordinate spaces
+
+The contract explicitly distinguishes:
+
+- `scene-metric` — scene/world metric coordinates;
+- `image-plane-metric` — optical-axis origin, +X right, +Y up, millimetres;
+- `native-sensor-physical` — optical-axis origin, +X right, +Y down, millimetres;
+- `native-raster` — top-left origin, +X right, +Y down, pixels;
+- `oriented-capture-raster` — explicit physical-orientation transform of native raster coordinates;
+- `output-raster` — digital crop/resampling result;
+- `display` — consumer/display coordinates, which are never authoritative camera-science coordinates.
+
+Native sensor/raster coordinates remain invariant under physical camera orientation.
+
+Use `mapOrientedPhysicalUvToImagePlanePoint()` and
+`mapImagePlanePointToOrientedPhysicalUv()` when a renderer or integration
+boundary must cross between a normalized oriented physical raster region and
+the pre-orientation `image-plane-metric` space. These transforms explicitly
+undo/apply physical orientation and convert the capture contract's physical
++Y-down basis to/from the optical image plane's +Y-up basis. They do not apply
+projection, distortion, crop, or lens equations, and asymmetric physical bounds
+remain asymmetric.
+
+## Partial ordering and coupling
+
+`requiredUpstreamStages` defines hard scientific dependencies.
+
+`coupledStages` identifies interactions that must not be treated as independent post-processes.
+
+The required-dependency graph is acyclic. Coupling may be bidirectional because it describes shared scientific state rather than execution order.
+
+An implementation may combine stages for performance only when the combination is mathematically equivalent and the public stage/effect semantics remain intact.
+
+## PSF contribution foundation
+
+The `field-wavelength-psf` stage has a dedicated public foundation documented in [PSF and Pupil Foundation](PSF_FOUNDATION.md).
+
+Current implementation:
+- geometric defocus-circle diagnostic;
+- ideal circular-pupil Airy first-zero diagnostic;
+- explicit field/depth/wavelength/pupil context.
+
+Reserved contributions:
+- non-circular diffraction;
+- mechanical pupil clipping;
+- field curvature;
+- field-dependent aberration;
+- field-dependent bokeh.
+
+No combined PSF is currently calculated.
+
+## Temporal basis
+
+Physical time is measured in **seconds from exposure start**.
+
+A normalized `[0,1]` shutter parameter may be derived for an algorithm, but it is not the authoritative time coordinate.
+
+Exposure duration and sensor readout timing are independent:
+
+- global readout does not mean zero motion blur;
+- rolling readout changes when different native sensor locations are sampled/integrated;
+- native readout direction remains defined in native sensor coordinates even when the camera is physically rotated.
+
+This allows later rolling-shutter work to consume the same time-parameterized camera-motion model used for global exposure.
+
+## Renderer semantics
+
+Renderer implementations may use a bounded real-time preview approximation or a higher-fidelity deterministic reference evaluation, but both must consume the same engine-owned scientific contract.
+
+For geometric warps:
+
+- destination samples are inverse-mapped to source locations;
+- premultiplied-alpha semantics are preserved;
+- scene depth/occlusion order is preserved across warps;
+- renderer backend choice may change implementation/fidelity, not model semantics.
+
+## Reserved sensor ordering
+
+The contract reserves a future sensor path without claiming it is implemented:
+
+```text
+optical PSF
+  -> sensor optical stack (OLPF / cover glass / microlens)
+  -> photosite / CFA sampling
+  -> photon / charge statistics
+  -> electronic read noise / conversion
+  -> ADC / quantization
+  -> reconstruction (demosaic / remosaic / capture-mode combination)
+  -> physical orientation transform
+  -> output crop / resampling
+  -> display processing
+```
+
+Temporal exposure/readout couples into the photosite/charge stages rather than acting as an unrelated display blur.
+
+## Current implementation status
+
+Each stage is labeled:
+
+- `existing-foundation` — the root engine already contains the relevant foundation;
+- `partial-foundation` — some low-level science exists, but the full stage contract is not implemented; spatial camera rotation in the temporal domain plus declared-scale focus breathing, radial distortion, RGB-channel lateral CA, and illumination throughput in the lens-field domain are current examples;
+- `reserved-contract` — ordering/ownership is reserved for future work only.
+
+Do not infer capabilities from a stage merely because it is present in the contract.
+
+## Test Fixture relationship
+
+The private Test Fixture may provide deterministic browser regression targets, but it is not the scientific source of truth for the open engine.
+
+Engine analytical/invariant tests establish model correctness. Test Fixture images provide secondary integration and renderer evidence.
+
+In particular:
+
+- the LDR/sRGB optics target may verify deterministic field/channel mapping behavior;
+- it does not establish spectral lens calibration, MTF, RAW/CFA truth, HDR radiometry, or real-lens performance.

package/docs/MOTION_AND_SIGNAL.md

@@ -21,10 +21,49 @@ Projected displacement therefore depends on:
 - object velocity;
 - optional sensor pixel pitch for pixel-domain reporting.
 
+The low-level motion primitive still accepts one scalar pixel pitch. The newer sensor-geometry API preserves independent X/Y geometric pitch. The composed POC therefore fails closed when X/Y pitch differs by more than 1% rather than silently applying horizontal pitch to materially different vertical sampling.
+
 The model can represent a representative point moving laterally and/or along the optical axis. It does **not** yet model an extended object's changing apparent scale across the exposure, rotational subject motion, acceleration, deformation, or occlusion changes. A large object moving significantly in depth can therefore exhibit real scale blur that this point-displacement primitive does not describe.
 
 Camera motion is not folded into subject motion. Camera shake is modeled separately by `estimateCameraShakeBlur()`; panning detection/intent is not currently modeled.
 
+The returned `deltaXmm`/`deltaYmm` components are legacy camera/image-plane components: +X right and +Y up. They are preserved for compatibility.
+
+Capture raster coordinates use +X right and +Y down. POC API 0.19 therefore converts a legacy image-plane vector to native raster axes as `{ x, y: -y }` before applying the native↔oriented rotation helper. The additive capture diagnostics expose `nativeRasterDeltaPixels`, `orientedCaptureDeltaPixels`, and `outputDeltaPixels`; the legacy motion fields are not reinterpreted.
+
+## Spatial camera rotation
+
+`calculateCameraRotationImageMapping()` now provides the rotation-only primitive reserved by the image-formation contract.
+
+The function:
+
+- accepts one image-plane point at exposure start;
+- uses physical time in seconds from exposure start;
+- accepts constant pitch/yaw/roll angular velocity resolved in the camera axes at exposure start;
+- integrates the simultaneous angular velocity as one axis-angle vector;
+- transforms the stationary world ray by the inverse camera rotation;
+- returns field-position-dependent image-plane displacement;
+- optionally reports axis-aware geometric sample displacement.
+
+For pure yaw/pitch, image displacement varies with field position because the rectilinear projection denominator changes away from the optical axis. Pure roll leaves the optical-axis center fixed while rotating off-axis points.
+
+This is camera **rotation only**. Translation is excluded because parallax requires scene depth.
+
+The returned image-plane/sample components use +X right and +Y up. Native raster remains +X right/+Y down and requires the existing explicit coordinate transform at capture composition boundaries.
+
+## Temporal image-formation basis
+
+The image-formation contract defines physical time in **seconds from exposure start**.
+
+A future spatial camera-rotation model should be evaluable at arbitrary physical times rather than returning only one finished full-frame displacement. That allows global exposure and later rolling readout to consume the same camera-motion model.
+
+Exposure duration and sensor readout timing are independent concepts:
+
+- global readout can still contain subject/camera motion blur;
+- rolling readout changes the exposure/readout schedule across native sensor locations;
+- physical orientation does not redefine native sensor scan direction;
+- depth-dependent camera translation is not part of the initial rotational-flow model because parallax depends on scene depth.
+
 ## Exposure relations
 
 `calculateExposureValue100()` implements EV100 from aperture and shutter duration.
@@ -48,7 +87,19 @@ These functions do **not** derive incident photon counts from scene imagery.
 
 They do not currently model dark current, fixed-pattern noise, PRNU/DSNU, ADC quantization, clipping/full-well behavior, CFA/demosaic, downstream denoising, or a particular commercial sensor.
 
-The composed POC intentionally does not expose photon/noise output until there is a defensible calibrated radiometric path including the necessary scene, spectral, optical-transmission, pixel-area, quantum-efficiency, and calibration assumptions.
+The composed POC intentionally does not expose photon/noise output.
+
+The root package now includes a **radiometry-readiness gate** that validates whether a declared prerequisite package contains scene spectral radiance, optical transmission, pupil/vignetting behavior, explicit photosite collection-area semantics, exposure integration, sensor response, evidence, and uncertainty declarations.
+
+Readiness is deliberately separate from signal/noise calculation:
+
+- `not-ready`: prerequisite categories are missing;
+- `approximate-only`: all categories exist, but at least one is approximate or has unquantified uncertainty;
+- `calibrated-ready`: all categories are declared calibrated with quantified uncertainty.
+
+These states describe the declared prerequisite package only. They do not prove a calibration is correct, do not calculate incident photons, and never enable photon/noise output in `simulatePocCamera()` automatically.
+
+Geometric pixel/sample pitch is not accepted as photon-collection area. An explicit effective collection area or geometric cell area plus fill factor is required.
 
 ## Provenance
 

package/docs/PHYSICS_FOUNDATION.md

@@ -14,14 +14,71 @@ where `d` is the relevant sensor dimension and `v` is the projection/image-plane
 
 When no focus distance is supplied, `v = f` is the infinity-focus/pinhole compatibility approximation. When focus distance is supplied, `v` is the ideal Gaussian thin-lens image distance.
 
-### Pixel pitch and crop
+For a centered sensor interval, the usual symmetric form is sufficient. For an off-center sensor interval, Photivra uses signed sensor-plane bounds relative to the optical axis:
 
-Pixel pitch is derived directly from active sensor width and horizontal active pixel count.
+`FOV = atan(x_max / v) - atan(x_min / v)`
 
-Centered crop dimensions are derived from a linear crop factor while preserving the source aspect ratio, subject to integer pixel flooring.
+This preserves asymmetric left/right or top/bottom angular limits instead of pretending every active crop is centered.
+
+### Sensor geometry, sampling, capture, and crop
+
+Photivra separates physical image-formation geometry from digital sampling.
+
+`SensorImagingArea` represents the physical photosensitive area used for image formation. It is not a sensor package/die dimension.
+
+`NativeImageRaster` represents the effective native image-sampling grid. It does not imply that one output/image sample corresponds one-to-one with one physical photodiode. Generic active/output rasters use `RasterDimensions`.
+
+Geometric sample pitch is derived independently on each axis:
+
+- `pitchX = imagingWidth / nativePixelWidth`;
+- `pitchY = imagingHeight / nativePixelHeight`.
+
+These pitches are geometric sample spacing only. They are not fill factor, effective collection area, or photon-collection area.
+
+The capture pipeline is staged:
+
+```text
+physical imaging area + native raster
+              ↓
+native active-capture rectangle
+              ↓
+physical camera orientation
+              ↓
+oriented active capture
+              ↓
+digital/output crop
+              ↓
+output raster
+```
+
+Native raster coordinates use a top-left origin with +X right and +Y down. Integer rectangles are half-open. Physical camera rotation does not redefine the native coordinate system; Photivra transforms points, vectors, and rectangles explicitly between native and oriented coordinates.
+
+For the generic sensor model, active physical dimensions and optical-axis offset are derived by assuming the native sampling grid uniformly spans the declared physical imaging area. This assumption is recorded because a future calibrated camera profile may need explicit physical active-area data instead.
+
+An off-center active rectangle changes both retained physical extent and angular position relative to the optical axis. It must therefore use asymmetric angular bounds rather than a centered FOV formula.
+
+For an off-center rectangular active area, the two opposite-corner diagonal angular spans need not be equal. `calculateActiveCaptureFieldOfView()` reports both and uses the larger span for its compatibility `diagonalDegrees` summary.
+
+Output crop/resampling is digital geometry. It does not mutate physical sensor identity or active-capture geometry. Output raster aspect ratio must remain consistent with the selected output crop; implicit geometric stretching is rejected.
+
+Centered crop dimensions are derived from a linear crop factor while preserving source aspect ratio, subject to integer pixel flooring.
 
 Subject-height framing crop computes the additional same-aspect crop needed to target a requested subject-height fraction. It assumes the crop can be positioned around the subject and does not check subject position against image edges.
 
+### Crop factor and 35 mm-equivalent focal length
+
+Physical crop factor is diagonal-based relative to a 36 × 24 mm reference frame:
+
+`cropFactor = diagonal_35mm / activeCaptureDiagonal`
+
+Conventional 35 mm-equivalent focal length is:
+
+`equivalentFocalLength = actualFocalLength × cropFactor`
+
+The actual focal length remains the optical focal length. Equivalent focal length is a derived framing convention; it does not replace physical focal length in projection or depth-of-field calculations.
+
+Photivra bases equivalence on the active physical capture area, not later digital/output crop. Physical orientation leaves the active diagonal unchanged and therefore does not change diagonal-based equivalent focal length. Different aspect ratios can still produce different horizontal/vertical FOV even when the single diagonal-equivalent number is the same.
+
 ### Projection, focus extension, object size, and motion
 
 Field of view, projected fronto-parallel object size, projected representative-point subject motion, and camera-shake projection support two explicit projection modes:
@@ -37,18 +94,110 @@ The focus-aware model improves internal consistency with thin-lens DOF/defocus c
 
 Projected subject motion is a representative-point displacement model with constant linear world velocity. It does not yet describe scale blur of an extended object whose magnification changes materially during the exposure.
 
+### Generic illumination vignetting
+
+The engine exposes a generic rotationally symmetric **relative linear illumination** model:
+
+```text
+T(rho) = 1 + r2*rho² + r4*rho⁴ + r6*rho⁶
+```
+
+where `rho` is ideal image-plane field radius divided by the caller-declared physical normalization radius.
+
+The optical axis is normalized to `T(0) = 1`.
+
+The declared `maximumNormalizedRadius` is a scientific operating envelope. Photivra evaluates the polynomial endpoints and all real internal extrema over the full interval and rejects profiles that:
+
+- produce zero/negative throughput; or
+- exceed the center-normalized throughput of 1.
+
+The result is a linear-light multiplicative attenuation plus equivalent positive stop loss.
+
+This slice is **not mechanical/pupil vignetting**. It does not clip the pupil or change bokeh/PSF shape. It also does not claim calibrated radiometry or named-lens behavior.
+
+### Generic lateral chromatic aberration
+
+The standalone lateral-CA foundation uses the green channel as the reference field mapping.
+
+A shared base radial-distortion profile defines the common geometric lens mapping. Red and blue coefficient offsets are added to that base before each channel is mapped:
+
+```text
+green coefficients = base
+red coefficients   = base + red offset
+blue coefficients  = base + blue offset
+```
+
+This keeps ordinary geometric distortion and lateral chromatic separation distinct while allowing one renderer pass to consume the combined per-channel mapping.
+
+The model deliberately does **not** represent CA as finished-image RGB blur. Forward mapping reports per-channel field coordinates and vector separation; inverse mapping reports the per-channel ideal source coordinate required for one distorted destination.
+
+All combined channel profiles share one physical normalization radius and operating envelope and must remain individually invertible.
+
+The RGB labels are representative renderer channels only. The model does not define wavelengths, sensor CFA responses, longitudinal chromatic aberration, wavelength-dependent PSFs, or calibrated real-lens color behavior.
+
+### Generic radial distortion
+
+The engine includes a standalone rotationally symmetric radial field-mapping approximation:
+
+```text
+p_distorted = p_ideal × (1 + k1 r² + k2 r⁴ + k3 r⁶)
+```
+
+where `r` is image-plane radius divided by a caller-declared physical normalization radius.
+
+The declared `maximumNormalizedRadius` is part of the scientific contract. Photivra checks the derivative of the radial mapping over that interval and rejects profiles that are not strictly one-to-one. This makes deterministic inverse destination-to-source sampling well-defined.
+
+The model is centered on the optical axis and does not yet include tangential/decentering terms. Coefficients are generic inputs, not real-lens calibration data.
+
+### Declared-scale focus breathing
+
+The root engine exposes a generic focus-breathing projection approximation.
+
+For one selected focus state:
+
+```text
+effective projection distance
+  = ideal thin-lens image distance × caller-declared breathing projection scale
+```
+
+Scale `1` exactly preserves the existing thin-lens projection.
+
+The model intentionally does not infer a focus-breathing curve. It represents focus-dependent framing/magnification only when the caller supplies the scale for that state. Physical focal length remains unchanged.
+
+This simplified scale does not model principal-plane movement, pupil magnification, distortion, aberrations, or a named commercial lens. Those require separate models and, for calibrated profiles, defensible provenance.
+
 ### Thin-lens focus and depth of field
 
 The geometric depth-of-field model uses the conventional hyperfocal/near/far equations with a caller-supplied acceptable circle of confusion.
 
 The circle-of-confusion criterion is a viewing/acceptability input, not a physical sensor threshold. The optional equivalent-viewing helper scales a caller-supplied reference criterion by sensor-diagonal ratio and is explicitly labeled an approximation.
 
+In composed POC capture mode, the equivalent-viewing helper uses the final retained physical image region that will be enlarged to the assumed final viewing size. Active capture, digital output crop, and centered subject framing can therefore change the viewing criterion; output pixel resolution alone cannot. This changes only the viewing/acceptability convention, not the physical optical blur. An explicit caller-supplied `circleOfConfusionMm` is never rescaled.
+
 The model is not a macro calibration model and does not include diffraction, pupil magnification, aberrations, focus breathing, or lens-specific principal-plane behavior in its DOF criterion.
 
 ### Defocus circle
 
 Defocus is calculated geometrically by comparing the selected sensor plane for the focus distance with the ideal image plane for the subject distance and projecting an ideal circular entrance-pupil cone to the sensor.
 
+### PSF/pupil foundation
+
+The engine now exposes a PSF/pupil foundation that evaluates existing geometric defocus and circular diffraction diagnostics in one explicit context while keeping the numerical contributions separate.
+
+The context declares:
+
+- physical image-plane field position;
+- a comparison-only field normalization radius;
+- focus and subject depth;
+- monochromatic wavelength basis;
+- ideal circular f-number-derived pupil size.
+
+The current foundation does **not** calculate a combined point-spread function or MTF. Defocus-circle diameter and Airy first-zero diameter are not added together or collapsed into one sharpness value.
+
+Reserved future contributions include non-circular diffraction, mechanical pupil clipping, field curvature, field-dependent aberration structure, and field-dependent bokeh.
+
+Illumination vignetting remains outside the PSF contribution list because it is currently modeled as throughput-only.
+
 ### Diffraction
 
 For an ideal circular aperture, first-zero Airy diameter is:
@@ -79,6 +228,44 @@ The current model returns one global image-plane vector. It does not compute the
 
 Equivalent stabilization stops attenuate angular displacement by `2^-stops`; that attenuation is explicitly an educational approximation rather than a real IBIS/OIS or CIPA performance model.
 
+### Radiometry readiness boundary
+
+Absolute scene luminance or relative exposure alone is not enough to derive a defensible photon count.
+
+Before any future composed photon simulation, Photivra requires an explicit prerequisite package covering:
+
+- scene spectral radiance or a documented spectral approximation;
+- optical transmission;
+- pupil/vignetting behavior;
+- photosite collection-area semantics;
+- exposure integration;
+- sensor spectral response / quantum efficiency;
+- evidence and uncertainty/limitation metadata for each component.
+
+`assessRadiometryReadiness()` can classify a declared package as `not-ready`, `approximate-only`, or `calibrated-ready`. This classification validates the declared model/evidence structure; it does not prove that the calibration is scientifically correct and does not itself calculate photons.
+
+Geometric sample pitch is intentionally insufficient as a collection-area model. A profile must provide either an effective collection area or geometric cell area plus explicit fill factor.
+
+Approximate inputs remain approximate even when every prerequisite category is present. A calibrated-ready declaration requires calibrated components with quantified uncertainty.
+
+The composed POC continues to emit no photon/photoelectron/SNR output from scene settings. Low-level `calculatePhotoelectrons()` remains a separate primitive for callers that already possess a defensible incident-photon count and QE.
+
+## Image-formation domain boundary
+
+Future optical and sensor models must follow `getImageFormationContract()`.
+
+The contract intentionally avoids describing all image formation as independent serial post-processing. Some quantities are coupled:
+
+- focus-dependent projection and lens mapping;
+- wavelength-dependent field mapping and PSF basis;
+- pupil clipping, throughput, and bokeh/PSF shape;
+- time-varying scene/camera mapping and sensor readout schedule;
+- native sensor sampling and reconstruction.
+
+Current analytical primitives remain valid and separately named. Adding a broader stage must not silently reinterpret existing focal length, defocus, diffraction, motion, crop, or sensor-sampling outputs.
+
+Reserved sensor stages in the contract are ordering placeholders only; they do not establish OLPF, CFA, photon, ADC, or reconstruction capabilities.
+
 ## Source provenance
 
 These implementations were written independently from established mathematical/physical relations. No third-party source code, calibration dataset, table, or model weight is incorporated by these scientific modules.