README.md 4.93 KB
Newer Older
pangjm's avatar
pangjm committed
1

Kai Chen's avatar
Kai Chen committed
2
3
4
# MMDetection

**News**: We released the technical report on [ArXiv](https://arxiv.org/abs/1906.07155).
Dahua Lin's avatar
Dahua Lin committed
5

Kai Chen's avatar
Kai Chen committed
6
## Introduction
Dahua Lin's avatar
Dahua Lin committed
7

8
The master branch works with **PyTorch 1.1** or higher. If you would like to use PyTorch 0.4.1,
Kai Chen's avatar
Kai Chen committed
9
10
please checkout to the [pytorch-0.4.1](https://github.com/open-mmlab/mmdetection/tree/pytorch-0.4.1) branch.

Kai Chen's avatar
Kai Chen committed
11
12
mmdetection is an open source object detection toolbox based on PyTorch. It is
a part of the open-mmlab project developed by [Multimedia Laboratory, CUHK](http://mmlab.ie.cuhk.edu.hk/).
Dahua Lin's avatar
Dahua Lin committed
13

Kai Chen's avatar
Kai Chen committed
14
15
![demo image](demo/coco_test_12510.jpg)

Kai Chen's avatar
Kai Chen committed
16
### Major features
Dahua Lin's avatar
Dahua Lin committed
17
18
19

- **Modular Design**

pangjm's avatar
pangjm committed
20
21
  One can easily construct a customized object detection framework by combining different components.

Dahua Lin's avatar
Dahua Lin committed
22
23
- **Support of multiple frameworks out of box**

Kai Chen's avatar
Kai Chen committed
24
  The toolbox directly supports popular and contemporary detection frameworks, *e.g.* Faster RCNN, Mask RCNN, RetinaNet, etc.
Kai Chen's avatar
Kai Chen committed
25

Kai Chen's avatar
Kai Chen committed
26
- **High efficiency**
Kai Chen's avatar
Kai Chen committed
27
28

  All basic bbox and mask operations run on GPUs now.
Kai Chen's avatar
Kai Chen committed
29
  The training speed is nearly 2x faster than Detectron and comparable to maskrcnn-benchmark.
pangjm's avatar
pangjm committed
30

Dahua Lin's avatar
Dahua Lin committed
31
32
- **State of the art**

Kai Chen's avatar
Kai Chen committed
33
  This was the codebase of the *MMDet* team, who won the [COCO Detection 2018 challenge](http://cocodataset.org/#detection-leaderboard), and we keep pushing it forward.
Kai Chen's avatar
Kai Chen committed
34

Kai Chen's avatar
Kai Chen committed
35
Apart from MMDetection, we also released a library [mmcv](https://github.com/open-mmlab/mmcv) for computer vision research,
Kai Chen's avatar
Kai Chen committed
36
which is heavily depended on by this toolbox.
Kai Chen's avatar
Kai Chen committed
37
38
39

## License

Kai Chen's avatar
Kai Chen committed
40
This project is released under the [Apache 2.0 license](LICENSE).
Kai Chen's avatar
Kai Chen committed
41

Kai Chen's avatar
Kai Chen committed
42
43
## Updates

Kai Chen's avatar
Kai Chen committed
44
v0.6.0 (14/04/2019)
Kai Chen's avatar
Kai Chen committed
45
46
- Up to 30% speedup compared to the model zoo.
- Support both PyTorch stable and nightly version.
Kai Chen's avatar
Kai Chen committed
47
48
- Replace NMS and SigmoidFocalLoss with Pytorch CUDA extensions.

Kai Chen's avatar
Kai Chen committed
49
50
51
v0.6rc0(06/02/2019)
- Migrate to PyTorch 1.0.

Kai Chen's avatar
Kai Chen committed
52
53
54
55
v0.5.7 (06/02/2019)
- Add support for Deformable ConvNet v2. (Many thanks to the authors and [@chengdazhi](https://github.com/chengdazhi))
- This is the last release based on PyTorch 0.4.1.

Kai Chen's avatar
Kai Chen committed
56
57
58
59
v0.5.6 (17/01/2019)
- Add support for Group Normalization.
- Unify RPNHead and single stage heads (RetinaHead, SSDHead) with AnchorHead.

Kai Chen's avatar
Kai Chen committed
60
61
62
63
64
65
v0.5.5 (22/12/2018)
- Add SSD for COCO and PASCAL VOC.
- Add ResNeXt backbones and detection models.
- Refactoring for Samplers/Assigners and add OHEM.
- Add VOC dataset and evaluation scripts.

Kai Chen's avatar
Kai Chen committed
66
67
68
v0.5.4 (27/11/2018)
- Add SingleStageDetector and RetinaNet.

Kai Chen's avatar
Kai Chen committed
69
70
v0.5.3 (26/11/2018)
- Add Cascade R-CNN and Cascade Mask R-CNN.
Kai Chen's avatar
Kai Chen committed
71
- Add support for Soft-NMS in config files.
Kai Chen's avatar
Kai Chen committed
72

Kai Chen's avatar
Kai Chen committed
73
74
75
76
v0.5.2 (21/10/2018)
- Add support for custom datasets.
- Add a script to convert PASCAL VOC annotations to the expected format.

Kai Chen's avatar
Kai Chen committed
77
78
79
80
v0.5.1 (20/10/2018)
- Add BBoxAssigner and BBoxSampler, the `train_cfg` field in config files are restructured.
- `ConvFCRoIHead` / `SharedFCRoIHead` are renamed to `ConvFCBBoxHead` / `SharedFCBBoxHead` for consistency.

Kai Chen's avatar
Kai Chen committed
81
82
## Benchmark and model zoo

Kai Chen's avatar
Kai Chen committed
83
84
85
86
87
Supported methods and backbones are shown in the below table.
Results and models are available in the [Model zoo](MODEL_ZOO.md).

|                    | ResNet   | ResNeXt  | SENet    | VGG      |
|--------------------|:--------:|:--------:|:--------:|:--------:|
pangjm's avatar
pangjm committed
88
89
90
91
92
93
| RPN                | ✓        | ✓        | ☐        | ✗        |
| Fast R-CNN         | ✓        | ✓        | ☐        | ✗        |
| Faster R-CNN       | ✓        | ✓        | ☐        | ✗        |
| Mask R-CNN         | ✓        | ✓        | ☐        | ✗        |
| Cascade R-CNN      | ✓        | ✓        | ☐        | ✗        |
| Cascade Mask R-CNN | ✓        | ✓        | ☐        | ✗        |
Kai Chen's avatar
Kai Chen committed
94
| SSD                | ✗        | ✗        | ✗        | ✓        |
pangjm's avatar
pangjm committed
95
| RetinaNet          | ✓        | ✓        | ☐        | ✗        |
96
| Hybrid Task Cascade| ✓        | ✓        | ☐        | ✗        |
97
| FCOS               | ✓        | ✓        | ☐        | ✗        |
98
| Libra R-CNN        | ✓        | ✓        | ☐        | ✗        |
Kai Chen's avatar
Kai Chen committed
99

Kai Chen's avatar
Kai Chen committed
100
Other features
Kai Chen's avatar
Kai Chen committed
101
- [x] DCNv2
Kai Chen's avatar
Kai Chen committed
102
- [x] Group Normalization
103
- [x] Weight Standardization
Kai Chen's avatar
Kai Chen committed
104
105
- [x] OHEM
- [x] Soft-NMS
Kai Chen's avatar
Kai Chen committed
106
- [ ] Mixed Precision (FP16) Training (coming soon)
Kai Chen's avatar
Kai Chen committed
107
108


Kai Chen's avatar
Kai Chen committed
109
110
## Installation

Kai Chen's avatar
Kai Chen committed
111
Please refer to [INSTALL.md](INSTALL.md) for installation and dataset preparation.
Kai Chen's avatar
Kai Chen committed
112

Kai Chen's avatar
Kai Chen committed
113

Kai Chen's avatar
Kai Chen committed
114
## Get Started
Kai Chen's avatar
Kai Chen committed
115

Kai Chen's avatar
Kai Chen committed
116
Please see [GETTING_STARTED.md](GETTING_STARTED.md) for the basic usage of MMDetection.
Kai Chen's avatar
Kai Chen committed
117

Kai Chen's avatar
Kai Chen committed
118
119
## Contributing

Kai Chen's avatar
Kai Chen committed
120
We appreciate all contributions to improve MMDetection. Please refer to [CONTRIBUTING.md](CONTRIBUTING.md) for the contributing guideline.
Kai Chen's avatar
Kai Chen committed
121

Kai Chen's avatar
Kai Chen committed
122
123
124

## Citation

Kai Chen's avatar
Kai Chen committed
125
If you use this toolbox or benchmark in your research, please cite this project.
Kai Chen's avatar
Kai Chen committed
126
127

```
Kai Chen's avatar
Kai Chen committed
128
129
130
131
132
133
134
135
@article{mmdetection,
  title   = {MMDetection: Open MMLab Detection Toolbox and Benchmark},
  author  = {Kai Chen, Jiaqi Wang, Jiangmiao Pang, Yuhang Cao, Yu Xiong, Xiaoxiao Li,
             Shuyang Sun, Wansen Feng, Ziwei Liu, Jiarui Xu, Zheng Zhang, Dazhi Cheng,
             Chenchen Zhu, Tianheng Cheng, Qijie Zhao, Buyu Li, Xin Lu, Rui Zhu, Yue Wu,
             Jifeng Dai, Jingdong Wang, Jianping Shi, Wanli Ouyang, Chen Change Loy, Dahua Lin},
  journal = {arXiv preprint arXiv:1906.07155},
  year    = {2019}
Kai Chen's avatar
Kai Chen committed
136
137
}
```