pytorch3d.utils

pytorch3d.utils.cameras_from_opencv_projection(R: Tensor, tvec: Tensor, camera_matrix: Tensor, image_size: Tensor) → PerspectiveCameras[source]

Converts a batch of OpenCV-conventioned cameras parametrized with the rotation matrices R, translation vectors tvec, and the camera calibration matrices camera_matrix to PerspectiveCameras in PyTorch3D convention.

More specifically, the conversion is carried out such that a projection of a 3D shape to the OpenCV-conventioned screen of size image_size results in the same image as a projection with the corresponding PyTorch3D camera to the NDC screen convention of PyTorch3D.

More specifically, the OpenCV convention projects points to the OpenCV screen space as follows:

x_screen_opencv = camera_matrix @ (R @ x_world + tvec)

followed by the homogenization of x_screen_opencv.

Note

The parameters R, tvec, camera_matrix correspond to the inputs of cv2.projectPoints(x_world, rvec, tvec, camera_matrix, []), where rvec is an axis-angle vector that can be obtained from the rotation matrix R expected here by calling the so3_log_map function. Correspondingly, R can be obtained from rvec by calling so3_exp_map.

Parameters:

  • R – A batch of rotation matrices of shape (N, 3, 3).

  • tvec – A batch of translation vectors of shape (N, 3).

  • camera_matrix – A batch of camera calibration matrices of shape (N, 3, 3).

  • image_size – A tensor of shape (N, 2) containing the sizes of the images (height, width) attached to each camera.

Returns:

cameras_pytorch3d – A batch of N cameras in the PyTorch3D convention.

pytorch3d.utils.opencv_from_cameras_projection(cameras: PerspectiveCameras, image_size: Tensor) → Tuple[Tensor, Tensor, Tensor][source]

Converts a batch of PerspectiveCameras into OpenCV-convention rotation matrices R, translation vectors tvec, and the camera calibration matrices camera_matrix. This operation is exactly the inverse of cameras_from_opencv_projection.

Note

The outputs R, tvec, camera_matrix correspond to the inputs of cv2.projectPoints(x_world, rvec, tvec, camera_matrix, []), where rvec is an axis-angle vector that can be obtained from the rotation matrix R output here by calling the so3_log_map function. Correspondingly, R can be obtained from rvec by calling so3_exp_map.

Parameters:

  • cameras – A batch of N cameras in the PyTorch3D convention.

  • image_size – A tensor of shape (N, 2) containing the sizes of the images (height, width) attached to each camera.

  • return_as_rotmat (bool) – If set to True, return the full 3x3 rotation matrices. Otherwise, return an axis-angle vector (default).

Returns:

R – A batch of rotation matrices of shape (N, 3, 3). tvec: A batch of translation vectors of shape (N, 3). camera_matrix: A batch of camera calibration matrices of shape (N, 3, 3).

pytorch3d.utils.pulsar_from_cameras_projection(cameras: PerspectiveCameras, image_size: Tensor) → Tensor[source]

Convert PyTorch3D PerspectiveCameras to Pulsar style camera parameters.

Note

  • Pulsar does NOT support different focal lengths for x and y. For conversion, we use the average of fx and fy.

  • The Pulsar renderer MUST use a left-handed coordinate system for this mapping to work.

  • The resulting image will be vertically flipped - which has to be addressed AFTER rendering by the user.

Parameters:

  • cameras – A batch of N cameras in the PyTorch3D convention.

  • image_size – A tensor of shape (N, 2) containing the sizes of the images (height, width) attached to each camera.

Returns:

cameras_pulsar –

A batch of N Pulsar camera vectors in the Pulsar

convention (N, 13) (3 translation, 6 rotation, focal_length, sensor_width, c_x, c_y).

pytorch3d.utils.pulsar_from_opencv_projection(R: Tensor, tvec: Tensor, camera_matrix: Tensor, image_size: Tensor, znear: float = 0.1) → Tensor[source]

Convert OpenCV style camera parameters to Pulsar style camera parameters.

Note

  • Pulsar does NOT support different focal lengths for x and y. For conversion, we use the average of fx and fy.

  • The Pulsar renderer MUST use a left-handed coordinate system for this mapping to work.

  • The resulting image will be vertically flipped - which has to be addressed AFTER rendering by the user.

  • The parameters R, tvec, camera_matrix correspond to the outputs of cv2.decomposeProjectionMatrix.

Parameters:

  • R – A batch of rotation matrices of shape (N, 3, 3).

  • tvec – A batch of translation vectors of shape (N, 3).

  • camera_matrix – A batch of camera calibration matrices of shape (N, 3, 3).

  • image_size – A tensor of shape (N, 2) containing the sizes of the images (height, width) attached to each camera.

  • znear (float) – The near clipping value to use for Pulsar.

Returns:

cameras_pulsar –

A batch of N Pulsar camera vectors in the Pulsar

convention (N, 13) (3 translation, 6 rotation, focal_length, sensor_width, c_x, c_y).

pytorch3d.utils.checkerboard(radius: int = 4, color1: Tuple[float, ...] = (0.0, 0.0, 0.0), color2: Tuple[float, ...] = (1.0, 1.0, 1.0), device: device | None = None) → Meshes[source]

Returns a mesh of squares in the xy-plane where each unit is one of the two given colors and adjacent squares have opposite colors. :param radius: how many squares in each direction from the origin :param color1: background color :param color2: foreground color (must have the same number of channels as color1)

Returns:

new Meshes object containing one mesh.

pytorch3d.utils.ico_sphere(level: int = 0, device=None)[source]

Create verts and faces for a unit ico-sphere, with all faces oriented consistently.

Parameters:

  • level – integer specifying the number of iterations for subdivision of the mesh faces. Each additional level will result in four new faces per face.

  • device – A torch.device object on which the outputs will be allocated.

Returns:

Meshes object with verts and faces.

pytorch3d.utils.torus(r: float, R: float, sides: int, rings: int, device: device | None = None) → Meshes[source]

Create vertices and faces for a torus.

Parameters:

  • r – Inner radius of the torus.

  • R – Outer radius of the torus.

  • sides – Number of inner divisions.

  • rings – Number of outer divisions.

  • device – Device on which the outputs will be allocated.

Returns:

Meshes object with the generated vertices and faces.