Merge branch 'refine_docstrings' into 'master'

Refine mmdet3d docstrings

See merge request open-mmlab/mmdet.3d!135

mmdet3d/core/bbox/structures/base_box3d.py

@@ -14,14 +14,14 @@ class BaseInstance3DBoxes(object):
         the box is (0.5, 0.5, 0).
 
     Args:
-        tensor (torch.Tensor | np.ndarray | list): a Nxbox_dim matrix.
+        tensor (torch.Tensor | np.ndarray | list): a N x box_dim matrix.
         box_dim (int): number of the dimension of a box
             Each row is (x, y, z, x_size, y_size, z_size, yaw).
             Default to 7.
         with_yaw (bool): Whether the box is with yaw rotation.
             If False, the value of yaw will be set to 0 as minmax boxes.
             Default to True.
-        origin (tuple): The relative position of origin in the box.
+        origin (tuple[float]): The relative position of origin in the box.
             Default to (0.5, 0.5, 0). This will guide the box be converted to
             (0.5, 0.5, 0) mode.
     """
@@ -228,7 +228,7 @@ class BaseInstance3DBoxes(object):
         """Convert self to `dst` mode.
 
         Args:
-            dst (BoxMode): the target Box mode
+            dst (:obj:`BoxMode`): the target Box mode
             rt_mat (np.ndarray | torch.Tensor): The rotation and translation
                 matrix between different coordinates. Defaults to None.
                 The conversion from `src` coordinates to `dst` coordinates
@@ -236,7 +236,7 @@ class BaseInstance3DBoxes(object):
                 to LiDAR. This requires a transformation matrix.
 
         Returns:
-            BaseInstance3DBoxes:
+            A new object of :class:`xxx` after indexing:
                 The converted box of the same type in the `dst` mode.
         """
         pass
@@ -295,8 +295,7 @@ class BaseInstance3DBoxes(object):
             subject to Pytorch's indexing semantics.
 
         Returns:
-            BaseInstance3DBoxes: Create a new :class:`BaseInstance3DBoxes`
-                by indexing.
+            A new object of :class:`BaseInstances3DBoxes` after indexing.
         """
         original_type = type(self)
         if isinstance(item, int):
@@ -322,10 +321,10 @@ class BaseInstance3DBoxes(object):
         """Concatenates a list of Boxes into a single Boxes.
 
         Args:
-            boxes_list (list[Boxes]): List of boxes.
+            boxes_list (list[:obj:`BaseInstances3DBoxes`]): List of boxes.
 
         Returns:
-            Boxes: The concatenated Boxes.
+            :obj:`BaseInstances3DBoxes`: The concatenated Boxes.
         """
         assert isinstance(boxes_list, (list, tuple))
         if len(boxes_list) == 0:
