@photivra/engine 0.2.0 → 0.5.0

package/docs/POC_API.md

@@ -50,7 +50,7 @@ Example:
 {
   "ok": true,
   "service": "photivra-engine",
-  "apiVersion": "0.17.0"
+  "apiVersion": "0.20.0"
 }
 ```
 
@@ -62,13 +62,48 @@ Requests must use `Content-Type: application/json`.
 
 All physical quantities use explicit units in their property names.
 
-API 0.17 composes projection using the selected focus plane. The response includes a `projection` block with ideal thin-lens image distance, scale relative to the infinity-focus approximation, and model provenance. Full-sensor field of view, crop field of view, object sampling, subject motion, and camera-shake projection use that same selected projection plane.
+The POC transport reports the composed simulation contract version, not the root library `ENGINE_API_VERSION`. The current composed contract is exposed as `POC_SIMULATION_API_VERSION`.
+
+POC simulation API 0.20 composes projection using the selected focus plane. The response includes a `projection` block with ideal thin-lens image distance, scale relative to the infinity-focus approximation, and model provenance. Full-sensor field of view, crop field of view, object sampling, subject motion, and camera-shake projection use that same selected projection plane.
+
+### Sensor/capture composition in POC API 0.20
+
+POC simulation API 0.20 begins composing the standalone sensor/capture foundation **additively**.
+
+The existing request remains valid. New callers may opt into staged capture geometry with a `capture` object containing:
+
+- physical `orientation`;
+- optional native `activeCaptureRect`;
+- optional oriented `outputCropRect`;
+- optional final `outputRaster`.
+
+Compatibility rules are intentionally strict:
+
+- legacy `crop.factor` remains available for existing callers;
+- when `capture` is supplied, legacy `crop.factor` must be `1` so two crop models are not silently stacked;
+- legacy top-level `subjectCrop` response semantics remain unchanged when staged capture is absent;
+- with staged capture, subject framing is reported under `capture.subjectFraming` and is applied after declared output crop/resampling;
+- equivalent-viewing CoC in staged capture is based on the final retained physical image region used for viewing, including subject framing when present; output pixel count alone does not change it.
+
+The response keeps existing full-sensor/native-vector fields intact and adds an optional `capture` block with:
+
+- resolved native/active/oriented/output geometry, including final retained physical bounds;
+- active-capture and final-output FOV, including asymmetric bounds for off-center capture/output crop;
+- physical actual focal length plus active-capture diagonal-based 35 mm equivalence;
+- explicit oriented-capture→output pixel scaling;
+- optional capture-specific subject framing with final retained physical area and effective FOV;
+- explicit native-raster, oriented-capture, and final-output motion-vector diagnostics;
+- corresponding native-raster/oriented/output camera-shake vectors when camera shake is requested.
+
+Final digital/output crop does not redefine physical focal length or active-capture 35 mm equivalence. Physical `lens.focalLengthMm` remains the optical input.
+
+Sensor architecture metadata and radiometry-readiness profiles remain standalone foundations and are not yet composed into the POC.
 
 ### Required request groups
 
 The request includes:
 
-- sensor dimensions and resolution;
+- sensor physical imaging dimensions and native effective raster;
 - focal length and aperture;
 - shutter duration and ISO;
 - focus distance;
@@ -109,9 +144,33 @@ The top-level `fieldOfView` always describes the full sensor before digital crop
 
 This remains ideal paraxial geometry, not a real-lens focus-breathing calibration.
 
-### Crop
+### Sensor and staged capture geometry
 
-`crop` reports the requested fixed crop factor, retained pixel dimensions/area, megapixels, and its effective field of view.
+The `sensor` response now includes the shared `SensorGeometryMetrics` result in addition to the backwards-compatible representative pitch fields. This exposes physical imaging-area crop factor, exact native-raster megapixels, and independent X/Y geometric sample pitch without treating sample pitch as photosite collection area.
+
+When the opt-in `capture` request is present, the response additionally exposes the staged geometry pipeline:
+
+```text
+native physical imaging area + native raster
+                ↓
+native active-capture rectangle
+                ↓
+physical camera orientation
+                ↓
+oriented active capture
+                ↓
+digital/output crop
+                ↓
+final output raster
+```
+
+Native sensor coordinates remain invariant under orientation. Active-capture FOV is calculated from the physical retained area, including off-center asymmetric angular bounds.
+
+Legacy projected-motion/camera-shake X/Y values use the existing image-plane basis (+X right, +Y up). Capture raster coordinates use +X right, +Y down. The capture diagnostics therefore expose the explicit conversion to `nativeRasterDeltaPixels` before rotating to `orientedCaptureDeltaPixels` and scaling to `outputDeltaPixels`; legacy fields remain unchanged.
+
+### Legacy crop
+
+`crop` reports the requested legacy centered crop factor, retained pixel dimensions/area, megapixels, and its effective field of view.
 
 If `subjectCrop` is requested, subject framing is composed **after** the fixed crop. The response distinguishes:
 
@@ -122,8 +181,13 @@ If `subjectCrop` is requested, subject framing is composed **after** the fixed c
 
 The framing calculation assumes the crop can be positioned around the subject; it does not validate subject position against source-image edges.
 
+### Sensor sampling
+
+The response exposes horizontal and vertical geometric sampling pitch plus their relative difference. The composed POC still uses the backwards-compatible horizontal pitch as its representative scalar for blur/sampling calculations and therefore rejects sensor geometry whose X/Y pitch differs by more than 1%. This prevents silent directional error until the composed POC becomes fully axis-aware.
+
 ### Subject/object sampling
 
+
 When physical subject/object dimensions are supplied, projected dimensions are returned in sensor millimetres and pixels using the focus-aware projection plane.
 
 These values can drive pre-authored asset/detail selection without moving projection math into a renderer.
@@ -156,9 +220,11 @@ Polygon aperture geometry does not convert the circular Airy result into a polyg
 
 ### Focus criterion
 
-For cross-format comparisons, the equivalent-viewing helper scales a caller-supplied reference CoC by sensor-diagonal ratio.
+For cross-format comparisons, the equivalent-viewing helper scales a caller-supplied reference CoC by the diagonal of the physical image region assumed to be enlarged to the final viewing size.
+
+Legacy requests continue to use the full physical sensor. In staged capture mode the target is the final physical region retained by active capture + output crop and, when requested, centered subject framing. Changing only the encoded output raster does not change this viewing criterion.
 
-That is explicitly an approximation based on equivalent final viewing assumptions; it is not a physical lens/sensor blur threshold.
+This remains explicitly a viewing approximation, not a physical lens/sensor blur threshold. An explicit caller-supplied `circleOfConfusionMm` is never changed by crop or output geometry.
 
 ### Primary-subject diagnostics
 

package/docs/PROVENANCE.md

@@ -15,6 +15,20 @@ An implementation may be based on:
 
 A paper, standard, or patent publication may explain a method without granting copyright permission to copy its expression and without granting a patent license. Independent implementation addresses source-code/prose provenance; it does not by itself resolve active third-party patent claims.
 
+## Source evidence and reuse rights
+
+Factual/source evidence keeps **origin** separate from **reuse rights**.
+
+- `sourceOrigin` identifies who originated the referenced fact or data: manufacturer, third party, or Photivra.
+- `reuseStatus` identifies how Photivra may use it: factual-reference-only, reusable-data, or Photivra-owned.
+- Reusable data requires an explicit license.
+- Photivra-owned material must originate from Photivra.
+- Manufacturer or third-party sources may be either factual-reference-only or explicitly reusable when licensing supports that use.
+
+One evidence record must not silently support unrelated facts. Scalar metadata may cite multiple evidence records, and multi-valued capabilities should carry evidence per value.
+
+Evidence provenance is not a confidence score and does not establish scientific effect by itself. Descriptive hardware facts only affect calculations when a separate documented model explicitly consumes them.
+
 ## Independent implementation
 
 When a reference explains a method but does not license its implementation or text for reuse:
@@ -82,6 +96,16 @@ Valid-range metadata describes where a model/calibration is considered applicabl
 
 When composing models, preserve uncertainty components separately unless a documented model provides a defensible combination rule. Do not imply statistical independence, add errors in quadrature, or publish a single aggregate confidence score without evidence.
 
+## Radiometry readiness evidence
+
+Radiometry readiness is a declaration/validation gate, not proof that a calibration is correct.
+
+A component labeled `calibrated` must identify its model/version, supporting evidence, and quantified uncertainty. If uncertainty cannot yet be quantified, the component may still be represented, but the overall assessment cannot become `calibrated-ready`.
+
+Data-bearing calibration artifacts are referenced by stable identifier plus SHA-256 checksum. Publicly viewable curves/tables without reuse rights must not be copied into those artifacts. Manufacturer-published factual specifications may support independently authored models, while copied calibration datasets require explicit reusable licensing or Photivra ownership.
+
+An `approximation` remains explicitly approximate even when all prerequisite categories are present. Readiness must never be used to upgrade approximation provenance into calibration provenance.
+
 ## Release gate
 
 Ambiguous licensing, unresolved material patent risk, uncertain provenance, unexplained copied material, fabricated uncertainty, undocumented uncertainty combination, or unsupported scientific claims block release until resolved.

package/docs/PSF_FOUNDATION.md

@@ -0,0 +1,133 @@
+# PSF and Pupil Foundation
+
+Photivra's PSF/pupil foundation keeps optical blur contributions **separate and explicitly contextualized** until a defensible composition model exists.
+
+Use:
+
+```ts
+import {
+  calculatePsfFoundationComponents,
+  getPsfFoundationContract
+} from "@photivra/engine";
+
+const contract = getPsfFoundationContract();
+
+const components = calculatePsfFoundationComponents({
+  focalLengthMm: 85,
+  aperture: 2.8,
+  focusDistanceM: 10,
+  subjectDistanceM: 20,
+  fieldPointMm: { x: 12, y: 8 },
+  fieldNormalizationRadiusMm: 21.6,
+  spectralBasis: {
+    kind: "monochromatic",
+    wavelengthNm: 550
+  }
+});
+```
+
+## What is implemented
+
+The current foundation evaluates two existing diagnostics in one explicit context:
+
+- **geometric defocus circle** — the existing thin-lens defocus-circle diameter;
+- **circular diffraction first-zero diameter** — the existing ideal circular-pupil Airy diagnostic.
+
+Each contribution retains the provenance of its underlying primitive.
+
+The foundation records:
+
+- physical image-plane field position;
+- normalized field radius for comparison;
+- focus and subject depth;
+- monochromatic wavelength basis;
+- ideal circular f-number-derived pupil diameter.
+
+## What is deliberately not calculated
+
+The foundation does **not** currently calculate:
+
+- a combined PSF;
+- a convolution kernel;
+- MTF;
+- one combined blur diameter;
+- a lens-sharpness score.
+
+Defocus and diffraction are independent diagnostics. A future combined PSF must document the mathematical composition method and assumptions rather than adding their diameters or scores ad hoc.
+
+## Reserved contributions
+
+The public contract reserves ownership for:
+
+- non-circular diffraction;
+- mechanical/pupil clipping;
+- field curvature;
+- field-dependent aberration/PSF structure;
+- field-dependent bokeh.
+
+A reserved contribution is not an implemented capability.
+
+## Field position
+
+Field position uses physical image-plane coordinates:
+
+- optical axis at the origin;
+- +X right;
+- +Y up;
+- millimetres.
+
+`fieldNormalizationRadiusMm` exists only to make center/mid/edge/corner comparisons reproducible. It is not a real-lens calibration or model-validity limit by itself.
+
+The current defocus and circular Airy diagnostics are field invariant. Recording field position now gives future field-dependent contributions a stable context without changing those existing calculations.
+
+## Spectral basis
+
+The current foundation accepts an explicit monochromatic wavelength because the circular Airy diagnostic is wavelength dependent.
+
+This does not create:
+
+- a spectral lens model;
+- longitudinal chromatic aberration;
+- sensor spectral response;
+- CFA/color calibration.
+
+Future wavelength-dependent PSFs must declare their basis explicitly.
+
+## Pupil boundary
+
+The current context records an ideal circular, f-number-derived pupil diameter because the existing defocus/Airy diagnostics use circular-pupil assumptions.
+
+Polygon aperture geometry is not automatically a non-circular diffraction PSF.
+
+Mechanical/pupil vignetting is also separate from illumination vignetting:
+
+- illumination vignetting changes throughput only;
+- pupil clipping can change throughput **and** PSF/bokeh shape.
+
+## Preview and reference fidelity
+
+Browser preview and higher-fidelity reference implementations may use different numerical approximations or sampling budgets.
+
+They must preserve the same:
+
+- contribution identities;
+- field/depth/spectral context;
+- pupil semantics;
+- engine-owned parameters;
+- scientific limitations.
+
+A preview approximation must not redefine the science merely because it is cheaper to render.
+
+## Test Fixture relationship
+
+Test Fixture v0.3 provides deterministic center/mid/edge/corner detail and point-highlight targets for integration regression.
+
+It does not establish:
+
+- calibrated MTF;
+- a measured real-lens PSF;
+- spectral lens behavior;
+- calibrated mechanical vignetting;
+- named-lens performance.
+
+Engine analytical/reference tests remain the scientific source of truth.

package/docs/STABILIZATION.md

@@ -26,11 +26,24 @@ Projection has two modes:
 
 When pixel pitch is supplied, the same displacement is also reported in sensor pixels.
 
+The returned X/Y shake components are expressed in the primitive's sensor/image-plane axes. `estimateCameraShakeBlur()` does not accept `CaptureOrientation` and does not rotate its vector into portrait/oriented output coordinates. A caller combining this primitive with the capture-orientation layer must explicitly transform the vector with the orientation helpers.
+
 The supplied shake profile is synthetic input. The model is not an empirical statement about how much a particular photographer shakes.
 
-### Spatial limitation
+### Spatial limitation and the separate rotation primitive
+
+`estimateCameraShakeBlur()` intentionally remains one global image-plane yaw/pitch vector for backwards compatibility with the existing stabilization-equivalent teaching model.
+
+The root engine now separately exposes `calculateCameraRotationImageMapping()`, which models field-position-dependent **pure camera rotation** for yaw/pitch/roll at arbitrary physical time from exposure start.
+
+The two APIs do not share sign semantics:
+
+- the legacy shake estimator preserves its historical direct image-plane displacement convention;
+- the spatial rotation primitive represents physical camera rotation using right-hand pitch/yaw/roll, then maps a stationary world ray through the inverse camera rotation.
+
+Do not substitute one result for the other without an explicit migration.
 
-The current result is one global image-plane yaw/pitch vector. Real camera rotation produces position-dependent optical flow away from the optical axis; that spatial variation is not yet modeled. Roll and translational camera motion are also omitted.
+The spatial primitive does not apply stabilization stops. Real IBIS/OIS behavior and translation/parallax remain separate future models.
 
 ## Equivalent stabilization stops
 
@@ -60,11 +73,11 @@ Only the public standard identifier and high-level terminology are referenced he
 
 ## Not yet modeled
 
-The current model intentionally omits:
+The legacy stabilization-equivalent model intentionally omits:
 
 - roll;
 - translational camera shake;
-- spatially varying rotational optical flow;
+- spatially varying rotational optical flow inside this compatibility API;
 - frequency-dependent shake spectra;
 - photographer-to-photographer variation;
 - shutter-button impulse;