@photivra/engine 0.2.0 → 0.5.0

package/dist/index.js

@@ -5,23 +5,35 @@
  * This constant is intentionally independent of the package version so
  * schema/API compatibility can be discussed explicitly.
  */
-export const ENGINE_API_VERSION = "0.17.0";
+export const ENGINE_API_VERSION = "0.34.0";
 export { approximationResult, calibratedResult, calculatedResult, estimatedResult, validateCalculationQuality } from "./core/calculation-result.js";
 export { InvalidScientificInputError, InvalidScientificResultError } from "./core/validation.js";
-export { calculateFieldOfView } from "./camera/field-of-view.js";
+export { IMAGE_FORMATION_CONTRACT_VERSION, getImageFormationContract } from "./core/image-formation.js";
+export { calculateFieldOfView, calculateFieldOfViewBounds } from "./camera/field-of-view.js";
 export { calculateProjectedObjectSize } from "./camera/projected-object-size.js";
+export { calculateEquivalentFocalLength35Mm } from "./camera/equivalent-focal-length.js";
 export { calculatePixelPitch } from "./sensor/pixel-pitch.js";
+export { calculateImagingAreaMetrics, calculateSensorGeometryMetrics } from "./sensor/sensor-geometry.js";
+export { parseSensorArchitectureProfile } from "./sensor/architecture.js";
 export { calculateCenteredCrop } from "./output/crop.js";
 export { calculateSubjectFramingCrop } from "./output/subject-framing-crop.js";
+export { calculateActiveCaptureFieldOfView, calculateOutputFieldOfView, mapImagePlanePointToOrientedPhysicalUv, mapOrientedPhysicalUvToImagePlanePoint, resolveCaptureGeometry, transformNativeRasterPointToOriented, transformNativeRasterRectToOriented, transformNativeRasterVectorToOriented, transformOrientedRasterPointToNative, transformOrientedRasterRectToNative, transformOrientedRasterVectorToNative } from "./output/capture-geometry.js";
 export { calculateIdealApertureGeometry } from "./optics/aperture.js";
 export { calculateAiryDisk } from "./optics/diffraction.js";
 export { estimateEquivalentViewingCircleOfConfusion } from "./optics/circle-of-confusion.js";
 export { calculateThinLensImageDistance } from "./optics/thin-lens.js";
 export { calculateDefocusCircle, calculateDepthOfField } from "./optics/depth-of-field.js";
+export { calculateFocusBreathingFieldOfView, calculateFocusBreathingProjection } from "./optics/focus-breathing.js";
+export { calculateInverseRadialDistortionMapping, calculateInverseRadialDistortionMappings, calculateRadialDistortionMapping } from "./optics/radial-distortion.js";
+export { calculateInverseLateralChromaticAberrationMapping, calculateInverseLateralChromaticAberrationMappings, calculateLateralChromaticAberrationMapping } from "./optics/lateral-chromatic-aberration.js";
+export { calculateIlluminationVignetting } from "./optics/illumination-vignetting.js";
+export { PSF_FOUNDATION_VERSION, calculatePsfFoundationComponents, getPsfFoundationContract } from "./optics/psf-foundation.js";
 export { calculateProjectedMotionBlur } from "./motion/projected-motion.js";
+export { calculateCameraRotationImageMapping } from "./motion/camera-rotation.js";
 export { calculateEquivalentIso, calculateExposureValue100, calculateRelativeOpticalExposure, calculateRelativeRenderedExposure } from "./exposure/exposure.js";
 export { estimateCameraShakeBlur } from "./stabilization/camera-shake.js";
 export { calculatePhotoelectrons, calculateSignalToNoise } from "./sensor/signal-noise.js";
