@photivra/engine 1.5.0 → 2.1.0

package/dist/camera/field-of-view.js

@@ -1,20 +1,25 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Calculates rectilinear angular field of view as 2 * atan(sensorDimension / (2 *
- * projectionDistance)). Without focusDistanceM, projectionDistance is nominal focal length for
- * backwards-compatible infinity-focus/pinhole behavior. With focusDistanceM, projectionDistance is the
- * ideal Gaussian thin-lens image distance for that focus plane. Neither mode models real-lens focus
- * breathing or distortion.
- * Calculates an asymmetric rectilinear FOV span from signed sensor-plane bounds relative to the
- * optical axis. This is required for off-center active sensor crops where the optical axis is not at
- * the center of the retained rectangle.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Angular field of view (FOV) for a rectilinear lens.
+ *
+ * The symmetric FOV is 2 * atan(sensorDimension / (2 * projectionDistance)).
+ * - Without focusDistanceM, projectionDistance is the nominal focal length. This keeps the older
+ *   infinity-focus (pinhole) behaviour.
+ * - With focusDistanceM, projectionDistance is the ideal Gaussian thin-lens image distance for that
+ *   focus plane.
+ * Neither mode models real-lens focus breathing or distortion.
+ *
+ * The module also gives an asymmetric FOV span from signed sensor-plane bounds measured from the
+ * optical axis. Off-centre sensor crops need this, because the optical axis is not at the centre of
+ * the kept rectangle.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { calculatedResult } from "../core/calculation-result.js";
 import { InvalidScientificInputError, requirePositiveFinite } from "../core/validation.js";
 import { calculateThinLensImageDistance } from "../optics/thin-lens.js";
+import { requireInputKeys } from "../core/record-validation.js";
+import { calculateLensProjectionFieldOfView, calculateLensProjectionFieldOfViewBounds, parseLensProjectionModel } from "./lens-projection.js";
 function resolveProjectionDistance(focalLengthMm, focusDistanceM) {
     requirePositiveFinite("focalLengthMm", focalLengthMm);
     const focusProjection = focusDistanceM === undefined
@@ -28,6 +33,20 @@ function resolveProjectionDistance(focalLengthMm, focusDistanceM) {
         focusAware: focusProjection !== undefined
     };
 }
