@photivra/engine 2.19.0 → 2.21.0

package/dist/motion/subject-motion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject-motion.js","sourceRoot":"","sources":["../../src/motion/subject-motion.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Subject motion (#551, 2.22.0): the whole scene, or one declared rectangle of it, moving on the scene plane during the\n * exposure, over a still background. Translation in m/s on the plane and, optionally, a constant rotation about an axis\n * parallel to the optical axis (through the plane's origin for the whole scene, through the rectangle's centre for a\n * region). Times are seconds from the first opening reference, the camera rotation's time reference, so each site's own\n * exposure window (shifted by its rolling-shutter offset) sees the subject where it is during that window.\n *\n * The scene at plane point p and time t: a point of the subject at rest point q is at R(θ)(q − c) + c + d at time t\n * (d = v·t, θ = ω·t, c the centre), so p shows the subject's q = R(−θ)(p − c − d) + c when q lies in the subject; else\n * a region's rest rectangle shows a neutral 18 % background (what the subject revealed), and anywhere else the still scene at p. Exact for this\n * model (rigid motion of a planar layer); the blur is the capture's temporal midpoint quadrature.\n * @see docs/QUICK_START.md, \"Subject motion\".\n */\n\nimport type { PlanarSceneRadianceProvider } from \"../facade/scene-radiance.js\";\nimport type { SceneRadianceEvaluationRequest, SceneRadianceEvaluationResult } from \"../schema/scene-radiance.js\";\n\n/** `motion.subject` of `simulateCapture`: a moving subject on the scene plane (#551). */\nexport interface SimulateCaptureSubjectMotion {\n  /** Velocity on the scene plane, m/s: +x right, +y up as seen from the camera. Missing components are 0. */\n  velocityMPerSec?: { x?: number; y?: number };\n  /** Rotation about the optical axis direction, rad/s, counter-clockwise as seen from the camera (+x toward +y). Default 0. */\n  angularVelocityRadPerSec?: number;\n  /**\n   * The moving part: a rectangle on the scene plane at rest (at the first opening reference), its centre and size in metres\n   * (+x right, +y up from the optical axis). Omitted: the whole scene moves.\n   */\n  region?: { centerXM: number; centerYM: number; widthM: number; heightM: number };\n  /** Exact or fast (2.20.0 convention): fast takes fewer temporal midpoints when the subject's streak is short (see the docs). */\n  fast?: boolean;\n}\n\n/** Internal: a validated subject motion (simulate-capture.ts parses it). */\nexport interface SubjectMotion {\n  vx: number; vy: number; omega: number;\n  /** The region's centre and half sizes in metres, or undefined for the whole scene. */\n  region: { cx: number; cy: number; hw: number; hh: number } | undefined;\n}\n\n/**\n * The farthest any subject point travels on the plane during `seconds`, in metres (translation plus rotation at the subject's\n * farthest point from its centre; `reachM` is the whole scene's reach from the axis when no region is declared).\n */\nexport function subjectTravelM(motion: SubjectMotion, seconds: number, reachM: number): number {\n  const r = motion.region, arm = r ? Math.hypot(r.hw, r.hh) : reachM;\n  return (Math.hypot(motion.vx, motion.vy) + Math.abs(motion.omega) * arm) * seconds;\n}\n\n/**\n * The plane point that shows at (x, y) at time t (in the motion's length unit), written to out[0], out[1]; returns false where a region's rest\n * rectangle shows the revealed background. Without motion at t (d = 0, θ = 0) the point is (x, y) unchanged, bit for bit.\n */\nexport function subjectSourcePoint(motion: SubjectMotion, x: number, y: number, t: number, out: Float64Array): boolean {\n  const r = motion.region, th = motion.omega * t;\n  let qx = x - motion.vx * t, qy = y - motion.vy * t;\n  if (th !== 0) {\n    const cx = r ? r.cx : 0, cy = r ? r.cy : 0, c = Math.cos(th), s = Math.sin(th), dx = qx - cx, dy = qy - cy;\n    qx = c * dx + s * dy + cx; qy = c * dy - s * dx + cy;\n  }\n  if (r && !(Math.abs(qx - r.cx) <= r.hw && Math.abs(qy - r.cy) <= r.hh)) {\n    out[0] = x; out[1] = y;\n    return !(Math.abs(x - r.cx) <= r.hw && Math.abs(y - r.cy) <= r.hh);\n  }\n  out[0] = qx; out[1] = qy;\n  return true;\n}\n\n/**\n * The scene of `base` with the subject moving: `evaluateRadiance` reads each query at its request time (the base result, with the\n * radiance read where the subject shows), and `radianceAt` takes the time as a fourth argument (default 0) for the image-space\n * lattices and the display view. It has no chart material access, so renderers read radiance. `revealedRadiance` is the revealed\n * background's spectral radiance at a plane point in frame units (an 18 % neutral reflectance under the irradiance there).\n */\nexport function createSubjectMotionProvider(base: PlanarSceneRadianceProvider, motion: SubjectMotion, distanceM: number, scale: number,\n  revealedRadiance: (u: number, v: number, nm: number) => number): PlanarSceneRadianceProvider {\n  // The motion in frame units, so a still instant reads the base at the queried point itself.\n  const r = motion.region, framed: SubjectMotion = { vx: motion.vx / scale, vy: motion.vy / scale, omega: motion.omega,\n    region: r && { cx: r.cx / scale, cy: r.cy / scale, hw: r.hw / scale, hh: r.hh / scale } }, point = new Float64Array(2);\n  const radianceAt = (u: number, v: number, nm: number, t = 0): number =>\n    subjectSourcePoint(framed, u, v, t, point) ? base.radianceAt(point[0]!, point[1]!, nm) : revealedRadiance(u, v, nm);\n  return { sceneId: base.sceneId, providerProfileId: base.providerProfileId, radianceAt, evaluateApertureRadiance: base.evaluateApertureRadiance,\n    evaluateRadiance(request: Readonly<SceneRadianceEvaluationRequest>): SceneRadianceEvaluationResult {\n      const result = base.evaluateRadiance(request), o = (request.target as { outgoingDirectionUnitVector: { x: number; y: number; z: number } }).outgoingDirectionUnitVector;\n      if (!(o.z < 0)) return result;\n      // The base provider's own plane-point arithmetic for this direction.\n      const t = distanceM / -o.z;\n      return { ...result, spectralRadianceWattsPerSquareMeterSteradianNanometer: radianceAt(-o.x * t / scale, -o.y * t / scale, request.wavelengthNanometers, request.timeSecondsFromExposureStart) };\n    } };\n}\n"]}

package/dist/optics/aperture-diameter.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Entrance-pupil (aperture) diameter of a lens from its focal length and f-number.
+ *
+ * The f-number is defined as N = f/D, with f the focal length and D the entrance-pupil diameter,
+ * for an object at infinity (Greivenkamp, OPTI-502 course notes, sec. 12 (Objectives), free:
+ * https://wp.optics.arizona.edu/jgreivenkamp/wp-content/uploads/sites/11/2019/08/502-12-Objectives.pdf).
+ * So D = f/N is exact by that definition. It is the diameter of the entrance pupil, the image of
+ * the aperture stop seen from the front of the lens, not of the physical diaphragm opening.
+ *
+ * At close focus the f-number that sets exposure and diffraction is the working f-number
+ * N_w = N·(1 + m/P), with m the magnification and P the pupil magnification (exit-pupil over
+ * entrance-pupil diameter); a lens that focuses by changing its focal length changes f, and with
+ * it D at the same marked N. Neither is modeled here; the
+ * engine's own close-focus light factor, N·(1 + m) with unit pupil magnification, is in
+ * `calculateSceneRadianceToSensorIrradiance`.
+ * @see docs/PHYSICS_FOUNDATION.md "Aperture (entrance-pupil) diameter".
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+export interface CalculateApertureDiameterInput {
+    /** Focal length of the lens in millimetres (the physical focal length, not a 35 mm equivalent). */
+    focalLengthMm: number;
+    /** f-number set on the lens (N = focal length / entrance-pupil diameter). */
+    fNumber: number;
+}
+export interface ApertureDiameter {
+    /** Focal length supplied by the caller, in millimetres. */
+    focalLengthMm: number;
+    /** f-number supplied by the caller. */
+    fNumber: number;
+    /** Entrance-pupil diameter D = focalLengthMm / fNumber, in millimetres. */
+    entrancePupilDiameterMm: number;
+}
+/**
+ * Entrance-pupil (aperture) diameter in millimetres: focal length ÷ f-number.
+ *
+ * Exact by the definition of the f-number for an ideal lens focused at infinity. It is the
+ * entrance pupil (the aperture stop as seen from the front), not the diaphragm's physical
+ * opening. Close focus (working f-number N·(1 + m/P) with pupil magnification P) and focal-length
+ * changes while focusing are not modelled.
+ *
+ * Example: 50 mm at f/2 gives 25 mm; at f/4, 12.5 mm (half the diameter, a quarter of the area:
+ * two stops).
+ *
+ * @param input Focal length in millimetres and f-number.
+ * @returns The entrance-pupil diameter with the inputs.
+ */
+export declare function calculateApertureDiameter(input: CalculateApertureDiameterInput): CalculationResult<ApertureDiameter>;

package/dist/optics/aperture-diameter.js

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Entrance-pupil (aperture) diameter of a lens from its focal length and f-number.
+ *
+ * The f-number is defined as N = f/D, with f the focal length and D the entrance-pupil diameter,
+ * for an object at infinity (Greivenkamp, OPTI-502 course notes, sec. 12 (Objectives), free:
+ * https://wp.optics.arizona.edu/jgreivenkamp/wp-content/uploads/sites/11/2019/08/502-12-Objectives.pdf).
+ * So D = f/N is exact by that definition. It is the diameter of the entrance pupil, the image of
+ * the aperture stop seen from the front of the lens, not of the physical diaphragm opening.
+ *
+ * At close focus the f-number that sets exposure and diffraction is the working f-number
+ * N_w = N·(1 + m/P), with m the magnification and P the pupil magnification (exit-pupil over
+ * entrance-pupil diameter); a lens that focuses by changing its focal length changes f, and with
+ * it D at the same marked N. Neither is modeled here; the
+ * engine's own close-focus light factor, N·(1 + m) with unit pupil magnification, is in
+ * `calculateSceneRadianceToSensorIrradiance`.
+ * @see docs/PHYSICS_FOUNDATION.md "Aperture (entrance-pupil) diameter".
+ */
+import { calculatedResult } from "../core/calculation-result.js";
+import { requireInputKeys } from "../core/record-validation.js";
+import { InvalidScientificResultError, requirePositiveFinite } from "../core/validation.js";
+/**
+ * Entrance-pupil (aperture) diameter in millimetres: focal length ÷ f-number.
+ *
+ * Exact by the definition of the f-number for an ideal lens focused at infinity. It is the
+ * entrance pupil (the aperture stop as seen from the front), not the diaphragm's physical
+ * opening. Close focus (working f-number N·(1 + m/P) with pupil magnification P) and focal-length
+ * changes while focusing are not modelled.
+ *
+ * Example: 50 mm at f/2 gives 25 mm; at f/4, 12.5 mm (half the diameter, a quarter of the area:
+ * two stops).
+ *
+ * @param input Focal length in millimetres and f-number.
+ * @returns The entrance-pupil diameter with the inputs.
+ */
+export function calculateApertureDiameter(input) {
+    requireInputKeys(input, "calculateApertureDiameter", ["focalLengthMm", "fNumber"]);
+    requirePositiveFinite("focalLengthMm", input.focalLengthMm);
+    requirePositiveFinite("fNumber", input.fNumber);
+    const entrancePupilDiameterMm = input.focalLengthMm / input.fNumber;
+    if (!(entrancePupilDiameterMm > 0) || !Number.isFinite(entrancePupilDiameterMm)) {
+        throw new InvalidScientificResultError("entrancePupilDiameterMm must be a finite number greater than zero.");
+    }
+    return calculatedResult({ focalLengthMm: input.focalLengthMm, fNumber: input.fNumber, entrancePupilDiameterMm }, "aperture-diameter", "1.0.0", [
+        "Entrance-pupil diameter D = f/N, exact by the definition of the f-number for an object at infinity.",
+        "Ideal lens focused at infinity: close-focus working f-number N·(1 + m/P), pupil magnification P and focus breathing are not modelled.",
+        "D is the entrance pupil (the aperture stop seen from the front of the lens), not the physical diaphragm opening."
+    ]);
+}
+//# sourceMappingURL=aperture-diameter.js.map

package/dist/optics/aperture-diameter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aperture-diameter.js","sourceRoot":"","sources":["../../src/optics/aperture-diameter.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,gBAAgB,EAA0B,MAAM,+BAA+B,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,4BAA4B,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAkB5F;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAqC;IAErC,gBAAgB,CAAC,KAAK,EAAE,2BAA2B,EAAE,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC,CAAC;IACnF,qBAAqB,CAAC,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAC5D,qBAAqB,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAChD,MAAM,uBAAuB,GAAG,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC;IACpE,IAAI,CAAC,CAAC,uBAAuB,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAAC,EAAE,CAAC;QAChF,MAAM,IAAI,4BAA4B,CAAC,oEAAoE,CAAC,CAAC;IAC/G,CAAC;IACD,OAAO,gBAAgB,CACrB,EAAE,aAAa,EAAE,KAAK,CAAC,aAAa,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,uBAAuB,EAAE,EACvF,mBAAmB,EACnB,OAAO,EACP;QACE,qGAAqG;QACrG,uIAAuI;QACvI,kHAAkH;KACnH,CACF,CAAC;AACJ,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Entrance-pupil (aperture) diameter of a lens from its focal length and f-number.\n *\n * The f-number is defined as N = f/D, with f the focal length and D the entrance-pupil diameter,\n * for an object at infinity (Greivenkamp, OPTI-502 course notes, sec. 12 (Objectives), free:\n * https://wp.optics.arizona.edu/jgreivenkamp/wp-content/uploads/sites/11/2019/08/502-12-Objectives.pdf).\n * So D = f/N is exact by that definition. It is the diameter of the entrance pupil, the image of\n * the aperture stop seen from the front of the lens, not of the physical diaphragm opening.\n *\n * At close focus the f-number that sets exposure and diffraction is the working f-number\n * N_w = N·(1 + m/P), with m the magnification and P the pupil magnification (exit-pupil over\n * entrance-pupil diameter); a lens that focuses by changing its focal length changes f, and with\n * it D at the same marked N. Neither is modeled here; the\n * engine's own close-focus light factor, N·(1 + m) with unit pupil magnification, is in\n * `calculateSceneRadianceToSensorIrradiance`.\n * @see docs/PHYSICS_FOUNDATION.md \"Aperture (entrance-pupil) diameter\".\n */\n\nimport { calculatedResult, type CalculationResult } from \"../core/calculation-result.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidScientificResultError, requirePositiveFinite } from \"../core/validation.js\";\n\nexport interface CalculateApertureDiameterInput {\n  /** Focal length of the lens in millimetres (the physical focal length, not a 35 mm equivalent). */\n  focalLengthMm: number;\n  /** f-number set on the lens (N = focal length / entrance-pupil diameter). */\n  fNumber: number;\n}\n\nexport interface ApertureDiameter {\n  /** Focal length supplied by the caller, in millimetres. */\n  focalLengthMm: number;\n  /** f-number supplied by the caller. */\n  fNumber: number;\n  /** Entrance-pupil diameter D = focalLengthMm / fNumber, in millimetres. */\n  entrancePupilDiameterMm: number;\n}\n\n/**\n * Entrance-pupil (aperture) diameter in millimetres: focal length ÷ f-number.\n *\n * Exact by the definition of the f-number for an ideal lens focused at infinity. It is the\n * entrance pupil (the aperture stop as seen from the front), not the diaphragm's physical\n * opening. Close focus (working f-number N·(1 + m/P) with pupil magnification P) and focal-length\n * changes while focusing are not modelled.\n *\n * Example: 50 mm at f/2 gives 25 mm; at f/4, 12.5 mm (half the diameter, a quarter of the area:\n * two stops).\n *\n * @param input Focal length in millimetres and f-number.\n * @returns The entrance-pupil diameter with the inputs.\n */\nexport function calculateApertureDiameter(\n  input: CalculateApertureDiameterInput\n): CalculationResult<ApertureDiameter> {\n  requireInputKeys(input, \"calculateApertureDiameter\", [\"focalLengthMm\", \"fNumber\"]);\n  requirePositiveFinite(\"focalLengthMm\", input.focalLengthMm);\n  requirePositiveFinite(\"fNumber\", input.fNumber);\n  const entrancePupilDiameterMm = input.focalLengthMm / input.fNumber;\n  if (!(entrancePupilDiameterMm > 0) || !Number.isFinite(entrancePupilDiameterMm)) {\n    throw new InvalidScientificResultError(\"entrancePupilDiameterMm must be a finite number greater than zero.\");\n  }\n  return calculatedResult(\n    { focalLengthMm: input.focalLengthMm, fNumber: input.fNumber, entrancePupilDiameterMm },\n    \"aperture-diameter\",\n    \"1.0.0\",\n    [\n      \"Entrance-pupil diameter D = f/N, exact by the definition of the f-number for an object at infinity.\",\n      \"Ideal lens focused at infinity: close-focus working f-number N·(1 + m/P), pupil magnification P and focus breathing are not modelled.\",\n      \"D is the entrance pupil (the aperture stop seen from the front of the lens), not the physical diaphragm opening.\"\n    ]\n  );\n}\n"]}

package/dist/optics/detail-limit.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Which limits detail for given settings: the lens (diffraction at this f-number, aberrations, defocus) or the sensor's pixel
+ * pitch (#575, for the app's Learn section).
+ *
+ * Model (`detail-limit` 1.0.0; the decision rule is an approximation, see below):
+ * - **Optics.** The incoherent optical transfer function of a uniformly lit circular pupil carrying the wavefront W (in waves)
+ *   is the normalized autocorrelation of the pupil function P = exp(i·2π·W):
+ *   OTF(s) = (1/π)∫∫ P(ρ + s·e)·P*(ρ − s·e) d²ρ over the overlap of the two unit discs, s = ν/ν_c, ν_c = 1/(λ·N_w), N_w the
+ *   working f-number (thin-lens image distance / pupil diameter). With W = 0 it is the diffraction-limited
+ *   (2/π)(acos s − s√(1 − s²)) (MIT OpenCourseWare 2.71 Optics, Spring 2009, lectures 21–22, free; also see Goodman,
+ *   Introduction to Fourier Optics, 4th ed., §7.3–7.4). The integral is evaluated by Gauss–Legendre quadrature on a smooth
+ *   parametrisation of the overlap (√ edge removed), with node counts that grow with the phase variation; MTF = |OTF|.
+ * - **Wavefront.** `lens.ideal`: none. `lens.catalogue`: the lens's resolved Seidel terms (`resolveGenericLens`, the same
+ *   expansion as its PSF: Hopkins 1950; Wyant & Creath 1992, Applied Optics and Optical Engineering XI ch. 1, free author copy)
+ *   at the field height H, with axial color at the wavelength. Defocus of a subject away from the focus distance adds
+ *   W020 = dz/(8·N_w²), dz = sensor minus image distance (thin lens; `calculateDefocusWavefront`, Wyant & Creath eq. 18).
+ * - **Sampling.** Nyquist frequency 1/(2p) for pixel pitch p (exact for the lattice); a Bayer filter's red and blue sites
+ *   repeat every 2p, so their Nyquist frequency is 1/(4p), while its green sites still sample rows and columns up to 1/(2p).
+ *   Pixel aperture MTF |sinc(ν·p)| for a square, fully sensitive site (fill factor 1, an idealisation).
+ * - **Decision (approximation).** The sensor limits when the optics still pass at least 50 % contrast at the Nyquist
+ *   frequency (optics MTF50 ≥ 1/(2p)): a denser sensor would record finer detail. Otherwise the lens limits, and the cause is
+ *   diffraction when the wavefront error is within the Maréchal criterion (RMS ≤ λ/14, Strehl ≈ 0.8; Wyant & Creath 1992
+ *   eq. 67), else aberrations or defocus, whichever has the larger RMS wavefront error.
+ * @see docs/PHYSICS_FOUNDATION.md "Which limits detail: the lens or the sensor" for the equations, exactness and limits.
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+/**
+ * Limits of `calculateDetailLimit`: the wavelength range and the largest wavefront (sum of the magnitudes of its terms, in
+ * waves) whose transfer function is integrated. Beyond it the blur is geometric and the quadrature would grow without
+ * bound; use `calculateDefocusCircle` for such a blur.
+ */
+export declare const DETAIL_LIMIT_LIMITS: Readonly<{
+    minimumWavelengthNm: 380;
+    maximumWavelengthNm: 780;
+    maximumWavefrontWaves: 64;
+}>;
+/** A lens with no aberrations (diffraction only). */
+export interface DetailLimitIdealLens {
+    kind: "ideal";
+    /** Physical focal length in millimeters (for the working f-number and the defocus of a subject off the focus distance). */
+    focalLengthMm: number;
+}
+/** A generic catalogue lens (`GENERIC_LENS_IDS`), resolved for the sensor as `resolveGenericLens` does. */
+export interface DetailLimitCatalogueLens {
+    kind: "catalogue";
+    lensId: string;
+}
+export interface CalculateDetailLimitInput {
+    /** Active imaging area and horizontal pixel count; pitch = widthMm / pixelWidth. */
+    sensor: {
+        widthMm: number;
+        heightMm: number;
+        pixelWidth: number;
+        /** Default `"bayer"`. `"none"`: every site records full detail (a monochrome sensor). */
+        colorFilterArray?: "bayer" | "none";
+    };
+    lens: DetailLimitIdealLens | DetailLimitCatalogueLens;
+    /** f-number set on the lens. */
+    fNumber: number;
+    /**
+     * Focus and subject distances from the lens in meters. Omitted: focused at infinity, subject in focus. `subjectDistanceM`
+     * omitted: the subject is at the focus distance.
+     */
+    focus?: {
+        focusDistanceM: number;
+        subjectDistanceM?: number;
+    };
+    /** Field height as a fraction of the half-diagonal, 0 (center, default) to 1 (corner). Only aberrations depend on it. */
+    fieldPosition?: number;
+    /** Wavelength in nanometres, 380–780. Default 550. */
+    wavelengthNm?: number;
+}
+/** Which component limits detail. */
+export type DetailLimitedBy = "lens" | "sensor";
+/** What limits it: the lens's diffraction, aberrations or defocus, or the sensor's pixel pitch. */
+export type DetailLimitingFactor = "diffraction" | "aberrations" | "defocus" | "pixel-pitch";
+export interface DetailLimitOptics {
+    /** Working f-number N_w = N·v/f (thin-lens image distance v; N at infinity focus). */
+    workingFNumber: number;
+    /** Diffraction cut-off 1/(λ·N_w) in cycles/mm: no optics passes detail beyond it. */
+    cutoffCyclesPerMm: number;
+    /** Frequency where the optics' MTF falls to 0.5, the lower of the two directions, cycles/mm. */
+    mtf50CyclesPerMm: number;
+    /** MTF50 for detail along the radius from the image center (tangential), cycles/mm. */
+    tangentialMtf50CyclesPerMm: number;
+    /** MTF50 for detail across the radius (sagittal), cycles/mm. Equal to the tangential value at the center. */
+    sagittalMtf50CyclesPerMm: number;
+    /** MTF50 of an aberration-free lens in focus at the same working f-number (0.40397·cut-off), cycles/mm. */
+    diffractionMtf50CyclesPerMm: number;
+    /** Optics MTF at the sensor's Nyquist frequency (lower direction). */
+    mtfAtNyquist: number;
+    /** RMS wavefront error in waves at the wavelength: of the aberrations, of the defocus, and of both together. */
+    rmsWavefrontErrorWaves: {
+        aberrations: number;
+        defocus: number;
+        total: number;
+    };
+    /** Whether the total RMS wavefront error is within the Maréchal criterion λ/14. */
+    withinMarechalCriterion: boolean;
+    /** Geometric blur-circle diameter of the defocus on the sensor, mm (0 in focus). */
+    defocusBlurDiameterMm: number;
+}
+export interface DetailLimitSampling {
+    colorFilterArray: "bayer" | "none";
+    /** Pixel pitch in micrometres: widthMm / pixelWidth. */
+    pixelPitchMicrometers: number;
+    /** 1/(2p), cycles/mm: the finest detail the pixel grid records without aliasing (Bayer green sites too, along rows and columns). */
+    nyquistCyclesPerMm: number;
+    /** Bayer only: 1/(4p), the Nyquist frequency of the red and blue sites. Null without a color filter array. */
+    redBlueNyquistCyclesPerMm: number | null;
+    /** Pixel aperture MTF at the Nyquist frequency: sinc(1/2) = 2/π. */
+    pixelApertureMtfAtNyquist: number;
+    /** Frequency where the pixel aperture MTF falls to 0.5 (0.60335/p), cycles/mm: beyond the Nyquist frequency. */
+    pixelApertureMtf50CyclesPerMm: number;
+}
+export interface DetailLimitSystem {
+    /** MTF50 of optics × pixel aperture (lower direction), cycles/mm. Detail above the Nyquist frequency aliases. */
+    mtf50CyclesPerMm: number;
+    /** The same in line pairs per picture height (cycles/mm × heightMm). */
+    mtf50LinePairsPerPictureHeight: number;
+    /** System MTF at the Nyquist frequency (lower direction). */
+    mtfAtNyquist: number;
+}
+/** Whether a quantity is exact under its stated conditions or an approximation. */
+export interface DetailLimitBasis {
+    kind: "exact" | "approximation";
+    statement: string;
+}
+export interface DetailLimit {
+    /** The lens or the sensor. */
+    limitedBy: DetailLimitedBy;
+    /** Diffraction, aberrations or defocus (the lens), or the pixel pitch (the sensor). */
+    limitingFactor: DetailLimitingFactor;
+    /** Optics MTF50 / Nyquist frequency: at least 1 when the sensor limits. */
+    opticsToNyquistRatio: number;
+    fNumber: number;
+    wavelengthNm: number;
+    /** Physical focal length used (the catalogue lens's on this sensor), mm. */
+    focalLengthMm: number;
+    fieldPosition: number;
+    optics: DetailLimitOptics;
+    sampling: DetailLimitSampling;
+    system: DetailLimitSystem;
+    /**
+     * The f-number at which an aberration-free lens in focus has its MTF50 at the Nyquist frequency (2·p·0.40397/λ at
+     * infinity focus): from it on, diffraction limits detail on this sensor whatever the lens.
+     */
+    diffractionLimitedFNumber: number;
+    basis: Readonly<Record<"optics" | "sampling" | "system" | "limitedBy", DetailLimitBasis>>;
+}
+/** @internal Seidel and defocus terms of the wavefront in waves at the wavelength, field along +y. */
+export interface DetailLimitWavefront {
+    defocus: number;
+    spherical: number;
+    coma: number;
+    astigmatism: number;
+    fieldCurvature: number;
+}
+/**
+ * @internal |OTF| at normalized frequency s (0 ≤ s < 1) along the pupil's x axis (`tangential` false) or y axis (true). The overlap
+ * |ρ ± s·e| ≤ 1 is |a| ≤ 1 − s, |b| ≤ √(1 − (|a| + s)²) in coordinates (a along e, b across); |a| = (1 − s)(1 − τ²) removes
+ * the square-root edge, so the integrand is smooth in τ and in b/b_max.
+ */
+export declare function detailLimitOpticsMtf(w: DetailLimitWavefront, s: number, tangential: boolean, nodeScale?: number): number;
+/**
+ * Which limits detail for given settings: the lens (diffraction at this f-number, aberrations, defocus) or the sensor's pixel
+ * pitch. Returns the optics' resolution (MTF50 and the diffraction cut-off, cycles/mm), the sampling's (Nyquist frequency
+ * and, with a Bayer filter, the red and blue sites'), the system MTF50 (optics × pixel aperture), the f-number from which
+ * diffraction limits on this sensor, and which one limits.
+ *
+ * The sensor limits when the optics still pass 50 % contrast at the Nyquist frequency 1/(2p); otherwise the lens does,
+ * through diffraction when its wavefront error is within the Maréchal criterion (RMS ≤ λ/14), else through aberrations or
+ * defocus. The optics MTF is the exact scalar OTF of the stated wavefront at one wavelength; the decision rule and the
+ * catalogue lenses' wavefronts are approximations.
+ *
+ * Example: an ideal 50 mm lens at f/22 on a 36 × 24 mm, 6000-pixel-wide sensor (6 µm) is limited by diffraction (optics
+ * MTF50 ≈ 33 cycles/mm against a Nyquist frequency of ≈ 83); at f/4 the pixel pitch limits.
+ *
+ * @param input Sensor, lens, f-number, and optional focus, field position and wavelength.
+ * @returns The resolution of the optics and of the sampling, and which limits detail.
+ */
+export declare function calculateDetailLimit(input: CalculateDetailLimitInput): CalculationResult<DetailLimit>;