-export { simulatePocCamera } from "./simulation/poc-simulation.js";
+export { assessRadiometryReadiness, parseRadiometryReadinessProfile } from "./sensor/radiometry-readiness.js";
+export { POC_SIMULATION_API_VERSION, simulatePocCamera } from "./simulation/poc-simulation.js";
 export { InvalidConfigurationError, parseCameraConfiguration, parseSceneDefinition } from "./schema/validation.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,QAAiB,CAAC;AAEpD,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,0BAA0B,EAW3B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC7B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,oBAAoB,EAGrB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,4BAA4B,EAG7B,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,mBAAmB,EAGpB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,qBAAqB,EAGtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,2BAA2B,EAG5B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,8BAA8B,EAI/B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,iBAAiB,EAGlB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,0CAA0C,EAG3C,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,8BAA8B,EAG/B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EAKtB,MAAM,4BAA4B,CAAC;AAqBpC,OAAO,EACL,4BAA4B,EAG7B,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,gCAAgC,EAChC,iCAAiC,EAOlC,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,uBAAuB,EAIxB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EAIvB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,iBAAiB,EAGlB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,QAAiB,CAAC;AAEpD,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,0BAA0B,EAW3B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC7B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,gCAAgC,EAChC,yBAAyB,EAY1B,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAK3B,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,4BAA4B,EAG7B,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,kCAAkC,EAGnC,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EACL,mBAAmB,EAGpB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,2BAA2B,EAC3B,8BAA8B,EAO/B,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,8BAA8B,EAU/B,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,qBAAqB,EAGtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,2BAA2B,EAG5B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,iCAAiC,EACjC,0BAA0B,EAC1B,sCAAsC,EACtC,sCAAsC,EACtC,sBAAsB,EACtB,oCAAoC,EACpC,mCAAmC,EACnC,qCAAqC,EACrC,oCAAoC,EACpC,mCAAmC,EACnC,qCAAqC,EAmBtC,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,8BAA8B,EAI/B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,iBAAiB,EAGlB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,0CAA0C,EAG3C,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,8BAA8B,EAG/B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EAKtB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,kCAAkC,EAClC,iCAAiC,EAKlC,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,uCAAuC,EACvC,wCAAwC,EACxC,gCAAgC,EAUjC,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACL,iDAAiD,EACjD,kDAAkD,EAClD,0CAA0C,EAa3C,MAAM,0CAA0C,CAAC;AAElD,OAAO,EACL,+BAA+B,EAKhC,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EACL,sBAAsB,EACtB,gCAAgC,EAChC,wBAAwB,EAOzB,MAAM,4BAA4B,CAAC;AAqBpC,OAAO,EACL,4BAA4B,EAG7B,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,mCAAmC,EAMpC,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,gCAAgC,EAChC,iCAAiC,EAOlC,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,uBAAuB,EAIxB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EAIvB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,yBAAyB,EACzB,+BAA+B,EAchC,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EAGlB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,wBAAwB,CAAC"}

package/dist/motion/camera-rotation.d.ts

@@ -0,0 +1,91 @@
+import { type CalculationResult } from "../core/calculation-result.js";
+export interface CameraAngularVelocityRadPerSec {
+    /** Right-hand rotation rate about camera +X (right), in radians per second. */
+    pitch: number;
+    /** Right-hand rotation rate about camera +Y (up), in radians per second. */
+    yaw: number;
+    /** Right-hand rotation rate about camera +Z (forward), in radians per second. */
+    roll: number;
+}
+export interface ImagePlanePointMm {
+    /** Image-plane X coordinate relative to the optical axis, in millimetres. */
+    x: number;
+    /** Image-plane Y coordinate relative to the optical axis, in millimetres. */
+    y: number;
+}
+export interface AxisSamplingPitchMicrometers {
+    x: number;
+    y: number;
+}
+export interface CalculateCameraRotationImageMappingInput {
+    /** Physical focal length in millimetres. */
+    focalLengthMm: number;
+    /**
+     * Stationary-world-ray image-plane position at exposure start.
+     *
+     * Image-plane coordinates use optical-axis origin, +X right, +Y up.
+     */
+    imagePointMm: ImagePlanePointMm;
+    /**
+     * Time in seconds from exposure start. Must be greater than or equal to zero.
+     */
+    timeSecondsFromExposureStart: number;
+    /**
+     * Constant camera angular-velocity vector in radians per second.
+     *
+     * Components are resolved in the camera axes at exposure start and follow
+     * the right-hand rule: pitch about +X, yaw about +Y, roll about +Z.
+     */
+    angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;
+    /** Optional focus distance in metres for thin-lens projection distance. */
+    focusDistanceM?: number;
+    /**
+     * Optional axis-aware geometric sampling pitch for reporting sample-domain
+     * displacement. This is geometric sample spacing, not photosite collection
+     * area.
+     */
+    samplingPitchMicrometers?: AxisSamplingPitchMicrometers;
+}
+export interface CameraRotationImageMapping {
+    projectionDistanceMm: number;
+    timeSecondsFromExposureStart: number;
+    angularDisplacementRad: {
+        pitch: number;
+        yaw: number;
+        roll: number;
+        magnitude: number;
+    };
+    startImagePointMm: ImagePlanePointMm;
+    mappedImagePointMm: ImagePlanePointMm;
+    deltaMm: {
+        x: number;
+        y: number;
+        distance: number;
+    };
+    /**
+     * Optional geometric sample displacement in the image-plane basis
+     * (+X right, +Y up). This is not a native-raster vector.
+     */
+    deltaImagePlaneSamples?: {
+        x: number;
+        y: number;
+        distance: number;
+    };
+}
+/**
+ * Maps one stationary-world ray to its image-plane location after pure camera
+ * rotation at an arbitrary physical time from exposure start.
+ *
+ * The initial image point defines the world ray in the camera frame at t=0.
+ * Constant angular velocity is integrated as one axis-angle rotation vector,
+ * avoiding Euler-order dependence. The stationary world ray is then expressed
+ * in the rotated camera frame using the inverse camera rotation and projected
+ * rectilinearly back onto the image plane.
+ *
+ * This function models rotation only. It deliberately excludes camera
+ * translation because translational optical flow depends on scene depth.
+ *
+ * @returns Field-position-dependent image-plane mapping and displacement.
+ */
+export declare function calculateCameraRotationImageMapping(input: CalculateCameraRotationImageMappingInput): CalculationResult<CameraRotationImageMapping>;
+//# sourceMappingURL=camera-rotation.d.ts.map

