@photivra/engine 2.15.0 → 2.17.0

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

@@ -6,16 +6,18 @@ 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
-refuses `lens.defocus` out of focus (camera rotation, projection, distortion, vignetting, pupil sampling, a caller PSF)
-are not checked here.
+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.
 
 The blur circle is a geometric thin-lens approximation for an ideal uniform circular pupil (no diffraction, aberrations
 or pupil vignetting). Inputs follow `calculateDefocusCircle`: all positive and finite, both distances beyond the focal
@@ -48,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
@@ -74,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;
 }
 ```

package/docs/api/optics-sensor-environment-query.md

@@ -57,6 +57,12 @@ export interface EnvironmentLensFieldMapping {
     | { kind: "radial"; profile: RadialDistortionProfile }
     | { kind: "brown-conrady"; profile: BrownConradyDistortionProfile };
   radiometricAreaCorrection: "inverse-distortion-jacobian";
+  /**
+   * #549, optional: what an ideal image point outside a radial projection's image circle (for example beyond r = 2f of the
+   * equisolid fisheye) does. Omitted: the query fails, as before. `"backward-ray"`: the query looks straight back (0, 0, −1),
+   * a direction no forward scene answers, so a provider that treats directions beyond 90° as empty gives it zero radiance.
+   */
+  outsideImageCircle?: "backward-ray";
 }
 ```
 

package/docs/api/output-generic-lens-corrections.md

@@ -0,0 +1,39 @@
+# output/generic-lens-corrections.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.
+
+## createGenericLensCorrectionProfile
+
+Builds the catalogue lens's generic correction profile for one camera state: a radial distortion map (the lens's own
+r_d = r(1 + k1ρ²), read at each ideal destination point), per-channel lateral-colour scales 1 + L·D(λ_channel), and the
+relative-illumination gain at the state's aperture (strength 1). The result passes `parseGenericLensCorrectionProfile`.
+
+```ts
+export function createGenericLensCorrectionProfile(input: CreateGenericLensCorrectionProfileInput): GenericLensCorrectionProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateGenericLensCorrectionProfileInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateGenericLensCorrectionProfileInput {
+  /** A catalogue id (`GENERIC_LENS_IDS`); `state.lensId` must be the same id. */
+  lensId: string;
+  /** The sensor's active capture area, mm (the lens is scaled to it as in `resolveGenericLens`). */
+  activeImagingArea: { widthMm: number; heightMm: number };
+  /** The exact camera state the profile applies to: its focal length must be the lens's on this sensor, its aperture in range. */
+  state: OpticalProfileState;
+}
+```
+
+## GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM
+
+Effective wavelengths of the red, green and blue channels for the lateral-colour map, nm: a generic approximation of where
+a camera's channel responses peak, not a measured camera.
+
+```ts
+GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM: Readonly<Record<LensCorrectionChannel, number>> = Object.freeze({ red: 610, green: 540, blue: 465 })
+```

package/llms.txt

@@ -21,6 +21,7 @@
 - [calculateDepthOfField()](https://github.com/Photivra/photivra/blob/main/docs/api/optics-depth-of-field.md#calculatedepthoffield): near and far limits and hyperfocal distance (thin lens)
 - [calculateDefocusCircle()](https://github.com/Photivra/photivra/blob/main/docs/api/optics-depth-of-field.md#calculatedefocuscircle): blur-circle size for an out-of-focus subject
 - [calculateDefocusDiscKernelRadius()](https://github.com/Photivra/photivra/blob/main/docs/api/optics-defocus-disc-kernel.md#calculatedefocusdisckernelradius): whether `lens.defocus` can render a blur before you render it (the 64-site limit)
+- [resolveGenericLens()](https://github.com/Photivra/photivra/blob/main/docs/api/equipment-generic-lens-catalogue.md#resolvegenericlens): one of the 30 generic catalogue lenses ("PV 50 1.2 Pro") on a sensor, with its approximated optical character; `simulateCapture` renders it with `lens.catalogue`
 - [calculateFieldOfView()](https://github.com/Photivra/photivra/blob/main/docs/api/camera-field-of-view.md#calculatefieldofview): angle of view from focal length and sensor size
 - [calculateEquivalentFocalLength35Mm()](https://github.com/Photivra/photivra/blob/main/docs/api/camera-equivalent-focal-length.md#calculateequivalentfocallength35mm): crop factor and 35 mm-equivalent focal length
 - [calculateCenteredCrop()](https://github.com/Photivra/photivra/blob/main/docs/api/output-crop.md#calculatecenteredcrop): pixels left after a centred crop

package/package.json

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