@photivra/engine 2.16.0 → 2.18.0

package/docs/USAGE.md

@@ -374,6 +374,8 @@ The actual focal length stays the physical optical quantity used by projection a
 - Focus distance is not part of conventional 35 mm-equivalent focal length. A later digital/output crop and the output resolution are also excluded.
 - If a product wants to describe the final digital framing, it should label it as output framing. It should not silently replace the optical focal length or the capture-equivalent focal length.
 
+To render a lens by its physical focal length on any sensor, give `simulateCapture()` or the display view `lens.ideal: { focalLengthMm }` with any `lens.fNumber` within `IDEAL_LENS_LIMITS` (f/0.5–f/128, 1–4000 mm; optional `widestFNumber` and `narrowestFNumber` narrow the f-number range for the automatic exposure modes): an aberration-free thin lens that is not scaled by the crop factor, unlike `lens.prime` (see docs/QUICK_START.md, "Ideal lens at any focal length and f-number").
+
 `calculateImagingAreaMetrics()` provides the same canonical diagonal crop-factor calculation, independent of raster density, so other engine modules do not need to repeat that formula.
 
 ## Focus-breathing projection
@@ -1455,7 +1457,7 @@ console.log(blur.value.diameterMm);
 
 You supply the circle-of-confusion criterion used for depth of field (DOF). These are ideal geometric thin-lens models. They do not include diffraction or real-lens aberrations in the DOF criterion.
 