+/** Returns the non-rectilinear model, or undefined for the default rectilinear path. */
+function nonRectilinearModel(input) {
+    if (input.projectionModel === undefined) {
+        return undefined;
+    }
+    const model = parseLensProjectionModel(input.projectionModel);
+    if (model === "rectilinear") {
+        return undefined;
+    }
+    if (input.focusDistanceM !== undefined) {
+        throw new InvalidScientificInputError("focusDistanceM is supported only for the rectilinear projection; a finite-focus fisheye/equirectangular mapping scale is not modeled.");
+    }
+    return model;
+}
 function fieldOfViewAssumptions(focusAware) {
     return focusAware
         ? [
@@ -41,18 +60,35 @@ function fieldOfViewAssumptions(focusAware) {
         ];
 }
 /**
- * Calculates rectilinear angular field of view as
+ * Calculates the rectilinear angular field of view as
  * 2 * atan(sensorDimension / (2 * projectionDistance)).
  *
- * Without focusDistanceM, projectionDistance is nominal focal length for
- * backwards-compatible infinity-focus/pinhole behavior. With focusDistanceM,
+ * Without focusDistanceM, projectionDistance is the nominal focal length. This
+ * keeps the older infinity-focus (pinhole) behaviour. With focusDistanceM,
  * projectionDistance is the ideal Gaussian thin-lens image distance for that
  * focus plane.
  *
  * Neither mode models real-lens focus breathing or distortion.
  */
 export function calculateFieldOfView(input) {
+    requireInputKeys(input, "calculateFieldOfView", ["focalLengthMm", "sensorDimensionMm", "focusDistanceM", "projectionModel"]);
     requirePositiveFinite("sensorDimensionMm", input.sensorDimensionMm);
+    const projectionModel = nonRectilinearModel(input);
+    if (projectionModel !== undefined) {
+        const result = calculateLensProjectionFieldOfView({
+            projectionModel,
+            focalLengthMm: input.focalLengthMm,
+            sensorDimensionMm: input.sensorDimensionMm
+        });
+        return {
+            ...result,
+            value: {
+                radians: result.value.radians,
+                degrees: result.value.degrees,
+                projectionDistanceMm: result.value.projectionDistanceMm
+            }
+        };
+    }
     const { projectionDistanceMm, focusAware } = resolveProjectionDistance(input.focalLengthMm, input.focusDistanceM);
     const radians = 2 * Math.atan(input.sensorDimensionMm / (2 * projectionDistanceMm));
     return calculatedResult({
@@ -64,13 +100,14 @@ export function calculateFieldOfView(input) {
         : "rectilinear-field-of-view", "1.0.0", fieldOfViewAssumptions(focusAware));
 }
 /**
- * Calculates an asymmetric rectilinear FOV span from signed sensor-plane
- * bounds relative to the optical axis.
+ * Calculates an asymmetric rectilinear field-of-view span from signed
+ * sensor-plane bounds measured from the optical axis.
  *
- * This is required for off-center active sensor crops where the optical axis
- * is not at the center of the retained rectangle.
+ * Use it for off-centre sensor crops, where the optical axis is not at the
+ * centre of the kept rectangle.
  */
 export function calculateFieldOfViewBounds(input) {
+    requireInputKeys(input, "calculateFieldOfViewBounds", ["focalLengthMm", "minimumSensorCoordinateMm", "maximumSensorCoordinateMm", "focusDistanceM", "projectionModel"]);
     if (!Number.isFinite(input.minimumSensorCoordinateMm)) {
         throw new InvalidScientificInputError("minimumSensorCoordinateMm must be finite.");
     }
@@ -80,6 +117,18 @@ export function calculateFieldOfViewBounds(input) {
     if (input.maximumSensorCoordinateMm <= input.minimumSensorCoordinateMm) {
         throw new InvalidScientificInputError("maximumSensorCoordinateMm must be greater than minimumSensorCoordinateMm.");
     }
+    const projectionModel = nonRectilinearModel(input);
+    if (projectionModel !== undefined) {
+        const result = calculateLensProjectionFieldOfViewBounds({
+            projectionModel,
+            focalLengthMm: input.focalLengthMm,
+            minimumSensorCoordinateMm: input.minimumSensorCoordinateMm,
+            maximumSensorCoordinateMm: input.maximumSensorCoordinateMm
+        });
+        const { projectionModel: _model, ...value } = result.value;
+        void _model;
+        return { ...result, value };
+    }
     const { projectionDistanceMm, focusAware } = resolveProjectionDistance(input.focalLengthMm, input.focusDistanceM);
     const minimumRadians = Math.atan(input.minimumSensorCoordinateMm / projectionDistanceMm);
     const maximumRadians = Math.atan(input.maximumSensorCoordinateMm / projectionDistanceMm);

package/dist/camera/field-of-view.js.map

@@ -1 +1 @@
-{"version":3,"file":"field-of-view.js","sourceRoot":"","sources":["../../src/camera/field-of-view.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"field-of-view.js","sourceRoot":"","sources":["../../src/camera/field-of-view.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Angular field of view (FOV) for a rectilinear lens.\n *\n * The symmetric FOV is 2 * atan(sensorDimension / (2 * projectionDistance)).\n * - Without focusDistanceM, projectionDistance is the nominal focal length. This keeps the older\n *   infinity-focus (pinhole) behaviour.\n * - With focusDistanceM, projectionDistance is the ideal Gaussian thin-lens image distance for that\n *   focus plane.\n * Neither mode models real-lens focus breathing or distortion.\n *\n * The module also gives an asymmetric FOV span from signed sensor-plane bounds measured from the\n * optical axis. Off-centre sensor crops need this, because the optical axis is not at the centre of\n * the kept rectangle.\n * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport {\n  calculatedResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport {\n  InvalidScientificInputError,\n  requirePositiveFinite\n} from \"../core/validation.js\";\nimport { calculateThinLensImageDistance } from \"../optics/thin-lens.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\nimport {\n  calculateLensProjectionFieldOfView,\n  calculateLensProjectionFieldOfViewBounds,\n  parseLensProjectionModel,\n  type LensProjectionModel\n} from \"./lens-projection.js\";\n\nexport interface CalculateFieldOfViewInput {\n  /** Lens focal length in millimetres. */\n  focalLengthMm: number;\n  /** Sensor dimension corresponding to the requested field of view, in millimetres. */\n  sensorDimensionMm: number;\n  /**\n   * Optional focus distance in metres. When supplied, the ideal thin-lens\n   * image distance is used as the projection distance. Omit to preserve the\n   * infinity-focus/pinhole approximation.\n   */\n  focusDistanceM?: number;\n  /**\n   * Ideal projection model. Omit it or pass `\"rectilinear\"` to keep the rectilinear behaviour and\n   * model ids. Other models use the focal length as the mapping scale and do not accept\n   * focusDistanceM.\n   */\n  projectionModel?: LensProjectionModel;\n}\n\nexport interface CalculateFieldOfViewBoundsInput {\n  /** Lens focal length in millimetres. */\n  focalLengthMm: number;\n  /**\n   * Minimum sensor-plane coordinate in millimetres relative to the optical\n   * axis. Negative values lie on the negative side of the requested axis.\n   */\n  minimumSensorCoordinateMm: number;\n  /**\n   * Maximum sensor-plane coordinate in millimetres relative to the optical\n   * axis.\n   */\n  maximumSensorCoordinateMm: number;\n  /** Optional focus distance in metres. */\n  focusDistanceM?: number;\n  /** Ideal projection model; omitted or `\"rectilinear\"` keeps the existing behaviour. */\n  projectionModel?: LensProjectionModel;\n}\n\nexport interface FieldOfView {\n  /** Angular field of view in degrees. */\n  degrees: number;\n  /** Angular field of view in radians. */\n  radians: number;\n  /** Projection/image-plane distance used by the geometry, in millimetres. */\n  projectionDistanceMm: number;\n}\n\nexport interface FieldOfViewBounds {\n  /** Minimum signed angular bound in degrees. */\n  minimumDegrees: number;\n  /** Maximum signed angular bound in degrees. */\n  maximumDegrees: number;\n  /** Total angular span in degrees. */\n  degrees: number;\n  /** Minimum signed angular bound in radians. */\n  minimumRadians: number;\n  /** Maximum signed angular bound in radians. */\n  maximumRadians: number;\n  /** Total angular span in radians. */\n  radians: number;\n  /** Projection/image-plane distance used by the geometry, in millimetres. */\n  projectionDistanceMm: number;\n}\n\nfunction resolveProjectionDistance(\n  focalLengthMm: number,\n  focusDistanceM: number | undefined\n): {\n  projectionDistanceMm: number;\n  focusAware: boolean;\n} {\n  requirePositiveFinite(\"focalLengthMm\", focalLengthMm);\n\n  const focusProjection =\n    focusDistanceM === undefined\n      ? undefined\n      : calculateThinLensImageDistance({\n          focalLengthMm,\n          objectDistanceM: focusDistanceM\n        });\n\n  return {\n    projectionDistanceMm:\n      focusProjection?.value.imageDistanceMm ?? focalLengthMm,\n    focusAware: focusProjection !== undefined\n  };\n}\n\n/** Returns the non-rectilinear model, or undefined for the default rectilinear path. */\nfunction nonRectilinearModel(\n  input: { projectionModel?: unknown; focusDistanceM?: number }\n): Exclude<LensProjectionModel, \"rectilinear\"> | undefined {\n  if (input.projectionModel === undefined) {\n    return undefined;\n  }\n  const model = parseLensProjectionModel(input.projectionModel);\n  if (model === \"rectilinear\") {\n    return undefined;\n  }\n  if (input.focusDistanceM !== undefined) {\n    throw new InvalidScientificInputError(\n      \"focusDistanceM is supported only for the rectilinear projection; a finite-focus fisheye/equirectangular mapping scale is not modeled.\"\n    );\n  }\n  return model;\n}\n\nfunction fieldOfViewAssumptions(focusAware: boolean): readonly string[] {\n  return focusAware\n    ? [\n        \"Ideal rectilinear paraxial thin-lens projection\",\n        \"Sensor plane uses the thin-lens image distance for the supplied focus distance\",\n        \"Real-lens focus breathing and distortion are not modeled\"\n      ]\n    : [\n        \"Ideal rectilinear/pinhole projection\",\n        \"Nominal focal length represents the infinity-focus projection distance\"\n      ];\n}\n\n/**\n * Calculates the rectilinear angular field of view as\n * 2 * atan(sensorDimension / (2 * projectionDistance)).\n *\n * Without focusDistanceM, projectionDistance is the nominal focal length. This\n * keeps the older infinity-focus (pinhole) behaviour. With focusDistanceM,\n * projectionDistance is the ideal Gaussian thin-lens image distance for that\n * focus plane.\n *\n * Neither mode models real-lens focus breathing or distortion.\n */\nexport function calculateFieldOfView(\n  input: CalculateFieldOfViewInput\n): CalculationResult<FieldOfView> {\n  requireInputKeys(input, \"calculateFieldOfView\", [\"focalLengthMm\", \"sensorDimensionMm\", \"focusDistanceM\", \"projectionModel\"]);\n  requirePositiveFinite(\"sensorDimensionMm\", input.sensorDimensionMm);\n  const projectionModel = nonRectilinearModel(input);\n  if (projectionModel !== undefined) {\n    const result = calculateLensProjectionFieldOfView({\n      projectionModel,\n      focalLengthMm: input.focalLengthMm,\n      sensorDimensionMm: input.sensorDimensionMm\n    });\n    return {\n      ...result,\n      value: {\n        radians: result.value.radians,\n        degrees: result.value.degrees,\n        projectionDistanceMm: result.value.projectionDistanceMm\n      }\n    };\n  }\n\n  const { projectionDistanceMm, focusAware } = resolveProjectionDistance(\n    input.focalLengthMm,\n    input.focusDistanceM\n  );\n  const radians =\n    2 * Math.atan(input.sensorDimensionMm / (2 * projectionDistanceMm));\n\n  return calculatedResult(\n    {\n      radians,\n      degrees: (radians * 180) / Math.PI,\n      projectionDistanceMm\n    },\n    focusAware\n      ? \"focus-aware-rectilinear-field-of-view\"\n      : \"rectilinear-field-of-view\",\n    \"1.0.0\",\n    fieldOfViewAssumptions(focusAware)\n  );\n}\n\n/**\n * Calculates an asymmetric rectilinear field-of-view span from signed\n * sensor-plane bounds measured from the optical axis.\n *\n * Use it for off-centre sensor crops, where the optical axis is not at the\n * centre of the kept rectangle.\n */\nexport function calculateFieldOfViewBounds(\n  input: CalculateFieldOfViewBoundsInput\n): CalculationResult<FieldOfViewBounds> {\n  requireInputKeys(input, \"calculateFieldOfViewBounds\", [\"focalLengthMm\", \"minimumSensorCoordinateMm\", \"maximumSensorCoordinateMm\", \"focusDistanceM\", \"projectionModel\"]);\n  if (!Number.isFinite(input.minimumSensorCoordinateMm)) {\n    throw new InvalidScientificInputError(\n      \"minimumSensorCoordinateMm must be finite.\"\n    );\n  }\n  if (!Number.isFinite(input.maximumSensorCoordinateMm)) {\n    throw new InvalidScientificInputError(\n      \"maximumSensorCoordinateMm must be finite.\"\n    );\n  }\n  if (\n    input.maximumSensorCoordinateMm <= input.minimumSensorCoordinateMm\n  ) {\n    throw new InvalidScientificInputError(\n      \"maximumSensorCoordinateMm must be greater than minimumSensorCoordinateMm.\"\n    );\n  }\n\n  const projectionModel = nonRectilinearModel(input);\n  if (projectionModel !== undefined) {\n    const result = calculateLensProjectionFieldOfViewBounds({\n      projectionModel,\n      focalLengthMm: input.focalLengthMm,\n      minimumSensorCoordinateMm: input.minimumSensorCoordinateMm,\n      maximumSensorCoordinateMm: input.maximumSensorCoordinateMm\n    });\n    const { projectionModel: _model, ...value } = result.value;\n    void _model;\n    return { ...result, value };\n  }\n\n  const { projectionDistanceMm, focusAware } = resolveProjectionDistance(\n    input.focalLengthMm,\n    input.focusDistanceM\n  );\n\n  const minimumRadians = Math.atan(\n    input.minimumSensorCoordinateMm / projectionDistanceMm\n  );\n  const maximumRadians = Math.atan(\n    input.maximumSensorCoordinateMm / projectionDistanceMm\n  );\n  const radians = maximumRadians - minimumRadians;\n\n  return calculatedResult(\n    {\n      minimumRadians,\n      maximumRadians,\n      radians,\n      minimumDegrees: (minimumRadians * 180) / Math.PI,\n      maximumDegrees: (maximumRadians * 180) / Math.PI,\n      degrees: (radians * 180) / Math.PI,\n      projectionDistanceMm\n    },\n    focusAware\n      ? \"focus-aware-asymmetric-rectilinear-field-of-view\"\n      : \"asymmetric-rectilinear-field-of-view\",\n    \"1.0.0\",\n    [\n      ...fieldOfViewAssumptions(focusAware),\n      \"Signed sensor-plane bounds are measured relative to the optical axis.\"\n    ]\n  );\n}\n"]}

package/dist/camera/lens-projection.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Ideal lens projection (mapping) functions. They convert between a scene direction and a point on the
+ * image plane.
+ *
+ * A radial projection maps the field angle theta (the angle from the optical axis) to the image
+ * radius r:
+ *   rectilinear       r = f tan(theta)          (gnomonic / pinhole)
+ *   equidistant       r = f theta               ("f-theta" fisheye)
+ *   equisolid-angle   r = 2 f sin(theta / 2)    (equal-area fisheye)
+ *   stereographic     r = 2 f tan(theta / 2)    (conformal fisheye)
+ *   orthographic      r = f sin(theta)
+ * The image point keeps the direction's azimuth about the optical axis, so every radial projection is
+ * rotationally symmetric. Equirectangular (spherical, or cylindrical equidistant) is not radial:
+ * x = f * longitude, y = f * latitude, where f is the image distance per radian.
+ *
+ * Sources: Kannala & Brandt 2006 (IEEE TPAMI 28:1335, generic camera model listing these
+ * projections, eqs. 1-5; free author copy); Miyamoto 1964 (JOSA 54:1060, fish-eye projection
+ * functions); Snyder 1987 (Map Projections - A Working Manual, USGS PP 1395, free) for the
+ * equirectangular and stereographic projections. Also see: Kingslake 1989 (A History of the
+ * Photographic Lens, ch. on fish-eye lenses); Ray 2002 (Applied Photographic Optics, 3rd ed., ch. 6
+ * and 47).
+ *
+ * These are ideal mapping functions. Real fisheye lenses deviate from them. Modelling a real lens
+ * would need a calibrated polynomial (for example Kannala-Brandt) with defensible provenance.
+ *
+ * Camera frame: +X right, +Y up, +Z along the optical axis toward the scene. Image-plane coordinates
+ * use the same non-inverted +X right / +Y up convention as the rest of the engine.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+/** Ideal projection model discriminator. `rectilinear` is the engine default. */
+export type LensProjectionModel = "rectilinear" | "fisheye-equidistant" | "fisheye-equisolid-angle" | "fisheye-stereographic" | "fisheye-orthographic" | "equirectangular";
+/** Radial (rotationally symmetric) projection models. */
+export type RadialLensProjectionModel = Exclude<LensProjectionModel, "equirectangular">;
+export declare const LENS_PROJECTION_MODELS: readonly LensProjectionModel[];
+export interface LensDirection {
+    /** Camera-frame direction component, +X right. Any positive length. */
+    x: number;
+    /** Camera-frame direction component, +Y up. */
+    y: number;
+    /** Camera-frame direction component along the optical axis toward the scene. */
+    z: number;
+}
+export interface CalculateLensProjectionImagePointInput {
+    projectionModel: LensProjectionModel;
+    /**
+     * Projection scale in millimetres: the focal length f of the mapping function, or for
+     * equirectangular the image distance per radian.
+     */
+    focalLengthMm: number;
+    /** Scene direction in the camera frame. Need not be normalized; must be non-zero. */
+    direction: LensDirection;
+}
+export interface LensProjectionImagePoint {
+    projectionModel: LensProjectionModel;
+    imagePointMm: {
+        x: number;
+        y: number;
+    };
+    /** Angle between the direction and the optical axis, in radians. */
+    fieldAngleRadians: number;
+    /** Distance of the image point from the optical axis, in millimetres. */
+    imageRadiusMm: number;
+}
+export interface CalculateLensProjectionDirectionInput {
+    projectionModel: LensProjectionModel;
+    focalLengthMm: number;
+    /** Image-plane point relative to the optical axis, in millimetres. */
+    imagePointMm: {
+        x: number;
+        y: number;
+    };
+}
+export interface LensProjectionDirection {
+    projectionModel: LensProjectionModel;
+    /** Unit direction in the camera frame. */
+    direction: LensDirection;
+    fieldAngleRadians: number;
+    imageRadiusMm: number;
+}
+export interface CalculateLensProjectionFieldOfViewInput {
+    projectionModel: LensProjectionModel;
+    focalLengthMm: number;
+    /** Centred sensor/capture dimension along one axis through the optical axis, in mm. */
+    sensorDimensionMm: number;
+}
+export interface CalculateLensProjectionFieldOfViewBoundsInput {
+    projectionModel: LensProjectionModel;
+    focalLengthMm: number;
+    /** Signed minimum sensor coordinate along one axis through the optical axis, in mm. */
+    minimumSensorCoordinateMm: number;
+    /** Signed maximum sensor coordinate along the same axis, in mm. */
+    maximumSensorCoordinateMm: number;
+}
+export interface LensProjectionFieldOfView {
+    projectionModel: LensProjectionModel;
+    degrees: number;
+    radians: number;
+    /** Projection scale used by the mapping, in millimetres. */
+    projectionDistanceMm: number;
+}
+export interface LensProjectionFieldOfViewBounds {
+    projectionModel: LensProjectionModel;
+    minimumRadians: number;
+    maximumRadians: number;
+    radians: number;
+    minimumDegrees: number;
+    maximumDegrees: number;
+    degrees: number;
+    projectionDistanceMm: number;
+}
+/** Runtime parser for the projection discriminator. Rejects (fails closed on) unknown values. */
+export declare function parseLensProjectionModel(value: unknown): LensProjectionModel;
+/** Image radius r(theta) for one radial model. */
+export declare function radialProjectionImageRadius(model: RadialLensProjectionModel, focalLengthMm: number, fieldAngleRadians: number): number;
+/** Inverse theta(r) for one radial model; throws outside the image circle. */
+export declare function radialProjectionFieldAngle(model: RadialLensProjectionModel, focalLengthMm: number, imageRadiusMm: number): number;
+/**
+ * Maps one camera-frame scene direction to its ideal image-plane point under the declared
+ * projection model.
+ */
+export declare function calculateLensProjectionImagePoint(input: CalculateLensProjectionImagePointInput): CalculationResult<LensProjectionImagePoint>;
+/**
+ * Inverse-maps one image-plane point to its unit camera-frame scene direction under the declared
+ * projection model. It rejects points outside the model's image circle. For equirectangular, it
+ * rejects points outside +/-pi longitude and +/-pi/2 latitude.
+ */
+export declare function calculateLensProjectionDirection(input: CalculateLensProjectionDirectionInput): CalculationResult<LensProjectionDirection>;
+/**
+ * Angular field of view across a centred sensor dimension along one axis through the optical
+ * axis: 2 * theta(d / 2) for radial models and d / f for equirectangular.
+ *
+ * For equirectangular, the result is the longitude span for a horizontal dimension and the latitude
+ * span for a vertical one. A sensor dimension larger than a fisheye's image circle is rejected, not
+ * clipped.
+ */
+export declare function calculateLensProjectionFieldOfView(input: CalculateLensProjectionFieldOfViewInput): CalculationResult<LensProjectionFieldOfView>;
+/**
+ * Asymmetric angular span between two signed sensor coordinates on one axis through the optical
+ * axis, for off-centre crops.
+ */
+export declare function calculateLensProjectionFieldOfViewBounds(input: CalculateLensProjectionFieldOfViewBoundsInput): CalculationResult<LensProjectionFieldOfViewBounds>;
+/**
+ * @internal Image point of a non-zero camera-frame direction under one model (no envelope).
+ * Shared by the public mapping, geometric remaps and the environment ray query.
+ */
+export declare function lensProjectionImagePointValue(model: LensProjectionModel, focalLengthMm: number, x: number, y: number, z: number): {
+    imagePointMm: {
+        x: number;
+        y: number;
+    };
+    fieldAngleRadians: number;
+};
+/** @internal Unit camera-frame direction of one image point under one model (no envelope). */
+export declare function lensProjectionDirectionValue(model: LensProjectionModel, focalLengthMm: number, px: number, py: number): LensDirection;
+/**
+ * @internal Destination-to-source remap between two ideal projections: the destination point is
+ * unprojected with the destination model and reprojected with the source model. Returns the
+ * source point and the 2 x 2 Jacobian d(source)/d(destination), row-major.
+ */
+export declare function lensProjectionRemapValue(destinationModel: LensProjectionModel, destinationFocalLengthMm: number, sourceModel: LensProjectionModel, sourceFocalLengthMm: number, px: number, py: number): {
+    sourcePointMm: {
+        x: number;
+        y: number;
+    };
+    jacobian: readonly [number, number, number, number];
+};
+/** @internal Signed angle along one axis through the optical axis (exported for sampling plans). */
+export declare function lensProjectionSignedAxisAngle(model: LensProjectionModel, focalLengthMm: number, coordinateMm: number): number;