Camera

Module for managing cameras

Calibration

get_intrinsics_from_exif(exif) staticmethod

Constructs the camera intrinsics from exif tag.

Equation: focal_px=max(w_px,h_px)*focal_mm / ccdw_mm

Note

References for this functions can be found:

• https://github.com/colmap/colmap/blob/e3948b2098b73ae080b97901c3a1f9065b976a45/src/util/bitmap.cc#L282
• https://openmvg.readthedocs.io/en/latest/software/SfM/SfMInit_ImageListing/
• https://photo.stackexchange.com/questions/40865/how-can-i-get-the-image-sensor-dimensions-in-mm-to-get-circle-of-confusion-from # noqa: E501

Returns:

Name	Type	Description
K	ndarray	intrinsics matrix (3x3 numpy array).

Camera

Class to manage Pinhole Cameras.

Attributes:

Name	Type	Description
_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:

Type	Description
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:

Type	Description
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:

Type	Description
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:

Type	Description
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:

Type	Description
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:

Type	Description
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:

Type	Description
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:

Type	Description
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:

Name	Type	Description	Default
width	ndarray	Image width in pixels.	required
height	ndarray	Image height in pixels.	required
K	ndarray	Calibration matrix (intrinsics). Defaults to None.	None
dist	ndarray	Distortion vector in OpenCV format. Defaults to None.	None
R	ndarray	Rotation matrix (from world to camera coordinates). Defaults to None.	None
t	ndarray	Translation vector (from world to camera coordinates). Defaults to None.	None
extrinsics	ndarray	Extrinsics matrix (transformation from world to camera). Defaults to None.	None
calib_path	Union[str, Path]	Path to camera calibration file. Defaults to None.	None

Raises:

Type	Description
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:

Name	Type	Description	Default
R	ndarray	A 3x3 rotation matrix.	required

Returns:

Type	Description
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:

Name	Type	Description	Default
extrinsics	ndarray	The extrinsics matrix to use. If None, the camera's own extrinsics matrix will be used.	None

Returns:

Type	Description
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:

Type	Description
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:

Name	Type	Description	Default
pose	ndarray	The extrinsics matrix.	required

Returns:

Type	Description
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:

Name	Type	Description	Default
points3d	ndarray	A numpy array of shape (n, 3) representing the 3D points to be projected.	required

Returns:

Type	Description
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:

Name	Type	Description	Default
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.	required

Returns:

Type	Description
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:

Name	Type	Description	Default
K	ndarray	A 3x3 numpy array representing the internal orientation matrix of the camera.	required

Returns:

Type	Description
None	None

update_dist(dist)

Update the distortion coefficients of the camera.

Parameters:

Name	Type	Description	Default
dist	ndarray	A 1x5 numpy array representing the distortion coefficients of the camera.	required

Returns:

Type	Description
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:

Name	Type	Description	Default
extrinsics	ndarray	A 4x4 numpy array (extrinsics in homogeneous coordinates) representing the exterior orientation matrix of the camera.	required

Returns:

Type	Description
None	None

Raises:

Type	Description
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.

read_opencv_calibration(path, verbose=False)

Reads camera internal orientation from a file and returns them. The file must contain the full K matrix and distortion vector according to OpenCV standards, and should be organized on one line in the following format:

width height fx 0. cx 0. fy cy 0. 0. 1. k1 k2 p1 p2 [k3 [k4 k5 k6]]

All values must be float, and separated by a white space.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	The path to the calibration file.	required
verbose	bool	Prints verbose output. Defaults to False.	False

Returns:

Type	Description
Tuple[ndarray]	Tuple[np.ndarray]: Returns a tuple containing: - w: width of the calibration image. - h: height of the calibration image. - K: 3x3 matrix containing the intrinsic camera parameters. - dist: distortion parameters.

Raises: ValueError: If the calibration file is not found or if the file is not formatted correctly.