add README.md

README.md

@@ -2,22 +2,95 @@
 
 ## Introduction
 `OpenLidarPercept` is an open source project for LiDAR-based 3D scene perception. 
-As of now, it mainly consists of the `PCDet` toolbox for 3D object detection from point cloud.  
+As of now, it mainly consists of `PCDet` toolbox for 3D object detection from point cloud.  
 
 
 ### What does `PCDet` toolbox do?
 
 `PCDet` is a general PyTorch-based codebase for 3D object detection from point cloud. 
-It currently supports multiple state-of-the-art 3D object detection methods (`PointPillar`, `SECOND`, `Part-A^2 Net`, `PV-RCNN`) with highly refactored codes for both one-stage and two-stage frameworks.
+It currently supports multiple state-of-the-art 3D object detection methods with highly refactored codes for both one-stage and two-stage 3D detection frameworks.
 
 It is also the official code release of [`[Part-A^2 net]`](https://arxiv.org/abs/1907.03670) and [`[PV-RCNN]`](https://arxiv.org/abs/1912.13192). 
 
+We are actively updating this repo currently, and more datasets and models will be supported soon. 
+Contributions are also welcomed. 
+
 
 ### Currently Supported Features
+- [x] Unified point cloud coordinate and clear code structure and for supporting lots of datasets and approaches
 - [x] Support both one-stage and two-stage 3D object detection frameworks
-- [x] Distributed training & testing with multiple GPUs and multiple machines
-- [x] Clear code structure and unified point cloud coordinate for supporting more datasets and approaches
-- [x] RoI-aware point cloud pooling & RoI-grid point cloud pooling
-- [x] Stacked version set abstraction to support various number of points in differnet scenes
-- [x] GPU version 3D IoU calculation and rotated NMS 
+- [x] Support distributed training & testing with multiple GPUs and multiple machines
+- [x] Support multiple heads on different scales to detect different classes
+- [x] Support stacked version set abstraction to encode various number of points in different scenes
+- [x] Support Adaptive Training Sample Selection (ATSS) for target assignment
+- [x] Support RoI-aware point cloud pooling & RoI-grid point cloud pooling
+- [x] Support GPU version 3D IoU calculation and rotated NMS 
+
+## Model Zoo
+
+### KITTI 3D Object Detection Baselines
+Selected supported methods are shown in the below table. The results are the 3D detection performance of car class on the *val* set of KITTI dataset.
+All models are trained with 8 GPUs and are available for download.
+
+|                                             | Batch Size | AP_Easy | AP_Mod. | AP_Hard | download  |
+|---------------------------------------------|:----------:|:-------:|:-------:|:-------:|:---------:|
+| [PointPillar](tools/cfgs/kitti_models/pointpillar.yaml) | 32 | - | - | - | [model]() | 
+| [SECOND](tools/cfgs/kitti_models/second.yaml)           | 32  | - | - | - | [model]() |
+| [Part-A^2](tools/cfgs/kitti_models/PartA2.yaml)    | 32 | - | - | - | [model]() |
+| [PV-RCNN](tools/cfgs/kitti_models/pv_rcnn.yaml) | 16 | - | - | - | [model]() |
+| [SECOND-MultiHead](tools/cfgs/kitti_models/second_multihead.yaml) | 32 | - | - | - | - |
+
+## Installation
+
+Please refer to [INSTALL.md](docs/INSTALL.md) for installation and dataset preparation.
+
+
+## Get Started
+
+Please refer to [GETTING_STARTED.md](docs/GETTING_STARTED.md) to learn more usage about this project.
+
+## License
+
+`OpenLidarPercept` is released under the [Apache 2.0 license](LICENSE).
+
+## Acknowledgement
+`OpenLidarPercept` is an open source project for LiDAR-based 3D scene perception that supports multiple
+LiDAR-based perception models as shown above. Some parts of `PCDet` are learned from the official released codes of the above supported methods. 
+We would like to thank for their proposed methods and the official implementation.   
+
+We hope that this repo could serve as a strong and flexible codebase to benefit the research community by speeding up the process of reimplementing previous works and/or developing new methods.
+
+
+## Citation 
+If you find this project useful in your research, please consider cite:
+
+
+```
+@inproceedings{shi2020pv,
+  title={Pv-rcnn: Point-voxel feature set abstraction for 3d object detection},
+  author={Shi, Shaoshuai and Guo, Chaoxu and Jiang, Li and Wang, Zhe and Shi, Jianping and Wang, Xiaogang and Li, Hongsheng},
+  booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},
+  pages={10529--10538},
+  year={2020}
+}
+
+
+@article{shi2020points,
+  title={From Points to Parts: 3D Object Detection from Point Cloud with Part-aware and Part-aggregation Network},
+  author={Shi, Shaoshuai and Wang, Zhe and Shi, Jianping and Wang, Xiaogang and Li, Hongsheng},
+  journal={IEEE Transactions on Pattern Analysis and Machine Intelligence},
+  year={2020},
+  publisher={IEEE}
+}
+
+@inproceedings{shi2019pointrcnn,
+  title={PointRCNN: 3d Object Progposal Generation and Detection from Point Cloud},
+  author={Shi, Shaoshuai and Wang, Xiaogang and Li, Hongsheng},
+  booktitle={Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition},
+  pages={770--779},
+  year={2019}
+}
+```
 
+## Contact
+This project is currently maintained by Shaoshuai Shi ([@sshaoshuai](http://github.com/sshaoshuai)) and Chaoxu Guo ([@Gus-Guo](https://github.com/Gus-Guo)).

docs/GETTING_STARTED.md

+## Getting Started
+The dataset configs are located within [tools/cfgs/dataset_configs](tools/cfgs/dataset_configs), 
+and the model configs are located within [tools/cfgs](tools/cfgs) for different datasets, like [tools/cfgs/kitti_models/](tools/cfgs/kitti_models/). 
+ 
+
+
+### Test and evaluate the pretrained models
+* Test with a pretrained model: 
+```shell script
+python test.py --cfg_file ${CONFIG_FILE} --batch_size ${BATCH_SIZE} --ckpt ${CKPT}
+```
+
+* To test all the saved checkpoints of a specific training setting and draw the performance curve on the Tensorboard, add the `--eval_all` argument: 
+```shell script
+python test.py --cfg_file ${CONFIG_FILE} --batch_size ${BATCH_SIZE} --eval_all
+```
+
+* To test with multiple GPUs:
+```shell script
+sh scripts/slurm_test_mgpu.sh ${NUM_GPUS} \ 
+    --cfg_file ${CONFIG_FILE} --batch_size ${BATCH_SIZE}
+```
+
+
+### Train a model
+Note that the `--batch_size` depends on the number of your training GPUs, 
+please refer to `Model Zoo` of [README.md](../README.md) for the setting of batch_size for different models.  
+
+* Train with multiple GPUs:
+```shell script
+sh scripts/dist_train.sh ${NUM_GPUS} \ 
+    --cfg_file ${CONFIG_FILE} --batch_size ${BATCH_SIZE}  --epochs 80
+```
+
+* Train with multiple machines:
+```shell script
+sh scripts/slurm_train.sh ${PARTITION} ${JOB_NAME} ${NUM_GPUS} \ 
+    --cfg_file ${CONFIG_FILE} --batch_size ${BATCH_SIZE} --epochs 80
+```
+
+* Train with a single GPU:
+```shell script
+python train.py --cfg_file ${CONFIG_FILE} --batch_size ${BATCH_SIZE} --epochs 50
+```
\ No newline at end of file

docs/INSTALL.md

+## Installation
+
+### Requirements
+All the codes are tested in the following environment:
+* Linux (tested on Ubuntu 14.04/16.04)
+* Python 3.6+
+* PyTorch 1.1 or higher (tested on PyTorch 1.1)
+* CUDA 9.0 or higher
+* `spconv v1.0` ([commit 8da6f96](https://github.com/traveller59/spconv/tree/8da6f967fb9a054d8870c3515b1b44eca2103634))
+
+
+### Install `pcdet`
+a. Clone this repository.
+```shell
+git clone https://github.com/open-mmlab/OpenLidarPercept.git
+```
+
+b. Install the dependent libraries as follows:
+
+* Install the dependent python libraries: 
+```
+pip install -r requirements.txt 
+```
+
+* Install the SparseConv library, we use the non-official implementation from [`spconv`](https://github.com/traveller59/spconv). 
+Note that we use the initial version of `spconv`, make sure you install the `spconv v1.0` ([commit 8da6f96](https://github.com/traveller59/spconv/tree/8da6f967fb9a054d8870c3515b1b44eca2103634)) instead of the latest one.
+
+c. Install this `pcdet` library by running the following command:
+```shell
+python setup.py develop
+```
+
+## Dataset Preparation
+
+Currently we provide the dataloader of KITTI dataset, and the supporting of more datasets are on the way.  
+
+### KITTI Dataset
+* Please download the official [KITTI 3D object detection](http://www.cvlibs.net/datasets/kitti/eval_object.php?obj_benchmark=3d) dataset and organize the downloaded files as follows (the road planes could be downloaded from [[road plane]](https://drive.google.com/file/d/1d5mq0RXRnvHPVeKx6Q612z0YRO1t2wAp/view?usp=sharing), which are optional for data augmentation in the training): 
+
+```
+PCDet
+├── data
+│   ├── kitti
+│   │   │──ImageSets
+│   │   │──training
+│   │   │   ├──calib & velodyne & label_2 & image_2 & (optional: planes)
+│   │   │──testing
+│   │   │   ├──calib & velodyne & image_2
+├── pcdet
+├── tools
+```
+
+* Generate the data infos by running the following command: 
+```python 
+python -m pcdet.datasets.kitti.kitti_dataset create_kitti_infos 
+```