Merge branch 'fix-api-doc' into 'master'

Update docstrings

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

mmdet3d/datasets/pipelines/loading.py

@@ -145,8 +145,6 @@ class PointSegClassMapping(object):
 class NormalizePointsColor(object):
     """Normalize color of points.
 
-    Normalize color of the points.
-
     Args:
         color_mean (list[float]): Mean color of the point cloud.
     """

mmdet3d/datasets/pipelines/test_time_aug.py

@@ -19,7 +19,7 @@ class MultiScaleFlipAug3D(object):
         flip_direction (str | list[str]): Flip augmentation directions
             for images, options are "horizontal" and "vertical".
             If flip_direction is list, multiple flip augmentations will
-            be applied. It has no effect when flip == False.
+            be applied. It has no effect when ``flip == False``.
             Default: "horizontal".
         pcd_horizontal_flip (bool): Whether apply horizontal flip augmentation
             to point cloud. Default: True. Note that it works only when

mmdet3d/datasets/scannet_dataset.py

@@ -13,9 +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
-    $MMDETECTION3D/data and organize them as the doc shows.
+    Please refer to the `github repo <https://github.com/ScanNet/ScanNet>`_
+    for data downloading.
 
     Args:
         data_root (str): Path of dataset root.
@@ -70,10 +69,9 @@ class ScanNetDataset(Custom3DDataset):
             index (int): Index of the annotation data to get.
 
         Returns:
-            dict: Standard annotation dictionary
-                consists of the data information.
+            dict: annotation information consists of the following keys:
 
-                - 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/datasets/sunrgbd_dataset.py

@@ -9,13 +9,12 @@ from .custom_3d import Custom3DDataset
 
 @DATASETS.register_module()
 class SUNRGBDDataset(Custom3DDataset):
-    """SUNRGBD Dataset.
+    r"""SUNRGBD Dataset.
 
     This class serves as the API for experiments on the SUNRGBD Dataset.
 
-    Please refer to `<http://rgbd.cs.princeton.edu/challenge.html>`_for
-    data downloading. It is recommended to symlink the dataset root to
-    $MMDETECTION3D/data and organize them as the doc shows.
+    See the `download page <http://rgbd.cs.princeton.edu/challenge.html>`_
+    for data downloading.
 
     Args:
         data_root (str): Path of dataset root.
@@ -68,10 +67,9 @@ class SUNRGBDDataset(Custom3DDataset):
             index (int): Index of the annotation data to get.
 
         Returns:
-            dict: Standard annotation dictionary
-                consists of the data information.
+            dict: annotation information consists of the following keys:
 
-                - 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

@@ -121,11 +121,11 @@ class PointNet2SASSG(nn.Module):
         Returns:
             dict[str, list[torch.Tensor]]: outputs after SA and FP modules.
 
-                - fp_xyz (list[torch.Tensor]): contains the coordinates of
+                - fp_xyz (list[torch.Tensor]): contains the coordinates of \
                     each fp features.
-                - fp_features (list[torch.Tensor]): contains the features
+                - fp_features (list[torch.Tensor]): contains the features \
                     from each Feature Propagate Layers.
