Crate apex_camera_models 

Camera projection models for computer vision applications.

This crate provides a comprehensive collection of camera projection models commonly used in bundle adjustment, SLAM, visual odometry, and Structure-from-Motion (SfM). All models implement the CameraModel trait providing a unified interface for projection, unprojection, and analytic Jacobian computation.

Core Architecture

CameraModel Trait

The CameraModel trait defines the interface that all camera models must implement:

• Projection: 3D point (x,y,z) → 2D pixel (u,v)
• Unprojection: 2D pixel (u,v) → 3D unit ray
• Jacobians: Analytic derivatives for optimization
  • Point Jacobian: ∂(u,v)/∂(x,y,z) — 2×3 matrix
  • Pose Jacobian: ∂(u,v)/∂(pose) — 2×6 matrix (SE3 tangent space)
  • Intrinsic Jacobian: ∂(u,v)/∂(params) — 2×N matrix (N = parameter count)

Error Handling

All operations return Result with CameraModelError providing structured error variants that include actual parameter values for debugging:

• Parameter validation: FocalLengthNotPositive, FocalLengthNotFinite, ParameterOutOfRange
• Projection errors: PointBehindCamera, ProjectionOutOfBounds, DenominatorTooSmall
• Numerical errors: NumericalError with operation context

Available Camera Models

Standard Models (FOV < 90°)

• Pinhole: Standard perspective projection (4 params: fx, fy, cx, cy)
• Radial-Tangential: OpenCV Brown-Conrady model (9 params with k1,k2,k3,p1,p2)

Wide-Angle Models (FOV 90°-180°)

• Kannala-Brandt: Polynomial fisheye model (8 params, θ-based distortion)
• FOV: Field-of-view model (5 params, atan-based)

Omnidirectional Models (FOV > 180°)

• UCM: Unified Camera Model (5 params, α parameter)
• EUCM: Extended Unified Camera Model (6 params, α, β parameters)
• Double Sphere: Two-sphere projection (6 params, ξ, α parameters)

Specialized Models

• BAL Pinhole: Bundle Adjustment in the Large format (6 params, -Z convention)

Re-exports

pub use bal_pinhole::BALPinholeCameraStrict;

pub use double_sphere::DoubleSphereCamera;

pub use eucm::EucmCamera;

pub use fov::FovCamera;

pub use kannala_brandt::KannalaBrandtCamera;

pub use pinhole::PinholeCamera;

pub use rad_tan::RadTanCamera;

pub use ucm::UcmCamera;

Modules

bal_pinhole

BAL (Bundle Adjustment in the Large) pinhole camera model.

double_sphere

Double Sphere Camera Model

eucm

Extended Unified Camera Model (EUCM)

fov

Field-of-View (FOV) Camera Model

kannala_brandt

Kannala-Brandt Fisheye Camera Model

pinhole

Pinhole Camera Model

rad_tan

Radial-Tangential Distortion Camera Model.

ucm

Unified Camera Model (UCM)

Structs

PinholeParams

The “Common 4” - Linear intrinsic parameters.

Enums

CameraModelError

Camera model errors.

DistortionModel

Lens distortion models.

Constants

CONVERGENCE_THRESHOLD

Convergence threshold for iterative unprojection algorithms.

GEOMETRIC_PRECISION

Precision constant for geometric validity checks (e.g., point in front of camera).

JACOBIAN_TEST_TOLERANCE

Tolerance for numerical Jacobian validation in tests.

MIN_DEPTH

Minimum depth for valid 3D points (meters).

NUMERICAL_DERIVATIVE_EPS

Epsilon for numerical differentiation in Jacobian computation.

PROJECTION_TEST_TOLERANCE

Tolerance for projection/unprojection test assertions.

Traits

CameraModel

Trait for camera projection models.

Functions

skew_symmetric

Compute skew-symmetric matrix from a 3D vector.

validate_point_in_front

Validates that a 3D point is in front of the camera.