package/dist/motion/camera-rotation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera-rotation.d.ts","sourceRoot":"","sources":["../../src/motion/camera-rotation.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAOvC,MAAM,WAAW,8BAA8B;IAC7C,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;IACZ,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,CAAC,EAAE,MAAM,CAAC;IACV,6EAA6E;IAC7E,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,4BAA4B;IAC3C,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,wCAAwC;IACvD,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,YAAY,EAAE,iBAAiB,CAAC;IAChC;;OAEG;IACH,4BAA4B,EAAE,MAAM,CAAC;IACrC;;;;;OAKG;IACH,wBAAwB,EAAE,8BAA8B,CAAC;IACzD,2EAA2E;IAC3E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,4BAA4B,CAAC;CACzD;AAED,MAAM,WAAW,0BAA0B;IACzC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,4BAA4B,EAAE,MAAM,CAAC;IACrC,sBAAsB,EAAE;QACtB,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,kBAAkB,EAAE,iBAAiB,CAAC;IACtC,OAAO,EAAE;QACP,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF;;;OAGG;IACH,sBAAsB,CAAC,EAAE;QACvB,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAkFD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,wCAAwC,GAC9C,iBAAiB,CAAC,0BAA0B,CAAC,CAkJ/C"}

package/dist/motion/camera-rotation.js

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: Apache-2.0
+import { calculatedResult } from "../core/calculation-result.js";
+import { InvalidScientificInputError, requirePositiveFinite } from "../core/validation.js";
+import { calculateThinLensImageDistance } from "../optics/thin-lens.js";
+function requireFinite(name, value) {
+    if (!Number.isFinite(value)) {
+        throw new InvalidScientificInputError(`${name} must be finite.`);
+    }
+}
+function requireNonNegativeFinite(name, value) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new InvalidScientificInputError(`${name} must be finite and greater than or equal to zero.`);
+    }
+}
+function rotateVectorByAxisAngle(vector, axis, angleRad) {
+    if (angleRad === 0) {
+        return { ...vector };
+    }
+    const cosine = Math.cos(angleRad);
+    const sine = Math.sin(angleRad);
+    const oneMinusCosine = 1 - cosine;
+    const dot = axis.x * vector.x +
+        axis.y * vector.y +
+        axis.z * vector.z;
+    const cross = {
+        x: axis.y * vector.z - axis.z * vector.y,
+        y: axis.z * vector.x - axis.x * vector.z,
+        z: axis.x * vector.y - axis.y * vector.x
+    };
+    return {
+        x: vector.x * cosine +
+            cross.x * sine +
+            axis.x * dot * oneMinusCosine,
+        y: vector.y * cosine +
+            cross.y * sine +
+            axis.y * dot * oneMinusCosine,
+        z: vector.z * cosine +
+            cross.z * sine +
+            axis.z * dot * oneMinusCosine
+    };
+}
+function resolveProjectionDistanceMm(focalLengthMm, focusDistanceM) {
+    const projection = focusDistanceM === undefined
+        ? undefined
+        : calculateThinLensImageDistance({
+            focalLengthMm,
+            objectDistanceM: focusDistanceM
+        });
+    return {
+        projectionDistanceMm: projection?.value.imageDistanceMm ?? focalLengthMm,
+        focusAware: projection !== undefined
+    };
+}
+/**
+ * Maps one stationary-world ray to its image-plane location after pure camera
+ * rotation at an arbitrary physical time from exposure start.
+ *
+ * The initial image point defines the world ray in the camera frame at t=0.
+ * Constant angular velocity is integrated as one axis-angle rotation vector,
+ * avoiding Euler-order dependence. The stationary world ray is then expressed
+ * in the rotated camera frame using the inverse camera rotation and projected
+ * rectilinearly back onto the image plane.
+ *
+ * This function models rotation only. It deliberately excludes camera
+ * translation because translational optical flow depends on scene depth.
+ *
+ * @returns Field-position-dependent image-plane mapping and displacement.
+ */
+export function calculateCameraRotationImageMapping(input) {
+    requirePositiveFinite("focalLengthMm", input.focalLengthMm);
+    requireFinite("imagePointMm.x", input.imagePointMm.x);
+    requireFinite("imagePointMm.y", input.imagePointMm.y);
+    requireNonNegativeFinite("timeSecondsFromExposureStart", input.timeSecondsFromExposureStart);
+    requireFinite("angularVelocityRadPerSec.pitch", input.angularVelocityRadPerSec.pitch);
+    requireFinite("angularVelocityRadPerSec.yaw", input.angularVelocityRadPerSec.yaw);
+    requireFinite("angularVelocityRadPerSec.roll", input.angularVelocityRadPerSec.roll);
+    if (input.samplingPitchMicrometers !== undefined) {
+        requirePositiveFinite("samplingPitchMicrometers.x", input.samplingPitchMicrometers.x);
+        requirePositiveFinite("samplingPitchMicrometers.y", input.samplingPitchMicrometers.y);
+    }
+    const { projectionDistanceMm, focusAware } = resolveProjectionDistanceMm(input.focalLengthMm, input.focusDistanceM);
+    const angularDisplacementRad = {
+        pitch: input.angularVelocityRadPerSec.pitch *
+            input.timeSecondsFromExposureStart,
+        yaw: input.angularVelocityRadPerSec.yaw *
+            input.timeSecondsFromExposureStart,
+        roll: input.angularVelocityRadPerSec.roll *
+            input.timeSecondsFromExposureStart
+    };
+    const angularMagnitude = Math.hypot(angularDisplacementRad.pitch, angularDisplacementRad.yaw, angularDisplacementRad.roll);
+    const initialRay = {
+        x: input.imagePointMm.x / projectionDistanceMm,
+        y: input.imagePointMm.y / projectionDistanceMm,
+        z: 1
+    };
+    let mappedRay = initialRay;
+    if (angularMagnitude !== 0) {
+        const inverseAxis = {
+            x: angularDisplacementRad.pitch / angularMagnitude,
+            y: angularDisplacementRad.yaw / angularMagnitude,
+            z: angularDisplacementRad.roll / angularMagnitude
+        };
+        mappedRay = rotateVectorByAxisAngle(initialRay, inverseAxis, -angularMagnitude);
+    }
+    if (!Number.isFinite(mappedRay.z) || mappedRay.z <= 0) {
+        throw new InvalidScientificInputError("Camera rotation maps the requested world ray to or behind the camera plane.");
+    }
+    const mappedImagePointMm = {
+        x: projectionDistanceMm * (mappedRay.x / mappedRay.z),
+        y: projectionDistanceMm * (mappedRay.y / mappedRay.z)
+    };
+    const deltaMm = {
+        x: mappedImagePointMm.x - input.imagePointMm.x,
+        y: mappedImagePointMm.y - input.imagePointMm.y,
+        distance: Math.hypot(mappedImagePointMm.x - input.imagePointMm.x, mappedImagePointMm.y - input.imagePointMm.y)
+    };
+    let deltaImagePlaneSamples;
+    if (input.samplingPitchMicrometers !== undefined) {
+        const pitchXmm = input.samplingPitchMicrometers.x / 1000;
+        const pitchYmm = input.samplingPitchMicrometers.y / 1000;
+        const sampleX = deltaMm.x / pitchXmm;
+        const sampleY = deltaMm.y / pitchYmm;
+        deltaImagePlaneSamples = {
+            x: sampleX,
+            y: sampleY,
+            distance: Math.hypot(sampleX, sampleY)
+        };
+    }
+    return calculatedResult({
+        projectionDistanceMm,
+        timeSecondsFromExposureStart: input.timeSecondsFromExposureStart,
+        angularDisplacementRad: {
+            ...angularDisplacementRad,
+            magnitude: angularMagnitude
+        },
+        startImagePointMm: { ...input.imagePointMm },
+        mappedImagePointMm,
+        deltaMm,
+        ...(deltaImagePlaneSamples === undefined
+            ? {}
+            : { deltaImagePlaneSamples })
+    }, focusAware
+        ? "focus-aware-spatial-camera-rotation-mapping"
+        : "spatial-camera-rotation-mapping", "1.0.0", [
+        "Ideal rectilinear projection",
+        focusAware
+            ? "Thin-lens image distance for the selected focus plane is used as the projection distance"
+            : "Nominal focal length is used as the infinity-focus projection distance",
+        "Camera angular velocity is constant during the evaluated interval",
+        "Angular velocity components are resolved in the camera axes at exposure start and integrated as one axis-angle vector",
+        "Positive pitch/yaw/roll follow the right-hand rule about camera +X/+Y/+Z",
+        "The world ray is stationary; subject motion is not included",
+        "Camera translation and depth-dependent parallax are not modeled",
+        "The stationary world ray is transformed by the inverse camera rotation before rectilinear projection"
+    ]);
+}
+//# sourceMappingURL=camera-rotation.js.map

