@photivra/engine 2.16.0 → 2.17.0

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;
+}
+```

package/docs/api/exports.json

@@ -1,6 +1,6 @@
 {
-  "packageVersion": "2.16.0",
-  "engineApiVersion": "2.16.0",
+  "packageVersion": "2.17.0",
+  "engineApiVersion": "2.17.0",
   "exports": [
     {
       "name": "AbsoluteUncertaintyEstimate",
@@ -562,6 +562,16 @@
       "source": "src/color/illuminants.ts",
       "kind": "runtime"
     },
+    {
+      "name": "calculateDefocusBokehKernel",
+      "source": "src/optics/defocus-bokeh-kernel.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "CalculateDefocusBokehKernelInput",
+      "source": "src/optics/defocus-bokeh-kernel.ts",
+      "kind": "type"
+    },
     {
       "name": "calculateDefocusCircle",
       "source": "src/optics/depth-of-field.ts",
@@ -2432,6 +2442,16 @@
       "source": "src/equipment/generic-tier-presets.ts",
       "kind": "runtime"
     },
+    {
+      "name": "createGenericLensCorrectionProfile",
+      "source": "src/output/generic-lens-corrections.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "CreateGenericLensCorrectionProfileInput",
+      "source": "src/output/generic-lens-corrections.ts",
+      "kind": "type"
+    },
     {
       "name": "createHdrBracketMergeTask",
       "source": "src/processing/hdr.ts",
@@ -2702,11 +2722,46 @@
       "source": "src/sensor/capture-mode.ts",
       "kind": "type"
     },
+    {
+      "name": "DEFOCUS_BOKEH_MAXIMUM_BLADES",
+      "source": "src/optics/defocus-bokeh-kernel.ts",
+      "kind": "runtime"
+    },
     {
       "name": "DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES",
       "source": "src/optics/defocus-disc-kernel.ts",
       "kind": "runtime"
     },
+    {
+      "name": "DefocusBokehBlades",
+      "source": "src/optics/defocus-bokeh-kernel.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DefocusBokehCatsEye",
+      "source": "src/optics/defocus-bokeh-kernel.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DefocusBokehClippingAperture",
+      "source": "src/optics/defocus-bokeh-kernel.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DefocusBokehKernel",
+      "source": "src/optics/defocus-bokeh-kernel.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DefocusBokehOptions",
+      "source": "src/optics/defocus-bokeh-kernel.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DefocusBokehSphericalAberration",
+      "source": "src/optics/defocus-bokeh-kernel.ts",
+      "kind": "type"
+    },
     {
       "name": "DefocusCircle",
       "source": "src/optics/depth-of-field.ts",
@@ -3482,6 +3537,26 @@
       "source": "src/sensor/iso-signal-chain.ts",
       "kind": "runtime"
     },
+    {
+      "name": "GENERIC_LENS_CATALOGUE",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM",
+      "source": "src/output/generic-lens-corrections.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "GENERIC_LENS_IDS",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "GENERIC_LENS_SET_BASELINES",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "runtime"
+    },
     {
       "name": "GENERIC_PRIME_EQUIVALENT_FOCAL_LENGTHS_MM",
       "source": "src/equipment/generic-prime-lenses.ts",
@@ -3587,6 +3662,26 @@
       "source": "src/sensor/iso-signal-chain.ts",
       "kind": "type"
     },
+    {
+      "name": "GenericLensAdjustments",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
+    {
+      "name": "GenericLensCatalogueEntry",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
+    {
+      "name": "GenericLensCharacter",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
+    {
+      "name": "GenericLensCharacterValues",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
     {
       "name": "GenericLensCorrectionProfile",
       "source": "src/output/lens-corrections.ts",
@@ -3597,6 +3692,21 @@
       "source": "src/equipment/exposure-capabilities.ts",
       "kind": "type"
     },
+    {
+      "name": "GenericLensFocusError",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
+    {
+      "name": "GenericLensKind",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
+    {
+      "name": "GenericLensSet",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
     {
       "name": "GenericOpticalEvidence",
       "source": "src/optics/profile-contract.ts",
@@ -6622,6 +6732,11 @@
       "source": "src/sensor/iso-signal-chain.ts",
       "kind": "type"
     },
+    {
+      "name": "ResolvedGenericLens",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
     {
       "name": "ResolvedGenericTierLensProfiles",
       "source": "src/equipment/generic-tier-presets.ts",
@@ -6782,6 +6897,16 @@
       "source": "src/sensor/iso-signal-chain.ts",
       "kind": "runtime"
     },
+    {
+      "name": "resolveGenericLens",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "ResolveGenericLensInput",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
     {
       "name": "resolveGenericPrimeLens",
       "source": "src/equipment/generic-prime-lenses.ts",
@@ -8477,6 +8602,16 @@
       "source": "src/capture/environment-raw-producer.ts",
       "kind": "type"
     },
+    {
+      "name": "simulateGenericLensFocusError",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "SimulateGenericLensFocusErrorInput",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
     {
       "name": "simulateIdealReference",
       "source": "src/facade/simulate-capture.ts",

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

@@ -142,7 +142,7 @@ a capture does. `motion.rotation` is a non-zero angular velocity; `sensor.tempor
 
 ```ts
 SIMULATE_CAPTURE_COST_OPTIONS = Object.freeze(["lens.pupilSampling", "lens.projection", "lens.distortion", "lens.vignetting", "lens.psf",
-  "lens.diffraction", "lens.defocus", "sensor.antiAliasing", "sensor.pixelAperture.box", "sensor.temporalSampleCount", "motion.rotation", "motion.shutter.rolling", "output.borderHandling.mirror", "output.region",
+  "lens.diffraction", "lens.defocus", "lens.catalogue", "sensor.antiAliasing", "sensor.pixelAperture.box", "sensor.temporalSampleCount", "motion.rotation", "motion.shutter.rolling", "output.borderHandling.mirror", "output.region",
   "output.whiteBalance.auto", "output.demosaic.ahd", "output.highlightMode.reconstruct", "output.colorEncoding.wide-gamut", "output.gamutMapping.perceptual",
   "output.diffractionCorrection", "output.sharpening", "output.format.jpeg", "output.format.png", "output.format.dng"] as const)
 ```
