[Enhance] Add local yaw (alpha) property (#1130)

* add local yaw property

* fix typos

* delete local yaw in base

* change local yaw to alpha

* change local yaw to alpha

* update docstring

* update docstring again

mmdet3d/core/bbox/structures/cam_box3d.py

@@ -4,7 +4,7 @@ import torch
 
 from ...points import BasePoints
 from .base_box3d import BaseInstance3DBoxes
-from .utils import rotation_3d_in_axis
+from .utils import rotation_3d_in_axis, yaw2local
 
 
 class CameraInstance3DBoxes(BaseInstance3DBoxes):
@@ -90,6 +90,20 @@ class CameraInstance3DBoxes(BaseInstance3DBoxes):
             A vector with bottom's height of each box in shape (N, )."""
         return self.tensor[:, 1]
 
+    @property
+    def local_yaw(self):
+        """torch.Tensor:
+            A vector with local yaw of each box in shape (N, ).
+            local_yaw equals to alpha in kitti, which is commonly
+            used in monocular 3D object detection task, so only
+            :obj:`CameraInstance3DBoxes` has the property.
+        """
+        yaw = self.yaw
+        loc = self.gravity_center
+        local_yaw = yaw2local(yaw, loc)
+
+        return local_yaw
+
     @property
     def gravity_center(self):
         """torch.Tensor: A tensor with center of each box in shape (N, 3)."""

mmdet3d/core/bbox/structures/utils.py

@@ -308,3 +308,24 @@ def get_proj_mat_by_coord_type(img_meta, coord_type):
     mapping = {'LIDAR': 'lidar2img', 'DEPTH': 'depth2img', 'CAMERA': 'cam2img'}
     assert coord_type in mapping.keys()
     return img_meta[mapping[coord_type]]
+
+
+def yaw2local(yaw, loc):
+    """Transform global yaw to local yaw (alpha in kitti) in camera
+    coordinates, ranges from -pi to pi.
+
+    Args:
+        yaw (torch.Tensor): A vector with local yaw of each box.
+            shape: (N, )
+        loc (torch.Tensor): gravity center of each box.
+            shape: (N, 3)
+
+    Returns:
+        torch.Tensor: local yaw (alpha in kitti).
+    """
+    local_yaw = yaw - torch.atan2(loc[:, 0], loc[:, 2])
+    while local_yaw > np.pi:
+        local_yaw -= np.pi * 2
+    while local_yaw < -np.pi:
+        local_yaw += np.pi * 2
+    return local_yaw