package/dist/motion/camera-rotation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera-rotation.js","sourceRoot":"","sources":["../../src/motion/camera-rotation.ts"],"names":[],"mappings":"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"}

package/dist/optics/focus-breathing.d.ts

@@ -0,0 +1,73 @@
+import { type CalculationResult } from "../core/calculation-result.js";
+export interface CalculateFocusBreathingProjectionInput {
+    /** Physical lens focal length in millimetres. This value is never rewritten. */
+    focalLengthMm: number;
+    /** Selected focus distance in metres. */
+    focusDistanceM: number;
+    /**
+     * Caller-declared projection scale for this focus state, relative to the
+     * ideal thin-lens image distance.
+     *
+     * 1 means no additional breathing relative to the current thin-lens model.
+     * Values above 1 narrow framing / increase magnification; values below 1
+     * widen framing / reduce magnification.
+     */
+    breathingProjectionScale: number;
+}
+export interface FocusBreathingProjection {
+    /** Authoritative physical focal length supplied by the caller. */
+    physicalFocalLengthMm: number;
+    focusDistanceM: number;
+    /** Ideal Gaussian thin-lens image distance before breathing adjustment. */
+    idealProjectionDistanceMm: number;
+    /**
+     * Effective projection distance used by the generic breathing model.
+     *
+     * This is a projection/magnification parameter, not a replacement physical
+     * focal length.
+     */
+    effectiveProjectionDistanceMm: number;
+    /** Caller-declared scale relative to ideal thin-lens projection. */
+    breathingProjectionScale: number;
+    /** Ideal Gaussian thin-lens magnification at the selected focus distance. */
+    idealMagnification: number;
+    /** Generic breathing-adjusted magnification. */
+    effectiveMagnification: number;
+}
+export interface CalculateFocusBreathingFieldOfViewInput extends CalculateFocusBreathingProjectionInput {
+    /** Sensor/capture dimension corresponding to the requested FOV, in millimetres. */
+    sensorDimensionMm: number;
+}
+export interface FocusBreathingFieldOfView {
+    physicalFocalLengthMm: number;
+    focusDistanceM: number;
+    sensorDimensionMm: number;
+    breathingProjectionScale: number;
+    idealProjectionDistanceMm: number;
+    effectiveProjectionDistanceMm: number;
+    idealDegrees: number;
+    effectiveDegrees: number;
+    deltaDegrees: number;
+}
+/**
+ * Applies a caller-declared focus-breathing projection scale to the ideal
+ * Gaussian thin-lens projection for one focus state.
+ *
+ * Photivra does not infer the scale from focal length, focus distance, lens
+ * identity, or marketing data. A value of 1 exactly preserves the current
+ * thin-lens projection.
+ *
+ * This is a generic approximation of focus-dependent projection/magnification,
+ * not a calibrated real-lens model. The physical focal length remains
+ * authoritative and unchanged.
+ */
+export declare function calculateFocusBreathingProjection(input: CalculateFocusBreathingProjectionInput): CalculationResult<FocusBreathingProjection>;
+/**
+ * Calculates one-axis field of view for the generic declared-scale focus-
+ * breathing projection and reports the corresponding ideal thin-lens FOV.
+ *
+ * A breathingProjectionScale of 1 reproduces the current focus-aware
+ * thin-lens field-of-view result exactly.
+ */
+export declare function calculateFocusBreathingFieldOfView(input: CalculateFocusBreathingFieldOfViewInput): CalculationResult<FocusBreathingFieldOfView>;
+//# sourceMappingURL=focus-breathing.d.ts.map

