Update docs (tusen-ai#219)

* stash

* stash

* stash

* add

* update

* fix lr scheduler

* update merging description

* update lr scheduler for finetune

* update finetune

* update test

* update rpn test

* add json to roidb

* update

* stash

* allow negative iter step

* stash

* update

* fix

* add support for tensorboard

* fix

* update

* fix py3.5

* trident with gn

* update create voc roidb

* update for dataset other than coco

* add doc for datasets

* take time

* cleanup

* update

* update readme

* wording

* update distributed

* use 2017 split

* smaller diagram

* smaller

* update data preparation

* add all-in-one script

Author: RogerChern

README.md

@@ -1,11 +1,12 @@
 ## SimpleDet - A Simple and Versatile Framework for Object Detection and Instance Recognition
 ### Major Features
-![](./doc/image/diagram.png)
+![](./doc/image/diagram_v2.png)
 - FP16 training for memory saving and up to **2.5X** acceleration
 - Highly scalable distributed training available **out of box**
-- Full coverage of state-of-the-art models including FasterRCNN, MaskRCNN, CascadeRCNN, RetinaNet, **[TridentNet](./models/tridentnet)**, **[NASFPN](./models/NASFPN)** and **[EfficientNet](./models/efficientnet)**
-- Extensive feature set including **large batch BN**, **loss synchronization**, **automatic BN fusion**, deformable convolution, soft NMS, multi-scale train/test
+- Full coverage of state-of-the-art models including FasterRCNN, MaskRCNN, CascadeRCNN, RetinaNet, [DCNv1/v2](./models/dcn), **[TridentNet](./models/tridentnet)**, **[NASFPN](./models/NASFPN)** , **[EfficientNet](./models/efficientnet)**, and **[Kownledge Distillation](./models/KD)**
+- Extensive feature set including **large batch BN**, **loss synchronization**, **automatic BN fusion**, soft NMS, multi-scale train/test
 - Modular design for coding-free exploration of new experiment settings
+- Extensive documentations including [annotated config](./doc/fully_annotated_config.py), [Fintuning Guide](./doc/FINETUNE.md)
 
 ### Recent Updates
 - Add RPN test (2019.05.28)
@@ -21,80 +22,94 @@
 - Add python wheel for easy local installation (2019.08.20)
 - Add FitNet based Knowledge Distill (2019.08.27)
 - Add SE and train from scratch (2019.08.30)
+- Add a lot of docs (2019.09.03)
 
 ### Setup
+#### All-in-one Script
+We provide a [setup script](./scripts/setup.sh) for install simpledet and preppare the coco dataset.
+
 #### Install
-SimpleDet contains a lot of C++ operators not in MXNet offical repo, so one has to build MXNet from scratch. Please refer to [INSTALL.md](./doc/INSTALL.md) more details
+We provide a local installation here for Debian/Ubuntu system. To use a pre-built docker or singularity images, please refer to [INSTALL.md](./doc/INSTALL.md) for more information.
 
-#### Preparing Data
-SimpleDet requires groundtruth annotation organized as following format
-```
-[
-    {
-        "gt_class": (nBox, ),
-        "gt_bbox": (nBox, 4),
-        "flipped": bool,
-        "h": int,
-        "w": int,
-        "image_url": str,
-        "im_id": int,
-
-        # this fields are generated on the fly during test
-        "rec_id": int,
-        "resize_h": int,
-        "resize_w": int,
-        ...
-    },
-    ...
-]
-```
+```bash
+# install dependency
+sudo apt update && sudo apt install -y git wget make python3-dev libglib2.0-0 libsm6 libxext6 libxrender-dev unzip
 
-Especially, for experimenting on coco datatet, one can organize coco data in
-```
-data/
-    coco/
-        annotations/
-            instances_train2014.json
-            instances_valminusminival2014.json
-            instances_minival2014.json
-            image_info_test-dev2017.json
-        images/
-            train2014
-            val2014
-            test2017
-```
+# install python dependency
+pip3 install 'matplotlib<3.1' opencv-python pytz --user
 
-and run the helper script to generate roidb
-```bash
-python3 utils/generate_roidb.py --dataset coco --dataset-split train2014
-python3 utils/generate_roidb.py --dataset coco --dataset-split valminusminival2014
-python3 utils/generate_roidb.py --dataset coco --dataset-split minival2014
-python3 utils/generate_roidb.py --dataset coco --dataset-split test-dev2017
+# download and intall pre-built wheel for CUDA 10.0
+# check INSTALL.md for wheels for other CUDA version
+wget https://bit.ly/2jRGqdc -O mxnet_cu100-1.6.0b20190820-py2.py3-none-manylinux1_x86_64.whl
+pip3 install mxnet_cu100-1.6.0b20190820-py2.py3-none-manylinux1_x86_64.whl --user
+
+# install pycocotools
+pip3 install 'git+https://github.com/RogerChern/cocoapi.git#subdirectory=PythonAPI' --user
+
+# install mxnext, a wrapper around MXNet symbolic API
+pip3 install 'git+https://github.com/RogerChern/mxnext#egg=mxnext' --user
+
+# get simpledet
+git clone https://github.com/tusimple/simpledet
+cd simpledet
+make
+
+# test simpledet installation
+mkdir -p experiments/faster_r50v1_fpn_1x
+python3 detection_infer_speed.py --config config/faster_r50v1_fpn_1x.py --shape 800 1333
 ```
 
-#### Deploy dependency and compile extension
-1. setup mxnext, a wrapper of mxnet symbolic API
+If the last line execute successfully, the average running speed of Faster R-CNN R-50 FPN will be reported. And you have successfuly setup SimpleDet. Now you can head up to the next section to prepare your dataset.
+
+
+#### Preparing Data
+We provide a step by step preparation for the COCO dataset below.
 ```bash
-cd $SIMPLEDET_DIR
-pip install git+https://github.com/RogerChern/mxnext#egg=mxnext
+cd simpledet
+
+# make data dir
+mkdir -p data/coco/images data/src
+
+# skip this if you have the zip files
+wget -c http://images.cocodataset.org/zips/train2017.zip -O data/src/train2017.zip
+wget -c http://images.cocodataset.org/zips/val2017.zip -O data/src/val2017.zip
+wget -c http://images.cocodataset.org/zips/test2017.zip -O data/src/test2017.zip
+wget -c http://images.cocodataset.org/annotations/annotations_trainval2017.zip -O data/src/annotations_trainval2017.zip
+wget -c http://images.cocodataset.org/annotations/image_info_test2017.zip -O data/src/image_info_test2017.zip
+
+unzip data/src/train2017.zip -d data/coco/images
+unzip data/src/val2017.zip -d data/coco/images
+unzip data/src/test2017.zip -d data/coco/images
+unzip data/src/annotations_trainval2017.zip -d data/coco
+unzip data/src/image_info_test2017.zip -d data/coco
+
+python3 utils/create_coco_roidb.py --dataset coco --dataset-split train2017
+python3 utils/create_coco_roidb.py --dataset coco --dataset-split val2017
+python3 utils/create_coco_roidb.py --dataset coco --dataset-split test-dev2017
 ```
-2. run make in simpledet directory to install cython extensions
+
+For other datasets or your own data, please check [DATASET.md](doc/DATASET.md) for more details.
 
 #### Quick Start
 
 ```bash
 # train
-python3 detection_train.py --config config/detection_config.py
+python3 detection_train.py --config config/faster_r50v1_fpn_1x.py
 
 # test
-python3 detection_test.py --config config/detection_config.py
+python3 detection_test.py --config config/faster_r50v1_fpn_1x.py
 ```
 
+#### Finetune
+Please check [FINTUNE.md](doc/FINETUNE.md)
 
-### Project Design
 #### Model Zoo
 Please refer to [MODEL_ZOO.md](./MODEL_ZOO.md) for available models
 
+### Distributed Training
+Please refer to [DISTRIBUTED.md](./doc/DISTRIBUTED.md)
+
+### Project Organization
 #### Code Structure
 ```
 detection_train.py
@@ -135,8 +150,10 @@ experiments/
 #### Models
 The `models` directory contains SOTA models implemented in SimpletDet.
 
-#### How is Faster-RCNN built
-**Simpledet** supports many popular detection methods and here we take [**Faster-RCNN**](https://arxiv.org/abs/1506.01497) as a typical example to show how a detector is built.
+#### How is Faster R-CNN built
+![Faster R-CNN](doc/image/detector.png)
+
+**Simpledet** supports many popular detection methods and here we take [**Faster R-CNN**](https://arxiv.org/abs/1506.01497) as a typical example to show how a detector is built.
 
 - *Preprocessing*. The preprocessing methods of the detector is implemented through `DetectionAugmentation`.
   - Image/bbox-related preprocessing, such as `Norm2DImage` and `Resize2DImageBbox`.
@@ -149,18 +166,14 @@ The `models` directory contains SOTA models implemented in SimpletDet.
   - *Bounding Box Head*. `BboxHead` builds the R-CNN layers for proposal refinement.
 
 #### How to build a custom detector
-The flexibility of **simpledet** framework makes it easy to build different detectors. We take [**TridentNet**](https://arxiv.org/abs/1901.01892) as an example to demonstrate how to build a custom detector simply based on the **Faster-RCNN** framework.
+The flexibility of **simpledet** framework makes it easy to build different detectors. We take [**TridentNet**](https://arxiv.org/abs/1901.01892) as an example to demonstrate how to build a custom detector simply based on the Faster R-CNN framework.
 
 - *Preprocessing*. The additional processing methods could be provided accordingly by inheriting from `DetectionAugmentation`.
   - In TridentNet, a new `TridentAnchorTarget2D` is implemented to generate anchors for multiple branches and filter anchors for scale-aware training scheme.
 - *Network Structure*. The new network structure could be constructed easily for a custom detector by modifying some required components as needed and
   - For TridentNet, we build trident blocks in the `Backbone` according to the descriptions in the paper. We also provide a `TridentRpnHead` to generate filtered proposals in RPN to implement the scale-aware scheme. Other components are shared the same with original Faster-RCNN.
 
 
-### Distributed Training
-Please refer to [DISTRIBUTED.md](./doc/DISTRIBUTED.md)
-
-
 ### Contributors
 Yuntao Chen, Chenxia Han, Yanghao Li, Zehao Huang, Yi Jiang, Naiyan Wang
 

config/cascade_r101v1_fpn_1x.py

@@ -175,9 +175,9 @@ class RoiParam:
 
     class DatasetParam:
         if is_train:
-            image_set = ("coco_train2014", "coco_valminusminival2014")
+            image_set = ("coco_train2017", )
         else:
-            image_set = ("coco_minival2014", )
+            image_set = ("coco_val2017", )
 
     backbone = Backbone(BackboneParam)
     neck = Neck(NeckParam)

config/cascade_r101v2_c5_red_1x.py

@@ -176,9 +176,9 @@ class RoiParam:
 
     class DatasetParam:
         if is_train:
-            image_set = ("coco_train2014", "coco_valminusminival2014")
+            image_set = ("coco_train2017", )
         else:
-            image_set = ("coco_minival2014", )
+            image_set = ("coco_val2017", )
 
     backbone = Backbone(BackboneParam)
     neck = Neck(NeckParam)

config/cascade_r50v1_fpn_1x.py

@@ -175,9 +175,9 @@ class RoiParam:
 
     class DatasetParam:
         if is_train:
-            image_set = ("coco_train2014", "coco_valminusminival2014")
+            image_set = ("coco_train2017", )
         else:
-            image_set = ("coco_minival2014", )
+            image_set = ("coco_val2017", )
 
     backbone = Backbone(BackboneParam)
     neck = Neck(NeckParam)

config/cascade_r50v2_c5_red_1x.py

@@ -176,9 +176,9 @@ class RoiParam:
 
     class DatasetParam:
         if is_train:
-            image_set = ("coco_train2014", "coco_valminusminival2014")
+            image_set = ("coco_train2017", )
         else:
-            image_set = ("coco_minival2014", )
+            image_set = ("coco_val2017", )
 
     backbone = Backbone(BackboneParam)
     neck = Neck(NeckParam)

config/dcn/faster_dcn_r101v1bc4_c5_512roi_1x.py

@@ -99,9 +99,9 @@ class RoiParam:
 
     class DatasetParam:
         if is_train:
-            image_set = ("coco_train2014", "coco_valminusminival2014")
+            image_set = ("coco_train2017", )
         else:
-            image_set = ("coco_minival2014", )
+            image_set = ("coco_val2017", )
 
     backbone = Backbone(BackboneParam)
     neck = Neck(NeckParam)

config/dcn/faster_dcn_r50v1bc4_c5_512roi_1x.py

@@ -100,9 +100,9 @@ class RoiParam:
 
     class DatasetParam:
         if is_train:
-            image_set = ("coco_train2014", "coco_valminusminival2014")
+            image_set = ("coco_train2017", )
         else:
-            image_set = ("coco_minival2014", )
+            image_set = ("coco_val2017", )
 
     backbone = Backbone(BackboneParam)
     neck = Neck(NeckParam)

config/dcn/faster_dcnv2_r101v1bc4_c5_512roi_1x.py

@@ -99,9 +99,9 @@ class RoiParam:
 
     class DatasetParam:
         if is_train:
-            image_set = ("coco_train2014", "coco_valminusminival2014")
+            image_set = ("coco_train2017", )
         else:
-            image_set = ("coco_minival2014", )
+            image_set = ("coco_val2017", )
 
     backbone = Backbone(BackboneParam)
     neck = Neck(NeckParam)

config/dcn/faster_dcnv2_r101v1bc4_c5_512roi_2x.py

@@ -99,9 +99,9 @@ class RoiParam:
 
     class DatasetParam:
         if is_train:
-            image_set = ("coco_train2014", "coco_valminusminival2014")
+            image_set = ("coco_train2017", )
         else:
-            image_set = ("coco_minival2014", )
+            image_set = ("coco_val2017", )
 
     backbone = Backbone(BackboneParam)
     neck = Neck(NeckParam)

config/dcn/faster_dcnv2_r50v1bc4_c5_512roi_1x.py

@@ -99,9 +99,9 @@ class RoiParam:
 
     class DatasetParam:
         if is_train:
-            image_set = ("coco_train2014", "coco_valminusminival2014")
+            image_set = ("coco_train2017", )
         else:
-            image_set = ("coco_minival2014", )
+            image_set = ("coco_val2017", )
 
     backbone = Backbone(BackboneParam)
     neck = Neck(NeckParam)