Skip to content

Commit 73d7a85

Browse files
JosephKJJosephKJ
committed
Detectron2
1 parent 6b4cb9f commit 73d7a85

File tree

572 files changed

+64790
-2
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

572 files changed

+64790
-2
lines changed

‎GETTING_STARTED.md

+83
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
## Getting Started with Detectron2
2+
3+
This document provides a brief intro of the usage of builtin command-line tools in detectron2.
4+
5+
For a tutorial that involves actual coding with the API,
6+
see our [Colab Notebook](https://colab.research.google.com/drive/16jcaJoc6bCFAQ96jDe2HwtXj7BMD_-m5)
7+
which covers how to run inference with an
8+
existing model, and how to train a builtin model on a custom dataset.
9+
10+
For more advanced tutorials, refer to our [documentation](https://detectron2.readthedocs.io/tutorials/extend.html).
11+
12+
13+
### Inference Demo with Pre-trained Models
14+
15+
1. Pick a model and its config file from
16+
[model zoo](MODEL_ZOO.md),
17+
for example, `mask_rcnn_R_50_FPN_3x.yaml`.
18+
2. We provide `demo.py` that is able to demo builtin configs. Run it with:
19+
```
20+
cd demo/
21+
python demo.py --config-file ../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml \
22+
--input input1.jpg input2.jpg \
23+
[--other-options]
24+
--opts MODEL.WEIGHTS detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl
25+
```
26+
The configs are made for training, therefore we need to specify `MODEL.WEIGHTS` to a model from model zoo for evaluation.
27+
This command will run the inference and show visualizations in an OpenCV window.
28+
29+
For details of the command line arguments, see `demo.py -h` or look at its source code
30+
to understand its behavior. Some common arguments are:
31+
* To run __on your webcam__, replace `--input files` with `--webcam`.
32+
* To run __on a video__, replace `--input files` with `--video-input video.mp4`.
33+
* To run __on cpu__, add `MODEL.DEVICE cpu` after `--opts`.
34+
* To save outputs to a directory (for images) or a file (for webcam or video), use `--output`.
35+
36+
37+
### Training & Evaluation in Command Line
38+
39+
We provide two scripts in "tools/plain_train_net.py" and "tools/train_net.py",
40+
that are made to train all the configs provided in detectron2. You may want to
41+
use it as a reference to write your own training script.
42+
43+
Compared to "train_net.py", "plain_train_net.py" supports fewer default
44+
features. It also includes fewer abstraction, therefore is easier to add custom
45+
logic.
46+
47+
To train a model with "train_net.py", first
48+
setup the corresponding datasets following
49+
[datasets/README.md](./datasets/README.md),
50+
then run:
51+
```
52+
cd tools/
53+
./train_net.py --num-gpus 8 \
54+
--config-file ../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.yaml
55+
```
56+
57+
The configs are made for 8-GPU training.
58+
To train on 1 GPU, you may need to [change some parameters](https://arxiv.org/abs/1706.02677), e.g.:
59+
```
60+
./train_net.py \
61+
--config-file ../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.yaml \
62+
--num-gpus 1 SOLVER.IMS_PER_BATCH 2 SOLVER.BASE_LR 0.0025
63+
```
64+
65+
For most models, CPU training is not supported.
66+
67+
To evaluate a model's performance, use
68+
```
69+
./train_net.py \
70+
--config-file ../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.yaml \
71+
--eval-only MODEL.WEIGHTS /path/to/checkpoint_file
72+
```
73+
For more options, see `./train_net.py -h`.
74+
75+
### Use Detectron2 APIs in Your Code
76+
77+
See our [Colab Notebook](https://colab.research.google.com/drive/16jcaJoc6bCFAQ96jDe2HwtXj7BMD_-m5)
78+
to learn how to use detectron2 APIs to:
79+
1. run inference with an existing model
80+
2. train a builtin model on a custom dataset
81+
82+
See [detectron2/projects](https://github.com/facebookresearch/detectron2/tree/master/projects)
83+
for more ways to build your project on detectron2.

‎INSTALL.md

+230
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
## Installation
2+
3+
Our [Colab Notebook](https://colab.research.google.com/drive/16jcaJoc6bCFAQ96jDe2HwtXj7BMD_-m5)
4+
has step-by-step instructions that install detectron2.
5+
The [Dockerfile](docker)
6+
also installs detectron2 with a few simple commands.
7+
8+
### Requirements
9+
- Linux or macOS with Python ≥ 3.6
10+
- PyTorch ≥ 1.4 and [torchvision](https://github.com/pytorch/vision/) that matches the PyTorch installation.
11+
You can install them together at [pytorch.org](https://pytorch.org) to make sure of this
12+
- OpenCV is optional and needed by demo and visualization
13+
14+
15+
### Build Detectron2 from Source
16+
17+
gcc & g++ ≥ 5 are required. [ninja](https://ninja-build.org/) is recommended for faster build.
18+
After having them, run:
19+
```
20+
python -m pip install 'git+https://github.com/facebookresearch/detectron2.git'
21+
# (add --user if you don't have permission)
22+
23+
# Or, to install it from a local clone:
24+
git clone https://github.com/facebookresearch/detectron2.git
25+
python -m pip install -e detectron2
26+
27+
# Or if you are on macOS
28+
CC=clang CXX=clang++ python -m pip install ......
29+
```
30+
31+
To __rebuild__ detectron2 that's built from a local clone, use `rm -rf build/ **/*.so` to clean the
32+
old build first. You often need to rebuild detectron2 after reinstalling PyTorch.
33+
34+
### Install Pre-Built Detectron2 (Linux only)
35+
36+
Choose from this table to install [v0.2.1 (Aug 2020)](https://github.com/facebookresearch/detectron2/releases):
37+
38+
<table class="docutils"><tbody><th width="80"> CUDA </th><th valign="bottom" align="left" width="100">torch 1.6</th><th valign="bottom" align="left" width="100">torch 1.5</th><th valign="bottom" align="left" width="100">torch 1.4</th> <tr><td align="left">10.2</td><td align="left"><details><summary> install </summary><pre><code>python -m pip install detectron2 -f \
39+
https://dl.fbaipublicfiles.com/detectron2/wheels/cu102/torch1.6/index.html
40+
</code></pre> </details> </td> <td align="left"><details><summary> install </summary><pre><code>python -m pip install detectron2 -f \
41+
https://dl.fbaipublicfiles.com/detectron2/wheels/cu102/torch1.5/index.html
42+
</code></pre> </details> </td> <td align="left"> </td> </tr> <tr><td align="left">10.1</td><td align="left"><details><summary> install </summary><pre><code>python -m pip install detectron2 -f \
43+
https://dl.fbaipublicfiles.com/detectron2/wheels/cu101/torch1.6/index.html
44+
</code></pre> </details> </td> <td align="left"><details><summary> install </summary><pre><code>python -m pip install detectron2 -f \
45+
https://dl.fbaipublicfiles.com/detectron2/wheels/cu101/torch1.5/index.html
46+
</code></pre> </details> </td> <td align="left"><details><summary> install </summary><pre><code>python -m pip install detectron2 -f \
47+
https://dl.fbaipublicfiles.com/detectron2/wheels/cu101/torch1.4/index.html
48+
</code></pre> </details> </td> </tr> <tr><td align="left">10.0</td><td align="left"> </td> <td align="left"> </td> <td align="left"><details><summary> install </summary><pre><code>python -m pip install detectron2 -f \
49+
https://dl.fbaipublicfiles.com/detectron2/wheels/cu100/torch1.4/index.html
50+
</code></pre> </details> </td> </tr> <tr><td align="left">9.2</td><td align="left"><details><summary> install </summary><pre><code>python -m pip install detectron2 -f \
51+
https://dl.fbaipublicfiles.com/detectron2/wheels/cu92/torch1.6/index.html
52+
</code></pre> </details> </td> <td align="left"><details><summary> install </summary><pre><code>python -m pip install detectron2 -f \
53+
https://dl.fbaipublicfiles.com/detectron2/wheels/cu92/torch1.5/index.html
54+
</code></pre> </details> </td> <td align="left"><details><summary> install </summary><pre><code>python -m pip install detectron2 -f \
55+
https://dl.fbaipublicfiles.com/detectron2/wheels/cu92/torch1.4/index.html
56+
</code></pre> </details> </td> </tr> <tr><td align="left">cpu</td><td align="left"><details><summary> install </summary><pre><code>python -m pip install detectron2 -f \
57+
https://dl.fbaipublicfiles.com/detectron2/wheels/cpu/torch1.6/index.html
58+
</code></pre> </details> </td> <td align="left"><details><summary> install </summary><pre><code>python -m pip install detectron2 -f \
59+
https://dl.fbaipublicfiles.com/detectron2/wheels/cpu/torch1.5/index.html
60+
</code></pre> </details> </td> <td align="left"><details><summary> install </summary><pre><code>python -m pip install detectron2 -f \
61+
https://dl.fbaipublicfiles.com/detectron2/wheels/cpu/torch1.4/index.html
62+
</code></pre> </details> </td> </tr></tbody></table>
63+
64+
65+
Note that:
66+
1. The pre-built package has to be used with corresponding version of CUDA and official PyTorch release.
67+
It will not work with a different version of PyTorch or a non-official build of PyTorch.
68+
2. New packages are released every few months. Therefore, packages may not contain latest features in the master
69+
branch and may not be compatible with the master branch of a research project that uses detectron2
70+
(e.g. those in [projects](projects)).
71+
72+
### Common Installation Issues
73+
74+
Click each issue for its solutions:
75+
76+
<details>
77+
<summary>
78+
Undefined symbols that contains TH,aten,torch,caffe2; Missing torch dynamic libraries; Segmentation fault immediately when using detectron2.
79+
</summary>
80+
<br/>
81+
82+
This usually happens when detectron2 or torchvision is not
83+
compiled with the version of PyTorch you're running.
84+
85+
If the error comes from a pre-built torchvision, uninstall torchvision and pytorch and reinstall them
86+
following [pytorch.org](http://pytorch.org). So the versions will match.
87+
88+
If the error comes from a pre-built detectron2, check [release notes](https://github.com/facebookresearch/detectron2/releases)
89+
to see the corresponding pytorch version required for each pre-built detectron2.
90+
Or uninstall and reinstall the correct pre-built detectron2.
91+
92+
If the error comes from detectron2 or torchvision that you built manually from source,
93+
remove files you built (`build/`, `**/*.so`) and rebuild it so it can pick up the version of pytorch currently in your environment.
94+
95+
If you cannot resolve this problem, please include the output of `gdb -ex "r" -ex "bt" -ex "quit" --args python -m detectron2.utils.collect_env`
96+
in your issue.
97+
</details>
98+
99+
<details>
100+
<summary>
101+
Undefined C++ symbols (e.g. `GLIBCXX`) or C++ symbols not found.
102+
</summary>
103+
<br/>
104+
Usually it's because the library is compiled with a newer C++ compiler but run with an old C++ runtime.
105+
106+
This often happens with old anaconda.
107+
Try `conda update libgcc`. Then rebuild detectron2.
108+
109+
The fundamental solution is to run the code with proper C++ runtime.
110+
One way is to use `LD_PRELOAD=/path/to/libstdc++.so`.
111+
112+
</details>
113+
114+
<details>
115+
<summary>
116+
"nvcc not found" or "Not compiled with GPU support" or "Detectron2 CUDA Compiler: not available".
117+
</summary>
118+
<br/>
119+
CUDA is not found when building detectron2.
120+
You should make sure
121+
122+
```
123+
python -c 'import torch; from torch.utils.cpp_extension import CUDA_HOME; print(torch.cuda.is_available(), CUDA_HOME)'
124+
```
125+
126+
print `(True, a directory with cuda)` at the time you build detectron2.
127+
128+
Most models can run inference (but not training) without GPU support. To use CPUs, set `MODEL.DEVICE='cpu'` in the config.
129+
</details>
130+
131+
<details>
132+
<summary>
133+
"invalid device function" or "no kernel image is available for execution".
134+
</summary>
135+
<br/>
136+
Two possibilities:
137+
138+
* You build detectron2 with one version of CUDA but run it with a different version.
139+
140+
To check whether it is the case,
141+
use `python -m detectron2.utils.collect_env` to find out inconsistent CUDA versions.
142+
In the output of this command, you should expect "Detectron2 CUDA Compiler", "CUDA_HOME", "PyTorch built with - CUDA"
143+
to contain cuda libraries of the same version.
144+
145+
When they are inconsistent,
146+
you need to either install a different build of PyTorch (or build by yourself)
147+
to match your local CUDA installation, or install a different version of CUDA to match PyTorch.
148+
149+
* PyTorch/torchvision/Detectron2 is not built for the correct GPU architecture (aka. compute capability).
150+
151+
The architecture included by PyTorch/detectron2/torchvision is available in the "architecture flags" in
152+
`python -m detectron2.utils.collect_env`. It must include
153+
the architecture of your GPU, which can be found at [developer.nvidia.com/cuda-gpus](https://developer.nvidia.com/cuda-gpus).
154+
155+
If you're using pre-built PyTorch/detectron2/torchvision, they have included support for most popular GPUs already.
156+
If not supported, you need to build them from source.
157+
158+
When building detectron2/torchvision from source, they detect the GPU device and build for only the device.
159+
This means the compiled code may not work on a different GPU device.
160+
To recompile them for the correct architecture, remove all installed/compiled files,
161+
and rebuild them with the `TORCH_CUDA_ARCH_LIST` environment variable set properly.
162+
For example, `export TORCH_CUDA_ARCH_LIST=6.0,7.0` makes it compile for both P100s and V100s.
163+
</details>
164+
165+
<details>
166+
<summary>
167+
Undefined CUDA symbols; Cannot open libcudart.so
168+
</summary>
169+
<br/>
170+
The version of NVCC you use to build detectron2 or torchvision does
171+
not match the version of CUDA you are running with.
172+
This often happens when using anaconda's CUDA runtime.
173+
174+
Use `python -m detectron2.utils.collect_env` to find out inconsistent CUDA versions.
175+
In the output of this command, you should expect "Detectron2 CUDA Compiler", "CUDA_HOME", "PyTorch built with - CUDA"
176+
to contain cuda libraries of the same version.
177+
178+
When they are inconsistent,
179+
you need to either install a different build of PyTorch (or build by yourself)
180+
to match your local CUDA installation, or install a different version of CUDA to match PyTorch.
181+
</details>
182+
183+
184+
<details>
185+
<summary>
186+
C++ compilation errors from NVCC
187+
</summary>
188+
189+
1. NVCC version has to match the CUDA version of your PyTorch.
190+
191+
2. The combination of NVCC and GCC you use is incompatible. You need to change one of their versions.
192+
See [here](https://gist.github.com/ax3l/9489132) for some valid combinations.
193+
194+
The CUDA/GCC version used by PyTorch can be found by `print(torch.__config__.show())`.
195+
</details>
196+
197+
198+
<details>
199+
<summary>
200+
"ImportError: cannot import name '_C'".
201+
</summary>
202+
<br/>
203+
Please build and install detectron2 following the instructions above.
204+
205+
Or, if you are running code from detectron2's root directory, `cd` to a different one.
206+
Otherwise you may not import the code that you installed.
207+
</details>
208+
209+
210+
<details>
211+
<summary>
212+
Any issue on windows.
213+
</summary>
214+
<br/>
215+
216+
Detectron2 is continuously built on windows with [CircleCI](https://app.circleci.com/pipelines/github/facebookresearch/detectron2?branch=master).
217+
However we do not provide official support for it.
218+
PRs that improves code compatibility on windows are welcome.
219+
</details>
220+
221+
<details>
222+
<summary>
223+
ONNX conversion segfault after some "TraceWarning".
224+
</summary>
225+
<br/>
226+
The ONNX package is compiled with a too old compiler.
227+
228+
Please build and install ONNX from its source code using a compiler
229+
whose version is closer to what's used by PyTorch (available in `torch.__config__.show()`).
230+
</details>

0 commit comments

Comments
 (0)