package/dist/optics/focus-breathing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-breathing.d.ts","sourceRoot":"","sources":["../../src/optics/focus-breathing.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAIvC,MAAM,WAAW,sCAAsC;IACrD,gFAAgF;IAChF,aAAa,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,wBAAwB,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,wBAAwB;IACvC,kEAAkE;IAClE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,yBAAyB,EAAE,MAAM,CAAC;IAClC;;;;;OAKG;IACH,6BAA6B,EAAE,MAAM,CAAC;IACtC,oEAAoE;IACpE,wBAAwB,EAAE,MAAM,CAAC;IACjC,6EAA6E;IAC7E,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,uCACf,SAAQ,sCAAsC;IAC9C,mFAAmF;IACnF,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,yBAAyB;IACxC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,wBAAwB,EAAE,MAAM,CAAC;IACjC,yBAAyB,EAAE,MAAM,CAAC;IAClC,6BAA6B,EAAE,MAAM,CAAC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,sCAAsC,GAC5C,iBAAiB,CAAC,wBAAwB,CAAC,CAsC7C;AAED;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,uCAAuC,GAC7C,iBAAiB,CAAC,yBAAyB,CAAC,CAwC9C"}

package/dist/optics/focus-breathing.js

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: Apache-2.0
+import { approximationResult } from "../core/calculation-result.js";
+import { requirePositiveFinite } from "../core/validation.js";
+import { calculateThinLensImageDistance } from "./thin-lens.js";
+/**
+ * Applies a caller-declared focus-breathing projection scale to the ideal
+ * Gaussian thin-lens projection for one focus state.
+ *
+ * Photivra does not infer the scale from focal length, focus distance, lens
+ * identity, or marketing data. A value of 1 exactly preserves the current
+ * thin-lens projection.
+ *
+ * This is a generic approximation of focus-dependent projection/magnification,
+ * not a calibrated real-lens model. The physical focal length remains
+ * authoritative and unchanged.
+ */
+export function calculateFocusBreathingProjection(input) {
+    requirePositiveFinite("focalLengthMm", input.focalLengthMm);
+    requirePositiveFinite("focusDistanceM", input.focusDistanceM);
+    requirePositiveFinite("breathingProjectionScale", input.breathingProjectionScale);
+    const thinLens = calculateThinLensImageDistance({
+        focalLengthMm: input.focalLengthMm,
+        objectDistanceM: input.focusDistanceM
+    });
+    const idealProjectionDistanceMm = thinLens.value.imageDistanceMm;
+    const effectiveProjectionDistanceMm = idealProjectionDistanceMm * input.breathingProjectionScale;
+    const objectDistanceMm = input.focusDistanceM * 1000;
+    return approximationResult({
+        physicalFocalLengthMm: input.focalLengthMm,
+        focusDistanceM: input.focusDistanceM,
+        idealProjectionDistanceMm,
+        effectiveProjectionDistanceMm,
+        breathingProjectionScale: input.breathingProjectionScale,
+        idealMagnification: thinLens.value.magnification,
+        effectiveMagnification: effectiveProjectionDistanceMm / objectDistanceMm
+    }, "declared-scale-focus-breathing-projection", "1.0.0", [
+        "Base projection is the ideal Gaussian thin-lens image distance for the selected focus distance",
+        "The focus-breathing projection scale is supplied explicitly by the caller and is not inferred",
+        "One declared scale applies uniformly to the current focus state",
+        "Physical focal length remains unchanged and authoritative",
+        "The model represents focus-dependent framing/magnification only; distortion, pupil magnification, aberrations, and named-lens calibration are not modeled"
+    ]);
+}
+/**
+ * Calculates one-axis field of view for the generic declared-scale focus-
+ * breathing projection and reports the corresponding ideal thin-lens FOV.
+ *
+ * A breathingProjectionScale of 1 reproduces the current focus-aware
+ * thin-lens field-of-view result exactly.
+ */
+export function calculateFocusBreathingFieldOfView(input) {
+    requirePositiveFinite("sensorDimensionMm", input.sensorDimensionMm);
+    const projection = calculateFocusBreathingProjection(input);
+    const idealRadians = 2 *
+        Math.atan(input.sensorDimensionMm /
+            (2 * projection.value.idealProjectionDistanceMm));
+    const effectiveRadians = 2 *
+        Math.atan(input.sensorDimensionMm /
+            (2 * projection.value.effectiveProjectionDistanceMm));
+    const idealDegrees = (idealRadians * 180) / Math.PI;
+    const effectiveDegrees = (effectiveRadians * 180) / Math.PI;
+    return approximationResult({
+        physicalFocalLengthMm: input.focalLengthMm,
+        focusDistanceM: input.focusDistanceM,
+        sensorDimensionMm: input.sensorDimensionMm,
+        breathingProjectionScale: input.breathingProjectionScale,
+        idealProjectionDistanceMm: projection.value.idealProjectionDistanceMm,
+        effectiveProjectionDistanceMm: projection.value.effectiveProjectionDistanceMm,
+        idealDegrees,
+        effectiveDegrees,
+        deltaDegrees: effectiveDegrees - idealDegrees
+    }, "declared-scale-focus-breathing-field-of-view", "1.0.0", [
+        ...(projection.provenance.assumptions ?? []),
+        "Rectilinear field of view is calculated from the declared sensor/capture dimension and effective projection distance"
+    ]);
+}
+//# sourceMappingURL=focus-breathing.js.map

