Struct PinholeCamera 

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

Pinhole camera model with 4 intrinsic parameters.

Fields

pinhole: PinholeParams

distortion: DistortionModel

Implementations

impl PinholeCamera

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

Creates a new Pinhole camera model.

Arguments

• pinhole - Pinhole camera parameters (fx, fy, cx, cy).
• distortion - Distortion model (must be DistortionModel::None).

Returns

Returns a new PinholeCamera instance if the parameters are valid.

Errors

Returns CameraModelError if:

• The distortion model is not None.
• Parameters are invalid (e.g., negative focal length, infinite principal point).

Example

use apex_camera_models::{PinholeCamera, PinholeParams, DistortionModel};

let pinhole = PinholeParams::new(500.0, 500.0, 320.0, 240.0)?;
let distortion = DistortionModel::None;
let camera = PinholeCamera::new(pinhole, distortion)?;

Trait Implementations

impl CameraModel for PinholeCamera

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

Projects a 3D point to 2D image coordinates.

Mathematical Formula

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

Arguments

• p_cam - 3D point in camera coordinate frame (x, y, z).

Returns

Returns the 2D image coordinates if valid.

Errors

Returns CameraModelError::PointAtCameraCenter if the point is behind or at the camera center (z <= MIN_DEPTH).

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

Unprojects a 2D image point to a 3D ray in camera frame.

Mathematical Formula

mx = (u - cx) / fx
my = (v - cy) / fy
ray = normalize([mx, my, 1])

Arguments

• point_2d - 2D point in image coordinates (u, v).

Returns

Returns the normalized 3D ray direction.

Errors

This function never fails for the simple pinhole model, but returns a Result for trait consistency.

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

Jacobian of projection w.r.t. 3D point coordinates (2×3).

Computes ∂π/∂p where π is the projection function and p = (x, y, z) is the 3D point.

Mathematical Derivation

Given the pinhole projection model:

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

Derivatives:

∂u/∂x = fx/z,        ∂u/∂y = 0,     ∂u/∂z = -fx·x/z²
∂v/∂x = 0,           ∂v/∂y = fy/z,  ∂v/∂z = -fy·y/z²

Final Jacobian matrix (2×3):

J = [ ∂u/∂x   ∂u/∂y   ∂u/∂z  ]   [ fx/z    0      -fx·x/z² ]
    [ ∂v/∂x   ∂v/∂y   ∂v/∂z  ] = [  0     fy/z    -fy·y/z² ]

Arguments

• p_cam - 3D point in camera coordinate frame.

Returns

Returns the 2x3 Jacobian matrix.

Implementation Note

The implementation uses inv_z = 1/z and x_norm = x/z, y_norm = y/z to avoid redundant divisions and improve numerical stability.

References

• Hartley & Zisserman, “Multiple View Geometry”, Chapter 6
• Standard perspective projection derivatives
• Verified against numerical differentiation in tests

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

Jacobian of projection w.r.t. intrinsic parameters (2×4).

Computes ∂π/∂K where K = [fx, fy, cx, cy] are the intrinsic parameters.

Mathematical Derivation

The intrinsic parameters for the pinhole model are:

• Focal lengths: fx, fy (scaling factors)
• Principal point: cx, cy (image center offset)

Projection Model Recap

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

Derivatives:

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

Final Jacobian matrix (2×4):

J = [ ∂u/∂fx  ∂u/∂fy  ∂u/∂cx  ∂u/∂cy ]
    [ ∂v/∂fx  ∂v/∂fy  ∂v/∂cx  ∂v/∂cy ]

  = [ x/z      0       1       0    ]
    [  0      y/z      0       1    ]

Arguments

• p_cam - 3D point in camera coordinate frame.

Returns

Returns the 2x4 Intrinsic Jacobian matrix.

Implementation Note

The implementation uses precomputed normalized coordinates:

• x_norm = x/z
• y_norm = y/z

This avoids redundant divisions and improves efficiency.

References

• Standard camera calibration literature
• Hartley & Zisserman, “Multiple View Geometry”, Chapter 6
• Verified against numerical differentiation in tests

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

Validates camera parameters.

Validation Rules

• fx and fy must be positive.
• fx and fy must be finite.
• cx and cy must be finite.

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::None for pinhole).

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

Returns the string identifier for the camera model.

Returns

The string "pinhole".

const INTRINSIC_DIM: usize = 4

Number of intrinsic parameters (compile-time constant).

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

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 PinholeCamera

fn clone(&self) -> PinholeCamera

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PinholeCamera

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

Formats the value using the given formatter.

impl From<&[f64]> for PinholeCamera

Create PinholeCamera from parameter slice.

Panics

Panics if the slice has fewer than 4 elements.

Parameter Order

params = [fx, fy, cx, cy]

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

Converts to this type from the input type.

impl From<&PinholeCamera> for [f64; 4]

Convert PinholeCamera to fixed-size parameter array.

Returns intrinsic parameters as [fx, fy, cx, cy]

fn from(camera: &PinholeCamera) -> Self

Converts to this type from the input type.

impl From<&PinholeCamera> for DVector<f64>

Convert PinholeCamera to parameter vector.

Returns intrinsic parameters in the order: [fx, fy, cx, cy]

fn from(camera: &PinholeCamera) -> Self

Converts to this type from the input type.

impl From<[f64; 4]> for PinholeCamera

Create PinholeCamera from fixed-size parameter array.

Parameter Order

params = [fx, fy, cx, cy]

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

Converts to this type from the input type.

impl PartialEq for PinholeCamera

fn eq(&self, other: &PinholeCamera) -> 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 PinholeCamera

impl StructuralPartialEq for PinholeCamera