Update docs for multiple object tracking (#46)

* mv mmcls to requirements * rm empty docs * re-organize modelzoo * det cfgs * tracktor * sort
open-mmlab · Dec 30, 2020 · 1e2843c · 1e2843c
1 parent 10b586e
commit 1e2843c
Show file tree

Hide file tree

Showing 13 changed files with 81 additions and 57 deletions.
diff --git a/configs/det/README.md b/configs/det/README.md
@@ -0,0 +1,51 @@
+# Compatibility with MMDetection
+
+You may want to train a detector for multiple object tracking or other applications.
+
+To be compatablie with MMDetection, you only need to add a line of `USE_MMDET=True` in the config and run it with the same manner in mmdetection.
+
+A base example can be found at [faster_rcnn_r50_fpn.py](../_base_/models/faster_rcnn_r50_fpn.py).
+
+Please NOTE that there are some differences between the base config in MMTracking and MMDetection.
+
+1. `detector` is only a submodule of the `model`.
+
+    For example, the config of Faster R-CNN in MMDetection follows
+    ```python
+    model = dict(
+        type='FasterRCNN',
+        ...
+    )
+    ```
+
+    But in MMTracking, the config follows
+    ```python
+    model = dict(
+        detector=dict(
+            type='FasterRCNN',
+            ...
+        )
+    )
+    ```
+
+2. `train_cfg` and `test_cfg` are merged into `model` / `detector`.
+
+    In MMDetection, the configs follows
+    ```python
+    model = dict()
+    train_cfg = dict()
+    test_cfg = dict()
+    ```
+
+    While in MMTracking, the config follows
+    ```python
+    model = dict(
+        detector=dict(
+            train_cfg=dict(),
+            test_cfg=dict(),
+            ...
+        )
+    )
+    ```
+
+We are putting efforts to bridge these gaps across different codebases and try to give simpler configs.
diff --git a/configs/mot/deepsort/README.md b/configs/mot/deepsort/README.md
@@ -23,6 +23,11 @@
 
 ## Results and models on MOT17
 
+We implement DeepSORT following the offical practices.
+
+We train the detector with MMDetection. However, currently we do not support training ReID models.
+We directly use the model from [Tracktor](https://github.com/phil-bergmann/tracking_wo_bnw) for inference. These missed features will be supported in the future.
+
 |    Detector     |  ReID  | Train Set | Test Set | Public | Inf time (fps) | MOTA | IDF1 | FP | FN | IDSw. | Config | Download |
 | :-------------: | :----: | :-------: | :------: | :----: | :------------: | :--: | :--: |:--:|:--:| :---: | :----: | :------: |
 | R50-FasterRCNN-FPN | -  | half-train | half-val | Y     | 28.3 |   46.0 | 46.6 | 289 | 82451 | 4581 | [config](sort_faster-rcnn_fpn_4e_mot17-public-half.py) |  [detector](https://download.openmmlab.com/mmtracking/v0.5/mot/faster-rcnn_r50_fpn_4e_mot17-half-64ee2ed4.pth) [reid](https://download.openmmlab.com/mmtracking/v0.5/mot/tracktor_reid_r50_iter25245-a452f51f.pth) |

diff --git a/configs/mot/tracktor/README.md b/configs/mot/tracktor/README.md
@@ -14,6 +14,13 @@
 
 ## Results and models on MOT17
 
+We implement Tracktor following the offical practices.
+
+We train the detector with MMDetection. However, currently we do not support training ReID models.
+We directly use the model from [Tracktor](https://github.com/phil-bergmann/tracking_wo_bnw) for inference. These missed features will be supported in the future.
+
+The results marked with * (the last line) is the offical implementations. Our implementations outperform it by 4.9 points on MOTA and 3.3 points on IDF1.
+
 |    Detector     |  ReID  | Train Set | Test Set | Public | Inf time (fps) | MOTA | IDF1 | FP | FN | IDSw. | Config | Download |
 | :-------------: | :----: | :-------: | :------: | :----: | :------------: | :--: | :--: |:--:|:--:| :---: | :----: | :------: |
 | R50-FasterRCNN-FPN | R50 | half-train | half-val | Y     | 3.2  | 57.3 | 63.4 | 1254 | 67091 | 613 | [config](tracktor_faster-rcnn_r50_fpn_4e_mot17-public-half.py) | [detector](https://download.openmmlab.com/mmtracking/v0.5/mot/faster-rcnn_r50_fpn_4e_mot17-half-64ee2ed4.pth) [reid](https://download.openmmlab.com/mmtracking/v0.5/mot/tracktor_reid_r50_iter25245-a452f51f.pth) |

diff --git a/docs/faq.md b/docs/faq.md
diff --git a/docs/install.md b/docs/install.md
@@ -7,7 +7,7 @@
 - GCC 5+
 - [MMCV](https://mmcv.readthedocs.io/en/latest/#installation)
 - [MMDetection](https://mmdetection.readthedocs.io/en/latest/#installation)
-- [MMClassification](https://mmclassification.readthedocs.io/en/latest/#installation)
+<!-- - [MMClassification](https://mmclassification.readthedocs.io/en/latest/#installation) -->
 
 The compatible MMDetection and MMCV versions are as below. Please install the correct version of MMCV to avoid installation issues.
 
@@ -100,7 +100,7 @@ If mmcv and mmcv-full are both installed, there will be `ModuleNotFoundError`.
     pip install -v -e .  # or "python setup.py develop"
     ```
 
-5. Install MMClassification.
+<!-- 5. Install MMClassification.
 
     ```shell
     pip install git+https://github.com/open-mmlab/mmclassification.git
@@ -111,16 +111,16 @@ If mmcv and mmcv-full are both installed, there will be `ModuleNotFoundError`.
     git clone https://github.com/open-mmlab/mmclassification.git
     cd mmclassification
     pip install -v -e .  # or "python setup.py develop"
-    ```
+    ``` -->
 
-6. Clone the MMTracking repository.
+5. Clone the MMTracking repository.
 
     ```shell
     git clone https://github.com/open-mmlab/mmtracking.git
     cd mmtracking
     ```
 
-7. Install build requirements and then install MMTracking.
+6. Install build requirements and then install MMTracking.
 
     ```shell
     pip install -r requirements/build.txt

diff --git a/docs/model_zoo.md b/docs/model_zoo.md
@@ -8,6 +8,18 @@
 Note that this value is usually less than what `nvidia-smi` shows.
 - We report the inference time as the total time of network forwarding and post-processing, excluding the data loading time.
 Results are obtained with the script `tools/benchmark.py` which computes the average time on 2000 images.
+- Speed benchmark environments
+
+    HardWare
+    - 8 NVIDIA Tesla V100 (32G) GPUs
+    - Intel(R) Xeon(R) Gold 6148 CPU @ 2.40GHz
+
+    Software environment
+    - Python 3.7
+    - PyTorch 1.5
+    - CUDA 10.1
+    - CUDNN 7.6.03
+    - NCCL 2.4.08
 
 ## Baselines of video object detection
 
@@ -20,7 +32,7 @@ Please refer to [FGFA](../configs/vid/fgfa/README.md) for details.
 ### SELSA
 Please refer to [SELSA](../configs/vid/selsa/README.md) for details.
 
-## Baselines of multi object tracking
+## Baselines of multiple object tracking
 
 ### SORT/DeepSORT
 Please refer to [SORT/DeepSORT](../configs/mot/deepsort/README.md) for details.
@@ -32,54 +44,3 @@ Please refer to [Tracktor](../configs/mot/tracktor/README.md) for details.
 
 ### SiameseRPN++
 Please refer to [SiameseRPN++](../configs/sot/siamese_rpn/README.md) for details.
-
-## Speed Benchmark
-
-### HardWare
-- 8 NVIDIA Tesla V100 (32G) GPUs
-- Intel(R) Xeon(R) Gold 6148 CPU @ 2.40GHz
-
-### Software environment
-- Python 3.7
-- PyTorch 1.5
-- CUDA 10.1
-- CUDNN 7.6.03
-- NCCL 2.4.08
-
-### Training speed and memory of video object detection
-
-For fair comparison, we benchmark all implementations with ResNet-101.
-
-The training speed is reported as followed, in terms of second per iter (s/iter). The lower, the better.
-
-| Method       | speed      | memory      |
-|--------------|------------|-------------|
-| DFF          | 0.175      | 3333        |
-| FGFA         | 0.310      | 5935        |
-| SELSA        | 0.300      | 5305        |
-
-### Inference speed of video object detection
-
-For fair comparison, we benchmark all implementations with ResNet-101.
-
-The inference speed is measured with fps (img/s) on a single GPU, the higher, the better.
-
-| Method       | speed      |
-|--------------|------------|
-| DFF          | 39.8       |
-| FGFA         | 6.4        |
-| SELSA        | 7.2        |
-
-### Training speed and memory of multi object tracking
-
-
-
-### Inference speed of multi object tracking
-
-
-
-### Training speed and memory of single object tracking
-
-
-
-### Inference speed of single object tracking
diff --git a/docs/quick_run.md b/docs/quick_run.md
diff --git a/docs/tools.md b/docs/tools.md
diff --git a/docs/tutorials/config.md b/docs/tutorials/config.md
diff --git a/docs/tutorials/customize_data_pipeline.md b/docs/tutorials/customize_data_pipeline.md
diff --git a/docs/tutorials/customize_dataset.md b/docs/tutorials/customize_dataset.md
diff --git a/docs/tutorials/customize_models.md b/docs/tutorials/customize_models.md
diff --git a/docs/tutorials/customize_runtime.md b/docs/tutorials/customize_runtime.md