@@ -360,7 +359,8 @@ class BaseInstance3DBoxes(object):
         """Clone the Boxes.
 
         Returns:
-            BaseInstance3DBoxes: Box object with the same properties as self.
+            :obj:`BaseInstance3DBoxes`: Box object with the same properties
+                as self.
         """
         original_type = type(self)
         return original_type(
@@ -388,8 +388,8 @@ class BaseInstance3DBoxes(object):
             boxes2,  boxes1 and boxes2 should be in the same type.
 
         Args:
-            boxes1 (:obj:BaseInstanceBoxes): Boxes 1 contain N boxes.
-            boxes2 (:obj:BaseInstanceBoxes): Boxes 2 contain M boxes.
+            boxes1 (:obj:`BaseInstanceBoxes`): Boxes 1 contain N boxes.
+            boxes2 (:obj:`BaseInstanceBoxes`): Boxes 2 contain M boxes.
             mode (str, optional): Mode of iou calculation. Defaults to 'iou'.
 
         Returns:
@@ -420,8 +420,8 @@ class BaseInstance3DBoxes(object):
             boxes1 and boxes2 are not necessarily to be in the same type.
 
         Args:
-            boxes1 (:obj:BaseInstanceBoxes): Boxes 1 contain N boxes.
-            boxes2 (:obj:BaseInstanceBoxes): Boxes 2 contain M boxes.
+            boxes1 (:obj:`BaseInstanceBoxes`): Boxes 1 contain N boxes.
+            boxes2 (:obj:`BaseInstanceBoxes`): Boxes 2 contain M boxes.
             mode (str, optional): Mode of iou calculation. Defaults to 'iou'.
 
         Returns:
@@ -479,7 +479,7 @@ class BaseInstance3DBoxes(object):
                 returned Tensor copies.
 
         Returns:
-            BaseInstance3DBoxes: A new bbox with data and other
+            :obj:`BaseInstance3DBoxes`: A new bbox with data and other
                 properties are similar to self.
         """
         new_tensor = self.tensor.new_tensor(data) \

mmdet3d/core/bbox/structures/box_3d_mode.py

@@ -13,6 +13,7 @@ class Box3DMode(IntEnum):
     r"""Enum of different ways to represent a box.
 
     Coordinates in LiDAR:
+
     .. code-block:: none
 
                     up z
@@ -25,6 +26,7 @@ class Box3DMode(IntEnum):
     and the yaw is around the z axis, thus the rotation axis=2.
 
     Coordinates in camera:
+
     .. code-block:: none
 
                 z front
@@ -40,6 +42,7 @@ class Box3DMode(IntEnum):
     and the yaw is around the y axis, thus the rotation axis=1.
 
     Coordinates in Depth mode:
+
     .. code-block:: none
 
         up z

mmdet3d/core/bbox/structures/cam_box3d.py

@@ -9,6 +9,7 @@ class CameraInstance3DBoxes(BaseInstance3DBoxes):
     """3D boxes of instances in CAM coordinates.
 
     Coordinates in camera:
+
     .. code-block:: none
 
                 z front (yaw=0.5*pi)
@@ -124,7 +125,7 @@ class CameraInstance3DBoxes(BaseInstance3DBoxes):
         """Calculate the 2D bounding boxes in BEV with rotation.
 
         Returns:
-            torch.Tensor: A nx5 tensor of 2D BEV box of each box.
+            torch.Tensor: A n x 5 tensor of 2D BEV box of each box.
                 The box is in XYWHR format.
         """
         return self.tensor[:, [0, 2, 3, 5, 6]]
@@ -249,8 +250,8 @@ class CameraInstance3DBoxes(BaseInstance3DBoxes):
             boxes2,  boxes1 and boxes2 should be in the same type.
 
         Args:
-            boxes1 (:obj:BaseInstanceBoxes): Boxes 1 contain N boxes.
-            boxes2 (:obj:BaseInstanceBoxes): Boxes 2 contain M boxes.
+            boxes1 (:obj:`BaseInstanceBoxes`): Boxes 1 contain N boxes.
+            boxes2 (:obj:`BaseInstanceBoxes`): Boxes 2 contain M boxes.
             mode (str, optional): Mode of iou calculation. Defaults to 'iou'.
 
         Returns:
@@ -278,7 +279,7 @@ class CameraInstance3DBoxes(BaseInstance3DBoxes):
         """Convert self to `dst` mode.
 
         Args:
-            dst (BoxMode): The target Box mode.
+            dst (:obj:`BoxMode`): The target Box mode.
             rt_mat (np.dnarray | torch.Tensor): The rotation and translation
                 matrix between different coordinates. Defaults to None.
                 The conversion from `src` coordinates to `dst` coordinates

mmdet3d/core/bbox/structures/depth_box3d.py

@@ -10,6 +10,7 @@ class DepthInstance3DBoxes(BaseInstance3DBoxes):
     """3D boxes of instances in Depth coordinates.
 
     Coordinates in Depth:
+
     .. code-block:: none
 
                     up z    y front (yaw=0.5*pi)
@@ -24,7 +25,7 @@ class DepthInstance3DBoxes(BaseInstance3DBoxes):
     the positive direction of x to the positive direction of y.
 
     Args:
-        tensor (Tensor): Float matrix of N x box_dim.
+        tensor (torch.Tensor): Float matrix of N x box_dim.
         box_dim (int): Integer indicates the dimension of a box
             Each row is (x, y, z, x_size, y_size, z_size, yaw, ...).
         with_yaw (bool): If True, the value of yaw will be set to 0 as minmax
@@ -92,7 +93,7 @@ class DepthInstance3DBoxes(BaseInstance3DBoxes):
         """Calculate the 2D bounding boxes in BEV with rotation.
 
         Returns:
-            torch.Tensor: A nx5 tensor of 2D BEV box of each box.
+            torch.Tensor: A n x 5 tensor of 2D BEV box of each box.
                 The box is in XYWHR format.
         """
         return self.tensor[:, [0, 1, 3, 4, 6]]
@@ -222,7 +223,7 @@ class DepthInstance3DBoxes(BaseInstance3DBoxes):
         """Convert self to `dst` mode.
 
         Args:
-            dst (BoxMode): The target Box mode.
+            dst (:obj:`BoxMode`): The target Box mode.
             rt_mat (np.ndarray | torch.Tensor): The rotation and translation
                 matrix between different coordinates. Defaults to None.
                 The conversion from `src` coordinates to `dst` coordinates
@@ -230,7 +231,7 @@ class DepthInstance3DBoxes(BaseInstance3DBoxes):
                 to LiDAR. This requires a transformation matrix.
 
         Returns:
-            BaseInstance3DBoxes:
+            :obj:`BaseInstance3DBoxes`:
                 The converted box of the same type in the `dst` mode.
         """
         from .box_3d_mode import Box3DMode

mmdet3d/core/bbox/structures/lidar_box3d.py

@@ -10,6 +10,7 @@ class LiDARInstance3DBoxes(BaseInstance3DBoxes):
     """3D boxes of instances in LIDAR coordinates.
 
     Coordinates in LiDAR:
+
     .. code-block:: none
 
                             up z    x front (yaw=0.5*pi)
@@ -216,7 +217,7 @@ class LiDARInstance3DBoxes(BaseInstance3DBoxes):
         """Convert self to `dst` mode.
 
         Args:
-            dst (BoxMode): the target Box mode
+            dst (:obj:`BoxMode`): the target Box mode
             rt_mat (np.ndarray | torch.Tensor): The rotation and translation
                 matrix between different coordinates. Defaults to None.
                 The conversion from `src` coordinates to `dst` coordinates
@@ -224,7 +225,7 @@ class LiDARInstance3DBoxes(BaseInstance3DBoxes):
                 to LiDAR. This requires a transformation matrix.
 
         Returns:
-            BaseInstance3DBoxes:
+            :obj:`BaseInstance3DBoxes`:
                 The converted box of the same type in the `dst` mode.
         """
         from .box_3d_mode import Box3DMode
@@ -238,7 +239,7 @@ class LiDARInstance3DBoxes(BaseInstance3DBoxes):
             extra_width (float | torch.Tensor): extra width to enlarge the box
 
         Returns:
-            :obj:LiDARInstance3DBoxes: enlarged boxes
+            :obj:`LiDARInstance3DBoxes`: enlarged boxes
         """
         enlarged_boxes = self.tensor.clone()
         enlarged_boxes[:, 3:6] += extra_width * 2
@@ -250,7 +251,7 @@ class LiDARInstance3DBoxes(BaseInstance3DBoxes):
         """Find the box which the points are in.
 
         Args:
-            points (:obj:torch.Tensor): Points in shape Nx3
+            points (torch.Tensor): Points in shape Nx3
 
         Returns:
             torch.Tensor: The index of box where each point are in.

mmdet3d/core/bbox/transforms.py

@@ -2,7 +2,17 @@ import torch
 
 
 def bbox3d_mapping_back(bboxes, scale_factor, flip_horizontal, flip_vertical):
-    """Map bboxes from testing scale to original image scale."""
+    """Map bboxes from testing scale to original image scale.
+
+    Args:
+        bboxes (:obj:`BaseInstance3DBoxes`): Boxes to be mapped back.
+        scale_factor (float): Scale factor.
+        flip_horizontal (bool): Whether to flip horizontally.
+        flip_vertical (bool): Whether to flip vertically.
+
+    Returns:
+        :obj:`BaseInstance3DBoxes`: Boxes mapped back.
+    """
     new_bboxes = bboxes.clone()
     if flip_horizontal:
         new_bboxes.flip('horizontal')
@@ -44,7 +54,11 @@ def bbox3d2result(bboxes, scores, labels):
         scores (torch.Tensor): shape (n, )
 
     Returns:
-        dict(torch.Tensor): Bbox results in cpu mode.
+        dict[str, torch.Tensor]: Bbox results in cpu mode.
+
+            - boxes_3d (torch.Tensor): 3D boxes
+            - scores (torch.Tensor): prediction scores
+            - labels_3d (torch.Tensor): box labels
     """
     return dict(
         boxes_3d=bboxes.to('cpu'),

mmdet3d/core/evaluation/lyft_eval.py

@@ -14,7 +14,7 @@ def load_lyft_gts(lyft, data_root, eval_split, logger=None):
     """Loads ground truth boxes from database.
 
     Args:
-        lyft (:obj:``LyftDataset``): Lyft class in the sdk.
+        lyft (:obj:`LyftDataset`): Lyft class in the sdk.
         data_root (str): Root of data for reading splits.
         eval_split (str): Name of the split for evaluation.
         logger (logging.Logger | str | None): Logger used for printing

mmdet3d/core/post_processing/box3d_nms.py

@@ -27,7 +27,8 @@ def box3d_multiclass_nms(mlvl_bboxes,
             of direction classifier. Defaults to None.
 
     Returns:
-        tuple: Return (bboxes, scores, labels, dir_scores).
+        tuple[torch.Tensor]: Return results after nms, including 3D
+            bounding boxes, scores, labels and direction scores.
     """
     # do multi class nms
     # the fg class id range: [0, num_classes-1]

mmdet3d/datasets/custom_3d.py

@@ -112,7 +112,7 @@ class Custom3DDataset(Dataset):
         """Initialization before data preparation.
 
         Args:
-            dict: Dict before data preprocessing.
+            results (dict): Dict before data preprocessing.
 
                 - img_fields (list): image fields
                 - bbox3d_fields (list): 3D bounding boxes fields

mmdet3d/datasets/kitti_dataset.py

@@ -19,10 +19,10 @@ class KittiDataset(Custom3DDataset):
 
     This class serves as the API for experiments on the KITTI Dataset.
 
-    Please refer to `<http://www.cvlibs.net/datasets/kitti/eval_object.php?
-    obj_benchmark=3d>`_for data downloading. It is recommended to symlink
-    the dataset root to $MMDETECTION3D/data and organize them as the doc
-    shows.
+    Please refer to
+    `<http://www.cvlibs.net/datasets/kitti/eval_object.php?obj_benchmark=3d>`_
+    for data downloading. It is recommended to symlink the dataset root to
+    $MMDETECTION3D/data and organize them as the doc shows.
 
     Args:
         data_root (str): Path of dataset root.
@@ -461,14 +461,14 @@ class KittiDataset(Custom3DDataset):
         """Convert results to kitti format for evaluation and test submission.
 
         Args:
-            net_outputs (List[np.ndarray]): list of array storing the
+            net_outputs (list[np.ndarray]): list of array storing the
                 bbox and score
-            class_nanes (List[String]): A list of class names
+            class_nanes (list[String]): A list of class names
             pklfile_prefix (str | None): The prefix of pkl file.
             submission_prefix (str | None): The prefix of submission file.
 
         Returns:
-            List[dict]: A list of dict have the kitti format
+            list[dict]: A list of dict have the kitti format
         """
         assert len(net_outputs) == len(self.data_infos)
 
@@ -633,7 +633,7 @@ class KittiDataset(Custom3DDataset):
         """Results visualization.
 
         Args:
-            results (list[dict]): List of bounding boxes results.
+            results (list[dict]): list of bounding boxes results.
             out_dir (str): Output directory of visualization result.
         """
         assert out_dir is not None, 'Expect out_dir, got none.'

mmdet3d/datasets/lyft_dataset.py

@@ -21,8 +21,8 @@ class LyftDataset(Custom3DDataset):
     This class serves as the API for experiments on the Lyft Dataset.
 
     Please refer to
-    `<https://www.kaggle.com/c/3d-object-detection-for-autonomous-vehicles
-    /data>`_for data downloading. It is recommended to symlink the dataset
+    `<https://www.kaggle.com/c/3d-object-detection-for-autonomous-vehicles/data>`_  # noqa
+    for data downloading. It is recommended to symlink the dataset
     root to $MMDETECTION3D/data and organize them as the doc shows.
 
     Args:

mmdet3d/datasets/nuscenes_dataset.py

@@ -443,7 +443,7 @@ class NuScenesDataset(Custom3DDataset):
                 Default: None.
 
         Returns:
-            dict[str: float]
+            dict[str, float]: results of each evaluation metric
         """
         result_files, tmp_dir = self.format_results(results, jsonfile_prefix)
 

mmdet3d/datasets/pipelines/dbsampler.py

@@ -191,7 +191,7 @@ class DataBaseSampler(object):
 
                 - gt_labels_3d (np.ndarray): labels of ground truths:
                     labels of sampled ground truths
-                - gt_bboxes_3d (:obj:``BaseInstance3DBoxes``):
+                - gt_bboxes_3d (:obj:`BaseInstance3DBoxes`):
                     sampled 3D bounding boxes
                 - points (np.ndarray): sampled points
                 - group_ids (np.ndarray): ids of sampled ground truths

mmdet3d/datasets/pipelines/transforms_3d.py

@@ -423,15 +423,16 @@ class IndoorPointSample(object):
         Sample points to a certain number.
 
         Args:
-            points (ndarray): 3D Points.
+            points (np.ndarray): 3D Points.
             num_samples (int): Number of samples to be sampled.
             replace (bool): Whether the sample is with or without replacement.
             return_choices (bool): Whether return choice.
 
         Returns:
-            tuple (np.ndarray, np.ndarray) | np.ndarray:
-                points (np.ndarray): 3D Points.
-                choices (np.ndarray, optional): The generated random samples.
+            tuple[np.ndarray] | np.ndarray:
+
+                - points (np.ndarray): 3D Points.
+                - choices (np.ndarray, optional): The generated random samples.
         """
         if replace is None:
             replace = (points.shape[0] < num_samples)

mmdet3d/datasets/scannet_dataset.py

@@ -13,8 +13,8 @@ class ScanNetDataset(Custom3DDataset):
 
     This class serves as the API for experiments on the ScanNet Dataset.
 
-    Please refer to `<https://github.com/ScanNet/ScanNet>`_for data
-    downloading. It is recommended to symlink the dataset root to
+    Please refer to `<https://github.com/ScanNet/ScanNet>`_
+    for data downloading. It is recommended to symlink the dataset root to
     $MMDETECTION3D/data and organize them as the doc shows.
 
     Args:
@@ -73,7 +73,7 @@ class ScanNetDataset(Custom3DDataset):
             dict: Standard annotation dictionary
                 consists of the data information.
 
-                - gt_bboxes_3d (:obj:``DepthInstance3DBoxes``):
+                - gt_bboxes_3d (:obj:`DepthInstance3DBoxes`):
                     3D ground truth bboxes
                 - gt_labels_3d (np.ndarray): labels of ground truths
                 - pts_instance_mask_path (str): path of instance masks

mmdet3d/models/backbones/pointnet2_sa_ssg.py

@@ -115,17 +115,17 @@ class PointNet2SASSG(nn.Module):
         """Forward pass.
 
         Args:
-            points (Tensor): point coordinates with features,
+            points (torch.Tensor): point coordinates with features,
                 with shape (B, N, 3 + input_feature_dim).
 
         Returns:
-            dict[str, list[Tensor]]: outputs after SA and FP modules.
+            dict[str, list[torch.Tensor]]: outputs after SA and FP modules.
 
-                - fp_xyz (list[Tensor]): contains the coordinates of
+                - fp_xyz (list[torch.Tensor]): contains the coordinates of
                     each fp features.
-                - fp_features (list[Tensor]): contains the features
+                - fp_features (list[torch.Tensor]): contains the features
                     from each Feature Propagate Layers.
-                - fp_indices (list[Tensor]): contains indices of the
+                - fp_indices (list[torch.Tensor]): contains indices of the
                     input points.
         """
         xyz, features = self._split_point_feats(points)

mmdet3d/models/dense_heads/anchor3d_head.py

@@ -356,7 +356,7 @@ class Anchor3DHead(nn.Module, AnchorTrainMixin):
             dir_cls_preds (list[torch.Tensor]): Multi-level direction
                 class predictions.
             input_metas (list[dict]): Contain pcd and img's meta info.
-            cfg (None | ConfigDict): Training or testing config.
+            cfg (None | :obj:`ConfigDict`): Training or testing config.
             rescale (list[torch.Tensor]): whether th rescale bbox.
 
         Returns:
@@ -410,7 +410,7 @@ class Anchor3DHead(nn.Module, AnchorTrainMixin):
             mlvl_anchors (List[torch.Tensor]): Multi-level anchors
                 in single batch.
             input_meta (list[dict]): Contain pcd and img's meta info.
-            cfg (None | ConfigDict): Training or testing config.
+            cfg (None | :obj:`ConfigDict`): Training or testing config.
             rescale (list[torch.Tensor]): whether th rescale bbox.
 
         Returns:

mmdet3d/models/dense_heads/parta2_rpn_head.py

@@ -139,7 +139,7 @@ class PartA2RPNHead(Anchor3DHead):
             mlvl_anchors (List[torch.Tensor]): Multi-level anchors
                 in single batch.
             input_meta (list[dict]): Contain pcd and img's meta info.
-            cfg (None | ConfigDict): Training or testing config.
+            cfg (None | :obj:`ConfigDict`): Training or testing config.
             rescale (list[torch.Tensor]): whether th rescale bbox.
 
         Returns:
@@ -236,7 +236,7 @@ class PartA2RPNHead(Anchor3DHead):
                 Multi-level bbox.
             score_thr (int): Score threshold.
             max_num (int): Max number of bboxes after nms.
-            cfg (None | ConfigDict): Training or testing config.
+            cfg (None | :obj:`ConfigDict`): Training or testing config.
             input_meta (dict): Contain pcd and img's meta info.
 
         Returns:

mmdet3d/models/dense_heads/vote_head.py

@@ -21,7 +21,7 @@ class VoteHead(nn.Module):
 
     Args:
         num_classes (int): The number of class.
-        bbox_coder (BaseBBoxCoder): Bbox coder for encoding and
+        bbox_coder (:obj:`BaseBBoxCoder`): Bbox coder for encoding and
             decoding boxes.
         train_cfg (dict): Config for training.
         test_cfg (dict): Config for testing.

mmdet3d/models/fusion_layers/point_fusion.py

@@ -229,9 +229,9 @@ class PointFusion(nn.Module):
         """Forward function.
 
         Args:
-            img_feats (list[Tensor]): img features
-            pts: [list[Tensor]]: a batch of points with shape Nx3
-            pts_feats (Tensor): a tensor consist of point features of the
+            img_feats (list[torch.Tensor]): img features
+            pts: [list[torch.Tensor]]: a batch of points with shape Nx3
+            pts_feats (torch.Tensor): a tensor consist of point features of the
                 total batch
             img_metas (list[dict]): meta information of images