-                - fp_indices (list[torch.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

@@ -140,8 +140,8 @@ class Anchor3DHead(nn.Module, AnchorTrainMixin):
             x (torch.Tensor): Input features.
 
         Returns:
-            tuple[torch.Tensor]: Contain score of each class, bbox predictions
-                and class predictions of direction.
+            tuple[torch.Tensor]: Contain score of each class, bbox \
+                regression and direction classification predictions.
         """
         cls_score = self.conv_cls(x)
         bbox_pred = self.conv_reg(x)
@@ -158,7 +158,7 @@ class Anchor3DHead(nn.Module, AnchorTrainMixin):
                 features produced by FPN.
 
         Returns:
-            tuple[list[torch.Tensor]]: Multi-level class score, bbox
+            tuple[list[torch.Tensor]]: Multi-level class score, bbox \
                 and direction predictions.
         """
         return multi_apply(self.forward_single, feats)
@@ -172,7 +172,7 @@ class Anchor3DHead(nn.Module, AnchorTrainMixin):
             device (str): device of current module
 
         Returns:
-            list[list[torch.Tensor]]: anchors of each image, valid flags
+            list[list[torch.Tensor]]: anchors of each image, valid flags \
                 of each image
         """
         num_imgs = len(input_metas)
@@ -202,7 +202,7 @@ class Anchor3DHead(nn.Module, AnchorTrainMixin):
             num_total_samples (int): The number of valid samples.
 
         Returns:
-            tuple[torch.Tensor]: losses of class, bbox
+            tuple[torch.Tensor]: losses of class, bbox \
                 and direction, respectively.
         """
         # classification loss
@@ -251,14 +251,14 @@ class Anchor3DHead(nn.Module, AnchorTrainMixin):
         """Convert the rotation difference to difference in sine function.
 
         Args:
-            boxes1 (torch.Tensor): shape (NxC), where C>=7 and
-                the 7th dimension is rotation dimension
-            boxes2 (torch.Tensor): shape (NxC), where C>=7 and the 7th
-                dimension is rotation dimension
+            boxes1 (torch.Tensor): Original Boxes in shape (NxC), where C>=7
+                and the 7th dimension is rotation dimension.
+            boxes2 (torch.Tensor): Target boxes in shape (NxC), where C>=7 and
+                the 7th dimension is rotation dimension.
 
         Returns:
-            tuple[torch.Tensor]: boxes1 and boxes2 whose 7th dimensions
-                are changed
+            tuple[torch.Tensor]: ``boxes1`` and ``boxes2`` whose 7th \
+                dimensions are changed.
         """
         rad_pred_encoding = torch.sin(boxes1[..., 6:7]) * torch.cos(
             boxes2[..., 6:7])
@@ -293,12 +293,12 @@ class Anchor3DHead(nn.Module, AnchorTrainMixin):
                 which bounding.
 
         Returns:
-            dict[str, list[torch.Tensor]]: Classification, bbox, and direction
-                losses of each level.
+            dict[str, list[torch.Tensor]]: Classification, bbox, and \
+                direction losses of each level.
 
                 - loss_cls (list[torch.Tensor]): Classification losses.
                 - loss_bbox (list[torch.Tensor]): Box regression losses.
-                - loss_dir (list[torch.Tensor]): Direction classification
+                - loss_dir (list[torch.Tensor]): Direction classification \
                     losses.
         """
         featmap_sizes = [featmap.size()[-2:] for featmap in cls_scores]

mmdet3d/models/dense_heads/parta2_rpn_head.py

@@ -104,12 +104,12 @@ class PartA2RPNHead(Anchor3DHead):
                 which bounding.
 
         Returns:
-            dict[str, list[torch.Tensor]]: Classification, bbox, and direction
-                losses of each level.
+            dict[str, list[torch.Tensor]]: Classification, bbox, and \
+                direction losses of each level.
 
                 - loss_rpn_cls (list[torch.Tensor]): Classification losses.
                 - loss_rpn_bbox (list[torch.Tensor]): Box regression losses.
-                - loss_rpn_dir (list[torch.Tensor]): Direction classification
+                - loss_rpn_dir (list[torch.Tensor]): Direction classification \
                     losses.
         """
         loss_dict = super().loss(cls_scores, bbox_preds, dir_cls_preds,
@@ -143,7 +143,7 @@ class PartA2RPNHead(Anchor3DHead):
             rescale (list[torch.Tensor]): whether th rescale bbox.
 
         Returns:
-            dict: Predictions of single batch. Contain the keys:
+            dict: Predictions of single batch containing the following keys:
 
                 - boxes_3d (:obj:`BaseInstance3DBoxes`): Predicted 3d bboxes.
                 - scores_3d (torch.Tensor): Score of each bbox.

mmdet3d/models/dense_heads/vote_head.py

@@ -15,9 +15,7 @@ from mmdet.models import HEADS
 
 @HEADS.register_module()
 class VoteHead(nn.Module):
-    """Bbox head of Votenet.
-
-    https://arxiv.org/pdf/1904.09664.pdf
+    r"""Bbox head of `Votenet <https://arxiv.org/abs/1904.09664>`_.
 
     Args:
         num_classes (int): The number of class.
@@ -113,11 +111,13 @@ class VoteHead(nn.Module):
     def forward(self, feat_dict, sample_mod):
         """Forward pass.
 
-        The forward of VoteHead is devided into 4 steps:
-            1. Generate vote_points from seed_points.
-            2. Aggregate vote_points.
-            3. Predict bbox and score.
-            4. Decode predictions.
+        Note:
+            The forward of VoteHead is devided into 4 steps:
+
+                1. Generate vote_points from seed_points.
+                2. Aggregate vote_points.
+                3. Predict bbox and score.
+                4. Decode predictions.
 
         Args:
             feat_dict (dict): feature dict from backbone.

mmdet3d/models/losses/chamfer_distance.py

@@ -26,14 +26,15 @@ def chamfer_distance(src,
             The valid reduction method are 'none', 'sum' or 'mean'.
 
     Returns:
-        tuple: Source and Destination loss with indices.
-            - loss_src (torch.Tensor): The min distance
+        tuple: Source and Destination loss with the corresponding indices.
+
+            - loss_src (torch.Tensor): The min distance \
                 from source to destination.
-            - loss_dst (torch.Tensor): The min distance
+            - loss_dst (torch.Tensor): The min distance \
                 from destination to source.
-            - indices1 (torch.Tensor): Index the min distance point
+            - indices1 (torch.Tensor): Index the min distance point \
                 for each point in source to destination.
-            - indices2 (torch.Tensor): Index the min distance point
+            - indices2 (torch.Tensor): Index the min distance point \
                 for each point in destination to source.
     """
 
@@ -123,10 +124,11 @@ class ChamferDistance(nn.Module):
                 Defaults to False.
 
         Returns:
-            tuple[torch.Tensor]: If ``return_indices=True``, return losses of
-                source and target with their corresponding indices in the order
-                of (loss_source, loss_target, indices1, indices2). If
-                ``return_indices=False``, return (loss_source, loss_target).
+            tuple[torch.Tensor]: If ``return_indices=True``, return losses of \
+                source and target with their corresponding indices in the \
+                order of ``(loss_source, loss_target, indices1, indices2)``. \
+                If ``return_indices=False``, return \
+                ``(loss_source, loss_target)``.
         """
         assert reduction_override in (None, 'none', 'mean', 'sum')
         reduction = (

mmdet3d/models/middle_encoders/sparse_encoder.py

@@ -7,9 +7,7 @@ from ..registry import MIDDLE_ENCODERS
 
 @MIDDLE_ENCODERS.register_module()
 class SparseEncoder(nn.Module):
-    """Sparse encoder for Second.
-
-    See https://arxiv.org/abs/1907.03670 for more detials.
+    r"""Sparse encoder for SECOND and Part-A2.
 
     Args:
         in_channels (int): the number of input channels

mmdet3d/models/middle_encoders/sparse_unet.py

@@ -8,9 +8,9 @@ from ..registry import MIDDLE_ENCODERS
 
 @MIDDLE_ENCODERS.register_module()
 class SparseUNet(nn.Module):
-    """SparseUNet for PartA^2.
+    r"""SparseUNet for PartA^2.
 
-    See https://arxiv.org/abs/1907.03670 for more detials.
+    See the `paper <https://arxiv.org/abs/1907.03670>`_ for more detials.
 
     Args:
         in_channels (int): the number of input channels
@@ -95,12 +95,13 @@ class SparseUNet(nn.Module):
         """Forward of SparseUNet.
 
         Args:
-            voxel_features (torch.float32): shape [N, C]
-            coors (torch.int32): shape [N, 4](batch_idx, z_idx, y_idx, x_idx)
-            batch_size (int): batch size
+            voxel_features (torch.float32): Voxel features in shape [N, C].
+            coors (torch.int32): Coordinates in shape [N, 4],
+                the columns in the order of (batch_idx, z_idx, y_idx, x_idx).
+            batch_size (int): Batch size.
 
         Returns:
-            dict: backbone features
+            dict[str, torch.Tensor]: Backbone features.
         """
         coors = coors.int()
         input_sp_tensor = spconv.SparseConvTensor(voxel_features, coors,
@@ -147,14 +148,14 @@ class SparseUNet(nn.Module):
         """Forward of upsample and residual block.
 
         Args:
-            x_lateral (:obj:`SparseConvTensor`): lateral tensor
-            x_bottom (:obj:`SparseConvTensor`): feature from bottom layer
-            lateral_layer (SparseBasicBlock): convolution for lateral tensor
-            merge_layer (SparseSequential): convolution for merging features
-            upsample_layer (SparseSequential): convolution for upsampling
+            x_lateral (:obj:`SparseConvTensor`): Lateral tensor.
+            x_bottom (:obj:`SparseConvTensor`): Feature from bottom layer.
+            lateral_layer (SparseBasicBlock): Convolution for lateral tensor.
+            merge_layer (SparseSequential): Convolution for merging features.
+            upsample_layer (SparseSequential): Convolution for upsampling.
 
         Returns:
-            :obj:`SparseConvTensor`: upsampled feature
+            :obj:`SparseConvTensor`: Upsampled feature.
         """
         x = lateral_layer(x_lateral)
         x.features = torch.cat((x_bottom.features, x.features), dim=1)
@@ -169,11 +170,12 @@ class SparseUNet(nn.Module):
         """reduce channel for element-wise addition.
 
         Args:
-            x (:obj:`SparseConvTensor`): x.features (N, C1)
-            out_channels (int): the number of channel after reduction
+            x (:obj:`SparseConvTensor`): Sparse tensor, ``x.features``
+                are in shape (N, C1).
+            out_channels (int): The number of channel after reduction.
 
         Returns:
-            :obj:`SparseConvTensor`: channel reduced feature
+            :obj:`SparseConvTensor`: Channel reduced feature.
         """
         features = x.features
         n, in_channels = features.shape
@@ -187,12 +189,12 @@ class SparseUNet(nn.Module):
         """make encoder layers using sparse convs.
 
         Args:
-            make_block (method): a bounded function to build blocks
-            norm_cfg (dict[str]): config of normalization layer
-            in_channels (int): the number of encoder input channels
+            make_block (method): A bounded function to build blocks.
+            norm_cfg (dict[str]): Config of normalization layer.
+            in_channels (int): The number of encoder input channels.
 
         Returns:
-            int: the number of encoder output channels
+            int: the number of encoder output channels.
         """
         self.encoder_layers = spconv.SparseSequential()
 
@@ -233,12 +235,12 @@ class SparseUNet(nn.Module):
         """make decoder layers using sparse convs.
 
         Args:
-            make_block (method): a bounded function to build blocks
-            norm_cfg (dict[str]): config of normalization layer
-            in_channels (int): the number of encoder input channels
+            make_block (method): A bounded function to build blocks.
+            norm_cfg (dict[str]): Config of normalization layer.
+            in_channels (int): The number of encoder input channels.
 
         Returns:
-            int: the number of encoder output channels
+            int: The number of encoder output channels.
         """
         block_num = len(self.decoder_channels)
         for i, block_channels in enumerate(self.decoder_channels):

mmdet3d/models/model_utils/vote_module.py

@@ -23,7 +23,7 @@ class VoteModule(nn.Module):
             Default: dict(type='BN1d').
         norm_feats (bool): Whether to normalize features.
             Default: True.
-        vote_loss (dict): config of vote loss.
+        vote_loss (dict): Config of vote loss.
     """
 
     def __init__(self,
@@ -66,18 +66,19 @@ class VoteModule(nn.Module):
         """forward.
 
         Args:
-            seed_points (torch.Tensor): (B, N, 3) coordinate of the seed
-                points.
-            seed_feats (torch.Tensor): (B, C, N) features of the seed points.
+            seed_points (torch.Tensor): Coordinate of the seed
+                points in shape (B, N, 3).
+            seed_feats (torch.Tensor): Features of the seed points in shape
+                (B, C, N).
 
         Returns:
             tuple[torch.Tensor]:
 
-                - vote_points: Voted xyz based on the seed points
-                    with shape (B, M, 3) M=num_seed*vote_per_seed.
-                - vote_features: Voted features based on the seed points with
-                    shape (B, C, M) where M=num_seed*vote_per_seed,
-                    C=vote_feature_dim.
+                - vote_points: Voted xyz based on the seed points \
+                    with shape (B, M, 3), ``M=num_seed*vote_per_seed``.
+                - vote_features: Voted features based on the seed points with \
+                    shape (B, C, M) where ``M=num_seed*vote_per_seed``, \
+                    ``C=vote_feature_dim``.
         """
         batch_size, feat_channels, num_seed = seed_feats.shape
         num_vote = num_seed * self.vote_per_seed
@@ -108,14 +109,14 @@ class VoteModule(nn.Module):
         """Calculate loss of voting module.
 
         Args:
-            seed_points (torch.Tensor): coordinate of the seed points.
-            vote_points (torch.Tensor): coordinate of the vote points.
-            seed_indices (torch.Tensor): indices of seed points in raw points.
-            vote_targets_mask (torch.Tensor): mask of valid vote targets.
-            vote_targets (torch.Tensor): targets of votes.
+            seed_points (torch.Tensor): Coordinate of the seed points.
+            vote_points (torch.Tensor): Coordinate of the vote points.
+            seed_indices (torch.Tensor): Indices of seed points in raw points.
+            vote_targets_mask (torch.Tensor): Mask of valid vote targets.
+            vote_targets (torch.Tensor): Targets of votes.
 
         Returns:
-            torch.Tensor: weighted vote loss.
+            torch.Tensor: Weighted vote loss.
         """
         batch_size, num_seed = seed_points.shape[:2]
 

mmdet3d/models/roi_heads/base_3droi_head.py

@@ -73,10 +73,10 @@ class Base3DRoIHead(nn.Module, metaclass=ABCMeta):
                 by 3D box structures.
             gt_labels (list[torch.LongTensor]): GT labels of each sample.
             gt_bboxes_ignore (list[torch.Tensor], optional):
-                Specify which bounding.
+                Ground truth boxes to be ignored.
 
         Returns:
-            dict: losses from each head.
+            dict[str, torch.Tensor]: losses from each head.
         """
         pass
 

mmdet3d/models/roi_heads/mask_heads/pointwise_semantic_head.py

@@ -87,7 +87,7 @@ class PointwiseSemanticHead(nn.Module):
             gt_labels_3d (torch.Tensor): shape [box_num], class label of gt
 
         Returns:
-            tuple[torch.Tensor]: segmentation targets with shape [voxel_num]
+            tuple[torch.Tensor]: segmentation targets with shape [voxel_num] \
                 part prediction targets with shape [voxel_num, 3]
         """
         gt_bboxes_3d = gt_bboxes_3d.to(voxel_centers.device)
@@ -136,10 +136,10 @@ class PointwiseSemanticHead(nn.Module):
         Returns:
             dict: prediction targets
 
-                - seg_targets (torch.Tensor): segmentation targets
-                    with shape [voxel_num]
-                - part_targets (torch.Tensor): part prediction targets
-                    with shape [voxel_num, 3]
+                - seg_targets (torch.Tensor): Segmentation targets \
+                    with shape [voxel_num].
+                - part_targets (torch.Tensor): Part prediction targets \
+                    with shape [voxel_num, 3].
         """
         batch_size = len(gt_labels_3d)
         voxel_center_list = []

tools/data_converter/lyft_converter.py

@@ -96,7 +96,7 @@ def _fill_trainval_infos(lyft,
     """Generate the train/val infos from the raw data.
 
     Args:
-        lyft (:obj:``LyftDataset``): Dataset class in the Lyft dataset.
+        lyft (:obj:`LyftDataset`): Dataset class in the Lyft dataset.
         train_scenes (list[str]): Basic information of training scenes.
         val_scenes (list[str]): Basic information of validation scenes.
         test (bool): Whether use the test mode. In the test mode, no

tools/data_converter/nuscenes_converter.py

@@ -146,7 +146,7 @@ def _fill_trainval_infos(nusc,
     """Generate the train/val infos from the raw data.
 
     Args:
-        nusc (:obj:``NuScenes``): Dataset class in the nuScenes dataset.
+        nusc (:obj:`NuScenes`): Dataset class in the nuScenes dataset.
         train_scenes (list[str]): Basic information of training scenes.
         val_scenes (list[str]): Basic information of validation scenes.
         test (bool): Whether use the test mode. In the test mode, no