Merge branch 'refine-doc' into 'master'

refine docs of benchmark and requirements

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

docs/benchmarks.md

@@ -18,111 +18,135 @@ with some other popular open source 3D detection codebases.
 
 ### VoteNet
 
-We compare our implementation with VoteNet and report the performance of VoteNets on SUNRGB-D v2 dataset under the AP@0.5 metric.
+We compare our implementation of VoteNet with [votenet](https://github.com/facebookresearch/votenet/) and report the performance on SUNRGB-D v2 dataset under the AP@0.5 metric.
 
 ```eval_rst
-  +----------------+---------------------+--------------------+-------------------+--------+
-  | Implementation | Training (sample/s) | Testing (sample/s) | Training Time (h) | AP@0.5 |
-  +================+=====================+====================+===================+========+
-  | MMDetection3D  |                     |                    |                   |        |
-  +----------------+---------------------+--------------------+-------------------+--------+
-  | VoteNet        |                     |                    |                   |        |
-  +----------------+---------------------+--------------------+-------------------+--------+
+  +----------------+---------------------+--------------------+--------+
+  | Implementation | Training (sample/s) | Testing (sample/s) | AP@0.5 |
+  +================+=====================+====================+========+
+  | MMDetection3D  |        358          |         17         |  35.8  |
+  +----------------+---------------------+--------------------+--------+
+  | VoteNet        |        77           |         3          |  31.5  |
+  +----------------+---------------------+--------------------+--------+
 ```
 
 ### PointPillars
 
-Since Det3D only provides PointPillars on car class while PCDet only provides PointPillars
+Since [Det3D](https://github.com/poodarchu/Det3D/) only provides PointPillars on car class while [PCDet](https://github.com/sshaoshuai/PCDet) only provides PointPillars
 on 3 classes, we compare with them separately. For performance on single class, we report the AP on moderate
 condition following the KITTI benchmark and compare average AP over all classes on moderate condition for
 performance on 3 classes.
 
 ```eval_rst
-  +----------------+---------------------+--------------------+-------------------+-------------+
-  | Implementation | Training (sample/s) | Testing (sample/s) | Training Time (h) | Moderate AP |
-  +================+=====================+====================+===================+=============+
-  | MMDetection3D  |                     |                    |                   |             |
-  +----------------+---------------------+--------------------+-------------------+-------------+
-  | PCDet          |                     |                    |                   |             |
-  +----------------+---------------------+--------------------+-------------------+-------------+
+  +----------------+---------------------+--------------------+
+  | Implementation | Training (sample/s) | Testing (sample/s) |
+  +================+=====================+====================+
+  | MMDetection3D  |         141         |                    |
+  +----------------+---------------------+--------------------+
+  | Det3D          |         140         |        20          |
+  +----------------+---------------------+--------------------+
 ```
 
 ```eval_rst
-  +----------------+---------------------+--------------------+-------------------+-------------+
-  | Implementation | Training (sample/s) | Testing (sample/s) | Training Time (h) | Moderate AP |
-  +================+=====================+====================+===================+=============+
-  | MMDetection3D  |                     |                    |                   |             |
-  +----------------+---------------------+--------------------+-------------------+-------------+
-  | Det3D          |                     |                    |                   |             |
-  +----------------+---------------------+--------------------+-------------------+-------------+
+  +----------------+---------------------+--------------------+
+  | Implementation | Training (sample/s) | Testing (sample/s) |
+  +================+=====================+====================+
+  | MMDetection3D  |         120         |                    |
+  +----------------+---------------------+--------------------+
+  | PCDet          |         43          |        64          |
+  +----------------+---------------------+--------------------+
 ```
 
 ### SECOND
 
-Det3D provides a different SECOND on car class and we cannot train the original SECOND by modifying the config.
-So we only compare with PCDet, which is a SECOND model on 3 classes, we report the AP on moderate
+[Det3D](https://github.com/poodarchu/Det3D/) provides a different SECOND on car class and we cannot train the original SECOND by modifying the config.
+So we only compare with [PCDet](https://github.com/sshaoshuai/PCDet), which is a SECOND model on 3 classes, we report the AP on moderate
 condition following the KITTI benchmark and compare average AP over all classes on moderate condition for
 performance on 3 classes.
 
   ```eval_rst
-    +----------------+---------------------+--------------------+-------------------+-------------+
-    | Implementation | Training (sample/s) | Testing (sample/s) | Training Time (h) | Moderate AP |
-    +================+=====================+====================+===================+=============+
-    | MMDetection3D  |                     |                    |                   |             |
-    +----------------+---------------------+--------------------+-------------------+-------------+
-    | PCDet          |                     |                    |                   |             |
-    +----------------+---------------------+--------------------+-------------------+-------------+
+    +----------------+---------------------+--------------------+
+    | Implementation | Training (sample/s) | Testing (sample/s) |
+    +================+=====================+====================+
+    | MMDetection3D  |         54          |                    |
+    +----------------+---------------------+--------------------+
+    | PCDet          |         44          |         30         |
+    +----------------+---------------------+--------------------+
   ```
 
 ### Part-A2
 
-We benchmark Part-A2 with that in PCDet. We report the AP on moderate condition following the KITTI benchmark
+We benchmark Part-A2 with that in [PCDet](https://github.com/sshaoshuai/PCDet). We report the AP on moderate condition following the KITTI benchmark
 and compare average AP over all classes on moderate condition for performance on 3 classes.
 
   ```eval_rst
-    +----------------+---------------------+--------------------+-------------------+-------------+
-    | Implementation | Training (sample/s) | Testing (sample/s) | Training Time (h) | Moderate AP |
-    +================+=====================+====================+===================+=============+
-    | MMDetection3D  |                     |                    |                   |             |
-    +----------------+---------------------+--------------------+-------------------+-------------+
-    | PCDet          |                     |                    |                   |             |
-    +----------------+---------------------+--------------------+-------------------+-------------+
+    +----------------+---------------------+--------------------+
+    | Implementation | Training (sample/s) | Testing (sample/s) |
+    +================+=====================+====================+
+    | MMDetection3D  |         17          |                    |
+    +----------------+---------------------+--------------------+
+    | PCDet          |         15          |         12         |
+    +----------------+---------------------+--------------------+
   ```
 
 ## Details of Comparison
 
+### Modification for Calculating Speed
+
+* __Det3D__: At commit 255c593
+
+
+* __PCDet__: At commit 2244be4
+
+
+
 ### VoteNet
 
 * __MMDetection3D__: With release v0.1.0, run
 ```
-./tools/dist_train.sh configs/votenet/mask_rcnn_r50_caffe_fpn_1x_coco.py 8
+./tools/dist_train.sh configs/votenet/votenet_16x8_sunrgbd-3d-10class.py 8 --no-validate
+```
+* __votenet__: At commit xxxx, run
+```
 ```
-* __votenet__:
 
 
 ### PointPillars
 
 * __MMDetection3D__: With release v0.1.0, run
 ```
+./tools/dist_train.sh configs/benchmark/hv_pointpillars_secfpn_6x8_160e_pcdet_kitti-3d-3class.py 8 --no-validate
 ```
 * __PCDet__: At commit xxxx
+```
+./tools/dist_train.sh configs/benchmark/hv_pointpillars_secfpn_6x8_160e_pcdet_kitti-3d-3class.py 8 --no-validate
+```
+
+* __MMDetection3D__: With release v0.1.0, run
+```
+./tools/dist_train.sh configs/benchmark/hv_pointpillars_secfpn_3x8_100e_det3d_kitti-3d-car.py 8 --no-validate
+```
+* __Det3D__: At commit xxxx
+```
+
+```
 
 
 ### SECOND
 
 * __MMDetection3D__: With release v0.1.0, run
 ```
+./tools/dist_train.sh configs/benchmark/hv_second_secfpn_6x8_80e_pcdet_kitti-3d-3class.py 8 --no-validate
 ```
 
-* __PCDet__:
+* __PCDet__: At commit 2244be4
 
 
 ### Part-A2
 
 * __MMDetection3D__: With release v0.1.0, run
 ```
+./tools/dist_train.sh configs/benchmark/hv_PartA2_secfpn_2x8_cyclic_80e_pcdet_kitti-3d-3class.py 8 --no-validate
 ```
 
-* __PCDet__: At commit xxxx
-
-### Modification for Calculating Training Speed
+* __PCDet__:

docs/index.rst

@@ -6,6 +6,8 @@ Welcome to MMDetection3D's documentation!
 
    install.md
    getting_started.md
+   model_zoo.md
+   benchmarks.md
    config.md
    tutorials/finetune.md
    tutorials/new_dataset.md

docs/install.md

@@ -58,6 +58,7 @@ for better compatibility with our repo.)
 
 ```shell
 pip install -r requirements/build.txt
+pip install cython  # cython is necessary for pycocotools
 pip install "git+https://github.com/open-mmlab/cocoapi.git#subdirectory=pycocotools"
 pip install -v -e .  # or "python setup.py develop"
 ```
@@ -68,6 +69,20 @@ If you build mmdetection on macOS, replace the last command with
 CC=clang CXX=clang++ CFLAGS='-stdlib=libc++' pip install -e .
 ```
 
+e. Clone the mmdetection3d repository.
+
+```shell
+git clone https://github.com/open-mmlab/mmdetection3d.git
+cd mmdetection3d
+```
+
+f.Install build requirements and then install mmdetection3d.
+
+```shell
+pip install -r requirements/build.txt
+pip install -v -e .  # or "python setup.py develop"
+```
+
 Note:
 
 1. The git commit id will be written to the version number with step d, e.g. 0.6.0+2e7045c. The version will also be saved in trained models.
@@ -76,7 +91,7 @@ It is recommended that you run step d each time you pull some updates from githu
     > Important: Be sure to remove the `./build` folder if you reinstall mmdet with a different CUDA/PyTorch version.
 
     ```
-    pip uninstall mmdet
+    pip uninstall mmdet3d
     rm -rf ./build
     find . -name "*.so" | xargs rm
     ```
@@ -88,35 +103,8 @@ you can install it before installing MMCV.
 
 4. Some dependencies are optional. Simply running `pip install -v -e .` will only install the minimum runtime requirements. To use optional dependencies like `albumentations` and `imagecorruptions` either install them manually with `pip install -r requirements/optional.txt` or specify desired extras when calling `pip` (e.g. `pip install -v -e .[optional]`). Valid keys for the extras field are: `all`, `tests`, `build`, and `optional`.
 
-### Install with CPU only
-The code can be built for CPU only environment (where CUDA isn't available).
-
-In CPU mode you can run the demo/webcam_demo.py for example.
-However some functionality is gone in this mode:
-
-- Deformable Convolution
-- Deformable ROI pooling
-- CARAFE: Content-Aware ReAssembly of FEatures
-- nms_cuda
-- sigmoid_focal_loss_cuda
+5. The code can not be built for CPU only environment (where CUDA isn't available) for now.
 
-So if you try to run inference with a model containing deformable convolution you will get an error.
-Note: We set `use_torchvision=True` on-the-fly in CPU mode for `RoIPool` and `RoIAlign`
-
-### Another option: Docker Image
-
-We provide a [Dockerfile](https://github.com/open-mmlab/mmdetection/blob/master/docker/Dockerfile) to build an image.
-
-```shell
-# build an image with PyTorch 1.5, CUDA 10.1
-docker build -t mmdetection docker/
-```
-
-Run it with
-
-```shell
-docker run --gpus all --shm-size=8g -it -v {DATA_DIR}:/mmdetection/data mmdetection
-```
 
 ### A from-scratch setup script
 
@@ -131,15 +119,22 @@ conda install -c pytorch pytorch torchvision -y
 git clone https://github.com/open-mmlab/mmdetection.git
 cd mmdetection
 pip install -r requirements/build.txt
+pip install cython
 pip install "git+https://github.com/open-mmlab/cocoapi.git#subdirectory=pycocotools"
 pip install -v -e .
+
+cd ..
+git clone https://github.com/open-mmlab/mmdetection3d.git
+cd mmdetection3d
+pip install -r requirements/build.txt
+pip install -v -e .
 ```
 
-### Using multiple MMDetection versions
+### Using multiple MMDetection3D versions
 
-The train and test scripts already modify the `PYTHONPATH` to ensure the script use the MMDetection in the current directory.
+The train and test scripts already modify the `PYTHONPATH` to ensure the script use the MMDetection3D in the current directory.
 
-To use the default MMDetection installed in the environment rather than that you are working with, you can remove the following line in those scripts
+To use the default MMDetection3D installed in the environment rather than that you are working with, you can remove the following line in those scripts
 
 ```shell
 PYTHONPATH="$(dirname $0)/..":$PYTHONPATH

requirements/optional.txt

-# To avoid install too many unnecessary packages
-nuscenes-devkit==1.0.5

requirements/runtime.txt

@@ -2,6 +2,7 @@ matplotlib
 mmcv>=0.6.0
 numba==0.48.0
 numpy
+nuscenes-devkit==1.0.5
 # need older pillow until torchvision is fixed
 Pillow<=6.2.2
 six