package/dist/optics/focus-breathing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-breathing.js","sourceRoot":"","sources":["../../src/optics/focus-breathing.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC,OAAO,EACL,mBAAmB,EAEpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,8BAA8B,EAAE,MAAM,gBAAgB,CAAC;AAyDhE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iCAAiC,CAC/C,KAA6C;IAE7C,qBAAqB,CAAC,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAC5D,qBAAqB,CAAC,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAC9D,qBAAqB,CACnB,0BAA0B,EAC1B,KAAK,CAAC,wBAAwB,CAC/B,CAAC;IAEF,MAAM,QAAQ,GAAG,8BAA8B,CAAC;QAC9C,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,eAAe,EAAE,KAAK,CAAC,cAAc;KACtC,CAAC,CAAC;IACH,MAAM,yBAAyB,GAAG,QAAQ,CAAC,KAAK,CAAC,eAAe,CAAC;IACjE,MAAM,6BAA6B,GACjC,yBAAyB,GAAG,KAAK,CAAC,wBAAwB,CAAC;IAC7D,MAAM,gBAAgB,GAAG,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC;IAErD,OAAO,mBAAmB,CACxB;QACE,qBAAqB,EAAE,KAAK,CAAC,aAAa;QAC1C,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,yBAAyB;QACzB,6BAA6B;QAC7B,wBAAwB,EAAE,KAAK,CAAC,wBAAwB;QACxD,kBAAkB,EAAE,QAAQ,CAAC,KAAK,CAAC,aAAa;QAChD,sBAAsB,EACpB,6BAA6B,GAAG,gBAAgB;KACnD,EACD,2CAA2C,EAC3C,OAAO,EACP;QACE,gGAAgG;QAChG,+FAA+F;QAC/F,iEAAiE;QACjE,2DAA2D;QAC3D,2JAA2J;KAC5J,CACF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kCAAkC,CAChD,KAA8C;IAE9C,qBAAqB,CAAC,mBAAmB,EAAE,KAAK,CAAC,iBAAiB,CAAC,CAAC;IAEpE,MAAM,UAAU,GAAG,iCAAiC,CAAC,KAAK,CAAC,CAAC;IAC5D,MAAM,YAAY,GAChB,CAAC;QACD,IAAI,CAAC,IAAI,CACP,KAAK,CAAC,iBAAiB;YACrB,CAAC,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,yBAAyB,CAAC,CACnD,CAAC;IACJ,MAAM,gBAAgB,GACpB,CAAC;QACD,IAAI,CAAC,IAAI,CACP,KAAK,CAAC,iBAAiB;YACrB,CAAC,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,6BAA6B,CAAC,CACvD,CAAC;IACJ,MAAM,YAAY,GAAG,CAAC,YAAY,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;IACpD,MAAM,gBAAgB,GAAG,CAAC,gBAAgB,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;IAE5D,OAAO,mBAAmB,CACxB;QACE,qBAAqB,EAAE,KAAK,CAAC,aAAa;QAC1C,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;QAC1C,wBAAwB,EAAE,KAAK,CAAC,wBAAwB;QACxD,yBAAyB,EACvB,UAAU,CAAC,KAAK,CAAC,yBAAyB;QAC5C,6BAA6B,EAC3B,UAAU,CAAC,KAAK,CAAC,6BAA6B;QAChD,YAAY;QACZ,gBAAgB;QAChB,YAAY,EAAE,gBAAgB,GAAG,YAAY;KAC9C,EACD,8CAA8C,EAC9C,OAAO,EACP;QACE,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,WAAW,IAAI,EAAE,CAAC;QAC5C,sHAAsH;KACvH,CACF,CAAC;AACJ,CAAC"}

