Struct UcmCamera 

pub struct UcmCamera {
    pub pinhole: PinholeParams,
    pub distortion: DistortionModel,
}

Unified Camera Model with 5 parameters.

Fields

pinhole: PinholeParams

distortion: DistortionModel

Implementations

impl UcmCamera

pub fn new( pinhole: PinholeParams, distortion: DistortionModel, ) -> Result<Self, CameraModelError>

Create a new Unified Camera Model (UCM) camera.

Arguments

• pinhole - Pinhole parameters (fx, fy, cx, cy).
• distortion - MUST be DistortionModel::UCM with alpha.

Returns

Returns a new UcmCamera instance if the distortion model matches.

Errors

Returns CameraModelError::InvalidParams if distortion is not DistortionModel::UCM.

pub fn linear_estimation( &mut self, points_3d: &Matrix3xX<f64>, points_2d: &Matrix2xX<f64>, ) -> Result<(), CameraModelError>

Performs linear estimation to initialize the alpha parameter from point correspondences.

This method estimates the alpha parameter using a linear least squares approach given 3D-2D point correspondences. It assumes the intrinsic parameters (fx, fy, cx, cy) are already set.

Arguments

• points_3d: Matrix3xX - 3D points in camera coordinates (each column is a point)
• points_2d: Matrix2xX - Corresponding 2D points in image coordinates

Returns

Returns Ok(()) on success or a CameraModelError if the estimation fails.

Trait Implementations

impl CameraModel for UcmCamera

fn project( &self, p_cam: &Vector3<f64>, ) -> Result<Vector2<f64>, CameraModelError>

Projects a 3D point to 2D image coordinates.

Mathematical Formula

d = √(x² + y² + z²)
denom = α·d + (1-α)·z
u = fx · (x/denom) + cx
v = fy · (y/denom) + cy

Arguments

• p_cam - 3D point in camera coordinate frame.

Returns

• Ok(uv) - 2D image coordinates if valid.

Errors

Returns CameraModelError::PointAtCameraCenter if the projection condition fails or the denominator is too small.

fn unproject( &self, point_2d: &Vector2<f64>, ) -> Result<Vector3<f64>, CameraModelError>

Unprojects a 2D image point to a 3D ray.

Algorithm

Algebraic solution for UCM inverse projection.

Arguments

• point_2d - 2D point in image coordinates.

Returns

• Ok(ray) - Normalized 3D ray direction.

Errors

Returns CameraModelError::PointOutsideImage if the unprojection condition fails.

fn jacobian_point(&self, p_cam: &Vector3<f64>) -> Self::PointJacobian

Checks if a 3D point can be validly projected.

Computes the Jacobian of the projection function with respect to the 3D point in camera frame.

Mathematical Derivation

The UCM projection model maps a 3D point p = (x, y, z) to 2D pixel coordinates (u, v).

Projection:

ρ = √(x² + y² + z²)
D = α·ρ + (1-α)·z
u = fx · (x/D) + cx
v = fy · (y/D) + cy

Jacobian:

Derivatives of D with respect to (x, y, z):

∂D/∂x = α · (x/ρ)
∂D/∂y = α · (y/ρ)
∂D/∂z = α · (z/ρ) + (1-α)

Using the quotient rule for u = fx · (x/D):

∂u/∂x = fx · (D - x·∂D/∂x) / D²
∂u/∂y = fx · (-x·∂D/∂y) / D²
∂u/∂z = fx · (-x·∂D/∂z) / D²

Similarly for v:

∂v/∂x = fy · (-y·∂D/∂x) / D²
∂v/∂y = fy · (D - y·∂D/∂y) / D²
∂v/∂z = fy · (-y·∂D/∂z) / D²

Arguments

• p_cam - 3D point in camera coordinate frame.

Returns

Returns the 2x3 Jacobian matrix.

References

• Geyer & Daniilidis, “A Unifying Theory for Central Panoramic Systems”, ICCV 2000
• Mei & Rives, “Single View Point Omnidirectional Camera Calibration from Planar Grids”, ICRA 2007

Verification

This Jacobian is verified against numerical differentiation in tests.

fn jacobian_intrinsics(&self, p_cam: &Vector3<f64>) -> Self::IntrinsicJacobian

