rotate_on_spot

Summary: Function to relatively rotate a camera position. Also document how to relatively translate a camera position.

Reviewed By: theschnitz

Differential Revision: D25900166

fbshipit-source-id: 2ddaf06ee7c5e2a2e973c04d7dee6ccb61c6ff84

pytorch3d/renderer/__init__.py

@@ -6,6 +6,7 @@ from .blending import (
     sigmoid_alpha_blend,
     softmax_rgb_blend,
 )
+from .camera_utils import rotate_on_spot
 from .cameras import OpenGLOrthographicCameras  # deprecated
 from .cameras import OpenGLPerspectiveCameras  # deprecated
 from .cameras import SfMOrthographicCameras  # deprecated

pytorch3d/renderer/camera_utils.py

@@ -62,3 +62,78 @@ def camera_to_eye_at_up(
     eye, at, up_plus_eye = eye_at_up_world.unbind(1)
     up = up_plus_eye - eye
     return eye, at, up
+
+
+def rotate_on_spot(
+    R: torch.Tensor, T: torch.Tensor, rotation: torch.Tensor
+) -> Tuple[torch.Tensor, torch.Tensor]:
+    """
+    Given a camera position as R and T (batched or not),
+    and a rotation matrix (batched or not)
+    return a new R and T representing camera position(s)
+    in the same location but rotated on the spot by the
+    given rotation. In particular the new world to view
+    rotation will be the previous one followed by the inverse
+    of the given rotation.
+
+    For example, adding the following lines before constructing a camera
+    will make the camera point a little to the right of where it
+    otherwise would have been.
+
+    .. code-block::
+
+        from math import radians
+        from pytorch3d.transforms import axis_angle_to_matrix
+        angles = [0, radians(10), 0]
+        rotation = axis_angle_to_matrix(torch.FloatTensor(angles))
+        R, T = rotate_on_spot(R, T, rotation)
+
+    Note here that if you have a column vector, then when you
+    premultiply it by this `rotation` (see the rotation_conversions doc),
+    then it will be rotated anticlockwise if facing the -y axis.
+    In our context, where we postmultiply row vectors to transform them,
+    `rotation` will rotate the camera clockwise around the -y axis
+    (i.e. when looking down), which is a turn to the right.
+
+    If angles was [radians(10), 0, 0], the camera would get pointed
+    up a bit instead.
+
+    If angles was [0, 0, radians(10)], the camera would be rotated anticlockwise
+    a bit, so the image would appear rotated clockwise from how it
+    otherwise would have been.
+
+    If you want to translate the camera from the origin in camera
+    coordinates, this is simple and does not need a separate function.
+    In particular, a translation by X = [a, b, c] would cause
+    the camera to move a units left, b units up, and c units
+    forward. This is achieved by using T-X in place of T.
+
+    Args:
+        R: FloatTensor of shape [3, 3] or [N, 3, 3]
+        T: FloatTensor of shape [3] or [N, 3]
+        rotation: FloatTensor of shape [3, 3] or [n, 3, 3]
+        where if neither n nor N is 1, then n and N must be equal.
+
+    Returns:
+        R: FloatTensor of shape [max(N, n), 3, 3]
+        T: FloatTensor of shape [max(N, n), 3]
+    """
+    if R.ndim == 2:
+        R = R[None]
+    if T.ndim == 1:
+        T = T[None]
+    if rotation.ndim == 2:
+        rotation = rotation[None]
+
+    if R.ndim != 3 or R.shape[1:] != (3, 3):
+        raise ValueError("Invalid R")
+    if T.ndim != 2 or T.shape[1] != 3:
+        raise ValueError("Invalid T")
+    if rotation.ndim != 3 or rotation.shape[1:] != (3, 3):
+        raise ValueError("Invalid rotation")
+
+    new_R = R @ rotation.transpose(1, 2)
+    old_RT = torch.bmm(R, T[:, :, None])
+    new_T = torch.matmul(new_R.transpose(1, 2), old_RT)[:, :, 0]
+
+    return new_R, new_T

pytorch3d/renderer/cameras.py

@@ -38,7 +38,8 @@ class CamerasBase(TensorProperties):
     - Screen coordinate system: This is another representation of the view volume with
         the XY coordinates defined in pixel space instead of a normalized space.
 
-    A better illustration of the coordinate systems can be found in pytorch3d/docs/notes/cameras.md.
+    A better illustration of the coordinate systems can be found in
+    pytorch3d/docs/notes/cameras.md.
 
     It defines methods that are common to all camera models:
         - `get_camera_center` that returns the optical center of the camera in