@@ -514,6 +514,22 @@ export interface SimulateCaptureOptions {
      * focus distance below its minimum focus distance, is rejected. Not combinable with `focalLengthMm`.
      */
     prime?: number;
+    /**
+     * Opt-in (#549): a lens of the generic lens catalogue by id (`GENERIC_LENS_IDS`, for example "pv-50-1.2-pro" or "pv-50-1.8";
+     * docs/LENS_CATALOGUE.md). Like `prime`, its focal length is the full-frame equivalent ÷ the simulated frame's diagonal crop
+     * factor and it replaces the tier lens's focal length and f-number range (the transmission is kept). The capture renders the
+     * lens's character, all labelled approximations: its PSF (diffraction with the lens's Seidel aberrations, axial and lateral
+     * colour, at the resolved f-number and focus) through the environment PSF quadrature, its radial distortion, its vignetting
+     * and, for the fisheyes, the equisolid projection. Flare, focus breathing and bokeh shape are not rendered. Not combinable
+     * with `prime`, `focalLengthMm`, `projection`, `distortion`, `vignetting`, `psf`, `diffraction` or `pupilSampling` (the
+     * lens sets them); `defocus` convolves the disc into the lens's PSF. Not offered by the display view. Default off.
+     */
+    catalogue?: string;
+    /**
+     * Opt-in (#549), with `catalogue` only: a seeded autofocus error (`simulateGenericLensFocusError`). The focus distance becomes
+     * the sampled one for (seed, shotIndex), reported in the `lens.focusScatter` assumption; it is visible with `defocus`. Default off.
+     */
+    focusScatter?: { seed: number; shotIndex?: number };
     /** Aperture for manual and aperture-priority modes. Default 8. */
     fNumber?: number;
     /** Focus distance in metres. Default: the subject distance. */
@@ -547,8 +563,13 @@ export interface SimulateCaptureOptions {
      * kernel is convolved with the disc (a further approximation). In focus the result is that of the same request
      * without the option, plus the assumption.
      * Not combinable with `pupilSampling` or `psf`. Default off.
+     *
+     * Bokeh character (#553), each part off by default (without them the disc is unchanged, byte for byte): `blades` (a
+     * polygonal or rounded-blade opening), `sphericalAberration` (primary W040: soft-edged blur on one side of the focus
+     * plane, bright-rimmed on the other) and `catsEye` (mechanical vignetting clipping the pupil by field position; the
+     * capture only, not with `diffraction`). See `calculateDefocusBokehKernel` and docs/QUICK_START.md, "Bokeh character".
      */
-    defocus?: { model: "geometric-disc" };
+    defocus?: { model: "geometric-disc" } & DefocusBokehOptions;
   };
   exposure?: {
     /** Default "manual". */

package/docs/api/optics-defocus-bokeh-kernel.md

@@ -0,0 +1,145 @@
+# optics/defocus-bokeh-kernel.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.
+
+## calculateDefocusBokehKernel
+
+The defocus kernel of `lens.defocus` with bokeh options (#553), on the site lattice, for one field point: the same kernel
+`simulateCapture` and the display view apply (on the field zone's centre with a cat's eye). Pure; for tests, previews and
+lens catalogues. Fails with `InvalidScientificInputError` past {@link DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES} (spherical
+aberration can widen the blur beyond the disc) or when the cat's eye closes the pupil, `InvalidConfigurationError` for
+unknown fields. A geometric approximation: see the module comment of `defocus-bokeh-kernel.ts` and docs/QUICK_START.md,
+"Bokeh character".
+
+```ts
+export function calculateDefocusBokehKernel(input: CalculateDefocusBokehKernelInput): CalculationResult<DefocusBokehKernel>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateDefocusBokehKernelInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateDefocusBokehKernelInput {
+  /** Lens focal length, mm. */
+  focalLengthMm: number;
+  /** Working f-number. */
+  aperture: number;
+  /** Focus-plane distance, m. */
+  focusDistanceM: number;
+  /** Scene-plane distance, m. */
+  subjectDistanceM: number;
+  /** Sensor site pitch, µm: the lattice the kernel is sampled on. */
+  pixelPitchMicrometers: number;
+  /** The bokeh options, as `lens.defocus` takes them (blades, sphericalAberration, catsEye). */
+  bokeh: DefocusBokehOptions;
+  /** Field tangent tan θ·(cos φ, sin φ) in output-image axes (+X right, +Y up); only the cat's eye reads it. Default on axis. */
+  fieldTangent?: { x: number; y: number };
+}
+```
+
+## DEFOCUS_BOKEH_MAXIMUM_BLADES
+
+Largest blade count of `lens.defocus.blades` (and of {@link DefocusBokehBlades}).
+
+```ts
+DEFOCUS_BOKEH_MAXIMUM_BLADES = 32
+```
+
+## DefocusBokehBlades
+
+Aperture blades: a regular polygon, optionally with rounded blades and open at wide f-numbers.
+
+```ts
+export interface DefocusBokehBlades {
+  /** Number of diaphragm blades, 3 to {@link DEFOCUS_BOKEH_MAXIMUM_BLADES}. */
+  count: number;
+  /** Rotation of the first blade edge, degrees counter-clockwise (`calculateIdealApertureGeometry`'s convention). Default 0. */
+  firstBladeEdgeAngleDegrees?: number;
+  /** Blade roundness κ in [0, 1]: each edge is an arc of radius 1/κ circumradii (0: straight blades, 1: a circle). Default 0. */
+  curvature?: number;
+  /** At or below this f-number the blades are open and the opening is circular (the lens's widest aperture). Default: never. */
+  circularAtOrBelowFNumber?: number;
+}
+```
+
+## DefocusBokehCatsEye
+
+Mechanical vignetting (cat's eye): the open pupil clipped by each aperture at the field point.
+
+```ts
+export interface DefocusBokehCatsEye {
+  /** One through eight clipping apertures. */
+  apertures: readonly DefocusBokehClippingAperture[];
+  /**
+   * `lens.defocus` only: zones across the frame's long side (1 to {@link DEFOCUS_BOKEH_MAXIMUM_FIELD_ZONES}, default
+   * {@link DEFOCUS_BOKEH_DEFAULT_FIELD_ZONES}); square zones, each with the kernel of its centre's field point.
+   */
+  fieldZonesAcrossLongSide?: number;
+}
+```
+
+## DefocusBokehClippingAperture
+
+One clipping aperture of the cat's eye, as `MechanicalVignettingAperture` of `calculateMechanicalVignetting`.
+
+```ts
+export interface DefocusBokehClippingAperture {
+  /** Aperture radius referred to the entrance-pupil plane, mm. */
+  radiusMm: number;
+  /** Shift of its projected centre per unit tan(field angle), mm, toward the field point when positive. */
+  shiftPerTanFieldMm: number;
+}
+```
+
+## DefocusBokehKernel
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DefocusBokehKernel {
+  /** "behind-focus" (subject farther than focus), "in-front-of-focus", or "in-focus" (no kernel). */
+  side: "behind-focus" | "in-front-of-focus" | "in-focus";
+  /** Thin-lens blur diameter c, µm and sites (`calculateDefocusCircle`, thin-lens model 1.1.0). */
+  diameterMicrometers: number;
+  diameterSites: number;
+  /** Kernel radius R and window side 2R + 1 (0 and 1 in focus). */
+  kernelRadiusSites: number;
+  width: number;
+  /** Row-major weights, index (j + R)·width + (i + R) for site offset (i right, j down) from the chief ray; null in focus. */
+  weights: Float64Array | null;
+  /** Open pupil area / unclipped opening area at the field point (the cat's eye's open fraction; 1 without one). */
+  openAreaRatio: number;
+  method: "exact-polygon-cell-area" | "pupil-ray-binning" | "none";
+  /** Transverse spherical aberration of the marginal ray at the working f-number, sites (8·N·W040(N)/pitch). */
+  sphericalAberrationSites: number;
+  raySamples: number;
+}
+```
+
+## DefocusBokehOptions
+
+The bokeh options of `lens.defocus` (#553), each off when omitted; a lens catalogue entry can carry them as they are.
+
+```ts
+export interface DefocusBokehOptions {
+  blades?: DefocusBokehBlades;
+  sphericalAberration?: DefocusBokehSphericalAberration;
+  catsEye?: DefocusBokehCatsEye;
+}
+```
+
+## DefocusBokehSphericalAberration
+
+Primary (Seidel) spherical aberration W = W040·ρ⁴, given at a reference f-number.
+
+```ts
+export interface DefocusBokehSphericalAberration {
+  /** W040 in µm of optical path at the pupil edge of `atFNumber`; positive = undercorrected (marginal rays focus short). */
+  w040Micrometers: number;
+  /** The f-number at which `w040Micrometers` is given; the working value is W040·(atFNumber/N)⁴. */
+  atFNumber: number;
+}
+```