@photivra/engine 2.16.0 → 2.18.0

package/docs/api/equipment-ideal-lens.md

@@ -0,0 +1,26 @@
+# equipment/ideal-lens.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.
+
+## IDEAL_LENS_LIMITS
+
+Ideal lens (#576): the bounds of `simulateCapture`'s and the display view's `lens.ideal`, a plain aberration-free thin lens
+named by its physical focal length, on any sensor. Its blur is that of the options the request gives, the same models as with
+`lens.prime`: `lens.defocus` (the thin-lens blur circle, `calculateDefocusCircle`), `lens.diffraction` (the Airy pattern of a
+circular pupil) and `lens.vignetting` (a caller profile). Without them it renders sharp and evenly lit.
+
+- `fNumber.minimum` 0.5 is a physical limit: a lens in air that satisfies the Abbe sine condition (aplanatic) has
+  N = 1/(2·n·sin θ′) with n = 1 and sin θ′ ≤ 1, so N ≥ 0.5 (the sine condition: Born & Wolf, *Principles of Optics*, 7th ed.;
+  Kingslake & Johnson, *Lens Design Fundamentals*, 2nd ed.). The engine's thin-lens defocus and scalar Airy diffraction
+  are paraxial models, so near f/0.5 they are approximations further from a real lens than at f/2.
+- `fNumber.maximum` 128 and both focal-length bounds are engine bounds, not physical limits: 1 mm is shorter than phone
+  camera lenses, 4000 mm longer than photographic lenses, and f/128 beyond large-format lenses' smallest stops.
+- The ideal lens's f-number range is the whole of `fNumber`: manual and aperture priority take any `lens.fNumber` in it, and
+  shutter priority and program may choose any aperture in it (in dim light, wider than real lenses open).
+
+```ts
+IDEAL_LENS_LIMITS = Object.freeze({
+  focalLengthMm: Object.freeze({ minimum: 1, maximum: 4000 }),
+  fNumber: Object.freeze({ minimum: 0.5, maximum: 128 })
+})
+```

package/docs/api/exports.json

@@ -1,6 +1,6 @@
 {
-  "packageVersion": "2.16.0",
-  "engineApiVersion": "2.16.0",
+  "packageVersion": "2.18.0",
+  "engineApiVersion": "2.18.0",
   "exports": [
     {
       "name": "AbsoluteUncertaintyEstimate",
@@ -282,6 +282,16 @@
       "source": "src/sensor/local-exposure-binding.ts",
       "kind": "type"
     },
+    {
+      "name": "BlurShareOfFrame",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "type"
+    },
+    {
+      "name": "BlurShareOfPrint",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "type"
+    },
     {
       "name": "BOLTZMANN_CONSTANT_JOULES_PER_KELVIN",
       "source": "src/color/illuminants.ts",
@@ -367,6 +377,16 @@
       "source": "src/facade/chart-scenes.ts",
       "kind": "runtime"
     },
+    {
+      "name": "calculateBlurShareOfFrame",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "CalculateBlurShareOfFrameInput",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "type"
+    },
     {
       "name": "calculateBrownConradyDistortionMapping",
       "source": "src/optics/brown-conrady-distortion.ts",
@@ -562,6 +582,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",
@@ -1277,6 +1307,16 @@
       "source": "src/sensor/eqe-temporal-exposure.ts",
       "kind": "type"
     },
+    {
+      "name": "calculateSensorEquivalence",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "CalculateSensorEquivalenceInput",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "type"
+    },
     {
       "name": "calculateSensorFixedPatternSite",
       "source": "src/sensor/fixed-pattern-noise.ts",
@@ -2432,6 +2472,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 +2752,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",
@@ -2902,6 +2987,16 @@
       "source": "src/capture/environment-raw-producer.ts",
       "kind": "type"
     },
+    {
+      "name": "EquivalenceExactness",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "type"
+    },
+    {
+      "name": "EquivalenceValueBasis",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "type"
+    },
     {
       "name": "EquivalentFocalLength35Mm",
       "source": "src/camera/equivalent-focal-length.ts",
@@ -3482,6 +3577,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 +3702,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 +3732,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",
@@ -3782,6 +3932,11 @@
       "source": "src/facade/chart-scenes.ts",
       "kind": "type"
     },
+    {
+      "name": "IDEAL_LENS_LIMITS",
+      "source": "src/equipment/ideal-lens.ts",
+      "kind": "runtime"
+    },
     {
       "name": "IdealApertureGeometry",
       "source": "src/optics/aperture.ts",
@@ -6622,6 +6777,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 +6942,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",
@@ -7702,6 +7872,21 @@
       "source": "src/sensor/eqe-electron-rate.ts",
       "kind": "type"
     },
+    {
+      "name": "SensorEquivalence",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "type"
+    },
+    {
+      "name": "SensorEquivalenceFieldOfView",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "type"
+    },
+    {
+      "name": "SensorEquivalenceQuantity",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "type"
+    },
     {
       "name": "SensorExpectedReadoutSignal",
       "source": "src/sensor/raw-readout.ts",
@@ -8387,6 +8572,11 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "SimulateCaptureLensCatalogueRecord",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
     {
       "name": "SimulateCaptureLensDistortion",
       "source": "src/facade/simulate-capture.ts",
@@ -8477,6 +8667,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)
 ```
@@ -173,7 +173,7 @@ the record form with `fast` and is reported in `diagnostics.fast.applied` when i
 whether or not it has a fast method yet; one without runs exact and reports `false`.
 
 ```ts
-SIMULATE_CAPTURE_FAST_OPTIONS = Object.freeze(["lens.diffraction", "sensor.antiAliasing", "sensor.pixelAperture.box", "output.demosaic.ahd"] as const)
+SIMULATE_CAPTURE_FAST_OPTIONS = Object.freeze(["lens.diffraction", "lens.catalogue", "sensor.antiAliasing", "sensor.pixelAperture.box", "output.demosaic.ahd"] as const)
 ```
 
 ## SIMULATE_CAPTURE_METERING_MODES
@@ -459,6 +459,14 @@ export interface SimulateCaptureFastReport {
 }
 ```
 
+## SimulateCaptureLensCatalogueRecord
+
+`lens.catalogue` as a record (#568): the lens id as `kind` and the `fast` override (see {@link SimulateCaptureOptions.fast}).
+
+```ts
+export interface SimulateCaptureLensCatalogueRecord { kind: string; fast?: boolean }
+```
+
 ## SimulateCaptureLensDistortion
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -514,6 +522,37 @@ export interface SimulateCaptureOptions {
      * focus distance below its minimum focus distance, is rejected. Not combinable with `focalLengthMm`.
      */
     prime?: number;
+    /**
+     * Opt-in (#576): an ideal lens, an aberration-free thin lens of this physical focal length (1–4000 mm) on whatever sensor the
+     * frame is (output width × height × pixel pitch; no crop-factor scaling), at any `fNumber` from f/0.5 to f/128
+     * (`IDEAL_LENS_LIMITS`; beyond them the request is refused). It replaces the tier lens's focal length and f-number range (the
+     * transmission is kept); shutter priority and program may choose any aperture in that range. Recorded in the `lens.ideal`
+     * assumption. Its blur is that of `defocus`, `diffraction` and `vignetting`, the same models as with `prime`. It focuses at any
+     * distance beyond the focal length (no minimum focus distance; `subjectDistanceM` must be at least twice the focal length, as for
+     * every lens). Works in `simulateCapture` and the display view. Not combinable with `prime`, `catalogue` or `focalLengthMm`.
+     * Optional `widestFNumber` and `narrowestFNumber` (within `IDEAL_LENS_LIMITS`, widest ≤ narrowest; each defaults to its bound)
+     * narrow the range: `fNumber` must lie in it, and shutter priority and program choose apertures only in it. Default off.
+     */
+    ideal?: { focalLengthMm: number; widestFNumber?: number; narrowestFNumber?: 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. The display view renders it with the PSF taken per field zone (#569; docs/DISPLAY_VIEW.md). Default off.
+     * #568: the record form `{ kind: <lens id>, fast }` overrides the top-level `fast` flag for this option; the fast method
+     * blends the PSF between exactly resolved kernels on a field grid and tabulates each site's expected signal
+     * (docs/LENS_CATALOGUE.md, "Fast method").
+     */
+    catalogue?: string | SimulateCaptureLensCatalogueRecord;
+    /**
+     * 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 +586,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". */
@@ -727,7 +771,7 @@ export interface SimulateCaptureOptions {
    * Exact or fast (#395). `false` or omitted: every option runs its exact method, the engine reference. `true`: each option
    * listed in {@link SIMULATE_CAPTURE_FAST_OPTIONS} runs its fast method where it has one, a measured, bounded approximation of
    * the exact one; an option without a fast method runs exact. An option's own record `fast` overrides this for that option
-   * only. `diagnostics.fast` reports what was requested and what ran. No option has a fast method yet, so every result is exact.
+   * only. `diagnostics.fast` reports what was requested and what ran. `lens.catalogue` has a fast method (#568); the other options run exact.
    */
   fast?: boolean;
   /** Aborting cancels the running task; the promise rejects with a domain error and returns no partial image. */

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

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

@@ -6,14 +6,15 @@ The package and root API versions are recorded once in [Navigation](../API_REFER
 
 Checks, before rendering, whether `lens.defocus: { model: "geometric-disc" }` can render a request: the geometric
 defocus disc's diameter on the site lattice, the kernel radius it needs, and whether that radius is within
-{@link DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES} (#532). Pure and cheap: no kernel is built and nothing is rendered.
+{@link DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES} (#532; 512 sites since 2.17.0, #564), and which convolution the renderers
+would use. Pure and cheap: no kernel is built and nothing is rendered.
 
 It runs the same resolution and the same limit test as `simulateCapture`, `simulateDisplayView` and `prepareDisplayView`
 (the blur circle c = f²·|s − d| / (N·d·(s − f)) of `calculateDefocusCircle`, thin-lens model 1.1.0, divided by the pitch),
 so for the same focal length, f-number, distances and pitch a request they refuse for its defocus size has
 `withinLimit: false`, and one they accept has `withinLimit: true`. Pass the values the capture uses: in an automatic
-exposure mode that is the resolved f-number. The limit applies to the disc alone; with `lens.diffraction` the combined
-kernel (diffraction radius plus defocus radius, at most 32 + 64 sites) has no further limit. Other reasons a capture
+exposure mode that is the resolved f-number. The limit applies to the disc alone; with `lens.diffraction` the diffraction
+kernel (at most 32 sites) is applied with it and has no further limit. Other reasons a capture
 refuses `lens.defocus` out of focus (pupil sampling, a caller PSF, camera rotation with a rolling shutter, a vignetting or
 distortion profile that does not reach the kernel's radius beyond the frame, and in the display view a projection,
 distortion, vignetting or rotation) are not checked here.
@@ -49,18 +50,19 @@ export interface CalculateDefocusDiscKernelRadiusInput {
 
 ## DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES
 
-Largest kernel radius in sites of `lens.defocus: { model: "geometric-disc" }`, R ≤ 64: a disc of at most 129 sites
-across (a 129 × 129 window, 16 641 taps per site; the diffraction kernels stop at 32). `simulateCapture`,
-`simulateDisplayView` and `prepareDisplayView` refuse a request whose disc needs more, and never clip the disc; check a
-request first with {@link calculateDefocusDiscKernelRadius}.
+Largest kernel radius in sites of `lens.defocus: { model: "geometric-disc" }`, R ≤ 512 (#564, 2.17.0; 64 before): a disc of
+at most 1025 sites across (6.15 mm at 6 µm). `simulateCapture`, `simulateDisplayView` and `prepareDisplayView` refuse a
+request whose disc needs more, and never clip the disc; check a request first with {@link calculateDefocusDiscKernelRadius}.
 
-Set from the cost measured in the capture (#492, step 2a; docs/QUICK_START.md, "Optics"): the capture's time grows with
-R² at every site the disc sees an edge from, and a 0.7 MP Siemens star took 0.37 s in focus, 2.9 s at R = 32, 4.7 s at
-R = 41 and 11.6 s at R = 64 (Node, one thread). 64 keeps the issue's 1.4 µm example (50 mm f/2.8, subject 2 m, focus
-1.6 m: R = 41) with room for larger blurs, at a cost the caller chooses and the docs state; past it the call fails.
+Up to 64 sites the disc is convolved directly ((2R + 1)² taps per site,
+byte-identical to 2.16.0). Above it the renderers use the exact run convolution (`site-kernel-runs.ts`: one prefix-sum
+difference per kernel row plus the cells the circle crosses, about 12·R reads per site), whose cost grows with R instead of
+R². 512 bounds that cost (6,145 reads per site, below the 16,641 taps of the direct gather at 64), the kernel's own
+memory ((2R + 1)² doubles, 8.4 MB) and each tile's source ((64 + 2R)² doubles per field, 9.5 MB): measured in
+docs/QUICK_START.md, "Optics".
 
 ```ts
-DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES = 64
+DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES = 512
 ```
 
 ## DefocusDiscKernelRadius
@@ -75,13 +77,18 @@ export interface DefocusDiscKernelRadius {
   diameterSites: number;
   /** Kernel radius R in sites the renderer needs for this disc, ⌈c / (2·pitch) − ½⌉ (0 for a disc inside one site, and in focus). */
   kernelRadiusSites: number;
-  /** {@link DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES}, 64. */
+  /** {@link DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES}, 512 (64 before 2.17.0). */
   maximumKernelRadiusSites: number;
-  /** Largest disc diameter in sites within the limit, 2·64 + 1 = 129: within the limit exactly when `diameterSites` ≤ 129. */
+  /** Largest disc diameter in sites within the limit, 2·512 + 1 = 1025: within the limit exactly when `diameterSites` ≤ 1025. */
   maximumDiameterSites: number;
   /** True when `kernelRadiusSites` ≤ `maximumKernelRadiusSites`: `lens.defocus` renders the request; false: it refuses it. */
   withinLimit: boolean;
-  /** How far past the limit the kernel radius is, max(0, R − 64) sites; 0 when within the limit. */
+  /** How far past the limit the kernel radius is, max(0, R − 512) sites; 0 when within the limit. */
   excessKernelRadiusSites: number;
+  /**
+   * How the renderers convolve this disc (#564): `"direct"` for a kernel radius up to 64 sites (as in 2.16.0; also in focus),
+   * `"runs"` above it (the exact run convolution, cost about proportional to R per site), null past the limit.
+   */
+  convolution: "direct" | "runs" | null;
 }
 ```