Computes the Jacobian of the projection function with respect to intrinsic parameters.

Mathematical Derivation

The UCM camera has 5 intrinsic parameters: θ = [fx, fy, cx, cy, α]

Projection Model

u = fx · (x/D) + cx
v = fy · (y/D) + cy

Where D = α·ρ + (1-α)·z and ρ = √(x²+y²+z²)

Jacobian Structure

Linear parameters (fx, fy, cx, cy):

∂u/∂fx = x/D,  ∂u/∂fy = 0,    ∂u/∂cx = 1,    ∂u/∂cy = 0
∂v/∂fx = 0,    ∂v/∂fy = y/D,  ∂v/∂cx = 0,    ∂v/∂cy = 1

Projection parameter α:

∂D/∂α = ρ - z
∂u/∂α = -fx · (x/D²) · (ρ - z)
∂v/∂α = -fy · (y/D²) · (ρ - z)

Arguments

• p_cam - 3D point in camera coordinate frame.

Returns

Returns the 2x5 Intrinsic Jacobian matrix.

References

• Geyer & Daniilidis, “A Unifying Theory for Central Panoramic Systems”, ICCV 2000

Verification

This Jacobian is verified against numerical differentiation in tests.

fn validate_params(&self) -> Result<(), CameraModelError>

Validates camera parameters.

Validation Rules

• fx, fy must be positive.
• fx, fy must be finite.
• cx, cy must be finite.
• α must be in [0, 1].

Errors

Returns CameraModelError if any parameter violates validation rules.

fn get_pinhole_params(&self) -> PinholeParams

Returns the pinhole parameters of the camera.

Returns

A PinholeParams struct containing the focal lengths (fx, fy) and principal point (cx, cy).

fn get_distortion(&self) -> DistortionModel

Returns the distortion model and parameters of the camera.

Returns

The DistortionModel associated with this camera (typically DistortionModel::UCM).

fn get_model_name(&self) -> &'static str

Returns the string identifier for the camera model.

Returns

The string "ucm".

const INTRINSIC_DIM: usize = 5

Number of intrinsic parameters (compile-time constant).

type IntrinsicJacobian = Matrix<f64, Const<2>, Const<5>, ArrayStorage<f64, 2, 5>>

Jacobian type for intrinsics: 2 × INTRINSIC_DIM.

type PointJacobian = Matrix<f64, Const<2>, Const<3>, ArrayStorage<f64, 2, 3>>

Jacobian type for 3D point: 2 × 3.

fn jacobian_pose( &self, p_world: &Vector3<f64>, pose: &SE3, ) -> (Self::PointJacobian, SMatrix<f64, 3, 6>)

Jacobian of projection w.r.t. camera pose (SE3).

fn project_batch(&self, points_cam: &Matrix3xX<f64>) -> Matrix2xX<f64>

Batch projection of multiple 3D points to 2D image coordinates.

impl Clone for UcmCamera

fn clone(&self) -> UcmCamera

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for UcmCamera

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<&[f64]> for UcmCamera

Create camera from slice of intrinsic parameters.

Layout

Expected parameter order: [fx, fy, cx, cy, alpha]

Panics

Panics if the slice has fewer than 5 elements.

fn from(params: &[f64]) -> Self

Converts to this type from the input type.

impl From<&UcmCamera> for [f64; 5]

Convert camera to fixed-size array of intrinsic parameters.

Layout

The parameters are ordered as: [fx, fy, cx, cy, alpha]

fn from(camera: &UcmCamera) -> Self

Converts to this type from the input type.

impl From<&UcmCamera> for DVector<f64>

Convert camera to dynamic vector of intrinsic parameters.

Layout

The parameters are ordered as: [fx, fy, cx, cy, alpha]

fn from(camera: &UcmCamera) -> Self

Converts to this type from the input type.

impl From<[f64; 5]> for UcmCamera

Create camera from fixed-size array of intrinsic parameters.

Layout

Expected parameter order: [fx, fy, cx, cy, alpha]

fn from(params: [f64; 5]) -> Self

Converts to this type from the input type.

impl PartialEq for UcmCamera

fn eq(&self, other: &UcmCamera) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for UcmCamera

impl StructuralPartialEq for UcmCamera