-`simulateCapture` and the display view render the defocus blur disc with `lens.defocus: { model: "geometric-disc" }`, up to a kernel radius of `DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES` (64 sites, a disc 129 sites across) and refuse a larger one. Use `calculateDefocusDiscKernelRadius()` to check a request before rendering it. It runs the capture's own resolution and limit test, so it agrees with the capture's refusal. Pass the f-number the capture uses (in an automatic exposure mode, the resolved one) and the sensor's pixel pitch:
+`simulateCapture` and the display view render the defocus blur disc with `lens.defocus: { model: "geometric-disc" }`, up to a kernel radius of `DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES` (512 sites, a disc 1025 sites across, 6.15 mm at 6 µm; 64 sites before 2.17.0) and refuse a larger one. Up to 64 sites the disc is convolved directly, as before; above it, by runs of equal kernel weights (#564), the same sums at a cost that grows with the radius instead of its square ([Quick start, Large defocus discs](QUICK_START.md#large-defocus-discs-564)). Use `calculateDefocusDiscKernelRadius()` to check a request before rendering it. It runs the capture's own resolution and limit test, so it agrees with the capture's refusal, and `convolution` says which method renders it. Pass the f-number the capture uses (in an automatic exposure mode, the resolved one) and the sensor's pixel pitch:
 
 ```ts
 import { calculateDefocusDiscKernelRadius } from "@photivra/engine";
@@ -1463,13 +1465,14 @@ import { calculateDefocusDiscKernelRadius } from "@photivra/engine";
 const check = calculateDefocusDiscKernelRadius({
   focalLengthMm: 50,
   aperture: 1.4,
-  focusDistanceM: 1,
+  focusDistanceM: 0.25,
   subjectDistanceM: 2,
   pixelPitchMicrometers: 6
 });
 
-console.log(check.value.withinLimit); // false: lens.defocus refuses this request
-console.log(check.value.kernelRadiusSites, check.value.excessKernelRadiusSites); // 78, 14
+console.log(check.value.withinLimit); // false: lens.defocus refuses this request (a 7.81 mm blur, 1,303 sites across)
+console.log(check.value.kernelRadiusSites, check.value.excessKernelRadiusSites); // 651, 139
+// Focused at 1 m instead: 157 sites across, radius 78, withinLimit true, convolution "runs".
 ```
 
 See [Physics Foundation](https://github.com/Photivra/photivra/blob/main/docs/PHYSICS_FOUNDATION.md#thin-lens-focus-and-depth-of-field).
@@ -7470,6 +7473,29 @@ console.log(calculateGeometricFocusBreathing({
 }).value.deltaDegrees);
 ```
 
+## Generic lens catalogue (#549)
+
+`GENERIC_LENS_CATALOGUE` lists the engine's 30 generic primes (17 professional, 13 consumer, "PV 50 1.2 Pro", "PV 50 1.8"; Photivra's
+own designs, not real products). `resolveGenericLens` resolves one for a sensor, an f-number and a focus distance: its focal length
+(scaled by the crop factor), aperture range, close focus, projection and its character, Seidel aberrations, axial and lateral
+colour, distortion and vignetting profiles, flare, breathing and focus scatter, each a labelled approximation.
+`simulateGenericLensFocusError` draws a seeded autofocus error; `createGenericLensCorrectionProfile` builds the lens's generic
+correction profile for `resolveLensCorrectionPlan`. `simulateCapture` renders a catalogue lens with `lens.catalogue`
+([quick start](QUICK_START.md#generic-lens-catalogue-549)); `fast: true` (or `lens: { catalogue: { kind, fast: true } }`) takes its
+fast method (#568), a labeled approximation that blends the PSF over a field grid, for interactive captures. Equations, tables and the
+chart measurements: [LENS_CATALOGUE.md](https://github.com/Photivra/photivra/blob/main/docs/LENS_CATALOGUE.md).
+
+```ts
+import { GENERIC_LENS_CATALOGUE, resolveGenericLens, simulateGenericLensFocusError } from "@photivra/engine";
+
+const frame = { widthMm: 36, heightMm: 24 };
+const pro = resolveGenericLens({ lensId: "pv-50-1.2-pro", activeImagingArea: frame, fNumber: 2 });
+const consumer = resolveGenericLens({ lensId: "pv-50-1.8", activeImagingArea: frame, fNumber: 2 });
+console.log(GENERIC_LENS_CATALOGUE.length, pro.character.aberrations.comaWaves < consumer.character.aberrations.comaWaves); // 30 true
+const shot = simulateGenericLensFocusError({ lensId: "pv-50-1.8", activeImagingArea: frame, fNumber: 1.8, focusDistanceM: 2, seed: 1, shotIndex: 0 });
+console.log(shot.focusDistanceM, shot.imageSideErrorMicrometers);
+```
+
 ## Parallel native environment RAW (row-band partitions, 2.0)
 
 `createNativeEnvironmentRawTask` runs on one thread. For several cores, split the capture into row bands with
@@ -7814,6 +7840,20 @@ region that have a clipped contributing site. `simulateCapture` counts the same
 are equal where every site is far from white. Counts of regions that tile a view add up to the whole view's count. See
 [Highlight count](https://github.com/Photivra/photivra/blob/main/docs/DISPLAY_VIEW.md#highlight-count-533).
 
+From #563 the view renders `lens.projection`, `lens.distortion`, `lens.vignetting` and camera rotation (global
+shutter), in focus and with `lens.defocus` out of focus, with each real site's expected electrons as the capture's. These
+requests run on the CPU (`gpu: "auto"` falls back labelled `unsupported-on-backend`); rotation with a rolling shutter is
+refused. See [Lens projection, distortion, vignetting and rotation](https://github.com/Photivra/photivra/blob/main/docs/DISPLAY_VIEW.md#lens-projection-distortion-vignetting-and-rotation).
+
+```ts
+import { simulateDisplayView } from "@photivra/engine";
+
+const fisheye = await simulateDisplayView({ scene: { preset: "siemens-star" }, sensor: { pixelPitchMicrometers: 3 }, output: { width: 120, height: 80 },
+  lens: { projection: "fisheye-equisolid-angle", vignetting: { normalizationRadiusMm: 0.25, maximumNormalizedRadius: 1, coefficients: { r2: -0.4, r4: 0, r6: 0 } } } },
+  { width: 30, height: 20 });
+console.log(fisheye.kind, fisheye.assumptions.find((a) => a.id === "lens.vignetting")?.kind); // "display-view" "model"
+```
+
 #### Rendering a prepared view on the GPU (2.11, #481)
 
 `prepareDisplayView(request, { gpu })` chooses the renderer: `"off"` (the default) is the CPU reference, `"auto"` the GPU
@@ -7923,7 +7963,7 @@ console.log(barrel.request.siteInput(0).environment.lensFieldMapping?.distortion
 lattice, and the capture convolves the scene radiance with it, which is a geometric approximation. With
 `lens.diffraction`, each spectral node's diffraction kernel is convolved with the disc, which is a further
 approximation. The `lens.defocus` assumption records the diameter in µm and in sites, the kernel radius and the
-execution. `simulateDisplayView` does not render it yet. See [Optics](QUICK_START.md#optics).
+execution. `simulateDisplayView` renders it too, also with projection, distortion, vignetting and rotation (#563). See [Optics](QUICK_START.md#optics).
 
 ```ts
 import { simulateCapture } from "@photivra/engine";
@@ -7937,6 +7977,21 @@ const blurred = await simulateCapture({
 console.log(blurred.assumptions.find((a) => a.id === "lens.defocus")?.value); // diameterSites ≈ 5.95, kernelRadiusSites 3
 ```
 
+Bokeh character (#553): `lens.defocus` also takes `blades` (a polygonal or rounded-blade opening), `sphericalAberration`
+(primary W040: a soft-edged blur on one side of the focus plane and a bright-rimmed one on the other) and `catsEye`
+(mechanical vignetting by field position; `simulateCapture` only). Each is off by default. `calculateDefocusBokehKernel`
+returns the kernel without rendering. See [Bokeh character](QUICK_START.md#bokeh-character-553).
+
+```ts
+import { calculateDefocusBokehKernel } from "@photivra/engine";
+
+const kernel = calculateDefocusBokehKernel({
+  focalLengthMm: 50, aperture: 4, focusDistanceM: 1.4, subjectDistanceM: 2, pixelPitchMicrometers: 6,
+  bokeh: { blades: { count: 5 }, sphericalAberration: { w040Micrometers: 0.5, atFNumber: 4 } }
+});
+console.log(kernel.value.side, kernel.value.kernelRadiusSites, kernel.value.method); // "behind-focus", 17, "pupil-ray-binning"
+```
+
 `motion.angularVelocityRadPerSec` rotates the camera during the exposure (8 time midpoints by
 default). `motion.shutter: "rolling"` derives each site's exposure window from the body's rolling
 readout, with `resolveElectronicRollingShutterExposureSchedule`. See [Motion](QUICK_START.md#motion).
@@ -7947,3 +8002,41 @@ import { simulateCapture } from "@photivra/engine";
 const rolling = await simulateCapture({ scene: { preset: "checkerboard" }, motion: { angularVelocityRadPerSec: { pitch: 0.02 }, shutter: "rolling" }, output: { width: 6, height: 6 } });
 console.log(rolling.request.siteInput(7 * 8).charge.completenessProfile.startOffsetSecondsFromOpeningReference);
 ```
+
+## Equivalent f-number, sensor area and blur as a share of the frame
+
+`calculateSensorEquivalence()` says what a lens on one sensor corresponds to on a 36 × 24 mm frame (or on a `reference` you pass). Call it once per sensor to fill a lens table:
+
+```ts
+import { calculateBlurShareOfFrame, calculateSensorEquivalence } from "@photivra/engine";
+
+const apsC = calculateSensorEquivalence({
+  sensor: { widthMm: 23.5, heightMm: 15.6 },
+  focalLengthMm: 50,
+  fNumber: 2
+}).value;
+
+console.log(apsC.cropFactor); // ≈ 1.53
+console.log(apsC.equivalentFocalLengthMm); // ≈ 76.7 (framing)
+console.log(apsC.equivalentFNumber); // ≈ 3.07 (depth of field, blur and total light; not exposure)
+console.log(apsC.exposureFNumber); // 2 (exposure does not change with sensor size)
+console.log(apsC.areaRatio); // ≈ 0.42 of the full-frame area
+console.log(apsC.totalLightDifferenceStops); // ≈ -1.24 stops at the same f-number and shutter
+console.log(apsC.basis.equivalentFNumber.kind); // "approximation"
+
+const share = calculateBlurShareOfFrame({
+  blurCircleMm: 0.03,
+  sensor: { widthMm: 36, heightMm: 24 },
+  print: { widthMm: 300, heightMm: 200 }
+}).value;
+
+console.log(share.shareOfDiagonal); // ≈ 0.00069 of the frame diagonal
+console.log(share.print?.blurOnPrintMm); // 0.25 mm on the print
+```
+
+- `basis` gives, for every number, `kind: "exact"` or `"approximation"` and the conditions. Crop factor, equivalent focal length, area ratio, total-light difference, entrance pupil and angles of view are exact under their stated conditions.
+- The equivalent f-number (crop factor × f-number) assumes the same framing, subject distance and output size. It is a thin-lens approximation that is exact only when the focus distance is much greater than the focal length; at close focus the blur shares match at `k·N·(s − f)/(s − k·f)`.
+- Exposure uses the f-number on the lens. Equivalence never changes shutter, ISO or exposure.
+- Equal shares of the frame diagonal look the same when images are shown at the same size. `calculateBlurShareOfFrame()` does not judge whether a blur is visible.
+
+See [Physics Foundation](https://github.com/Photivra/photivra/blob/main/docs/PHYSICS_FOUNDATION.md#sensor-equivalence-f-number-area-and-blur-share).

package/docs/api/camera-sensor-equivalence.md

@@ -0,0 +1,209 @@
+# camera/sensor-equivalence.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.
+
+## BlurShareOfFrame
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface BlurShareOfFrame {
+  /** Blur-circle diameter on the sensor in millimetres. */
+  blurCircleMm: number;
+  /** Sensor diagonal in millimetres. */
+  frameDiagonalMm: number;
+  /** Blur diameter / frame diagonal. Equal shares look the same at the same output size. */
+  shareOfDiagonal: number;
+  /** Blur diameter / frame width. */
+  shareOfWidth: number;
+  /** Blur diameter / frame height. */
+  shareOfHeight: number;
+  /** Blur on the print; present only when a print size was given. */
+  print?: BlurShareOfPrint;
+}
+```
+
+## BlurShareOfPrint
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface BlurShareOfPrint {
+  /** Linear enlargement from sensor to print: the smaller of the long-side and short-side ratios. */
+  enlargement: number;
+  /** Blur-circle diameter on the print in millimetres: blurCircleMm × enlargement. */
+  blurOnPrintMm: number;
+  /** Size of the printed image in millimetres (equal to the print when the aspect ratios match). */
+  imageLongSideMm: number;
+  imageShortSideMm: number;
+}
+```
+
+## calculateBlurShareOfFrame
+
+A blur circle on the sensor as a share of the frame (diagonal, width and height) and, when a
+print size is given, its diameter on that print.
+
+Equal shares of the diagonal look the same when the images are shown at the same size, which
+is how "same framing" comparisons across sensor sizes are stated. Every value is an exact ratio
+or scaling; whether a blur is visible depends on viewing distance and acuity, which this
+function does not judge.
+
+```ts
+export function calculateBlurShareOfFrame(
+  input: CalculateBlurShareOfFrameInput
+): CalculationResult<BlurShareOfFrame>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateBlurShareOfFrameInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateBlurShareOfFrameInput {
+  /** Blur-circle diameter on the sensor in millimetres (for example from calculateDefocusCircle). Zero is allowed. */
+  blurCircleMm: number;
+  /** Physical active imaging area of the sensor. */
+  sensor: SensorImagingArea;
+  /**
+   * Optional print size. The whole frame is enlarged to fit inside it without cropping, long side
+   * to long side.
+   */
+  print?: { widthMm: number; heightMm: number };
+}
+```
+
+## calculateSensorEquivalence
+
+Equivalence of a lens (focal length, f-number) on one sensor against a reference format,
+36 × 24 mm by default: crop factor, equivalent focal length, equivalent f-number for depth of
+field, blur and total light, the unchanged f-number for exposure, sensor area ratio, total-light
+difference in stops and the angles of view.
+
+Call it once per sensor for a lens table. Every quantity carries a `basis` entry saying whether it
+is exact under its stated conditions or an approximation. The equivalent f-number is an
+approximation (exact when the focus distance is much greater than the focal length) and never an
+exposure setting: exposure uses `exposureFNumber`, the f-number on the lens.
+
+Example: 50 mm f/2 on a 23.5 × 15.6 mm sensor gives crop factor ≈ 1.53, ≈ 77 mm and ≈ f/3.1.
+
+```ts
+export function calculateSensorEquivalence(
+  input: CalculateSensorEquivalenceInput
+): CalculationResult<SensorEquivalence>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSensorEquivalenceInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateSensorEquivalenceInput {
+  /** Physical active imaging area of the sensor the lens is used on. */
+  sensor: SensorImagingArea;
+  /** Physical focal length of the lens in millimetres. */
+  focalLengthMm: number;
+  /** f-number set on the lens (N = focal length / entrance-pupil diameter). */
+  fNumber: number;
+  /** Format to compare against. Defaults to the 36 × 24 mm frame. */
+  reference?: SensorImagingArea;
+}
+```
+
+## EquivalenceExactness
+
+Whether a value is exact under its stated conditions or an approximation.
+
+```ts
+export type EquivalenceExactness = "exact" | "approximation";
+```
+
+## EquivalenceValueBasis
+
+How one equivalence quantity was obtained, and under which conditions it holds.
+
+```ts
+export interface EquivalenceValueBasis {
+  /** `"exact"` under the stated conditions, or `"approximation"`. */
+  kind: EquivalenceExactness;
+  /** Plain statement of the definition and its conditions. */
+  statement: string;
+}
+```
+
+## SensorEquivalence
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorEquivalence {
+  /** Physical focal length supplied by the caller, in millimetres. */
+  focalLengthMm: number;
+  /** f-number supplied by the caller. */
+  fNumber: number;
+  /** Sensor active imaging area used. */
+  sensor: SensorImagingArea;
+  /** Reference format used (36 × 24 mm unless the caller passed one). */
+  reference: SensorImagingArea;
+  /** Sensor diagonal in millimetres. */
+  sensorDiagonalMm: number;
+  /** Reference diagonal in millimetres. */
+  referenceDiagonalMm: number;
+  /** Diagonal crop factor: reference diagonal / sensor diagonal. Greater than 1 for a smaller sensor. */
+  cropFactor: number;
+  /** Focal length on the reference format with the same diagonal angle of view: cropFactor × focalLengthMm. */
+  equivalentFocalLengthMm: number;
+  /**
+   * f-number on the reference format that gives the same depth of field, background blur and total
+   * light for the same framing and output size: cropFactor × fNumber. Not an exposure setting.
+   */
+  equivalentFNumber: number;
+  /** f-number that sets exposure (image brightness): the f-number on the lens, unchanged by sensor size. */
+  exposureFNumber: number;
+  /** Entrance-pupil diameter f/N in millimetres; the equivalent lens has the same diameter. */
+  entrancePupilDiameterMm: number;
+  /** Sensor area / reference area. Less than 1 for a smaller sensor. */
+  areaRatio: number;
+  /**
+   * log2(areaRatio): total light collected by the sensor relative to the reference at the same
+   * f-number, shutter time and scene, in stops. Negative for a smaller sensor.
+   */
+  totalLightDifferenceStops: number;
+  /** Angles of view of this lens on the sensor (the equivalent lens gives the same diagonal angle). */
+  fieldOfView: SensorEquivalenceFieldOfView;
+  /** Exact or approximated, with the conditions, for every quantity above. */
+  basis: Readonly<Record<SensorEquivalenceQuantity, EquivalenceValueBasis>>;
+}
+```
+
+## SensorEquivalenceFieldOfView
+
+Angles of view of an ideal rectilinear lens focused at infinity, in degrees.
+
+```ts
+export interface SensorEquivalenceFieldOfView {
+  horizontalDegrees: number;
+  verticalDegrees: number;
+  diagonalDegrees: number;
+}
+```
+
+## SensorEquivalenceQuantity
+
+Quantities of a sensor equivalence result that carry an exactness statement.
+
+```ts
+export type SensorEquivalenceQuantity =
+  | "cropFactor"
+  | "equivalentFocalLengthMm"
+  | "equivalentFNumber"
+  | "exposureFNumber"
+  | "entrancePupilDiameterMm"
+  | "areaRatio"
+  | "totalLightDifferenceStops"
+  | "fieldOfView";
+```

package/docs/api/core-version.md

@@ -11,5 +11,5 @@ version they were made with. Proof-of-concept (POC), schema and model contracts
 own versions. Release checks confirm it matches package.json and the packed package.
 
 ```ts
-ENGINE_API_VERSION = "2.16.0" as const
+ENGINE_API_VERSION = "2.18.0" as const
 ```

package/docs/api/equipment-generic-lens-catalogue.md

@@ -0,0 +1,281 @@
+# equipment/generic-lens-catalogue.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.
+
+## GENERIC_LENS_CATALOGUE
+
+The 30 lenses: 17 professional, then 13 consumer, each set by focal length.
+
+```ts
+GENERIC_LENS_CATALOGUE: readonly GenericLensCatalogueEntry[] = Object.freeze([...PRO.map((row) => entry("professional", row)),
+  ...CONSUMER.map((row) => entry("consumer", row))])
+```
+
+## GENERIC_LENS_IDS
+
+The catalogue ids, in catalogue order.
+
+```ts
+GENERIC_LENS_IDS: readonly string[] = Object.freeze(GENERIC_LENS_CATALOGUE.map((lens) => lens.lensId))
+```
+
+## GENERIC_LENS_SET_BASELINES
+
+The set baselines (owner's table, #549), each lens's starting point before its adjustments.
+
+```ts
+GENERIC_LENS_SET_BASELINES: Readonly<Record<GenericLensSet, Readonly<GenericLensCharacterValues>>> = Object.freeze({
+  professional: Object.freeze({ sphericalWaves: 0.25, comaWaves: 0.35, astigmatismWaves: 0.3, fieldCurvatureWaves: 0.15, axialColorWaves: 0.15,
+    lateralColorFraction: 0.00008, distortionMagnitude: 0.01, naturalVignettingStops: 0.4, opticalVignettingStops: 0.6, veilingGlareFraction: 0.005, ghostFraction: 0.002,
+    breathingFraction: -0.03, focusScatterDepthOfFocusFraction: 0.1, closeFocusFactor: 0.15 }),
+  consumer: Object.freeze({ sphericalWaves: 0.5, comaWaves: 1.0, astigmatismWaves: 0.8, fieldCurvatureWaves: 0.45, axialColorWaves: 0.4,
+    lateralColorFraction: 0.0003, distortionMagnitude: 0.03, naturalVignettingStops: 0.7, opticalVignettingStops: 1.1, veilingGlareFraction: 0.02, ghostFraction: 0.008,
+    breathingFraction: -0.08, focusScatterDepthOfFocusFraction: 0.3, closeFocusFactor: 0.5 })
+})
+```
+
+## GenericLensAdjustments
+
+Per-lens multipliers of the set baseline (missing: 1). `distortion` is signed and required: −1 barrel, +1 pincushion at the baseline.
+
+```ts
+export type GenericLensAdjustments = { distortion: number } & Partial<Record<"spherical" | "coma" | "astigmatism" | "fieldCurvature" | "axialColor" | "lateralColor" |
+  "vignetting" | "strayLight" | "breathing" | "focusScatter" | "closeFocus", number>>;
+```
+
+## GenericLensCatalogueEntry
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GenericLensCatalogueEntry {
+  /** Catalogue id, for example "pv-50-1.2-pro". */
+  lensId: string;
+  /** Display name, for example "PV 50 1.2 Pro". */
+  name: string;
+  set: GenericLensSet;
+  kind: GenericLensKind;
+  /** Full-frame-equivalent focal length (36 × 24 mm reference). */
+  equivalentFocalLengthMm: number;
+  widestFNumber: number;
+  narrowestFNumber: number;
+  /** Largest magnification: 0.15 (the generic rule) or 1 for the professional macro. */
+  maximumMagnification: number;
+  projection: LensProjectionModel;
+  /** Fisheyes only: a circular image inside the frame, or one that fills it. */
+  fisheyeImage?: "circular" | "full-frame";
+  adjustments: Readonly<GenericLensAdjustments>;
+  /** Why this lens departs from its set's baseline. */
+  note: string;
+  /**
+   * A short plain-English summary of the lens's character (at most 40 characters, US spelling), written from its adjustments and
+   * `note`, for lists and pickers. It describes only what the catalogue models (bokeh shape is not modeled: the defocus is a disc).
+   */
+  summary: string;
+}
+```
+
+## GenericLensCharacter
+
+A catalogue lens's character resolved for a sensor, an f-number and a focus distance. Aberrations in waves at 550 nm.
+
+```ts
+export interface GenericLensCharacter {
+  fNumber: number;
+  focusDistanceM: number | null;
+  /** Thin-lens magnification at the focus distance (0 at infinity). */
+  magnification: number;
+  /** 1 + c·m/m_max. */
+  closeFocusGain: number;
+  /** Pupil-radius ratio N0/N. */
+  pupilScale: number;
+  /** Resolved Seidel coefficients at the frame corner (H = 1), waves at 550 nm; `balancingDefocusWaves` = −spherical. */
+  aberrations: { sphericalWaves: number; balancingDefocusWaves: number; comaWaves: number; astigmatismWaves: number; fieldCurvatureWaves: number; axialColorWaves: number };
+  /** Lateral colour: F-to-C image-radius difference at the corner, fraction of the half-diagonal and micrometres on this sensor. */
+  lateralColor: { fraction: number; cornerMicrometers: number };
+  /** Radial distortion profile (normalised to the half-diagonal, valid to 1.25 of it, beyond the corner) and its corner value (fraction; negative = barrel). */
+  distortion: { profile: RadialDistortionProfile; corner: number };
+  /** Relative illumination profile (normalised to the half-diagonal, valid to 1.25 of it) and the corner fall-off in stops. */
+  vignetting: { profile: IlluminationVignettingProfile; cornerStops: number };
+  strayLight: { veilingGlareFraction: number; ghostFraction: number };
+  /** Field-of-view change at this focus and at minimum focus, beyond thin-lens unit focusing (fraction, negative = narrower). */
+  breathing: { fieldOfViewChange: number; atMinimumFocus: number };
+  /** Standard deviation of the autofocus error as a fraction of the depth of focus 2·N·c. */
+  focusScatterDepthOfFocusFraction: number;
+}
+```
+
+## GenericLensCharacterValues
+
+The character of a set, at each lens's widest aperture. Aberrations are in waves at 550 nm at the frame corner.
+
+```ts
+export interface GenericLensCharacterValues {
+  /** Spherical aberration W040 (balanced by W020 = −W040): centre sharpness. */
+  sphericalWaves: number;
+  /** Coma W131 at H = 1: the comet-shaped point images of night photography. */
+  comaWaves: number;
+  /** Astigmatism W222 at H = 1: edge and corner sharpness. */
+  astigmatismWaves: number;
+  /** Field curvature W220 at H = 1: edge and corner sharpness. */
+  fieldCurvatureWaves: number;
+  /** Axial colour: the F-to-C difference of the defocus W020, waves at 550 nm. */
+  axialColorWaves: number;
+  /** Lateral colour: the F-to-C difference of the image radius at the corner, as a fraction of the half-diagonal. */
+  lateralColorFraction: number;
+  /** Corner distortion magnitude |k1| (fraction); each lens gives the sign (barrel −, pincushion +). */
+  distortionMagnitude: number;
+  /** Corner fall-off in stops that stays when stopped down (natural vignetting). */
+  naturalVignettingStops: number;
+  /** Extra corner fall-off in stops at the widest aperture (optical vignetting); gone two stops down. */
+  opticalVignettingStops: number;
+  /** Veiling glare: the fraction of the image's mean irradiance spread as a uniform veil. */
+  veilingGlareFraction: number;
+  /** Peak ghost power as a fraction of a bright source's power on the axis. */
+  ghostFraction: number;
+  /** Field-of-view change between infinity and minimum focus as a fraction (negative: narrower), beyond thin-lens unit focusing. */
+  breathingFraction: number;
+  /** Standard deviation of the autofocus error as a fraction of the depth of focus 2·N·c. */
+  focusScatterDepthOfFocusFraction: number;
+  /** c in the close-focus factor 1 + c·m/m_max. */
+  closeFocusFactor: number;
+}
+```
+
+## GenericLensFocusError
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GenericLensFocusError {
+  lensId: string;
+  /** The intended and the sampled focus distance, m (the sampled one held within minimum focus and a far limit). */
+  intendedFocusDistanceM: number;
+  focusDistanceM: number;
+  /** The standard normal draw z and the image-side focus error z·σ·2Nc, µm (positive: a longer image distance, so focused nearer). */
+  standardNormal: number;
+  imageSideErrorMicrometers: number;
+  /** σ (fraction of the depth of focus) and the depth of focus 2·N·c, µm. */
+  depthOfFocusFraction: number;
+  depthOfFocusMicrometers: number;
+  /** True when the sampled image distance was held at the minimum-focus or the far (1000 m) limit. */
+  held: "minimum-focus" | "far-limit" | null;
+  scientificStatus: "approximation";
+}
+```
+
+## GenericLensKind
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type GenericLensKind = "standard" | "macro" | "fisheye";
+```
+
+## GenericLensSet
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type GenericLensSet = "professional" | "consumer";
+```
+
+## ResolvedGenericLens
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedGenericLens {
+  lensId: string;
+  name: string;
+  set: GenericLensSet;
+  kind: GenericLensKind;
+  equivalentFocalLengthMm: number;
+  /** Physical focal length on this sensor: equivalent ÷ crop factor. */
+  focalLengthMm: number;
+  cropFactor35Mm: number;
+  /** Half-diagonal of the sensor, mm: field height H = 1 and ρ = 1 of the profiles. */
+  halfDiagonalMm: number;
+  widestFNumber: number;
+  narrowestFNumber: number;
+  /** Marked third-stop f-numbers within the range. */
+  fNumbers: readonly number[];
+  /** max(0.10 m, f·(1 + 1/m_max)), metres from the lens (thin lens). */
+  minimumFocusDistanceM: number;
+  maximumMagnification: number;
+  projection: LensProjectionModel;
+  fisheyeImage: "circular" | "full-frame" | null;
+  /** Fisheyes: the radius of the 180° image circle on this sensor, 2·f·sin 45° (equisolid), mm. Null otherwise. */
+  imageCircleRadiusMm: number | null;
+  character: GenericLensCharacter;
+  note: string;
+  /** The catalogue entry's `summary`: a short plain-English description of the lens's character (at most 40 characters). */
+  summary: string;
+  evidence: readonly EvidenceProvenance[];
+  scientificStatus: "approximation";
+  limitations: readonly string[];
+}
+```
+
+## resolveGenericLens
+
+Resolves a catalogue lens for a sensor: its focal length (equivalent ÷ the diagonal crop factor), f-number range, close focus
+and projection, and its character (aberrations, colour, distortion, vignetting, flare, breathing and focus scatter) at the
+given f-number and focus distance. Every value is a labelled approximation of a generic lens, not a measured product.
+
+```ts
+export function resolveGenericLens(input: ResolveGenericLensInput): ResolvedGenericLens;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveGenericLensInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveGenericLensInput {
+  /** A catalogue id (`GENERIC_LENS_IDS`). */
+  lensId: string;
+  /** The sensor's active capture area, mm. */
+  activeImagingArea: { widthMm: number; heightMm: number };
+  /** Default: the widest aperture. Must lie in the lens's range. */
+  fNumber?: number;
+  /** Default: infinity. At least the minimum focus distance. */
+  focusDistanceM?: number;
+}
+```
+
+## simulateGenericLensFocusError
+
+Focus consistency (#549): a seeded, reproducible autofocus error for one shot. The image-side error is z·σ·2Nc, with z a
+standard normal draw from (seed, shotIndex) (MurmurHash3 stream seed, xorshift32 and Box–Muller, the generators of the
+capture's sensor noise), σ the lens's focus scatter as a fraction of the depth of focus 2·N·c, and
+c the circle of confusion. The thin-lens image distance of the intended focus moves by that error and the focus distance is
+read back from it. An approximation of autofocus variation; off unless called (or `simulateCapture`'s `lens.focusScatter`).
+
+```ts
+export function simulateGenericLensFocusError(input: SimulateGenericLensFocusErrorInput): GenericLensFocusError;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SimulateGenericLensFocusErrorInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SimulateGenericLensFocusErrorInput {
+  lensId: string;
+  activeImagingArea: { widthMm: number; heightMm: number };
+  fNumber: number;
+  /** The intended focus distance, m. */
+  focusDistanceM: number;
+  /** uint32 seed of the shooting session. */
+  seed: number;
+  /** uint32 index of the shot in the session. Default 0. */
+  shotIndex?: number;
+  /** Circle of confusion for the depth of focus, mm. Default: the sensor diagonal / 1500. */
+  circleOfConfusionMm?: number;
+}
+```