Pinhole Camera¶

In this module we have all the functions and data structures needed to describe the projection of a 3D scene space onto a 2D image plane.

In computer vision, we can map between the 3D world and a 2D image using projective geometry. The module implements the simplest camera model, the Pinhole Camera, which is the most basic model for general projective cameras from the finite cameras group.

The Pinhole Camera model is shown in the following figure:

Using this model, a scene view can be formed by projecting 3D points into the image plane using a perspective transformation.

\[s \; m' = K [R|t] M'\]

or

\[\begin{split}s \begin{bmatrix} u \\ v \\ 1\end{bmatrix} = \begin{bmatrix} f_x & 0 & u_0 \\ 0 & f_y & v_0 \\ 0 & 0 & 1 \end{bmatrix} \begin{bmatrix} r_{11} & r_{12} & r_{13} & t_1 \\ r_{21} & r_{22} & r_{23} & t_2 \\ r_{31} & r_{32} & r_{33} & t_3 \end{bmatrix} \begin{bmatrix} X \\ Y \\ Z \\ 1 \end{bmatrix}\end{split}\]

where:

\(M'\) is a 3D point in space with coordinates \([X,Y,Z]^T\) expressed in a Euclidean coordinate system.
\(m'\) is the projection of the 3D point \(M'\) onto the image plane with coordinates \([u,v]^T\) expressed in pixel units.
\(K\) is the camera calibration matrix, also referred as the intrinsics parameters matrix.
\(C\) is the principal point offset with coordinates \([u_0, v_0]^T\) at the origin in the image plane.
\(fx, fy\) are the focal lengths expressed in pixel units.

The camera rotation and translation are expressed in terms of Euclidean coordinate frame, also known as the world coordinates system. This terms are usually expressed by the joint rotation-translation matrix \([R|t]\), or also called as the extrinsics parameters matrix. It is used to describe the camera pose around a static scene and translates the coordinates of a 3D point \((X,Y,Z)\) to a coordinate system respect to the camera.

The PinholeCamera expects the intrinsics parameters matrix and the extrensics parameters matrix to be of shape (B, 4, 4) such that each intrinsics parameters matrix has the following format:

\[\begin{split}\begin{bmatrix} f_x & 0 & u_0 & 0\\ 0 & f_y & v_0 & 0\\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix}\end{split}\]

And each extrensics parameters matrix has the following format:

\[\begin{split}\begin{bmatrix} r_{11} & r_{12} & r_{13} & t_1 \\ r_{21} & r_{22} & r_{23} & t_2 \\ r_{31} & r_{32} & r_{33} & t_3 \\ 0 & 0 & 0 & 1 \end{bmatrix}\end{split}\]

class PinholeCamera(intrinsics: torch.Tensor, extrinsics: torch.Tensor, height: torch.Tensor, width: torch.Tensor)[source]¶

Class that represents a Pinhole Camera model.

Parameters

intrinsics (torch.Tensor) – tensor with shape \((B, 4, 4)\) containing the full 4x4 camera calibration matrix.
extrinsics (torch.Tensor) – tensor with shape \((B, 4, 4)\) containing the full 4x4 rotation-translation matrix.
height (torch.Tensor) – tensor with shape \((B)\) containing the image height.
width (torch.Tensor) – tensor with shape \((B)\) containing the image width.

Note

We assume that the class attributes are in batch form in order to take advantage of PyTorch parallelism to boost computing performance.

property batch_size¶

Returns the batch size of the storage.

Returns: scalar with the batch size
Return type: int

property camera_matrix¶

Returns the 3x3 camera matrix containing the intrinsics.

Returns: tensor of shape \((B, 3, 3)\)
Return type: torch.Tensor

clone() → kornia.geometry.camera.pinhole.PinholeCamera[source]¶: Returns a deep copy of the current object instance.

property cx¶

Returns the x-coordinate of the principal point.

Returns: tensor of shape \((B)\)
Return type: torch.Tensor

property cy¶

Returns the y-coordinate of the principal point.

Returns: tensor of shape \((B)\)
Return type: torch.Tensor

property extrinsics¶

The full 4x4 extrinsics matrix.

Returns: tensor of shape \((B, 4, 4)\)
Return type: torch.Tensor

property fx¶

Returns the focal lenght in the x-direction.

Returns: tensor of shape \((B)\)
Return type: torch.Tensor

property fy¶

Returns the focal length in the y-direction.

Returns: tensor of shape \((B)\)
Return type: torch.Tensor

property intrinsics¶

The full 4x4 intrinsics matrix.

Returns: tensor of shape \((B, 4, 4)\)
Return type: torch.Tensor

intrinsics_inverse() → torch.Tensor[source]¶

Returns the inverse of the 4x4 instrisics matrix.

Returns: tensor of shape \((B, 4, 4)\)
Return type: torch.Tensor

property rotation_matrix¶

Returns the 3x3 rotation matrix from the extrinsics.

Returns: tensor of shape \((B, 3, 3)\)
Return type: torch.Tensor

property rt_matrix¶

Returns the 3x4 rotation-translation matrix.

Returns: tensor of shape \((B, 3, 4)\)
Return type: torch.Tensor

scale(scale_factor) → kornia.geometry.camera.pinhole.PinholeCamera[source]¶

Scales the pinhole model.

Parameters: scale_factor (torch.Tensor) – a tensor with the scale factor. It has to be broadcastable with class members. The expected shape is \((B)\) or \((1)\).
Returns: the camera model with scaled parameters.
Return type: PinholeCamera

scale_(scale_factor) → kornia.geometry.camera.pinhole.PinholeCamera[source]¶

Scales the pinhole model in-place.

Parameters: scale_factor (torch.Tensor) – a tensor with the scale factor. It has to be broadcastable with class members. The expected shape is \((B)\) or \((1)\).
Returns: the camera model with scaled parameters.
Return type: PinholeCamera

property translation_vector¶

Returns the translation vector from the extrinsics.

Returns: tensor of shape \((B, 3, 1)\)
Return type: torch.Tensor

property tx¶

Returns the x-coordinate of the translation vector.

Returns: tensor of shape \((B)\)
Return type: torch.Tensor

property ty¶

Returns the y-coordinate of the translation vector.

Returns: tensor of shape \((B)\)
Return type: torch.Tensor

property tz¶

Returns the z-coordinate of the translation vector.

Returns: tensor of shape \((B)\)
Return type: torch.Tensor

cam2pixel(cam_coords_src: torch.Tensor, dst_proj_src: torch.Tensor, eps: Optional[float] = 1e-06) → torch.Tensor[source]¶

Transform coordinates in the camera frame to the pixel frame.

Parameters

cam_coords (torch.Tensor) – pixel coordinates defined in the first camera coordinates system. Shape must be BxHxWx3.
dst_proj_src (torch.Tensor) – the projection matrix between the reference and the non reference camera frame. Shape must be Bx4x4.

Returns

array of [-1, 1] coordinates of shape BxHxWx2.

Return type

torch.Tensor

pixel2cam(depth: torch.Tensor, intrinsics_inv: torch.Tensor, pixel_coords: torch.Tensor) → torch.Tensor[source]¶

Transform coordinates in the pixel frame to the camera frame.

Parameters

depth (torch.Tensor) – the source depth maps. Shape must be Bx1xHxW.
intrinsics_inv (torch.Tensor) – the inverse intrinsics camera matrix. Shape must be Bx4x4.
pixel_coords (torch.Tensor) – the grid with the homogeneous camera coordinates. Shape must be BxHxWx3.

Returns

array of (u, v, 1) cam coordinates with shape BxHxWx3.

Return type

torch.Tensor