@photivra/engine 2.16.0 → 2.18.0

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,8 +21,11 @@
 - [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
+- [calculateSensorEquivalence()](https://github.com/Photivra/photivra/blob/main/docs/api/camera-sensor-equivalence.md#calculatesensorequivalence): equivalent focal length and f-number, sensor area ratio and angles of view of a lens on one sensor, each marked exact or approximated
+- [calculateBlurShareOfFrame()](https://github.com/Photivra/photivra/blob/main/docs/api/camera-sensor-equivalence.md#calculateblurshareofframe): a blur circle as a share of the frame diagonal, or its size on a print
 - [calculateCenteredCrop()](https://github.com/Photivra/photivra/blob/main/docs/api/output-crop.md#calculatecenteredcrop): pixels left after a centred crop
 - [calculateProjectedMotionBlur()](https://github.com/Photivra/photivra/blob/main/docs/api/motion-projected-motion.md#calculateprojectedmotionblur): how far a moving subject smears on the sensor during the shutter time
 - [calculateAiryDisk()](https://github.com/Photivra/photivra/blob/main/docs/api/optics-diffraction.md#calculateairydisk): diffraction spot size from f-number and wavelength

package/package.json

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