getting_started.md 8.89 KB
Newer Older
twang's avatar
twang committed
1
# Prerequisites
zhangwenwei's avatar
zhangwenwei committed
2

twang's avatar
twang committed
3
4
5
6
7
- Linux or macOS (Windows is not currently officially supported)
- Python 3.6+
- PyTorch 1.3+
- CUDA 9.2+ (If you build PyTorch from source, CUDA 9.0 is also compatible)
- GCC 5+
xiliu8006's avatar
xiliu8006 committed
8
9
10
11
12
13
14
15
16
17
18
19
20
21
- [MMCV](https://mmcv.readthedocs.io/en/latest/#installation)


The required versions of MMCV and MMDetection for different versions of MMDetection3D are as below. Please install the correct version of MMCV and MMDetection to avoid installation issues.

| MMDetection3D version | MMDetection version |    MMCV version     |
|:-------------------:|:-------------------:|:-------------------:|
| master              | mmdet>=2.5.0        | mmcv-full>=1.2.4, <=1.3|
| 0.10.0              | mmdet>=2.5.0        | mmcv-full>=1.2.4, <=1.3|
| 0.9.0               | mmdet>=2.5.0        | mmcv-full>=1.2.4, <=1.3|
| 0.8.0               | mmdet>=2.5.0        | mmcv-full>=1.1.5, <=1.3|
| 0.7.0               | mmdet>=2.5.0        | mmcv-full>=1.1.5, <=1.3|
| 0.6.0               | mmdet>=2.4.0        | mmcv-full>=1.1.3, <=1.2|
| 0.5.0               | 2.3.0               | mmcv-full==1.0.5|
zhangwenwei's avatar
Doc  
zhangwenwei committed
22

twang's avatar
twang committed
23
# Installation
zhangwenwei's avatar
Doc  
zhangwenwei committed
24

twang's avatar
twang committed
25
## Install MMDetection3D
zhangwenwei's avatar
Doc  
zhangwenwei committed
26

27
**a. Create a conda virtual environment and activate it.**
zhangwenwei's avatar
zhangwenwei committed
28

twang's avatar
twang committed
29
30
31
```shell
conda create -n open-mmlab python=3.7 -y
conda activate open-mmlab
zhangwenwei's avatar
Doc  
zhangwenwei committed
32
33
```

34
**b. Install PyTorch and torchvision following the [official instructions](https://pytorch.org/).**
Wenwei Zhang's avatar
Wenwei Zhang committed
35

twang's avatar
twang committed
36
37
```shell
conda install pytorch torchvision -c pytorch
Wenwei Zhang's avatar
Wenwei Zhang committed
38
39
```

twang's avatar
twang committed
40
41
Note: Make sure that your compilation CUDA version and runtime CUDA version match.
You can check the supported CUDA version for precompiled packages on the [PyTorch website](https://pytorch.org/).
Wenwei Zhang's avatar
Wenwei Zhang committed
42

43
`E.g. 1` If you have CUDA 10.1 installed under `/usr/local/cuda` and would like to install
twang's avatar
twang committed
44
PyTorch 1.5, you need to install the prebuilt PyTorch with CUDA 10.1.
Wenwei Zhang's avatar
Wenwei Zhang committed
45

twang's avatar
twang committed
46
```python
47
conda install pytorch==1.5.0 cudatoolkit=10.1 torchvision==0.6.0 -c pytorch
Wenwei Zhang's avatar
Wenwei Zhang committed
48
49
```

twang's avatar
twang committed
50
51
`E.g. 2` If you have CUDA 9.2 installed under `/usr/local/cuda` and would like to install
PyTorch 1.3.1., you need to install the prebuilt PyTorch with CUDA 9.2.
zhangwenwei's avatar
zhangwenwei committed
52

twang's avatar
twang committed
53
54
```python
conda install pytorch=1.3.1 cudatoolkit=9.2 torchvision=0.4.2 -c pytorch
wangtai's avatar
wangtai committed
55
56
```

twang's avatar
twang committed
57
58
If you build PyTorch from source instead of installing the prebuilt pacakge,
you can use more CUDA versions such as 9.0.
59

60
**c. Install [MMCV](https://mmcv.readthedocs.io/en/latest/).**
xiliu8006's avatar
xiliu8006 committed
61
*mmcv-full* is necessary since MMDetection3D relies on MMDetection, CUDA ops in *mmcv-full* are required.
zhangwenwei's avatar
Doc  
zhangwenwei committed
62

63
`e.g.` The pre-build *mmcv-full* could be installed by running: (available versions could be found [here](https://mmcv.readthedocs.io/en/latest/#install-with-pip))
zhangwenwei's avatar
zhangwenwei committed
64

xiliu8006's avatar
xiliu8006 committed
65
66
67
68
69
70
 ```shell
pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html
```

Please replace `{cu_version}` and `{torch_version}` in the url to your desired one. For example, to install the latest `mmcv-full` with `CUDA 11` and `PyTorch 1.7.0`, use the following command:

twang's avatar
twang committed
71
```shell
xiliu8006's avatar
xiliu8006 committed
72
pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu110/torch1.7.0/index.html
twang's avatar
twang committed
73
```
zhangwenwei's avatar
zhangwenwei committed
74

xiliu8006's avatar
xiliu8006 committed
75
See [here](https://github.com/open-mmlab/mmcv#install-with-pip) for different versions of MMCV compatible to different PyTorch and CUDA versions.
twang's avatar
twang committed
76
Optionally, you could also build the full version from source:
zhangwenwei's avatar
zhangwenwei committed
77

twang's avatar
twang committed
78
```shell
xiliu8006's avatar
xiliu8006 committed
79
80
81
82
83
84
85
86
87
88
git clone https://github.com/open-mmlab/mmcv.git
cd mmcv
MMCV_WITH_OPS=1 pip install -e .  # package mmcv-full will be installed after this step
cd ..
```

Or directly run

```shell
pip install mmcv-full
twang's avatar
twang committed
89
```
zhangwenwei's avatar
zhangwenwei committed
90

91
**d. Install [MMDetection](https://github.com/open-mmlab/mmdetection).**
zhangwenwei's avatar
zhangwenwei committed
92

twang's avatar
twang committed
93
94
95
```shell
pip install git+https://github.com/open-mmlab/mmdetection.git
```
zhangwenwei's avatar
zhangwenwei committed
96

twang's avatar
twang committed
97
Optionally, you could also build MMDetection from source in case you want to modify the code:
zhangwenwei's avatar
zhangwenwei committed
98
99

```shell
twang's avatar
twang committed
100
101
102
103
git clone https://github.com/open-mmlab/mmdetection.git
cd mmdetection
pip install -r requirements/build.txt
pip install -v -e .  # or "python setup.py develop"
zhangwenwei's avatar
zhangwenwei committed
104
105
```

106
**e. Clone the MMDetection3D repository.**
zhangwenwei's avatar
Doc  
zhangwenwei committed
107

twang's avatar
twang committed
108
109
110
111
```shell
git clone https://github.com/open-mmlab/mmdetection3d.git
cd mmdetection3d
```
zhangwenwei's avatar
zhangwenwei committed
112

113
**f.Install build requirements and then install MMDetection3D.**
zhangwenwei's avatar
zhangwenwei committed
114

twang's avatar
twang committed
115
116
117
```shell
pip install -v -e .  # or "python setup.py develop"
```
zhangwenwei's avatar
zhangwenwei committed
118

twang's avatar
twang committed
119
Note:
zhangwenwei's avatar
Doc  
zhangwenwei committed
120

twang's avatar
twang committed
121
122
1. The git commit id will be written to the version number with step d, e.g. 0.6.0+2e7045c. The version will also be saved in trained models.
It is recommended that you run step d each time you pull some updates from github. If C++/CUDA codes are modified, then this step is compulsory.
zhangwenwei's avatar
Doc  
zhangwenwei committed
123

twang's avatar
twang committed
124
    > Important: Be sure to remove the `./build` folder if you reinstall mmdet with a different CUDA/PyTorch version.
zhangwenwei's avatar
zhangwenwei committed
125

twang's avatar
twang committed
126
127
128
129
130
    ```shell
    pip uninstall mmdet3d
    rm -rf ./build
    find . -name "*.so" | xargs rm
    ```
zhangwenwei's avatar
zhangwenwei committed
131

twang's avatar
twang committed
132
2. Following the above instructions, mmdetection is installed on `dev` mode, any local modifications made to the code will take effect without the need to reinstall it (unless you submit some commits and want to update the version number).
zhangwenwei's avatar
zhangwenwei committed
133

twang's avatar
twang committed
134
135
3. If you would like to use `opencv-python-headless` instead of `opencv-python`,
you can install it before installing MMCV.
zhangwenwei's avatar
zhangwenwei committed
136

twang's avatar
twang committed
137
4. Some dependencies are optional. Simply running `pip install -v -e .` will only install the minimum runtime requirements. To use optional dependencies like `albumentations` and `imagecorruptions` either install them manually with `pip install -r requirements/optional.txt` or specify desired extras when calling `pip` (e.g. `pip install -v -e .[optional]`). Valid keys for the extras field are: `all`, `tests`, `build`, and `optional`.
zhangwenwei's avatar
zhangwenwei committed
138

twang's avatar
twang committed
139
5. The code can not be built for CPU only environment (where CUDA isn't available) for now.
zhangwenwei's avatar
zhangwenwei committed
140

twang's avatar
twang committed
141
## Another option: Docker Image
Wenwei Zhang's avatar
Wenwei Zhang committed
142

twang's avatar
twang committed
143
We provide a [Dockerfile](https://github.com/open-mmlab/mmdetection3d/blob/master/docker/Dockerfile) to build an image.
Wenwei Zhang's avatar
Wenwei Zhang committed
144

twang's avatar
twang committed
145
146
147
148
```shell
# build an image with PyTorch 1.6, CUDA 10.1
docker build -t mmdetection3d docker/
```
Wenwei Zhang's avatar
Wenwei Zhang committed
149

twang's avatar
twang committed
150
Run it with
Wenwei Zhang's avatar
Wenwei Zhang committed
151

twang's avatar
twang committed
152
153
154
```shell
docker run --gpus all --shm-size=8g -it -v {DATA_DIR}:/mmdetection3d/data mmdetection3d
```
Wenwei Zhang's avatar
Wenwei Zhang committed
155

twang's avatar
twang committed
156
## A from-scratch setup script
Wenwei Zhang's avatar
Wenwei Zhang committed
157

twang's avatar
twang committed
158
Here is a full script for setting up mmdetection with conda.
Wenwei Zhang's avatar
Wenwei Zhang committed
159

twang's avatar
twang committed
160
161
162
```shell
conda create -n open-mmlab python=3.7 -y
conda activate open-mmlab
Wenwei Zhang's avatar
Wenwei Zhang committed
163

twang's avatar
twang committed
164
165
# install latest pytorch prebuilt with the default prebuilt CUDA version (usually the latest)
conda install -c pytorch pytorch torchvision -y
Wenwei Zhang's avatar
Wenwei Zhang committed
166

twang's avatar
twang committed
167
168
# install mmcv
pip install mmcv-full
liyinhao's avatar
liyinhao committed
169

twang's avatar
twang committed
170
171
# install mmdetection
pip install git+https://github.com/open-mmlab/mmdetection.git
liyinhao's avatar
liyinhao committed
172

twang's avatar
twang committed
173
174
175
176
# install mmdetection3d
git clone https://github.com/open-mmlab/mmdetection3d.git
cd mmdetection3d
pip install -v -e .
zhangwenwei's avatar
zhangwenwei committed
177
```
liyinhao's avatar
liyinhao committed
178

twang's avatar
twang committed
179
180
181
## Using multiple MMDetection3D versions

The train and test scripts already modify the `PYTHONPATH` to ensure the script use the MMDetection3D in the current directory.
liyinhao's avatar
liyinhao committed
182

twang's avatar
twang committed
183
184
185
186
To use the default MMDetection3D installed in the environment rather than that you are working with, you can remove the following line in those scripts

```shell
PYTHONPATH="$(dirname $0)/..":$PYTHONPATH
liyinhao's avatar
liyinhao committed
187
188
```

twang's avatar
twang committed
189
# Verification
liyinhao's avatar
liyinhao committed
190

twang's avatar
twang committed
191
## Demo
zhangwenwei's avatar
zhangwenwei committed
192

wuyuefeng's avatar
Demo  
wuyuefeng committed
193
### Point cloud demo
zhangwenwei's avatar
Doc  
zhangwenwei committed
194

xiliu8006's avatar
xiliu8006 committed
195
We provide a demo script to test a single sample. Pre-trained models can be downloaded from [model zoo](model_zoo.md)
zhangwenwei's avatar
Doc  
zhangwenwei committed
196
197

```shell
wuyuefeng's avatar
Demo  
wuyuefeng committed
198
python demo/pcd_demo.py ${PCD_FILE} ${CONFIG_FILE} ${CHECKPOINT_FILE} [--device ${GPU_ID}] [--score-thr ${SCORE_THR}] [--out-dir ${OUT_DIR}]
zhangwenwei's avatar
Doc  
zhangwenwei committed
199
200
201
202
203
```

Examples:

```shell
204
python demo/pcd_demo.py demo/kitti_000008.bin configs/second/hv_second_secfpn_6x8_80e_kitti-3d-car.py checkpoints/hv_second_secfpn_6x8_80e_kitti-3d-car_20200620_230238-393f000c.pth
zhangwenwei's avatar
zhangwenwei committed
205
```
yinchimaoliang's avatar
yinchimaoliang committed
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
If you want to input a `ply` file, you can use the following function and convert it to `bin` format. Then you can use the converted `bin` file to generate demo.
Note that you need to install pandas and plyfile before using this script. This function can also be used for data preprocessing for training ```ply data```.
```python
import numpy as np
import pandas as pd
from plyfile import PlyData

def conver_ply(input_path, output_path):
    plydata = PlyData.read(input_path)  # read file
    data = plydata.elements[0].data  # read data
    data_pd = pd.DataFrame(data)  # convert to DataFrame
    data_np = np.zeros(data_pd.shape, dtype=np.float)  # initialize array to store data
    property_names = data[0].dtype.names  # read names of properties
    for i, name in enumerate(
            property_names):  # read data by property
        data_np[:, i] = data_pd[name]
    data_np.astype(np.float32).tofile(output_path)
```
Examples:
zhangwenwei's avatar
zhangwenwei committed
225

yinchimaoliang's avatar
yinchimaoliang committed
226
227
228
```python
convert_ply('./test.ply', './test.bin')
```
zhangwenwei's avatar
zhangwenwei committed
229

twang's avatar
twang committed
230
## High-level APIs for testing point clouds
zhangwenwei's avatar
zhangwenwei committed
231

twang's avatar
twang committed
232
### Synchronous interface
liyinhao's avatar
liyinhao committed
233
Here is an example of building the model and test given point clouds.
zhangwenwei's avatar
zhangwenwei committed
234
235

```python
liyinhao's avatar
liyinhao committed
236
from mmdet3d.apis import init_detector, inference_detector
zhangwenwei's avatar
zhangwenwei committed
237

liyinhao's avatar
liyinhao committed
238
239
config_file = 'configs/votenet/votenet_8x8_scannet-3d-18class.py'
checkpoint_file = 'checkpoints/votenet_8x8_scannet-3d-18class_20200620_230238-2cea9c3a.pth'
zhangwenwei's avatar
zhangwenwei committed
240
241
242
243
244

# build the model from a config file and a checkpoint file
model = init_detector(config_file, checkpoint_file, device='cuda:0')

# test a single image and show the results
liyinhao's avatar
liyinhao committed
245
246
247
248
point_cloud = 'test.bin'
result, data = inference_detector(model, point_cloud)
# visualize the results and save the results in 'results' folder
model.show_results(data, result, out_dir='results')
zhangwenwei's avatar
zhangwenwei committed
249
```