Camera

You can import icepy4d classes by

from icepy4d import core as icecore

and directly access to the Camera class by

icecore.Camera

icepy4d.core.camera.Camera

Class to manage Pinhole Cameras.

Attributes:
  • _w (int) –

    Image width in pixels.

  • _h (int) –

    Image height in pixels.

  • _K (ndarray) –

    Calibration matrix (intrinsics).

  • _dist (ndarray) –

    Distortion vector in OpenCV format.

  • _extrinsics (ndarray) –

    Extrinsics matrix (transformation from world to camera).
Note

All the Camera members are private in order to guarantee consistency between the different possible expressions of the exterior orientation. Use ONLY Getter and Setter methods to access Camera parameters from outside the Class. Use the method "update_extrinsics" to update Camera Exterior Orientataion given a new extrinsics matrix. If you need to update the camera EO from a pose matrix or from R,t, compute the extrinsics matrix first with the methods Camera.pose_to_extrinsics (pose) or Camera.Rt_to_extrinsics(R,t), that return the extrinsics matrix.

C: np.ndarray property

Returns the camera center of the camera (i.e., coordinates of the projective centre in world reference system, that is the translation from camera to world)

Returns:
  • ndarray –

    np.ndarray: A 3x1 matrix that represents the camera center of the camera. The matrix is represented as: C = - R' * t

K: np.ndarray property

Returns the intrinsic matrix of the camera.

Returns:
  • ndarray –

    np.ndarray: A 3x3 matrix that represents the intrinsic matrix of the camera. The matrix is represented as: K = [ fx s cx ] | 0 fy cy | [ 0 0 1 ]

P: np.ndarray property

Get Projective matrix P = K [ R | t ]

Returns:
  • ndarray –

    numpy.ndarray: The projective matrix P = K [R|t], where K is the camera internal orientation matrix, and R and t are the rotation matrix and translation vector representing the camera external orientation, respectively.

R: np.ndarray property

Returns the rotation matrix of the camera (i.e., rotation matrix from world to camera).

Returns:
  • ndarray –

    np.ndarray: A 3x3 matrix that represents the rotation matrix of the camera. R is used to project a point in the world to the camera as: R = Extrinsics[0:3, 0:3] x = K * [ R | t ] * X

dist: np.ndarray property

Returns the non-linear distortion parameter vector of the camera.

