@photivra/engine 2.17.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
@@ -7479,8 +7481,9 @@ own designs, not real products). `resolveGenericLens` resolves one for a sensor,
 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)). Equations, tables and the chart measurements:
-[LENS_CATALOGUE.md](https://github.com/Photivra/photivra/blob/main/docs/LENS_CATALOGUE.md).
+([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";
@@ -7999,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.17.0" as const
+ENGINE_API_VERSION = "2.18.0" as const
 ```

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.17.0",
-  "engineApiVersion": "2.17.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",
@@ -1287,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",
@@ -2957,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",
@@ -3892,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",
@@ -7827,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",
@@ -8512,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",

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

@@ -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,18 @@ 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
@@ -522,9 +542,12 @@ export interface SimulateCaptureOptions {
      * 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.
+     * 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;
+    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.
@@ -748,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/llms.txt

@@ -24,6 +24,8 @@
 - [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.17.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",