package/dist/optics/illumination-vignetting.d.ts

@@ -0,0 +1,59 @@
+import { type CalculationResult } from "../core/calculation-result.js";
+import type { LensFieldPointMm } from "./radial-distortion.js";
+export interface IlluminationVignettingCoefficients {
+    /** Coefficient on normalized radius squared. */
+    r2: number;
+    /** Coefficient on normalized radius to the fourth power. */
+    r4: number;
+    /** Coefficient on normalized radius to the sixth power. */
+    r6: number;
+}
+export interface IlluminationVignettingProfile {
+    /** Physical image-plane radius used to normalize field position, in mm. */
+    normalizationRadiusMm: number;
+    /** Maximum normalized image-plane radius over which the profile is valid. */
+    maximumNormalizedRadius: number;
+    /**
+     * Generic radial relative-illumination coefficients.
+     *
+     * Relative linear throughput is:
+     *   1 + r2 * rho^2 + r4 * rho^4 + r6 * rho^6
+     *
+     * where rho is physical image-plane radius / normalizationRadiusMm.
+     */
+    coefficients: IlluminationVignettingCoefficients;
+}
+export interface CalculateIlluminationVignettingInput {
+    /**
+     * Ideal image-plane field position relative to the optical axis, in mm.
+     *
+     * This slice evaluates throughput from the declared ideal field coordinate;
+     * it does not apply or invert geometric distortion.
+     */
+    imagePointMm: LensFieldPointMm;
+    profile: IlluminationVignettingProfile;
+}
+export interface IlluminationVignetting {
+    imagePointMm: LensFieldPointMm;
+    normalizedRadius: number;
+    /**
+     * Multiplicative factor for scene-linear/channel-linear signal.
+     *
+     * 1 means no attenuation; values are required to remain in (0, 1].
+     */
+    linearThroughputFactor: number;
+    /** Positive exposure loss relative to the optical axis, in stops. */
+    attenuationStops: number;
+    profileMinimumThroughputFactor: number;
+    profileMaximumThroughputFactor: number;
+}
+/**
+ * Calculates generic field-dependent illumination falloff as a multiplicative
+ * linear-light throughput factor.
+ *
+ * The profile is accepted only when its relative throughput remains strictly
+ * positive and never exceeds the optical-axis normalization of 1 throughout
+ * the complete declared operating envelope.
+ */
+export declare function calculateIlluminationVignetting(input: CalculateIlluminationVignettingInput): CalculationResult<IlluminationVignetting>;
+//# sourceMappingURL=illumination-vignetting.d.ts.map

package/dist/optics/illumination-vignetting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"illumination-vignetting.d.ts","sourceRoot":"","sources":["../../src/optics/illumination-vignetting.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAKvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,MAAM,WAAW,kCAAkC;IACjD,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,6BAA6B;IAC5C,2EAA2E;IAC3E,qBAAqB,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,uBAAuB,EAAE,MAAM,CAAC;IAChC;;;;;;;OAOG;IACH,YAAY,EAAE,kCAAkC,CAAC;CAClD;AAED,MAAM,WAAW,oCAAoC;IACnD;;;;;OAKG;IACH,YAAY,EAAE,gBAAgB,CAAC;IAC/B,OAAO,EAAE,6BAA6B,CAAC;CACxC;AAED,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,gBAAgB,CAAC;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,CAAC;IACzB,8BAA8B,EAAE,MAAM,CAAC;IACvC,8BAA8B,EAAE,MAAM,CAAC;CACxC;AA0HD;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,oCAAoC,GAC1C,iBAAiB,CAAC,sBAAsB,CAAC,CAsC3C"}