Returns:
  • ndarray –

    np.ndarray: A 1xn array containing the non-linear distortion parameters as OpenCV standard:

  • ndarray –

    [k1 k2 p1 p2 [k3 [k4 k5 k6]]

euler_angles: Tuple[float] property

Returns the Euler angles of the camera.

Returns:
  • Tuple[float] –

    Tuple[float]: A tuple of 3 floating-point values representing the Euler angles of the camera. The angles are in degrees and describe the orientation of the camera in 3D space (i.e., they are angles from the Camera to the World and they describe the orientation of the camera in the 3D space). The angles are obtained from the camera pose matrix.

extrinsics: np.ndarray property

Returns the extrinsic matrix of the camera.

Returns:
  • ndarray –

    np.ndarray: A 3x4 matrix that represents the extrinsic matrix of the camera. The matrix is represented as: Extrinsics = [ R | t]

height: np.ndarray property

Get image height

pose: np.ndarray property

Get Pose Matrix (i.e., transformation from camera to world) as: Pose = [ R' | C ]

t: np.ndarray property

Returns the translation vector of the camera. (i.e., translation from world to camera)

Returns:
  • ndarray –

    np.ndarray: A 3x1 matrix that represents the translation vector of the camera. The matrix is represented as: t = - R * C

width: np.ndarray property

Get image width

C_from_P(P)

turn the camera center from a projection matrix P, as C = [- inv(KR) * Kt] = [-inv(P[1:3]) * P[4]]

Rt_to_extrinsics(R, t)

Return 4x4 Extrinsics matrix, given a 3x3 Rotation matrix and 3x1 translation vector, as follows:

[ R | t ] [ I | t ] [ R | 0 ] | --|-- | = | --|-- | * | --|-- | [ 0 | 1 ] [ 0 | 1 ] [ 0 | 1 ]

__init__(width, height, K=None, dist=None, R=None, t=None, extrinsics=None, calib_path=None)

Initialize the pinhole camera model.

Parameters:
  • width (ndarray) –

    Image width in pixels.

  • height (ndarray) –

    Image height in pixels.

  • K (ndarray, default: None ) –

    Calibration matrix (intrinsics). Defaults to None.

  • dist (ndarray, default: None ) –

    Distortion vector in OpenCV format. Defaults to None.

  • R (ndarray, default: None ) –

    Rotation matrix (from world to camera coordinates). Defaults to None.

  • t (ndarray, default: None ) –

    Translation vector (from world to camera coordinates). Defaults to None.

  • extrinsics (ndarray, default: None ) –

    Extrinsics matrix (transformation from world to camera). Defaults to None.

  • calib_path (Union[str, Path], default: None ) –

    Path to camera calibration file. Defaults to None.
Raises:
  • FileNotFoundError –

    If calib_path is provided and file not found.

build_pose_matrix(R, C)

Return the Pose Matrix given R and C

euler_from_R(R)

Compute Euler angles from a given rotation matrix.

Parameters:
  • R (ndarray) –

    A 3x3 rotation matrix.
Returns:
  • list –

    Tuple[float, float, float]: A tuple containing the computed Euler angles in radians, ordered as (omega, phi, kappa).

extrinsics_to_pose(extrinsics=None)

Computes the Pose matrix (i.e., transformation from camera to world) from the extrinsics matrix (i.e, transformation from world to camera).

Parameters:
  • extrinsics (ndarray, default: None ) –

    The extrinsics matrix to use. If None, the camera's own extrinsics matrix will be used.
Returns:
  • ndarray –

    The computed Pose matrix.

factor_P()

Factorize the camera matrix into intrinsic and extrinsic parameters, i.e., K, R, and t, as P = K[R | t].

Returns:
  • Tuple[ndarray] –

    A tuple containing: K: A numpy array of shape (3, 3) representing the camera's intrinsic matrix, R: A numpy array of shape (3, 3) representing the camera's rotation matrix, t: A numpy array of shape (3, 1) representing the camera's translation vector.

make_mat_homogeneous(mat)

Return a homogeneous matrix, given a euclidean matrix (i.e., it adds a row of zeros with the last elemmatrixent as 1) [ mat ] [------------] [ 0 0 0 1 ]

pose_to_extrinsics(pose)

Returns the Pose matrix given an extrinsics matrix.

Parameters:
  • pose (ndarray) –

    The extrinsics matrix.
Returns:
  • ndarray –

    np.ndarray: The computed Pose matrix.

project_point(points3d)

Project 3D points onto the image plane using the camera's projection matrix and non-linear distortion parameters.

Note

This method replicates the project_points function in lib.geometry. However, the project_points function cannot be imported due to a circular import. If any changes are made to one of the two functions, the other one must also be manually updated.

Parameters:
  • points3d (ndarray) –

    A numpy array of shape (n, 3) representing the 3D points to be projected.
Returns:
  • ndarray –

    np.ndarray: A numpy array of shape (n, 2) representing the 2D projected points in image coordinates.

read_calibration_from_file(path)

Reads the camera's internal orientation from a file and saves it in the camera class.

Parameters:
  • path (Union[str, Path]) –

    The path to the file containing the full K matrix and distortion vector, according to OpenCV standards, organized in one line as follows: width height fx 0. cx 0. fy cy 0. 0. 1. k1 k2 p1 p2 [k3 [k4 k5 k6]]. Values must be floats and divided by a white space.
Returns:
  • None –

    None

reset_EO()

Reset camera External Orientation (EO), in such a way as to make camera reference system parallel to world reference system

update_K(K)

Update the internal orientation matrix of the camera.

Parameters:
  • K (ndarray) –

    A 3x3 numpy array representing the internal orientation matrix of the camera.
Returns:
  • None –

    None

update_dist(dist)

Update the distortion coefficients of the camera.

Parameters:
  • dist (ndarray) –

    A 1x5 numpy array representing the distortion coefficients of the camera.
Returns:
  • None –

    None

update_extrinsics(extrinsics)

Update the exterior orientation matrix of the camera.

Note

update_extrinsics() is is the only method to update the camera Exterior Orientation. If you need to update the camera EO from a pose matrix or from R,t, compute the extrinsics matrix first with the method self.pose_to_extrinsics(pose) or Rt_to_extrinsics(R,t)

Parameters:
  • extrinsics (ndarray) –

    A 4x4 numpy array (extrinsics in homogeneous coordinates) representing the exterior orientation matrix of the camera.
Returns:
  • None –

    None
Raises:
  • ValueError –

    If the dimension of the extrinsics matrix is not 4x4.

  • ValueError –

    If the data type of the extrinsics matrix is not np.float64.

  • ValueError –

    If the last row of the extrinsics matrix is not [0 0 0 1], i.e., the extrinsics are not in homogeneous coordinates.