[Refactor] Refactor code structure and docstrings (#803)

* refactor points_in_boxes

* Merge same functions of three boxes

* More docstring fixes and unify x/y/z size

* Add "optional" and fix "Default"

* Add "optional" and fix "Default"

* Add "optional" and fix "Default"

* Add "optional" and fix "Default"

* Add "optional" and fix "Default"

* Remove None in function param type

* Fix unittest

* Add comments for NMS functions

* Merge methods of Points

* Add unittest

* Add optional and default value

* Fix box conversion and add unittest

* Fix comments

* Add unit test

* Indent

* Fix CI

* Remove useless \\

* Remove useless \\

* Remove useless \\

* Remove useless \\

* Remove useless \\

* Add unit test for box bev

* More unit tests and refine docstrings in box_np_ops

* Fix comment

* Add deprecation warning

docs/datasets/scannet_det.md

@@ -110,8 +110,8 @@ def export(mesh_file,
                 instance_ids[verts] = object_id
                 if object_id not in object_id_to_label_id:
                     object_id_to_label_id[object_id] = label_ids[verts][0]
-        # bbox format is [x, y, z, dx, dy, dz, label_id]
-        # [x, y, z] is gravity center of bbox, [dx, dy, dz] is axis-aligned
+        # bbox format is [x, y, z, x_size, y_size, z_size, label_id]
+        # [x, y, z] is gravity center of bbox, [x_size, y_size, z_size] is axis-aligned
         # [label_id] is semantic label id in 'nyu40id' standard
         # Note: since 3D bbox is axis-aligned, the yaw is 0.
         unaligned_bboxes = extract_bbox(mesh_vertices, object_id_to_segs,

mmdet3d/apis/inference.py

@@ -460,15 +460,17 @@ def show_result_meshlab(data,
         data (dict): Contain data from pipeline.
         result (dict): Predicted result from model.
         out_dir (str): Directory to save visualized result.
-        score_thr (float): Minimum score of bboxes to be shown. Default: 0.0
-        show (bool): Visualize the results online. Defaults to False.
-        snapshot (bool): Whether to save the online results. Defaults to False.
-        task (str): Distinguish which task result to visualize. Currently we
-            support 3D detection, multi-modality detection and 3D segmentation.
-            Defaults to 'det'.
-        palette (list[list[int]]] | np.ndarray | None): The palette of
-                segmentation map. If None is given, random palette will be
-                generated. Defaults to None.
+        score_thr (float, optional): Minimum score of bboxes to be shown.
+            Default: 0.0
+        show (bool, optional): Visualize the results online. Defaults to False.
+        snapshot (bool, optional): Whether to save the online results.
+            Defaults to False.
+        task (str, optional): Distinguish which task result to visualize.
+            Currently we support 3D detection, multi-modality detection and
+            3D segmentation. Defaults to 'det'.
+        palette (list[list[int]]] | np.ndarray, optional): The palette
+            of segmentation map. If None is given, random palette will be
+            generated. Defaults to None.
     """
     assert task in ['det', 'multi_modality-det', 'seg', 'mono-det'], \
         f'unsupported visualization task {task}'

mmdet3d/apis/test.py

@@ -22,9 +22,9 @@ def single_gpu_test(model,
     Args:
         model (nn.Module): Model to be tested.
         data_loader (nn.Dataloader): Pytorch data loader.
-        show (bool): Whether to save viualization results.
+        show (bool, optional): Whether to save viualization results.
             Default: True.
-        out_dir (str): The path to save visualization results.
+        out_dir (str, optional): The path to save visualization results.
             Default: None.
 
     Returns:

mmdet3d/core/anchor/anchor_3d_generator.py

@@ -19,15 +19,21 @@ class Anchor3DRangeGenerator(object):
         ranges (list[list[float]]): Ranges of different anchors.
             The ranges are the same across different feature levels. But may
             vary for different anchor sizes if size_per_range is True.
-        sizes (list[list[float]]): 3D sizes of anchors.
-        scales (list[int]): Scales of anchors in different feature levels.
-        rotations (list[float]): Rotations of anchors in a feature grid.
-        custom_values (tuple[float]): Customized values of that anchor. For
-            example, in nuScenes the anchors have velocities.
-        reshape_out (bool): Whether to reshape the output into (N x 4).
-        size_per_range: Whether to use separate ranges for different sizes.
-            If size_per_range is True, the ranges should have the same length
-            as the sizes, if not, it will be duplicated.
+        sizes (list[list[float]], optional): 3D sizes of anchors.
+            Defaults to [[3.9, 1.6, 1.56]].
+        scales (list[int], optional): Scales of anchors in different feature
+            levels. Defaults to [1].
+        rotations (list[float], optional): Rotations of anchors in a feature
+            grid. Defaults to [0, 1.5707963].
+        custom_values (tuple[float], optional): Customized values of that
+            anchor. For example, in nuScenes the anchors have velocities.
+            Defaults to ().
+        reshape_out (bool, optional): Whether to reshape the output into
+            (N x 4). Defaults to True.
+        size_per_range (bool, optional): Whether to use separate ranges for
+            different sizes. If size_per_range is True, the ranges should have
+            the same length as the sizes, if not, it will be duplicated.
+            Defaults to True.
     """
 
     def __init__(self,
@@ -86,13 +92,14 @@ def grid_anchors(self, featmap_sizes, device='cuda'):
         Args:
             featmap_sizes (list[tuple]): List of feature map sizes in
                 multiple feature levels.
-            device (str): Device where the anchors will be put on.
+            device (str, optional): Device where the anchors will be put on.
+                Defaults to 'cuda'.
 
         Returns:
-            list[torch.Tensor]: Anchors in multiple feature levels. \
-                The sizes of each tensor should be [N, 4], where \
-                N = width * height * num_base_anchors, width and height \
-                are the sizes of the corresponding feature lavel, \
+            list[torch.Tensor]: Anchors in multiple feature levels.
+                The sizes of each tensor should be [N, 4], where
+                N = width * height * num_base_anchors, width and height
+                are the sizes of the corresponding feature lavel,
                 num_base_anchors is the number of anchors for that level.
         """
         assert self.num_levels == len(featmap_sizes)
@@ -161,14 +168,18 @@ def anchors_single_range(self,
                 shape [6]. The order is consistent with that of anchors, i.e.,
                 (x_min, y_min, z_min, x_max, y_max, z_max).
             scale (float | int, optional): The scale factor of anchors.
-            sizes (list[list] | np.ndarray | torch.Tensor): Anchor size with
-                shape [N, 3], in order of x, y, z.
-            rotations (list[float] | np.ndarray | torch.Tensor): Rotations of
-                anchors in a single feature grid.
+                Defaults to 1.
+            sizes (list[list] | np.ndarray | torch.Tensor, optional):
+                Anchor size with shape [N, 3], in order of x, y, z.
+                Defaults to [[3.9, 1.6, 1.56]].
+            rotations (list[float] | np.ndarray | torch.Tensor, optional):
+                Rotations of anchors in a single feature grid.
+                Defaults to [0, 1.5707963].
             device (str): Devices that the anchors will be put on.
+                Defaults to 'cuda'.
 
         Returns:
-            torch.Tensor: Anchors with shape \
+            torch.Tensor: Anchors with shape
                 [*feature_size, num_sizes, num_rots, 7].
         """
         if len(feature_size) == 2:
@@ -231,10 +242,10 @@ class AlignedAnchor3DRangeGenerator(Anchor3DRangeGenerator):
         up corner to distribute anchors.
 
     Args:
-        anchor_corner (bool): Whether to align with the corner of the voxel
-            grid. By default it is False and the anchor's center will be
+        anchor_corner (bool, optional): Whether to align with the corner of the
+            voxel grid. By default it is False and the anchor's center will be
             the same as the corresponding voxel's center, which is also the
-            center of the corresponding greature grid.
+            center of the corresponding greature grid. Defaults to False.
     """
 
     def __init__(self, align_corner=False, **kwargs):
@@ -256,15 +267,18 @@ def anchors_single_range(self,
             anchor_range (torch.Tensor | list[float]): Range of anchors with
                 shape [6]. The order is consistent with that of anchors, i.e.,
                 (x_min, y_min, z_min, x_max, y_max, z_max).
-            scale (float | int, optional): The scale factor of anchors.
-            sizes (list[list] | np.ndarray | torch.Tensor): Anchor size with
-                shape [N, 3], in order of x, y, z.
-            rotations (list[float] | np.ndarray | torch.Tensor): Rotations of
-                anchors in a single feature grid.
-            device (str): Devices that the anchors will be put on.
+            scale (float | int): The scale factor of anchors.
+            sizes (list[list] | np.ndarray | torch.Tensor, optional):
+                Anchor size with shape [N, 3], in order of x, y, z.
+                Defaults to [[3.9, 1.6, 1.56]].
+            rotations (list[float] | np.ndarray | torch.Tensor, optional):
+                Rotations of anchors in a single feature grid.
+                Defaults to [0, 1.5707963].
+            device (str, optional): Devices that the anchors will be put on.
+                Defaults to 'cuda'.
 
         Returns:
-            torch.Tensor: Anchors with shape \
+            torch.Tensor: Anchors with shape
                 [*feature_size, num_sizes, num_rots, 7].
         """
         if len(feature_size) == 2:
@@ -334,7 +348,7 @@ class AlignedAnchor3DRangeGeneratorPerCls(AlignedAnchor3DRangeGenerator):
     Note that feature maps of different classes may be different.
 
     Args:
-        kwargs (dict): Arguments are the same as those in \
+        kwargs (dict): Arguments are the same as those in
             :class:`AlignedAnchor3DRangeGenerator`.
     """
 
@@ -347,15 +361,16 @@ def grid_anchors(self, featmap_sizes, device='cuda'):
         """Generate grid anchors in multiple feature levels.
 
         Args:
-            featmap_sizes (list[tuple]): List of feature map sizes for \
+            featmap_sizes (list[tuple]): List of feature map sizes for
                 different classes in a single feature level.
-            device (str): Device where the anchors will be put on.
+            device (str, optional): Device where the anchors will be put on.
+                Defaults to 'cuda'.
 
         Returns:
-            list[list[torch.Tensor]]: Anchors in multiple feature levels. \
-                Note that in this anchor generator, we currently only \
-                support single feature level. The sizes of each tensor \
-                should be [num_sizes/ranges*num_rots*featmap_size, \
+            list[list[torch.Tensor]]: Anchors in multiple feature levels.
+                Note that in this anchor generator, we currently only
+                support single feature level. The sizes of each tensor
+                should be [num_sizes/ranges*num_rots*featmap_size,
                 box_code_size].
         """
         multi_level_anchors = []
@@ -371,7 +386,7 @@ def multi_cls_grid_anchors(self, featmap_sizes, scale, device='cuda'):
         This function is usually called by method ``self.grid_anchors``.
 
         Args:
-            featmap_sizes (list[tuple]): List of feature map sizes for \
+            featmap_sizes (list[tuple]): List of feature map sizes for
                 different classes in a single feature level.
             scale (float): Scale factor of the anchors in the current level.
             device (str, optional): Device the tensor will be put on.

mmdet3d/core/bbox/box_np_ops.py

@@ -1,6 +1,9 @@
 # Copyright (c) OpenMMLab. All rights reserved.
 # TODO: clean the functions in this file and move the APIs into box structures
 # in the future
+# NOTICE: All functions in this file are valid for LiDAR or depth boxes only
+# if we use default parameters.
+
 import numba
 import numpy as np
 
@@ -47,13 +50,13 @@ def box_camera_to_lidar(data, r_rect, velo2cam):
         np.ndarray, shape=[N, 3]: Boxes in lidar coordinate.
     """
     xyz = data[:, 0:3]
-    dx, dy, dz = data[:, 3:4], data[:, 4:5], data[:, 5:6]
+    x_size, y_size, z_size = data[:, 3:4], data[:, 4:5], data[:, 5:6]
     r = data[:, 6:7]
     xyz_lidar = camera_to_lidar(xyz, r_rect, velo2cam)
     # yaw and dims also needs to be converted
     r_new = -r - np.pi / 2
     r_new = limit_period(r_new, period=np.pi * 2)
-    return np.concatenate([xyz_lidar, dx, dz, dy, r_new], axis=1)
+    return np.concatenate([xyz_lidar, x_size, z_size, y_size, r_new], axis=1)
 
 
 def corners_nd(dims, origin=0.5):
@@ -92,7 +95,7 @@ def corners_nd(dims, origin=0.5):
 
 def center_to_corner_box2d(centers, dims, angles=None, origin=0.5):
     """Convert kitti locations, dimensions and angles to corners.
-    format: center(xy), dims(xy), angles(clockwise when positive)
+    format: center(xy), dims(xy), angles(counterclockwise when positive)
 
     Args:
         centers (np.ndarray): Locations in kitti label file with shape (N, 2).
@@ -187,7 +190,7 @@ def center_to_corner_box3d(centers,
         np.ndarray: Corners with the shape of (N, 8, 3).
     """
     # 'length' in kitti format is in x axis.
-    # yzx(hwl)(kitti label file)<->xyz(lhw)(camera)<->z(-x)(-y)(wlh)(lidar)
+    # yzx(hwl)(kitti label file)<->xyz(lhw)(camera)<->z(-x)(-y)(lwh)(lidar)
     # center in kitti format is [0.5, 1.0, 0.5] in xyz.
     corners = corners_nd(dims, origin=origin)
     # corners: [N, 8, 3]
@@ -348,7 +351,10 @@ def corner_to_surfaces_3d(corners):
 
 
 def points_in_rbbox(points, rbbox, z_axis=2, origin=(0.5, 0.5, 0)):
-    """Check points in rotated bbox and return indicces.
+    """Check points in rotated bbox and return indices.
+
+    Note:
+        This function is for counterclockwise boxes.
 
     Args:
         points (np.ndarray, shape=[N, 3+dim]): Points to query.
@@ -404,7 +410,7 @@ def create_anchors_3d_range(feature_size,
         rotations (list[float] | np.ndarray | torch.Tensor, optional):
             Rotations of anchors in a single feature grid.
             Defaults to (0, np.pi / 2).
-        dtype (type, optional): Data type. Default to np.float32.
+        dtype (type, optional): Data type. Defaults to np.float32.
 
     Returns:
         np.ndarray: Range based anchors with shape of
@@ -478,6 +484,9 @@ def iou_jit(boxes, query_boxes, mode='iou', eps=0.0):
     """Calculate box iou. Note that jit version runs ~10x faster than the
     box_overlaps function in mmdet3d.core.evaluation.
 
+    Note:
+        This function is for counterclockwise boxes.
+
     Args:
         boxes (np.ndarray): Input bounding boxes with shape of (N, 4).
         query_boxes (np.ndarray): Query boxes with shape of (K, 4).
@@ -515,7 +524,10 @@ def iou_jit(boxes, query_boxes, mode='iou', eps=0.0):
 
 
 def projection_matrix_to_CRT_kitti(proj):
-    """Split projection matrix of kitti.
+    """Split projection matrix of KITTI.
+
+    Note:
+        This function is for KITTI only.
 
     P = C @ [R|T]
     C is upper triangular matrix, so we need to inverse CR and use QR
@@ -541,6 +553,9 @@ def projection_matrix_to_CRT_kitti(proj):
 def remove_outside_points(points, rect, Trv2c, P2, image_shape):
     """Remove points which are outside of image.
 
+    Note:
+        This function is for KITTI only.
+
     Args:
         points (np.ndarray, shape=[N, 3+dims]): Total points.
         rect (np.ndarray, shape=[4, 4]): Matrix to project points in
@@ -691,7 +706,7 @@ def points_in_convex_polygon_3d_jit(points,
 
 
 @numba.jit
-def points_in_convex_polygon_jit(points, polygon, clockwise=True):
+def points_in_convex_polygon_jit(points, polygon, clockwise=False):
     """Check points is in 2d convex polygons. True when point in polygon.
 
     Args:
@@ -747,36 +762,39 @@ def boxes3d_to_corners3d_lidar(boxes3d, bottom_center=True):
       |/         |/
       2 -------- 1
 
+    Note:
+        This function is for LiDAR boxes only.
+
     Args:
         boxes3d (np.ndarray): Boxes with shape of (N, 7)
-            [x, y, z, dx, dy, dz, ry] in LiDAR coords, see the definition of
-            ry in KITTI dataset.
+            [x, y, z, x_size, y_size, z_size, ry] in LiDAR coords,
+            see the definition of ry in KITTI dataset.
         bottom_center (bool, optional): Whether z is on the bottom center
             of object. Defaults to True.
 
     Returns:
         np.ndarray: Box corners with the shape of [N, 8, 3].
     """
     boxes_num = boxes3d.shape[0]
-    dx, dy, dz = boxes3d[:, 3], boxes3d[:, 4], boxes3d[:, 5]
+    x_size, y_size, z_size = boxes3d[:, 3], boxes3d[:, 4], boxes3d[:, 5]
     x_corners = np.array([
-        dx / 2., -dx / 2., -dx / 2., dx / 2., dx / 2., -dx / 2., -dx / 2.,
-        dx / 2.
+        x_size / 2., -x_size / 2., -x_size / 2., x_size / 2., x_size / 2.,
+        -x_size / 2., -x_size / 2., x_size / 2.
     ],
                          dtype=np.float32).T
     y_corners = np.array([
-        -dy / 2., -dy / 2., dy / 2., dy / 2., -dy / 2., -dy / 2., dy / 2.,
-        dy / 2.
+        -y_size / 2., -y_size / 2., y_size / 2., y_size / 2., -y_size / 2.,
+        -y_size / 2., y_size / 2., y_size / 2.
     ],
                          dtype=np.float32).T
     if bottom_center:
         z_corners = np.zeros((boxes_num, 8), dtype=np.float32)
-        z_corners[:, 4:8] = dz.reshape(boxes_num, 1).repeat(
+        z_corners[:, 4:8] = z_size.reshape(boxes_num, 1).repeat(
             4, axis=1)  # (N, 8)
     else:
         z_corners = np.array([
-            -dz / 2., -dz / 2., -dz / 2., -dz / 2., dz / 2., dz / 2., dz / 2.,
-            dz / 2.
+            -z_size / 2., -z_size / 2., -z_size / 2., -z_size / 2.,
+            z_size / 2., z_size / 2., z_size / 2., z_size / 2.
         ],
                              dtype=np.float32).T
 

mmdet3d/core/bbox/coders/anchor_free_bbox_coder.py

@@ -25,7 +25,7 @@ def encode(self, gt_bboxes_3d, gt_labels_3d):
         """Encode ground truth to prediction targets.
 
         Args:
-            gt_bboxes_3d (BaseInstance3DBoxes): Ground truth bboxes \
+            gt_bboxes_3d (BaseInstance3DBoxes): Ground truth bboxes
                 with shape (n, 7).
             gt_labels_3d (torch.Tensor): Ground truth classes.