From 352cf7ffe5ed37842a506a377166b00f5a434b23 Mon Sep 17 00:00:00 2001
From: Wenwei Zhang <40779233+ZwwWayne@users.noreply.github.com>
Date: Fri, 24 Jul 2020 18:58:53 +0800
Subject: [PATCH] Refine doc (#3388)
* Refine docs and fix format issues
* reformat
* fix mock
* Refine format
* Reorganize tutorials
* Update install doc
* resolve comments
---
docs/install.md | 60 ++++++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 54 insertions(+), 6 deletions(-)
diff --git a/docs/install.md b/docs/install.md
index 48d6e472444..cc377478562 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -9,7 +9,6 @@
- GCC 5+
- [mmcv](https://github.com/open-mmlab/mmcv)
-
### Install mmdetection
a. Create a conda virtual environment and activate it.
@@ -54,17 +53,33 @@ pip install mmcv-full==latest+torch1.5.0+cu101 -f https://openmmlab.oss-accelera
See [here]((https://github.com/open-mmlab/mmcv#install-with-pip)) for different versions of MMCV compatible to different PyTorch and CUDA versions.
Optionally you can choose to compile mmcv from source by the following command
-```
+```shell
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
-```python
+
+```shell
pip install mmcv-full
```
-**Important**: You need to run `pip unisntall mmcv` first if you have mmcv installed.
+
+**Important**:
+
+1. The required versions of MMCV for different versions of MMDetection since V2.0 are as below. Please install the correct version of MMCV to avoid installation issues.
+
+| MMDetection version | MMCV version |
+|:-------------------:|:-------------------:|
+| master | mmcv-full>=1.0.2 |
+| 2.3.0rc0 | mmcv-full>=1.0.2 |
+| 2.2.1 | mmcv==0.6.2 |
+| 2.2.0 | mmcv==0.6.2 |
+| 2.1.0 | mmcv>=0.5.9, <=0.6.1|
+| 2.0.0 | mmcv>=0.5.1, <=0.5.8|
+
+2. You need to run `pip unisntall mmcv` first if you have mmcv installed.
If mmcv and mmcv-full are both installed, there will be `ModuleNotFoundError`.
d. Clone the mmdetection repository.
@@ -85,7 +100,7 @@ pip install -v -e . # or "python setup.py develop"
If you build mmdetection on macOS, replace the last command with
-```
+```shell
CC=clang CXX=clang++ CFLAGS='-stdlib=libc++' pip install -e .
```
@@ -96,7 +111,7 @@ It is recommended that you run step d each time you pull some updates from githu
> Important: Be sure to remove the `./build` folder if you reinstall mmdet with a different CUDA/PyTorch version.
- ```
+ ```shell
pip uninstall mmdet
rm -rf ./build
find . -name "*.so" | xargs rm
@@ -110,6 +125,7 @@ you can install it before installing MMCV.
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`.
### Install with CPU only
+
The code can be built for CPU only environment (where CUDA isn't available).
In CPU mode you can run the demo/webcam_demo.py for example.
@@ -169,3 +185,35 @@ To use the default MMDetection installed in the environment rather than that you
```shell
PYTHONPATH="$(dirname $0)/..":$PYTHONPATH
```
+
+### Common issues
+
+We list some common issues and their corresponding solutions here. Feel free to enrich the list if you find any frequent issues and have ways to help others to solve them.
+
+
+
+Compatibility issue between MMCV and MMDetection; "ConvWS is already registered in conv layer";
+
+ Please install the correct version of MMCV for the version of your MMDetection following the instruction above.
+
+
+
+
+"No module named 'mmcv.ops'"; "No module named 'mmcv._ext'".
+
+
+1. Uninstall existing mmcv in the environment using `pip uninstall mmcv`.
+2. Install mmcv-full following the instruction above.
+
+
+
+
+
+"invalid device function" or "no kernel image is available for execution".
+
+
+1. Check the CUDA compute capability of you GPU.
+2. Run `python mmdet/utils/collect_env.py` to check whether PyTorch, torchvision, and MMCV are built for the correct GPU architecture. You may need to set `TORCH_CUDA_ARCH_LIST` to reinstall MMCV. The compatibility issue could happen when using old GPUS, e.g., Tesla K80 (3.7) on colab.
+3. Check whether the running environment is the same as that when mmcv/mmdet is compiled. For example, you may compile mmcv using CUDA 10.0 bug run it on CUDA9.0 environments.
+
+