README.md 5.4 KB
Newer Older
zhangwenwei's avatar
zhangwenwei committed
1
<div align="center">
zhangwenwei's avatar
zhangwenwei committed
2
  <img src="resources/mmdet3d-logo.png" width="600"/>
zhangwenwei's avatar
zhangwenwei committed
3
</div>
zhangwenwei's avatar
zhangwenwei committed
4

Wenwei Zhang's avatar
Wenwei Zhang committed
5
6
7
8
9
10
[![docs](https://img.shields.io/badge/docs-latest-blue)](https://mmdetection3d.readthedocs.io/en/latest/)
[![badge](https://github.com/open-mmlab/mmdetection3d/workflows/build/badge.svg)](https://github.com/open-mmlab/mmdetection3d/actions)
[![codecov](https://codecov.io/gh/open-mmlab/mmdetection3d/branch/master/graph/badge.svg)](https://codecov.io/gh/open-mmlab/mmdetection3d)
[![license](https://img.shields.io/github/license/open-mmlab/mmdetection3d.svg)](https://github.com/open-mmlab/mmdetection3d/blob/master/LICENSE)


zhangwenwei's avatar
zhangwenwei committed
11
12
13
**News**: We released the codebase v0.1.0.

Documentation: https://mmdetection3d.readthedocs.io/
zhangwenwei's avatar
zhangwenwei committed
14
15
16

## Introduction

zhangwenwei's avatar
zhangwenwei committed
17
The master branch works with **PyTorch 1.3 to 1.5**.
zhangwenwei's avatar
zhangwenwei committed
18

19
MMDetection3D is an open source object detection toolbox based on PyTorch, towards the next-generation platform for general 3D detection. It is
zhangwenwei's avatar
zhangwenwei committed
20
a part of the OpenMMLab project developed by [MMLab](http://mmlab.ie.cuhk.edu.hk/).
zhangwenwei's avatar
zhangwenwei committed
21

zhangwenwei's avatar
zhangwenwei committed
22
![demo image](resources/mmdet3d_outdoor_demo.gif)
zhangwenwei's avatar
zhangwenwei committed
23
24
25

### Major features

zhangwenwei's avatar
zhangwenwei committed
26
- **Support multi-modality/single-modality detectors out of box**
zhangwenwei's avatar
zhangwenwei committed
27

28
  It directly supports multi-modality/single-modality detectors including MVXNet, VoteNet, PointPillars, etc.
zhangwenwei's avatar
zhangwenwei committed
29

zhangwenwei's avatar
zhangwenwei committed
30
- **Support indoor/outdoor 3D detection out of box**
zhangwenwei's avatar
zhangwenwei committed
31

32
  It directly supports popular indoor and outdoor 3D detection datasets, including ScanNet, SUNRGB-D, nuScenes, Lyft, and KITTI.
zhangwenwei's avatar
zhangwenwei committed
33

zhangwenwei's avatar
zhangwenwei committed
34
- **Natural integration with 2D detection**
35
36

  All the about **300 models, methods of 40+ papers**, and modules supported in [MMDetection](https://github.com/open-mmlab/mmdetection/blob/master/docs/model_zoo.md) can be trained or used in this codebase.
zhangwenwei's avatar
zhangwenwei committed
37

zhangwenwei's avatar
zhangwenwei committed
38
- **High efficiency**
zhangwenwei's avatar
zhangwenwei committed
39

40
  It trains [faster than other codebases](./docs/benchmarks.md).
zhangwenwei's avatar
zhangwenwei committed
41

42
Apart from MMDetection3D, we also released a library [MMDetection](https://github.com/open-mmlab/mmdetection) and [MMCV](https://github.com/open-mmlab/mmcv) for computer vision research, which are heavily depended on by this toolbox. Like [MMDetection](https://github.com/open-mmlab/mmdetection) and [MMCV](https://github.com/open-mmlab/mmcv), MMDetection3D can also be used as a library to support different projects on top of it.
zhangwenwei's avatar
zhangwenwei committed
43
44
45
46
47

## License

This project is released under the [Apache 2.0 license](LICENSE).

zhangwenwei's avatar
zhangwenwei committed
48
## Changelog
zhangwenwei's avatar
zhangwenwei committed
49

50
v0.1.0 was released in 9/7/2020.
zhangwenwei's avatar
zhangwenwei committed
51
Please refer to [changelog.md](docs/changelog.md) for details and release history.
zhangwenwei's avatar
zhangwenwei committed
52
53
54
55

## Benchmark and model zoo

Supported methods and backbones are shown in the below table.
zhangwenwei's avatar
zhangwenwei committed
56
Results and models are available in the [model zoo](docs/model_zoo.md).
zhangwenwei's avatar
zhangwenwei committed
57

zhangwenwei's avatar
zhangwenwei committed
58
59
|                    | ResNet   | ResNeXt  | SENet    |PointNet++ | HRNet | RegNetX | Res2Net |
|--------------------|:--------:|:--------:|:--------:|:---------:|:-----:|:--------:|:-----:|
60
61
62
| SECOND             | ☐        | ☐        | ☐        | ✗         | ☐     | ✓        | ☐     |
| PointPillars       | ☐        | ☐        | ☐        | ✗         | ☐     | ✓        | ☐     |
| FreeAnchor         | ☐        | ☐        | ☐        | ✗         | ☐     | ✓        | ☐     |
zhangwenwei's avatar
zhangwenwei committed
63
| VoteNet            | ✗        | ✗        | ✗        | ✓         | ✗     | ✗        | ✗     |
64
65
| Part-A2            | ☐        | ☐        | ☐        | ✗         | ☐     | ✓        | ☐     |
| MVXNet             | ☐        | ☐        | ☐        | ✗         | ☐     | ✓        | ☐     |
zhangwenwei's avatar
zhangwenwei committed
66
67
68
69

Other features
- [x] [Dynamic Voxelization](configs/carafe/README.md)

70
**Note:** All the about **300 models, methods of 40+ papers** in 2D detection supported by [MMDetection](https://github.com/open-mmlab/mmdetection/blob/master/docs/model_zoo.md) can be trained or used in this codebase.
zhangwenwei's avatar
zhangwenwei committed
71
72
73

## Installation

zhangwenwei's avatar
zhangwenwei committed
74
Please refer to [install.md](docs/install.md) for installation and dataset preparation.
zhangwenwei's avatar
zhangwenwei committed
75
76
77

## Get Started

zhangwenwei's avatar
zhangwenwei committed
78
Please see [getting_started.md](docs/getting_started.md) for the basic usage of MMDetection. There are also tutorials for [finetuning models](docs/tutorials/finetune.md), [adding new dataset](docs/tutorials/new_dataset.md), [designing data pipeline](docs/tutorials/data_pipeline.md), and [adding new modules](docs/tutorials/new_modules.md).
zhangwenwei's avatar
zhangwenwei committed
79
80
81

## Contributing

zhangwenwei's avatar
zhangwenwei committed
82
We appreciate all contributions to improve MMDetection3D. Please refer to [CONTRIBUTING.md](.github/CONTRIBUTING.md) for the contributing guideline.
zhangwenwei's avatar
zhangwenwei committed
83
84
85

## Acknowledgement

zhangwenwei's avatar
zhangwenwei committed
86
MMDetection3D is an open source project that is contributed by researchers and engineers from various colleges and companies. We appreciate all the contributors as well as users who give valuable feedbacks.
zhangwenwei's avatar
zhangwenwei committed
87
We wish that the toolbox and benchmark could serve the growing research community by providing a flexible toolkit to reimplement existing methods and develop their own new 3D detectors.
zhangwenwei's avatar
zhangwenwei committed
88
89
90

## Citation

zhangwenwei's avatar
zhangwenwei committed
91
92
93
94
95
If you use this toolbox or benchmark in your research, please cite this project.

```
@misc{mmdetection3d_2020,
  title   = {{MMDetection3D}},
zhangwenwei's avatar
zhangwenwei committed
96
97
98
  author  = {Zhang, Wenwei and Wu, Yuefeng and Wang, Tai and Li, Yinhao and
             Lin, Kwan-Yee and Wang, Zhe and Shi, Jianping and Qian, Chen and
             Chen, Kai, and Lin, Dahua and Loy, Chen Change},
zhangwenwei's avatar
zhangwenwei committed
99
100
101
102
  howpublished = {\url{https://github.com/open-mmlab/mmdetection3d}},
  year =         {2020}
}
```
zhangwenwei's avatar
zhangwenwei committed
103
104
105

## Contact

zhangwenwei's avatar
zhangwenwei committed
106
This repo is currently maintained by Wenwei Zhang ([@ZwwWayne](https://github.com/ZwwWayne)), Yuefeng Wu ([@xavierwu95](https://github.com/xavierwu95)), Tai Wang ([@Tai-Wang](https://github.com/Tai-Wang)), and Yinhao Li ([@yinchimaoliang](https://github.com/yinchimaoliang)).