@photivra/engine 2.4.1 → 2.5.0

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

@@ -2,6 +2,39 @@
 
 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.
 
+## calculateChartFraming
+
+How much of the frame a chart of a given physical size covers at any subject distance (2.5): magnification, framed plane size,
+coverage fractions (above 1 when cropped), the chart's image size and the minimum-focus check. The same thin-lens framing as
+`simulateCapture` (`scene.framing`, `result.scene.chart`) and `calculateSubjectDistanceForFraming`.
+
+```ts
+export function calculateChartFraming(input: CalculateChartFramingInput): ChartFraming;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateChartFramingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateChartFramingInput {
+  /** Active sensor (or simulated frame) size, mm: for `simulateCapture`, output width × height × pixel pitch. */
+  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 (as `lens.prime`). */
+  equivalentFocalLengthMm?: number;
+  /** Chart size as for `simulateCapture` `chartSize`: heightM defaults to widthM × the sensor aspect (height / width). */
+  chart: { widthM: number; heightM?: number };
+  /** Distance from the lens to the chart plane, metres; more than the focal length. */
+  subjectDistanceM: number;
+  /** Focus distance, metres (as `lens.focusDistanceM`); default the subject distance. More than the focal length. */
+  focusDistanceM?: number;
+}
+```
+
 ## 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).
@@ -30,6 +63,40 @@ export interface CalculateSubjectDistanceForFramingInput {
 }
 ```
 
+## ChartFraming
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ChartFraming {
+  subjectDistanceM: number;
+  focusDistanceM: number;
+  /** Thin-lens image distance at the focus distance, f·s/(s − f), mm. */
+  imageDistanceMm: number;
+  /** Image size ÷ object size on the chart plane, v/d: f/(d − f) when focused on the chart. */
+  magnification: number;
+  focalLengthMm: number;
+  equivalentFocalLengthMm: number;
+  cropFactor35Mm: number;
+  chart: { widthM: number; heightM: number };
+  /** Plane area the frame covers at the subject distance, metres: sensor side ÷ magnification. */
+  framedWidthM: number;
+  framedHeightM: number;
+  /** Fraction of the frame width and height the chart covers; above 1 means the chart is larger than the frame and cropped. */
+  coverage: { frameWidthFraction: number; frameHeightFraction: number };
+  /** The chart's image on the sensor, mm. */
+  chartImageMm: { width: number; height: 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 subject or focus distance is closer than the minimum focus distance (`simulateCapture` with `lens.prime` rejects it). */
+  belowMinimumFocus: boolean;
+  scientificStatus: "approximation";
+  assumptions: readonly SimulateCaptureAssumption[];
+}
+```
+
 ## SubjectFraming
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.

package/docs/api/optics-diffraction-psf-profile.md

@@ -71,7 +71,14 @@ export interface DiffractionLimitedPsfProfile {
   wavelengths: readonly DiffractionLimitedPsfWavelength[];
   /** Largest truncated energy over the wavelengths. */
   maximumTruncatedEnergyFraction: number;
-  quadrature: { method: "polar-frequency-domain-trapezoid-gauss-legendre"; maximumRadialNodes: number; maximumAngularNodes: number };
+  /**
+   * How the cells were integrated. 2.5: wavelengths with β = p·f_c ≥ 192 (cells far larger than the pattern) use the real-space
+   * encircled-energy method; `realSpaceWavelengthsNm` lists them, and `method` is `"frequency-domain-and-real-space"` when both ran.
+   * `maximumRadialNodes` counts frequency-domain radial nodes (0 when only the real-space method ran); `maximumAngularNodes` the
+   * angular nodes of either method (for the real-space method, all θ nodes of one wavelength).
+   */
+  quadrature: { method: "polar-frequency-domain-trapezoid-gauss-legendre" | "real-space-encircled-energy-gauss-legendre" | "frequency-domain-and-real-space";
+    maximumRadialNodes: number; maximumAngularNodes: number; realSpaceWavelengthsNm?: readonly number[] };
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photivra/engine",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",