package/dist/optics/illumination-vignetting.js

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: Apache-2.0
+import { approximationResult } from "../core/calculation-result.js";
+import { InvalidScientificInputError, requirePositiveFinite } from "../core/validation.js";
+function requireFinite(name, value) {
+    if (!Number.isFinite(value)) {
+        throw new InvalidScientificInputError(`${name} must be finite.`);
+    }
+}
+function throughputFromSquaredRadius(squaredRadius, coefficients) {
+    return (1 +
+        coefficients.r2 * squaredRadius +
+        coefficients.r4 * squaredRadius * squaredRadius +
+        coefficients.r6 *
+            squaredRadius *
+            squaredRadius *
+            squaredRadius);
+}
+function throughputCriticalSquaredRadii(coefficients) {
+    // For s = rho²:
+    // T(s) = 1 + r2*s + r4*s² + r6*s³
+    // dT/ds = r2 + 2*r4*s + 3*r6*s²
+    const a = 3 * coefficients.r6;
+    const b = 2 * coefficients.r4;
+    const c = coefficients.r2;
+    if (a === 0) {
+        return b === 0 ? [] : [-c / b];
+    }
+    const discriminant = b * b - 4 * a * c;
+    if (discriminant < 0) {
+        return [];
+    }
+    const root = Math.sqrt(discriminant);
+    return [(-b - root) / (2 * a), (-b + root) / (2 * a)];
+}
+function validateProfile(profile) {
+    requirePositiveFinite("profile.normalizationRadiusMm", profile.normalizationRadiusMm);
+    requirePositiveFinite("profile.maximumNormalizedRadius", profile.maximumNormalizedRadius);
+    requireFinite("profile.coefficients.r2", profile.coefficients.r2);
+    requireFinite("profile.coefficients.r4", profile.coefficients.r4);
+    requireFinite("profile.coefficients.r6", profile.coefficients.r6);
+    const maximumSquaredRadius = profile.maximumNormalizedRadius * profile.maximumNormalizedRadius;
+    const candidates = [
+        0,
+        maximumSquaredRadius,
+        ...throughputCriticalSquaredRadii(profile.coefficients).filter((value) => value > 0 && value < maximumSquaredRadius)
+    ];
+    const throughputs = candidates.map((squaredRadius) => throughputFromSquaredRadius(squaredRadius, profile.coefficients));
+    const minimumThroughputFactor = Math.min(...throughputs);
+    const maximumThroughputFactor = Math.max(...throughputs);
+    if (!Number.isFinite(minimumThroughputFactor) ||
+        minimumThroughputFactor <= 0) {
+        throw new InvalidScientificInputError("Illumination vignetting profile must keep relative linear throughput strictly greater than zero over maximumNormalizedRadius.");
+    }
+    if (!Number.isFinite(maximumThroughputFactor) ||
+        maximumThroughputFactor > 1) {
+        throw new InvalidScientificInputError("Illumination vignetting profile must not amplify relative linear throughput above the optical-axis value of 1.");
+    }
+    return {
+        normalizationRadiusMm: profile.normalizationRadiusMm,
+        maximumNormalizedRadius: profile.maximumNormalizedRadius,
+        coefficients: { ...profile.coefficients },
+        minimumThroughputFactor,
+        maximumThroughputFactor
+    };
+}
+function assumptions() {
+    return [
+        "Generic rotationally symmetric illumination-vignetting approximation evaluated from ideal image-plane field radius",
+        "Relative linear throughput is normalized to 1 on the optical axis",
+        "The model attenuates scene-linear/channel-linear signal only and must be applied before display/gamma encoding",
+        "The model changes throughput only; it does not alter field coordinates, pupil shape, PSF shape, bokeh, or focus",
+        "Mechanical/pupil vignetting and cat's-eye bokeh are separate pupil/PSF effects",
+        "The profile is a generic caller-supplied radial approximation, not calibrated radiometry or a named-lens measurement"
+    ];
+}
+/**
+ * Calculates generic field-dependent illumination falloff as a multiplicative
+ * linear-light throughput factor.
+ *
+ * The profile is accepted only when its relative throughput remains strictly
+ * positive and never exceeds the optical-axis normalization of 1 throughout
+ * the complete declared operating envelope.
+ */
+export function calculateIlluminationVignetting(input) {
+    requireFinite("imagePointMm.x", input.imagePointMm.x);
+    requireFinite("imagePointMm.y", input.imagePointMm.y);
+    const profile = validateProfile(input.profile);
+    const radiusMm = Math.hypot(input.imagePointMm.x, input.imagePointMm.y);
+    const normalizedRadius = radiusMm / profile.normalizationRadiusMm;
+    if (normalizedRadius > profile.maximumNormalizedRadius) {
+        throw new InvalidScientificInputError("imagePointMm lies outside the illumination vignetting profile maximumNormalizedRadius.");
+    }
+    const squaredRadius = normalizedRadius * normalizedRadius;
+    const linearThroughputFactor = throughputFromSquaredRadius(squaredRadius, profile.coefficients);
+    const attenuationStops = linearThroughputFactor === 1
+        ? 0
+        : -Math.log2(linearThroughputFactor);
+    return approximationResult({
+        imagePointMm: { ...input.imagePointMm },
+        normalizedRadius,
+        linearThroughputFactor,
+        attenuationStops,
+        profileMinimumThroughputFactor: profile.minimumThroughputFactor,
+        profileMaximumThroughputFactor: profile.maximumThroughputFactor
+    }, "generic-radial-illumination-vignetting", "1.0.0", assumptions());
+}
+//# sourceMappingURL=illumination-vignetting.js.map