mirrors
/
mmcv
mirror of https://github.com/open-mmlab/mmcv.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

[Docs] Refine README and installation documentations (#1977) 

* [Docs] Refine README

* refine table

* minor refinement

* refine

* refine

* add version info

* add version info

* update version info

* refine

* refine

* add module links in docs/en/introduction

* update docs/en

* fix typo

* update docs/en

* add version.json in zh_cn

* minor refinement

* update version.json

* update Dockerfile

* minor fix

* update installation of macOS

* resolve comments
pull/2058/head
Zaida Zhou 2022-10-17 17:10:03 +08:00 committed by GitHub
parent e417035f5d
commit bd1da5ab47
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 5186 additions and 1001 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

279
README.md
View File

@ -20,6 +20,7 @@
</div>
[![docs](https://img.shields.io/badge/docs-latest-blue)](https://mmcv.readthedocs.io/en/latest/)
[![platform](https://img.shields.io/badge/platform-Linux%7CWindows%7CmacOS-blue)](https://mmcv.readthedocs.io/en/latest/get_started/installation.html)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mmcv)](https://pypi.org/project/mmcv/)
[![PyPI](https://img.shields.io/pypi/v/mmcv)](https://pypi.org/project/mmcv)
[![badge](https://github.com/open-mmlab/mmcv/workflows/build/badge.svg)](https://github.com/open-mmlab/mmcv/actions)
@ -30,8 +31,84 @@ English | [简体中文](README_zh-CN.md)
## Introduction
MMCV is a foundational library for computer vision research and supports many
research projects as below:
MMCV is a foundational library for computer vision research and it provides the following functionalities:
- [Universal IO APIs](https://mmcv.readthedocs.io/en/latest/understand_mmcv/io.html)
- [Image/Video processing](https://mmcv.readthedocs.io/en/latest/understand_mmcv/data_process.html)
- [Image and annotation visualization](https://mmcv.readthedocs.io/en/latest/understand_mmcv/visualization.html)
- [Useful utilities (progress bar, timer, ...)](https://mmcv.readthedocs.io/en/latest/understand_mmcv/utils.html)
- [PyTorch runner with hooking mechanism](https://mmcv.readthedocs.io/en/latest/understand_mmcv/runner.html)
- [Various CNN architectures](https://mmcv.readthedocs.io/en/latest/understand_mmcv/cnn.html)
- [High-quality implementation of common CPU and CUDA ops](https://mmcv.readthedocs.io/en/latest/understand_mmcv/ops.html)
It supports the following systems:
- Linux
- Windows
- macOS
See the [documentation](http://mmcv.readthedocs.io/en/latest) for more features and usage.
Note: MMCV requires Python 3.6+.
## Installation
There are two versions of MMCV:
- **mmcv-full**: comprehensive, with full features and various CPU and CUDA ops out of the box. It takes longer time to build.
- **mmcv**: lite, without CPU and CUDA ops but all other features, similar to mmcv\<1.0.0. It is useful when you do not need those CUDA ops.
**Note**: Do not install both versions in the same environment, otherwise you may encounter errors like `ModuleNotFound`. You need to uninstall one before installing the other. `Installing the full version is highly recommended if CUDA is available`.
### Install mmcv-full
Before installing mmcv-full, make sure that PyTorch has been successfully installed following the [PyTorch official installation guide](https://github.com/pytorch/pytorch#installation).
The command to install mmcv-full on Linux or Windows platforms is as follows (if your system is macOS, please refer to [build mmcv-full from source](https://mmcv.readthedocs.io/en/latest/get_started/build.html#macos-mmcv-full))
```bash
pip install -U openmim
mim install mmcv-full
```
If you need to specify the version of mmcv-full, you can use the following command
```bash
mim install mmcv-full==1.5.0
```
If you find that the above installation command does not use a pre-built package ending with `.whl` but a source package ending with `.tar.gz`, you may not have a pre-build package corresponding to the PyTorch or CUDA or mmcv-full version, in which case you can [build mmcv-full from source](https://mmcv.readthedocs.io/en/latest/get_started/build.html).
<details>
<summary>Installation log using pre-built packages</summary>
Looking in links: https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html<br />
Collecting mmcv-full<br />
<b>Downloading https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/mmcv_full-1.6.1-cp38-cp38-manylinux1_x86_64.whl</b>
</details>
<details>
<summary>Installation log using source packages</summary>
Looking in links: https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html<br />
Collecting mmcv-full==1.6.0<br />
<b>Downloading mmcv-full-1.6.0.tar.gz</b>
</details>
For more installation methods, please refer to the [Installation documentation](https://mmcv.readthedocs.io/en/latest/get_started/installation.html).
### Install mmcv
If you need to use PyTorch-related modules, make sure PyTorch has been successfully installed in your environment by referring to the [PyTorch official installation guide](https://github.com/pytorch/pytorch#installation).
```bash
pip install -U openmim
mim install mmcv
```
## Supported projects
- [MIM](https://github.com/open-mmlab/mim): MIM installs OpenMMLab packages.
- [MMClassification](https://github.com/open-mmlab/mmclassification): OpenMMLab image classification toolbox and benchmark.
@ -52,205 +129,9 @@ research projects as below:
- [MMGeneration](https://github.com/open-mmlab/mmgeneration): OpenMMLab image and video generative models toolbox.
- [MMDeploy](https://github.com/open-mmlab/mmdeploy): OpenMMLab model deployment framework.
It provides the following functionalities.
- Universal IO APIs
- Image/Video processing
- Image and annotation visualization
- Useful utilities (progress bar, timer, ...)
- PyTorch runner with hooking mechanism
- Various CNN architectures
- High-quality implementation of common CUDA ops
It supports the following systems.
- Linux
- Windows
- macOS
See the [documentation](http://mmcv.readthedocs.io/en/latest) for more features and usage.
Note: MMCV requires Python 3.6+.
## Installation
There are two versions of MMCV:
- **mmcv-full**: comprehensive, with full features and various CUDA ops out of box. It takes longer time to build.
- **mmcv**: lite, without CUDA ops but all other features, similar to mmcv\<1.0.0. It is useful when you do not need those CUDA ops.
**Note**: Do not install both versions in the same environment, otherwise you may encounter errors like `ModuleNotFound`. You need to uninstall one before installing the other. `Installing the full version is highly recommended if CUDA is available`.
a. Install the full version.
Before installing mmcv-full, make sure that PyTorch has been successfully installed following the [official guide](https://pytorch.org/).
We provide pre-built mmcv packages (recommended) with different PyTorch and CUDA versions to simplify the building for **Linux and Windows systems**. In addition, you can run [check_installation.py](.dev_scripts/check_installation.py) to check the installation of mmcv-full after running the installation commands.
i. Install the latest version.
The rule for installing the latest `mmcv-full` is as follows:
```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.1` and `PyTorch 1.9.0`, use the following command:
```shell
pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html
```
**Note**: mmcv-full is only compiled on PyTorch 1.x.0 because the compatibility usually holds between 1.x.0 and 1.x.1. If your PyTorch version is 1.x.1, you can install mmcv-full compiled with PyTorch 1.x.0 and it usually works well. For example, if your PyTorch version is 1.8.1 and CUDA version is 11.1, you can use the following command to install mmcv-full.
```shell
pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.8.0/index.html
```
For more details, please refer the the following tables and delete `=={mmcv_version}`.
ii. Install a specified version.
The rule for installing a specified `mmcv-full` is as follows:
```shell
pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html
```
First of all, please refer to the Releases and replace `{mmcv_version}` a specified one. e.g. `1.3.9`.
Then replace `{cu_version}` and `{torch_version}` in the url to your desired versions. For example,
to install `mmcv-full==1.3.9` with `CUDA 11.1` and `PyTorch 1.9.0`, use the following command:
```shell
pip install mmcv-full==1.3.9 -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html
```
For more details, please refer the the following tables.
<table class="docutils">
<tbody>
<tr>
<th width="80"> CUDA </th>
<th valign="bottom" align="left" width="120">torch 1.11</th>
<th valign="bottom" align="left" width="120">torch 1.10</th>
<th valign="bottom" align="left" width="120">torch 1.9</th>
<th valign="bottom" align="left" width="120">torch 1.8</th>
<th valign="bottom" align="left" width="120">torch 1.7</th>
<th valign="bottom" align="left" width="120">torch 1.6</th>
<th valign="bottom" align="left" width="120">torch 1.5</th>
</tr>
<tr>
<td align="left">11.5</td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu115/torch1.11.0/index.html</code></pre> </details></td>
<td align="left"></td>
<td align="left"></td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
</tr>
<tr>
<td align="left">11.3</td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.11.0/index.html</code></pre> </details></td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10.0/index.html</code></pre> </details></td>
<td align="left"></td>
<td align="left"></code></pre> </details> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
</tr>
<tr>
<td align="left">11.1</td>
<td align="left"> </td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.10.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.8.0/index.html</code></pre> </details> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
</tr>
<tr>
<td align="left">11.0</td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu110/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"> </td>
<td align="left"> </td>
</tr>
<tr>
<td align="left">10.2</td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.11.0/index.html</code></pre> </details></td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.10.0/index.html</code></pre> </details></td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.9.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.6.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.5.0/index.html</code></pre> </details> </td>
</tr>
<tr>
<td align="left">10.1</td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.8.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.6.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.5.0/index.html</code></pre> </details> </td>
</tr>
<tr>
<td align="left">9.2</td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.6.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.5.0/index.html</code></pre> </details> </td>
</tr>
<tr>
<td align="left">cpu</td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.11.0/index.html</code></pre> </details></td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.10.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.9.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.8.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.6.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.5.0/index.html</code></pre> </details> </td>
</tr>
</tbody>
</table>
**Note**: The pre-built packages provided above do not include all versions of mmcv-full, you can click on the corresponding links to see the supported versions. For example, you can click [cu102-torch1.8.0](https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html) and you can see that `cu102-torch1.8.0` only provides 1.3.0 and above versions of mmcv-full. In addition, We no longer provide `mmcv-full` pre-built packages compiled with `PyTorch 1.3 & 1.4` since v1.3.17. You can find previous versions that compiled with PyTorch 1.3 & 1.4 [here](./docs/en/get_started/previous_versions.md). The compatibility is still ensured in our CI, but we will discard the support of PyTorch 1.3 & 1.4 next year.
**Note**: mmcv-full does not provide pre-built packages for `cu102-torch1.11` and `cu92-torch*` on Windows.
Another way is to compile locally by running
```python
pip install mmcv-full
```
Note that the local compiling may take up to 10 mins.
b. Install the lite version.
```python
pip install mmcv
```
c. Install full version with custom operators for onnxruntime
- Check [here](docs/en/deployment/onnxruntime_op.md) for detailed instruction.
If you would like to build MMCV from source, please refer to the [guide](https://mmcv.readthedocs.io/en/latest/get_started/build.html).
## FAQ
If you face some installation issues, CUDA related issues or RuntimeErrors,
you may first refer to this [Frequently Asked Questions](https://mmcv.readthedocs.io/en/latest/faq.html).
If you face installation problems or runtime issues, you may first refer to this [Frequently Asked Questions](https://mmcv.readthedocs.io/zh_CN/latest/faq.html) to see if there is a solution. If the problem is still not solved, feel free to open an [issue](https://github.com/open-mmlab/mmcv/issues).
## Citation

275
README_zh-CN.md
View File

@ -20,6 +20,7 @@
</div>
[![docs](https://img.shields.io/badge/docs-latest-blue)](https://mmcv.readthedocs.io/zh_CN/latest/)
[![platform](https://img.shields.io/badge/platform-Linux%7CWindows%7CmacOS-blue)](https://mmcv.readthedocs.io/zh_CN/latest/get_started/installation.html)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mmcv)](https://pypi.org/project/mmcv/)
[![PyPI](https://img.shields.io/pypi/v/mmcv)](https://pypi.org/project/mmcv)
[![badge](https://github.com/open-mmlab/mmcv/workflows/build/badge.svg)](https://github.com/open-mmlab/mmcv/actions)
@ -30,7 +31,84 @@
## 简介
MMCV 是一个面向计算机视觉的基础库，它支持了很多开源项目，例如：
MMCV 是一个面向计算机视觉的基础库，它提供了以下功能：
- [通用的 IO 接口](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/io.html)
- [图像和视频处理](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/data_process.html)
- [图像和标注结果可视化](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/visualization.html)
- [常用小工具（进度条，计时器等）](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/utils.html)
- [基于 PyTorch 的通用训练框架](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/runner.html)
- [多种 CNN 网络结构](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/cnn.html)
- [高质量实现的 CPU 和 CUDA 算子](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/ops.html)
MMCV 支持多种平台，包括：
- Linux
- Windows
- macOS
如想了解更多特性和用法，请参考[文档](http://mmcv.readthedocs.io/zh_CN/latest)。
提示: MMCV 需要 Python 3.6 以上版本。
## 安装
MMCV 有两个版本：
- **mmcv-full**: 完整版，包含所有的特性以及丰富的开箱即用的 CPU 和 CUDA 算子。
- **mmcv**: 精简版，不包含 CPU 和 CUDA 算子但包含其余所有特性和功能，类似 MMCV 1.0 之前的版本。如果你不需要使用算子的话，精简版可以作为一个考虑选项。
**注意**: 请不要在同一个环境中安装两个版本，否则可能会遇到类似 `ModuleNotFound` 的错误。在安装一个版本之前，需要先卸载另一个。`如果 CUDA 可用，强烈推荐安装 mmcv-full`。
### 安装 mmcv-full
在安装 mmcv-full 之前，请确保 PyTorch 已经成功安装在环境中，可以参考 [PyTorch 官方安装文档](https://github.com/pytorch/pytorch#installation)。
在 Linux 和 Windows 平台安装 mmcv-full 的命令如下（如果你的系统是 macOS，请参考[源码安装 mmcv-full](https://mmcv.readthedocs.io/zh_CN/latest/get_started/build.html#macos-mmcv-full)）
```bash
pip install -U openmim
mim install mmcv-full
```
如果需要指定 mmcv-full 的版本，可以使用以下命令
```bash
mim install mmcv-full==1.5.0
```
如果发现上述的安装命令没有使用预编译包（以 `.whl` 结尾）而是使用源码包（以 `.tar.gz` 结尾）安装，则有可能是我们没有提供和当前环境的 PyTorch 版本、CUDA 版本相匹配的 mmcv-full 预编译包，此时，你可以[源码安装 mmcv-full](https://mmcv.readthedocs.io/zh_CN/latest/get_started/build.html)。
<details>
<summary>使用预编译包的安装日志</summary>
Looking in links: https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html<br />
Collecting mmcv-full<br />
<b>Downloading https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/mmcv_full-1.6.1-cp38-cp38-manylinux1_x86_64.whl</b>
</details>
<details>
<summary>使用源码包的安装日志</summary>
Looking in links: https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html<br />
Collecting mmcv-full==1.6.0<br />
<b>Downloading mmcv-full-1.6.0.tar.gz</b>
</details>
更多安装方式请参考[安装文档](https://mmcv.readthedocs.io/zh_CN/latest/get_started/installation.html)。
### 安装 mmcv
如果你需要使用和 PyTorch 相关的模块，请确保 PyTorch 已经成功安装在环境中，可以参考 [PyTorch 官方安装文档](https://github.com/pytorch/pytorch#installation)。
```bash
pip install -U openmim
mim install mmcv
```
## 支持的开源项目
- [MIM](https://github.com/open-mmlab/mim): MIM 是 OpenMMlab 项目、算法、模型的统一入口
- [MMClassification](https://github.com/open-mmlab/mmclassification): OpenMMLab 图像分类工具箱
@ -51,202 +129,9 @@ MMCV 是一个面向计算机视觉的基础库，它支持了很多开源项目
- [MMGeneration](https://github.com/open-mmlab/mmgeneration): OpenMMLab 图片视频生成模型工具箱
- [MMDeploy](https://github.com/open-mmlab/mmdeploy): OpenMMLab 模型部署框架
MMCV 提供了如下众多功能：
- 通用的 IO 接口
- 图像和视频处理
- 图像和标注结果可视化
- 常用小工具（进度条，计时器等）
- 基于 PyTorch 的通用训练框架
- 多种 CNN 网络结构
- 高质量实现的常见 CUDA 算子
MMCV 支持以下的系统：
- Linux
- Windows
- macOS
如想了解更多特性和使用，请参考[文档](http://mmcv.readthedocs.io/zh_CN/latest)。
提示: MMCV 需要 Python 3.6 以上版本。
## 安装
MMCV 有两个版本：
- **mmcv-full**: 完整版，包含所有的特性以及丰富的开箱即用的 CUDA 算子。注意完整版本可能需要更长时间来编译。
- **mmcv**: 精简版，不包含 CUDA 算子但包含其余所有特性和功能，类似 MMCV 1.0 之前的版本。如果你不需要使用 CUDA 算子的话，精简版可以作为一个考虑选项。
**注意**: 请不要在同一个环境中安装两个版本，否则可能会遇到类似 `ModuleNotFound` 的错误。在安装一个版本之前，需要先卸载另一个。`如果CUDA可用，强烈推荐安装mmcv-full`。
a. 安装完整版
在安装 mmcv-full 之前，请确保 PyTorch 已经成功安装在环境中，可以参考 PyTorch [官方文档](https://pytorch.org/)。
我们提供了 **Linux 和 Windows 平台** PyTorch 和 CUDA 版本组合的 mmcv-full 预编译包，可以大大简化用户安装编译过程。强烈推荐通过预编译包来安装。另外，安装完成后可以运行 [check_installation.py](.dev_scripts/check_installation.py) 脚本检查 mmcv-full 是否安装成功。
i. 安装最新版本
如下是安装最新版 `mmcv-full` 的命令
```shell
pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html
```
请将链接中的 `{cu_version}` 和 `{torch_version}` 根据自身需求替换成实际的版本号，例如想安装和 `CUDA 11.1`、`PyTorch 1.9.0` 兼容的最新版 `mmcv-full`，使用如下替换过的命令
```shell
pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html
```
**注意**: PyTorch 在 1.x.0 和 1.x.1 之间通常是兼容的，故 mmcv-full 只提供 1.x.0 的编译包。如果你的 PyTorch 版本是 1.x.1，你可以放心地安装在 1.x.0 版本编译的 mmcv-full。例如，如果你的 PyTorch 版本是 1.8.1、CUDA 版本是 11.1，你可以使用以下命令安装 mmcv-full。
```shell
pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.8.0/index.html
```
如果想知道更多 CUDA 和 PyTorch 版本的命令，可以参考下面的表格，将链接中的 `=={mmcv_version}` 删去即可。
ii. 安装特定的版本
如下是安装特定版本 `mmcv-full` 的命令
```shell
pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html
```
首先请参考版本发布信息找到想要安装的版本号，将 `{mmcv_version}` 替换成该版本号，例如 `1.3.9`。
然后将链接中的 `{cu_version}` 和 `{torch_version}` 根据自身需求替换成实际的版本号，例如想安装和 `CUDA 11.1`、`PyTorch 1.9.0` 兼容的 `mmcv-full` 1.3.9 版本，使用如下替换过的命令
```shell
pip install mmcv-full==1.3.9 -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html
```
对于更多的 PyTorch 和 CUDA 版本组合，请参考下表：
<table class="docutils">
<tbody>
<tr>
<th width="80"> CUDA </th>
<th valign="bottom" align="left" width="120">torch 1.11</th>
<th valign="bottom" align="left" width="120">torch 1.10</th>
<th valign="bottom" align="left" width="120">torch 1.9</th>
<th valign="bottom" align="left" width="120">torch 1.8</th>
<th valign="bottom" align="left" width="120">torch 1.7</th>
<th valign="bottom" align="left" width="120">torch 1.6</th>
<th valign="bottom" align="left" width="120">torch 1.5</th>
</tr>
<tr>
<td align="left">11.5</td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu115/torch1.11.0/index.html</code></pre> </details> </td>
<td align="left"> </td>
<td align="left"></td>
<td align="left"></code></pre> </details> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
</tr>
<tr>
<td align="left">11.3</td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.11.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10.0/index.html</code></pre> </details> </td>
<td align="left"></td>
<td align="left"></code></pre> </details> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
</tr>
<tr>
<td align="left">11.1</td>
<td align="left"> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.10.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.8.0/index.html</code></pre> </details> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
</tr>
<tr>
<td align="left">11.0</td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu110/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"> </td>
<td align="left"> </td>
</tr>
<tr>
<td align="left">10.2</td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.11.0/index.html</code></pre> </details></td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.10.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.9.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.6.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.5.0/index.html</code></pre> </details> </td>
</tr>
<tr>
<td align="left">10.1</td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.8.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.6.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.5.0/index.html</code></pre> </details> </td>
</tr>
<tr>
<td align="left">9.2</td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.6.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.5.0/index.html</code></pre> </details> </td>
</tr>
<tr>
<td align="left">cpu</td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.11.0/index.html</code></pre> </details></td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.10.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.9.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.8.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.6.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.5.0/index.html</code></pre> </details> </td>
</tr>
</tbody>
</table>
**注意**：以上提供的预编译包并不囊括所有的 mmcv-full 版本，你可以点击对应链接查看支持的版本。例如，点击 [cu102-torch1.8.0](https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html)，可以看到 `cu102-torch1.8.0` 只提供了 1.3.0 及以上的 mmcv-full 版本。另外，从 `mmcv v1.3.17` 开始，我们不再提供`PyTorch 1.3 & 1.4` 对应的 mmcv-full 预编译包。你可以在 [这](./docs/zh_cn/get_started/previous_versions.md) 找到 `PyTorch 1.3 & 1.4` 对应的预编包。虽然我们不再提供 `PyTorch 1.3 & 1.4` 对应的预编译包，但是我们依然在 CI 中保证对它们的兼容持续到下一年。
**注意**：mmcv-full 没有提供 Windows 平台 `cu102-torch1.8.0` 和 `cu92-torch*` 的预编译包。
除了使用预编译包之外，另一种方式是在本地进行编译，直接运行下述命令
```python
pip install mmcv-full
```
但注意本地编译可能会耗时 10 分钟以上。
b. 安装精简版
```python
pip install mmcv
```
c. 安装完整版并且编译 onnxruntime 的自定义算子
- 详细的指南请查看[这里](docs/zh_cn/deployment/onnxruntime_op.md)。
如果想从源码编译 MMCV，请参考[该文档](https://mmcv.readthedocs.io/zh_CN/latest/get_started/build.html)。
## FAQ
如果你遇到了安装问题，CUDA 相关的问题或者 RuntimeErrors，可以首先参考[问题解决页面](https://mmcv.readthedocs.io/zh_CN/latest/faq.html) 看是否已经有解决方案。
如果你遇到了安装问题或者运行时问题，请查看[问题解决页面](https://mmcv.readthedocs.io/zh_CN/latest/faq.html)是否已有解决方案。如果问题仍然没有解决，欢迎提 [issue](https://github.com/open-mmlab/mmcv/issues)。
## 贡献指南

7
docker/release/Dockerfile
View File

@ -16,5 +16,8 @@ RUN apt-get update && apt-get install -y libgl1 libglib2.0-0 \
&& rm -rf /var/lib/apt/lists/*
# Install mmcv-full
ARG MMCV="1.5.1"
RUN pip install openmim && mim install mmcv-full==${MMCV} && python -c 'import mmcv;print(mmcv.__version__)'
ARG MMCV=""
RUN if [ "${MMCV}" = "" ]; then pip install -U openmim && mim install mmcv-full; else pip install -U openmim && mim install mmcv-full==${MMCV}; fi
# Verify the installation
RUN python -c 'import mmcv;print(mmcv.__version__)'

1931
docs/en/_static/version.json 100644
View File

File diff suppressed because it is too large Load Diff

2
docs/en/conf.py
View File

@ -56,6 +56,8 @@ extensions = [
myst_heading_anchors = 4
myst_enable_extensions = ['colon_fence']
autodoc_mock_imports = ['mmcv._ext', 'mmcv.utils.ext_loader', 'torchvision']
# Add any paths that contain templates here, relative to this directory.

344
docs/en/get_started/build.md
View File

@ -1,44 +1,18 @@
## Build MMCV from source
### Build on Linux or macOS
### Build mmcv-full
After cloning the repo with
Before installing mmcv-full, make sure that PyTorch has been successfully installed following the [PyTorch official installation guide](https://pytorch.org/get-started/locally/#start-locally). This can be verified using the following command
```bash
git clone https://github.com/open-mmlab/mmcv.git
cd mmcv
python -c 'import torch;print(torch.__version__)'
```
It is recommended to install `ninja` to speed up the compilation
If version information is output, then PyTorch is installed.
```bash
pip install -r requirements/optional.txt
```
You can either
- install the lite version
```bash
pip install -e .
```
- install the full version
```bash
MMCV_WITH_OPS=1 pip install -e .
```
If you are on macOS, add the following environment variables before the installing command.
```bash
CC=clang CXX=clang++ CFLAGS='-stdlib=libc++'
```
e.g.,
```bash
CC=clang CXX=clang++ CFLAGS='-stdlib=libc++' MMCV_WITH_OPS=1 pip install -e .
```{note}
- To compile ONNX Runtime custom operators, please refer to [How to build custom operators for ONNX Runtime](https://mmcv.readthedocs.io/en/latest/deployment/onnxruntime_op.html#how-to-build-custom-operators-for-onnx-runtime)
- To compile TensorRT customization, please refer to [How to build TensorRT plugins in MMCV](https://mmcv.readthedocs.io/en/latest/deployment/tensorrt_plugin.html#how-to-build-tensorrt-plugins-in-mmcv)
```
```{note}
@ -47,12 +21,104 @@ e.g., in a minimum container environment or servers without GUI,
you can first install it before installing MMCV to skip the installation of `opencv-python`.
```
### Build on Windows
#### Build on Linux
1. Clone the repo
```bash
git clone https://github.com/open-mmlab/mmcv.git
cd mmcv
```
2. Install `ninja` and `psutil` to speed up the compilation
```bash
pip install -r requirements/optional.txt
```
3. Check the nvcc version (requires 9.2+. Skip if no GPU available.)
```bash
nvcc --version
```
If the above command outputs the following message, it means that the nvcc setting is OK, otherwise you need to set CUDA_HOME.
```
nvcc: NVIDIA (R) Cuda compiler driver
Copyright (c) 2005-2020 NVIDIA Corporation
Built on Mon_Nov_30_19:08:53_PST_2020
Cuda compilation tools, release 11.2, V11.2.67
Build cuda_11.2.r11.2/compiler.29373293_0
```
:::{note}
If you want to support ROCm, you can refer to [AMD ROCm](https://rocmdocs.amd.com/en/latest/Installation_Guide/Installation-Guide.html) to install ROCm.
:::
4. Check the gcc version (requires 5.4+)
```bash
gcc --version
```
5. Start building (takes 10+ min)
```bash
MMCV_WITH_OPS=1 pip install -e . -v
```
6. Validate the installation
```bash
python .dev_scripts/check_installation.py
```
If no error is reported by the above command, the installation is successful. If there is an error reported, please check [Frequently Asked Questions](../faq.md) to see if there is already a solution.
If no solution is found, please feel free to open an [issue](https://github.com/open-mmlab/mmcv/issues).
#### Build on macOS
```{note}
If you are using a mac with an M1 chip, install the nightly version of PyTorch, otherwise you will encounter the problem in [issues#2218](https://github.com/open-mmlab/mmcv/issues/2218).
```
1. Clone the repo
```bash
git clone https://github.com/open-mmlab/mmcv.git
cd mmcv
```
2. Install `ninja` and `psutil` to speed up the compilation
```bash
pip install -r requirements/optional.txt
```
3. Start building
```bash
MMCV_WITH_OPS=1 pip install -e .
```
4. Validate the installation
```bash
python .dev_scripts/check_installation.py
```
If no error is reported by the above command, the installation is successful. If there is an error reported, please check [Frequently Asked Questions](../faq.md) to see if there is already a solution.
If no solution is found, please feel free to open an [issue](https://github.com/open-mmlab/mmcv/issues).
#### Build on Windows
Building MMCV on Windows is a bit more complicated than that on Linux.
The following instructions show how to get this accomplished.
#### Prerequisite
##### Prerequisite
The following software is required for building MMCV on windows.
Install them first.
@ -71,7 +137,7 @@ Install them first.
You should know how to set up environment variables, especially `Path`, on Windows. The following instruction relies heavily on this skill.
```
#### Setup Python Environment
##### Common steps
1. Launch Anaconda prompt from Windows Start menu
@ -79,62 +145,45 @@ You should know how to set up environment variables, especially `Path`, on Windo
2. Create a new conda environment
```shell
conda create --name mmcv python=3.7 # 3.6, 3.7, 3.8 should work too as tested
conda activate mmcv # make sure to activate environment before any operation
```powershell
(base) PS C:\Users\xxx> conda create --name mmcv python=3.7
(base) PS C:\Users\xxx> conda activate mmcv # make sure to activate environment before any operation
```
3. Install PyTorch. Choose a version based on your need.
```shell
conda install pytorch torchvision cudatoolkit=10.2 -c pytorch
```powershell
# CUDA version
(mmcv) PS C:\Users\xxx> conda install pytorch torchvision cudatoolkit=10.2 -c pytorch
# CPU version
(mmcv) PS C:\Users\xxx> conda install install pytorch torchvision cpuonly -c pytorch
```
We only tested PyTorch version >= 1.6.0.
4. Clone the repo
4. Prepare MMCV source code
```powershell
(mmcv) PS C:\Users\xxx> git clone https://github.com/open-mmlab/mmcv.git
(mmcv) PS C:\Users\xxx\mmcv> cd mmcv
```
5. Install `ninja` and `psutil` to speed up the compilation
```powershell
(mmcv) PS C:\Users\xxx\mmcv> pip install -r requirements/optional.txt
```
6. Install required Python packages
```shell
git clone https://github.com/open-mmlab/mmcv.git
cd mmcv
(mmcv) PS C:\Users\xxx\mmcv> pip install -r requirements/runtime.txt
```
5. Install required Python packages
```shell
pip3 install -r requirements/runtime.txt
```
6. It is recommended to install `ninja` to speed up the compilation
```bash
pip install -r requirements/optional.txt
```
#### Build and install MMCV
MMCV can be built in three ways:
1. Lite version (without ops)
In this way, no custom ops are compiled and mmcv is a pure python package.
2. Full version (CPU ops)
Module `ops` will be compiled as a pytorch extension, but only x86 code will be compiled. The compiled ops can be executed on CPU only.
3. Full version (CUDA ops)
Both x86 and CUDA codes of `ops` module will be compiled. The compiled version can be run on both CPU and CUDA-enabled GPU (if implemented).
##### Common steps
1. Set up MSVC compiler
7. Set up MSVC compiler
Set Environment variable, add `C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.27.29110\bin\Hostx86\x64` to `PATH`, so that `cl.exe` will be available in prompt, as shown below.
```none
(base) PS C:\Users\xxx> cl
```powershell
(mmcv) PS C:\Users\xxx\mmcv> cl
Microsoft (R) C/C++ Optimizing Compiler Version 19.27.29111 for x64
Copyright (C) Microsoft Corporation. All rights reserved.
@ -145,124 +194,135 @@ MMCV can be built in three ways:
You may want to change the system language to English because pytorch will parse text output from `cl.exe` to check its version. However only utf-8 is recognized. Navigate to Control Panel -> Region -> Administrative -> Language for Non-Unicode programs and change it to English.
##### Option 1: Build MMCV (lite version)
##### Build and install MMCV
After finishing above common steps, launch Anaconda shell from Start menu and issue the following commands:
mmcv-full can be built in two ways:
```shell
# activate environment
conda activate mmcv
# change directory
cd mmcv
# install
python setup.py develop
# check
pip list
1. Full version (CPU ops)
Module `ops` will be compiled as a pytorch extension, but only x86 code will be compiled. The compiled ops can be executed on CPU only.
2. Full version (CUDA ops)
Both x86 and CUDA codes of `ops` module will be compiled. The compiled version can be run on both CPU and CUDA-enabled GPU (if implemented).
###### CPU version
1. Set up environment variables
```powershell
(mmcv) PS C:\Users\xxx\mmcv> $env:MMCV_WITH_OPS = 1
```
##### Option 2: Build MMCV (full version with CPU)
2. Build and install
1. Finish above common steps
2. Set up environment variables
```shell
$env:MMCV_WITH_OPS = 1
$env:MAX_JOBS = 8 # based on your available number of CPU cores and amount of memory
```powershell
(mmcv) PS C:\Users\xxx\mmcv> python setup.py build_ext
(mmcv) PS C:\Users\xxx\mmcv> python setup.py develop
```
3. Following build steps of the lite version
```shell
# activate environment
conda activate mmcv
# change directory
cd mmcv
# build
python setup.py build_ext # if success, cl will be launched to compile ops
# install
python setup.py develop
# check
pip list
```
##### Option 3: Build MMCV (full version with CUDA)
1. Finish above common steps
###### GPU version
2. Make sure `CUDA_PATH` or `CUDA_HOME` is already set in `envs` via `ls env:`, desired output is shown as below:
```none
(base) PS C:\Users\WRH> ls env:
```powershell
(mmcv) PS C:\Users\xxx\mmcv> ls env:
Name Value
---- -----
<... omit some lines ...>
CUDA_PATH C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2
CUDA_PATH_V10_1 C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.1
CUDA_PATH_V10_2 C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2
<... omit some lines ...>
```
This should already be done by CUDA installer. If not, or you have multiple version of CUDA toolkit installed, set it with
```shell
$env:CUDA_HOME = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2"
```powershell
(mmcv) PS C:\Users\xxx\mmcv> $env:CUDA_HOME = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2"
# OR
$env:CUDA_HOME = $env:CUDA_PATH_V10_2 # if CUDA_PATH_V10_2 is in envs:
(mmcv) PS C:\Users\xxx\mmcv> $env:CUDA_HOME = $env:CUDA_PATH_V10_2 # if CUDA_PATH_V10_2 is in envs:
```
3. Set CUDA target arch
```shell
# Suppose you are using GTX 1080, which is of capability 6.1
$env:TORCH_CUDA_ARCH_LIST="6.1"
# OR build all supported arch, will be slow
$env:TORCH_CUDA_ARCH_LIST="3.5 3.7 5.0 5.2 6.0 6.1 7.0 7.5"
# Here you need to change to the target architecture corresponding to your GPU
(mmcv) PS C:\Users\xxx\mmcv> $env:TORCH_CUDA_ARCH_LIST="7.5"
```
```{note}
:::{note}
Check your the compute capability of your GPU from [here](https://developer.nvidia.com/cuda-gpus).
```powershell
(mmcv) PS C:\Users\xxx\mmcv> &"C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2\extras\demo_suite\deviceQuery.exe"
Device 0: "NVIDIA GeForce GTX 1660 SUPER"
CUDA Driver Version / Runtime Version 11.7 / 11.1
CUDA Capability Major/Minor version number: 7.5
```
4. Launch compiling the same way as CPU
The 7.5 above indicates the target architecture. Note: You need to replace v10.2 with your CUDA version in the above command.
:::
```shell
$env:MMCV_WITH_OPS = 1
$env:MAX_JOBS = 8 # based on available number of CPU cores and amount of memory
# activate environment
conda activate mmcv
# change directory
cd mmcv
4. Build and install
```powershell
# build
python setup.py build_ext # if success, cl will be launched to compile ops
# install
python setup.py develop
# check
pip list
```
```{note}
If you are compiling against PyTorch 1.6.0, you might meet some errors from PyTorch as described in [this issue](https://github.com/pytorch/pytorch/issues/42467). Follow [this pull request](https://github.com/pytorch/pytorch/pull/43380/files) to modify the source code in your local PyTorch installation.
```
If you meet issues when running or compiling mmcv, we list some common issues in [Frequently Asked Question](../faq.html).
##### Validate installation
## \[Optional\] Build MMCV on IPU machine
```powershell
(mmcv) PS C:\Users\xxx\mmcv> python .dev_scripts/check_installation.py
```
If no error is reported by the above command, the installation is successful. If there is an error reported, please check [Frequently Asked Questions](../faq.md) to see if there is already a solution.
If no solution is found, please feel free to open an [issue](https://github.com/open-mmlab/mmcv/issues).
### Build mmcv
If you need to use PyTorch-related modules, make sure PyTorch has been successfully installed in your environment by referring to the [PyTorch official installation guide](https://github.com/pytorch/pytorch#installation).
1. Clone the repo
```bash
git clone https://github.com/open-mmlab/mmcv.git
cd mmcv
```
2. Start building
```bash
pip install -e . -v
```
3. Validate installation
```bash
python -c 'import mmcv;print(mmcv.__version__)'
```
### Build mmcv-full on IPU machine
Firstly, you need to apply for an IPU cloud machine, see [here](https://www.graphcore.ai/ipus-in-the-cloud).
### Option 1: Docker
#### Option 1: Docker
1. Pull docker
```shell
```bash
docker pull graphcore/pytorch
```
2. Build MMCV under same python environment
### Option 2: Install from SDK
#### Option 2: Install from SDK
1. Build MMCV

497
docs/en/get_started/installation.md
View File

@ -2,183 +2,374 @@
There are two versions of MMCV:
- **mmcv-full**: comprehensive, with full features and various CUDA ops out of box. It takes longer time to build.
- **mmcv**: lite, without CUDA ops but all other features, similar to mmcv\<1.0.0. It is useful when you do not need those CUDA ops.
- **mmcv-full**: comprehensive, with full features and various CPU and CUDA ops out of box. It takes longer time to build.
- **mmcv**: lite, without CPU and CUDA ops but all other features, similar to mmcv\<1.0.0. It is useful when you do not need those CUDA ops.
```{warning}
Do not install both versions in the same environment, otherwise you may encounter errors like `ModuleNotFound`. You need to uninstall one before installing the other. `Installing the full version is highly recommended if CUDA is avaliable`.
```
a. Install the full version.
Before installing mmcv-full, make sure that PyTorch has been successfully installed following the [official guide](https://pytorch.org/).
We provide pre-built mmcv packages (recommended) with different PyTorch and CUDA versions to simplify the building for **Linux and Windows systems**. In addition, you can run [check_installation.py](.dev_scripts/check_installation.py) to check the installation of mmcv-full after running the installation commands.
i. Install the latest version.
The rule for installing the latest `mmcv-full` is as follows:
```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.1` and `PyTorch 1.9.0`, use the following command:
```shell
pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html
```
For more details, please refer the the following tables and delete `=={mmcv_version}`.
ii. Install a specified version.
The rule for installing a specified `mmcv-full` is as follows:
```shell
pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html
```
First of all, please refer to the Releases and replace `{mmcv_version}` a specified one. e.g. `1.3.9`.
Then replace `{cu_version}` and `{torch_version}` in the url to your desired versions. For example,
to install `mmcv-full==1.3.9` with `CUDA 11.1` and `PyTorch 1.9.0`, use the following command:
```shell
pip install mmcv-full==1.3.9 -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html
```
### Install mmcv-full
```{note}
- The following installation steps are for Linux and Windows platforms only. To install mmcv-full on macOS platform, please refer to [build mmcv-full from source](https://mmcv.readthedocs.io/en/latest/get_started/build.html#macos-mmcv-full).
- To compile ONNX Runtime custom operators, please refer to [How to build custom operators for ONNX Runtime](https://mmcv.readthedocs.io/en/latest/deployment/onnxruntime_op.html#how-to-build-custom-operators-for-onnx-runtime)
- To compile TensorRT customization, please refer to [How to build TensorRT plugins in MMCV](https://mmcv.readthedocs.io/en/latest/deployment/tensorrt_plugin.html#how-to-build-tensorrt-plugins-in-mmcv)
```
Before installing mmcv-full, make sure that PyTorch has been successfully installed following the [PyTorch official installation guide](https://pytorch.org/get-started/locally/#start-locally). This can be verified using the following command
```bash
python -c 'import torch;print(torch.__version__)'
```
If version information is output, then PyTorch is installed.
#### Install with mim (recommended)
[mim](https://github.com/open-mmlab/mim) is the package management tool for the OpenMMLab projects, which makes it easy to install mmcv-full
```bash
pip install -U openmim
mim install mmcv-full
```
If you find that the above installation command does not use a pre-built package ending with `.whl` but a source package ending with `.tar.gz`, you may not have a pre-build package corresponding to the PyTorch or CUDA or mmcv-full version, in which case you can [build mmcv-full from source](build.md).
<details>
<summary>Installation log using pre-built packages</summary>
Looking in links: https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html<br />
Collecting mmcv-full<br />
<b>Downloading https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/mmcv_full-1.6.1-cp38-cp38-manylinux1_x86_64.whl</b>
</details>
<details>
<summary>Installation log using source packages</summary>
Looking in links: https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html<br />
Collecting mmcv-full==1.6.0<br />
<b>Downloading mmcv-full-1.6.0.tar.gz</b>
</details>
To install a specific version of mmcv-full, for example, mmcv-full version 1.6.0, you can use the following command
```bash
mim install mmcv-full==1.6.0
```
:::{note}
If you would like to use `opencv-python-headless` instead of `opencv-python`,
e.g., in a minimum container environment or servers without GUI,
you can first install it before installing MMCV to skip the installation of `opencv-python`.
Alternatively, if it takes too long to install a dependency library, you can specify the pypi source
```bash
mim install mmcv-full -i https://pypi.tuna.tsinghua.edu.cn/simple
```
:::
You can run [check_installation.py](https://github.com/open-mmlab/mmcv/.dev_scripts/check_installation.py) to check the installation of mmcv-full after running the installation commands.
#### Install with pip
Use the following command to check the version of CUDA and PyTorch
```bash
python -c 'import torch;print(torch.__version__);print(torch.version.cuda)'
```
Select the appropriate installation command depending on the type of system, CUDA version, PyTorch version, and MMCV version
<html>
<body>
<style>
select {
z-index: 1000;
position: absolute;
top: 10px;
width: 6.7rem;
}
#select-container {
position: relative;
height: 30px;
}
#select-cmd {
background-color: #f5f6f7;
font-size: 14px;
margin-top: 20px;
}
/* 让每一个都间隔1.3rem */
#select-os {
/* left: 1.375rem; */
left: 0;
}
#select-cuda {
/* left: 9.375rem; 9.375 = 1.375 + 6.7 + 1.3 */
left: 8rem;
}
#select-torch {
/* left: 17.375rem; 17.375 = 9.375 + 6.7 + 1.3 */
left: 16rem;
}
#select-mmcv {
/* left: 25.375rem; 25.375 = 17.375 + 6.7 + 1.3 */
left: 24rem;
}
</style>
<div id="select-container">
<select
onmousedown="handleSelectMouseDown(this.id)"
onblur="handleSelectBlur(this.id)"
onchange="changeOS(this.value)"
id="select-os">
</select>
<select
onmousedown="handleSelectMouseDown(this.id)"
onblur="handleSelectBlur(this.id)"
onchange="changeCUDA(this.value)"
id="select-cuda">
</select>
<select
onmousedown="handleSelectMouseDown(this.id)"
onblur="handleSelectBlur(this.id)"
onchange="changeTorch(this.value)"
id="select-torch">
</select>
<select
onmousedown="handleSelectMouseDown(this.id)"
onblur="handleSelectBlur(this.id)"
onchange="changeMMCV(this.value)"
id="select-mmcv">
</select>
</div>
<pre id="select-cmd"></pre>
</body>
<script>
// 各个select当前的值
let osVal, cudaVal, torchVal, mmcvVal;
function changeMMCV(val) {
mmcvVal = val;
change("select-mmcv");
}
function changeTorch(val) {
torchVal = val;
change("select-torch");
}
function changeCUDA(val) {
cudaVal = val;
change("select-cuda");
}
function changeOS(val) {
osVal = val;
change("select-os");
}
// 控制size大小相关的几个方法
function handleSelectMouseDown(id) {
const dom = document.getElementById(id);
if (!dom) return;
const len = dom?.options?.length;
if (len >= 9) {
dom.size = 10;
dom.style.zIndex = 100;
}
}
function handleSelectClick() {
const selects = Array.from(document.getElementsByTagName("select"));
selects.forEach(select => {
select.size = 1;
});
}
function handleSelectBlur(id) {
const dom = document.getElementById(id);
if (!dom) {
// 如果没有指定特定的id，那就直接把所有的select都设置成size = 1
handleSelectClick();
return;
}
dom.size = 1;
dom.style.zIndex = 1;
}
function changeCmd() {
const cmd = document.getElementById("select-cmd");
let cmdString = "pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html";
// e.g: pip install mmcv-full==1.6.0 -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9/index.html
const cudaVersion = `${cudaVal === "cpu" ? cudaVal : `cu${cudaVal.split(".").join("")}`}`;
const torchVersion = `torch${torchVal.substring(0, torchVal.length - 2)}`;
cmdString = cmdString.replace("{cu_version}", cudaVersion).replace("{mmcv_version}", mmcvVal).replace("{torch_version}", torchVersion);
cmd.textContent = cmdString;
}
// string数组去重
function unique(arr) {
if (!arr || !Array.isArray(arr)) return [];
return [...new Set(arr)];
}
// 根据string数组生成option的DocumentFragment
function genOptionFragment(data, id) {
const name = id.includes("-")? id.split("-")[1] : id;
const fragment = new DocumentFragment();
data.forEach(option => {
const ele = document.createElement("option");
let text = `${name} ${option}`;
if (name === "os" || option.toUpperCase() === "CPU") {
text = `${option}`;
}
ele.textContent = text;
// 添加value属性，方便下拉框选择时直接读到数据
ele.value = option;
// 添加点击事件监听
ele.addEventListener('click', handleSelectClick);
fragment.appendChild(ele);
});
return fragment;
}
// 在dom树中找到id对应的dom（select元素），并将生成的options添加到元素内
function findAndAppend(data, id) {
const fragment = genOptionFragment(data, id);
const dom = document.getElementById(id);
if (dom) dom.replaceChildren(fragment);
}
/**
* change方法的重点在于
* 1. 各个下拉框数据的联动
* OS ==> cuda ==> torch ==> mmcv
* 2. 命令行的修改
*/
function change(id) {
const order = ["select-mmcv", "select-torch", "select-cuda", "select-os"];
const idx = order.indexOf(id);
if (idx === -1) return;
const versionDetail = version[osVal];
if (idx >= 3) {
// 根据os修改cuda
let cuda = [];
versionDetail.forEach(v => {
cuda.push(v.cuda);
});
cuda = unique(cuda);
cudaVal = cuda[0];
findAndAppend(cuda, "select-cuda");
}
if (idx >= 2) {
// 根据cuda修改torch
const torch = [];
versionDetail.forEach(v => {
if (v.cuda === cudaVal) torch.push(v.torch);
});
torchVal = torch[0];
findAndAppend(torch, "select-torch");
}
if (idx >= 1) {
// 根据torch修改mmcv
let mmcv = [];
versionDetail.forEach(v => {
if (v.cuda === cudaVal && v.torch === torchVal) mmcv = v.mmcv;
});
mmcvVal = mmcv[0];
findAndAppend(mmcv, "select-mmcv");
}
changeCmd();
}
// 初始化，处理version数据，并调用findAndAppend
function init() {
// 增加一个全局的click事件监听，作为select onBlur事件失效的兜底
document.addEventListener("click", handleSelectBlur);
const version = window.version;
// OS
const os = Object.keys(version);
osVal = os[0];
findAndAppend(os, "select-os");
change("select-os");
changeCmd();
}
// 利用xhr获取本地version数据，如果作为html直接浏览的话需要使用本地服务器打开，否则会有跨域问题
window.onload = function () {
const url = "../_static/version.json"
// 申明一个XMLHttpRequest
const request = new XMLHttpRequest();
// 设置请求方法与路径
request.open("get", url);
// 不发送数据到服务器
request.send(null);
//XHR对象获取到返回信息后执行
request.onload = function () {
// 返回状态为200，即为数据获取成功
if (request.status !== 200) return;
const data = JSON.parse(request.responseText);
window.version = data;
init();
}
}
</script>
</html>
If you do not find a corresponding version in the dropdown box above, you probably do not have a pre-built package corresponding to the PyTorch or CUDA or mmcv-full version, at which point you can [build mmcv-full from source](build.md).
:::{note}
mmcv-full is only compiled on PyTorch 1.x.0 because the compatibility
usually holds between 1.x.0 and 1.x.1. If your PyTorch version is 1.x.1, you
can install mmcv-full compiled with PyTorch 1.x.0 and it usually works well.
For example, if your PyTorch version is 1.8.1 and CUDA version is 11.1, you
can use the following command to install mmcv-full.
For example, if your PyTorch version is 1.8.1, you can feel free to choose 1.8.x.
:::
`pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.8.0/index.html`
:::{note}
If you would like to use `opencv-python-headless` instead of `opencv-python`,
e.g., in a minimum container environment or servers without GUI,
you can first install it before installing MMCV to skip the installation of `opencv-python`.
Alternatively, if it takes too long to install a dependency library, you can specify the pypi source
```bash
mim install mmcv-full -i https://pypi.tuna.tsinghua.edu.cn/simple
```
For more details, please refer the the following tables.
:::
<table class="docutils">
<tbody>
<tr>
<th width="80"> CUDA </th>
<th valign="bottom" align="left" width="120">torch 1.11</th>
<th valign="bottom" align="left" width="120">torch 1.10</th>
<th valign="bottom" align="left" width="120">torch 1.9</th>
<th valign="bottom" align="left" width="120">torch 1.8</th>
<th valign="bottom" align="left" width="120">torch 1.7</th>
<th valign="bottom" align="left" width="120">torch 1.6</th>
<th valign="bottom" align="left" width="120">torch 1.5</th>
</tr>
<tr>
<td align="left">11.5</td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu115/torch1.11.0/index.html</code></pre> </details></td>
<td align="left"></td>
<td align="left"></td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
</tr>
<tr>
<td align="left">11.3</td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.11.0/index.html</code></pre> </details></td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10.0/index.html</code></pre> </details></td>
<td align="left"></td>
<td align="left"></code></pre> </details> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
</tr>
<tr>
<td align="left">11.1</td>
<td align="left"> </td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.10.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.8.0/index.html</code></pre> </details> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
</tr>
<tr>
<td align="left">11.0</td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu110/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"> </td>
<td align="left"> </td>
</tr>
<tr>
<td align="left">10.2</td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.11.0/index.html</code></pre> </details></td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.10.0/index.html</code></pre> </details></td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.9.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.6.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.5.0/index.html</code></pre> </details> </td>
</tr>
<tr>
<td align="left">10.1</td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.8.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.6.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.5.0/index.html</code></pre> </details> </td>
</tr>
<tr>
<td align="left">9.2</td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.6.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.5.0/index.html</code></pre> </details> </td>
</tr>
<tr>
<td align="left">cpu</td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.11.0/index.html</code></pre> </details></td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.10.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.9.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.8.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.6.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.5.0/index.html</code></pre> </details> </td>
</tr>
</tbody>
</table>
You can run [check_installation.py](https://github.com/open-mmlab/mmcv/.dev_scripts/check_installation.py) to check the installation of mmcv-full after running the installation commands.
```{note}
The pre-built packages provided above do not include all versions of mmcv-full, you can click on the corresponding links to see the supported versions. For example, if you click [cu102-torch1.8.0](https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html), you can see that `cu102-torch1.8.0` only provides 1.3.0 and above versions of mmcv-full. In addition, We no longer provide `mmcv-full` pre-built packages compiled with `PyTorch 1.3 & 1.4` since v1.3.17. You can find previous versions that compiled with PyTorch 1.3 & 1.4 [here](./previous_versions.md). The compatibility is still ensured in our CI, but we will discard the support of PyTorch 1.3 & 1.4 next year.
#### Using mmcv-full with Docker
Build with local repository
```bash
git clone https://github.com/open-mmlab/mmcv.git && cd mmcv
docker build -t mmcv -f docker/release/Dockerfile .
```
```{note}
mmcv-full does not provide pre-built packages for `cu102-torch1.11` and `cu92-torch*` on Windows.
Or build with remote repository
```bash
docker build -t mmcv https://github.com/open-mmlab/mmcv.git#master:docker/release
```
Another way is to compile locally by running
The [Dockerfile](release/Dockerfile) installs latest released version of mmcv-full by default, but you can specify mmcv versions to install expected versions.
```python
pip install mmcv-full
```bash
docker image build -t mmcv -f docker/release/Dockerfile --build-arg MMCV=1.5.0 .
```
Note that the local compiling may take up to 10 mins.
If you also want to use other versions of PyTorch and CUDA, you can also pass them when building docker images.
b. Install the lite version.
An example to build an image with PyTorch 1.11 and CUDA 11.3.
```bash
docker build -t mmcv -f docker/release/Dockerfile \
--build-arg PYTORCH=1.9.0 \
--build-arg CUDA=11.1 \
--build-arg CUDNN=8 \
--build-arg MMCV=1.5.0 .
```
More available versions of PyTorch and CUDA can be found at [dockerhub/pytorch](https://hub.docker.com/r/pytorch/pytorch/tags).
### Install mmcv
If you need to use PyTorch-related modules, make sure PyTorch has been successfully installed in your environment by referring to the [PyTorch official installation guide](https://github.com/pytorch/pytorch#installation).
```python
pip install mmcv
```
c. Install full version with custom operators for onnxruntime
- Check [here](https://mmcv.readthedocs.io/en/latest/deployment/onnxruntime_custom_ops.html) for detailed instruction.
If you would like to build MMCV from source, please refer to the [guide](https://mmcv.readthedocs.io/en/latest/get_started/build.html).

18
docs/en/get_started/introduction.md
View File

@ -22,17 +22,17 @@ research projects as below:
- [MMGeneration](https://github.com/open-mmlab/mmgeneration): OpenMMLab image and video generative models toolbox.
- [MMDeploy](https://github.com/open-mmlab/mmdeploy): OpenMMLab model deployment framework.
It provides the following functionalities.
It provides the following functionalities:
- Universal IO APIs
- Image/Video processing
- Image and annotation visualization
- Useful utilities (progress bar, timer, ...)
- PyTorch runner with hooking mechanism
- Various CNN architectures
- High-quality implementation of common CUDA ops
- [Universal IO APIs](https://mmcv.readthedocs.io/en/latest/understand_mmcv/io.html)
- [Image/Video processing](https://mmcv.readthedocs.io/en/latest/understand_mmcv/data_process.html)
- [Image and annotation visualization](https://mmcv.readthedocs.io/en/latest/understand_mmcv/visualization.html)
- [Useful utilities (progress bar, timer, ...)](https://mmcv.readthedocs.io/en/latest/understand_mmcv/utils.html)
- [PyTorch runner with hooking mechanism](https://mmcv.readthedocs.io/en/latest/understand_mmcv/runner.html)
- [Various CNN architectures](https://mmcv.readthedocs.io/en/latest/understand_mmcv/cnn.html)
- [High-quality implementation of common CPU and CUDA ops](https://mmcv.readthedocs.io/en/latest/understand_mmcv/ops.html)
It supports the following systems.
It supports the following systems:
- Linux
- Windows

1931
docs/zh_cn/_static/version.json 100644
View File

File diff suppressed because it is too large Load Diff

2
docs/zh_cn/conf.py
View File

@ -57,6 +57,8 @@ extensions = [
myst_heading_anchors = 4
myst_enable_extensions = ['colon_fence']
autodoc_mock_imports = ['mmcv._ext', 'mmcv.utils.ext_loader', 'torchvision']
autosectionlabel_prefix_document = True

350
docs/zh_cn/get_started/build.md
View File

@ -1,55 +1,141 @@
## 从源码编译 MMCV
### 在 Linux 或者 macOS 上编译 MMCV
### 编译 mmcv-full
克隆算法库
在编译 mmcv-full 之前，请确保 PyTorch 已经成功安装在环境中，可以参考 [PyTorch 官方安装文档](https://pytorch.org/get-started/locally/#start-locally)。可使用以下命令验证
```bash
python -c 'import torch;print(torch.__version__)'
```
```{note}
- 如需编译 ONNX Runtime 自定义算子，请参考[如何编译ONNX Runtime自定义算子](https://mmcv.readthedocs.io/zh_CN/latest/deployment/onnxruntime_op.html#id1)
- 如需编译 TensorRT 自定义，请参考[如何编译MMCV中的TensorRT插件](https://mmcv.readthedocs.io/zh_CN/latest/deployment/tensorrt_plugin.html#id3)
```
:::{note}
- 如果克隆代码仓库的速度过慢，可以使用以下命令克隆（注意：gitee 的 mmcv 不一定和 github 的保持一致，因为每天只同步一次）
```bash
git clone https://gitee.com/open-mmlab/mmcv.git
```
- 如果打算使用 `opencv-python-headless` 而不是 `opencv-python`，例如在一个很小的容器环境或者没有图形用户界面的服务器中，你可以先安装 `opencv-python-headless`，这样在安装 mmcv 依赖的过程中会跳过 `opencv-python`。
- 如果编译过程安装依赖库的时间过长，可以[设置 pypi 源](https://mirrors.tuna.tsinghua.edu.cn/help/pypi/)
```bash
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
```
:::
#### 在 Linux 上编译 mmcv-full
| TODO: 视频教程
1. 克隆代码仓库
```bash
git clone https://github.com/open-mmlab/mmcv.git
cd mmcv
```
建议安装 `ninja` 以加快编译速度
2. 安装 `ninja` 和 `psutil` 以加快编译速度
```bash
pip install -r requirements/optional.txt
```
你可以安装 lite 版本
3. 检查 nvcc 的版本（要求大于等于 9.2，如果没有 GPU，可以跳过）
```bash
pip install -e .
nvcc --version
```
也可以安装 full 版本
上述命令如果输出以下信息，表示 nvcc 的设置没有问题，否则需要设置 CUDA_HOME
```
nvcc: NVIDIA (R) Cuda compiler driver
Copyright (c) 2005-2020 NVIDIA Corporation
Built on Mon_Nov_30_19:08:53_PST_2020
Cuda compilation tools, release 11.2, V11.2.67
Build cuda_11.2.r11.2/compiler.29373293_0
```
:::{note}
如果想要支持 ROCm，可以参考 [AMD ROCm](https://rocmdocs.amd.com/en/latest/Installation_Guide/Installation-Guide.html) 安装 ROCm。
:::
4. 检查 gcc 的版本（要求大于等于**5.4**）
```bash
gcc --version
```
5. 开始编译（预估耗时 10 分钟）
```bash
MMCV_WITH_OPS=1 pip install -e . -v
```
6. 验证安装
```bash
python .dev_scripts/check_installation.py
```
如果上述命令没有报错，说明安装成功。如有报错，请查看[问题解决页面](https://mmcv.readthedocs.io/zh_CN/latest/faq.html)是否已经有解决方案。
如果没有找到解决方案，欢迎提 [issue](https://github.com/open-mmlab/mmcv/issues)。
#### 在 macOS 上编译 mmcv-full
| TODO: 视频教程
```{note}
如果你使用的 mac 是 M1 芯片，请安装 PyTorch 的 nightly 版本，否则会遇到 [issues#2218](https://github.com/open-mmlab/mmcv/issues/2218) 中的问题。
```
1. 克隆代码仓库
```bash
git clone https://github.com/open-mmlab/mmcv.git
cd mmcv
```
2. 安装 `ninja` 和 `psutil` 以加快编译速度
```bash
pip install -r requirements/optional.txt
```
3. 开始编译
```bash
MMCV_WITH_OPS=1 pip install -e .
```
如果是在 macOS 上编译，则需要在安装命令前添加一些环境变量
4. 验证安装
```bash
CC=clang CXX=clang++ CFLAGS='-stdlib=libc++'
python .dev_scripts/check_installation.py
```
例如
如果上述命令没有报错，说明安装成功。如有报错，请查看[问题解决页面](../faq.md)是否已经有解决方案。
```bash
CC=clang CXX=clang++ CFLAGS='-stdlib=libc++' MMCV_WITH_OPS=1 pip install -e .
```
如果没有找到解决方案，欢迎提 [issue](https://github.com/open-mmlab/mmcv/issues)。
```{note}
如果你打算使用 `opencv-python-headless` 而不是 `opencv-python`，例如在一个很小的容器环境或者没有图形用户界面的服务器中，你可以先安装 `opencv-python-headless`，这样在安装 mmcv 依赖的过程中会跳过 `opencv-python`
```
#### 在 Windows 上编译 mmcv-full
### 在 Windows 上编译 MMCV
| TODO: 视频教程
在 Windows 上编译 MMCV 比 Linux 复杂，本节将一步步介绍如何在 Windows 上编译 MMCV。
在 Windows 上编译 mmcv-full 比 Linux 复杂，本节将一步步介绍如何在 Windows 上编译 mmcv-full。
#### 依赖项
##### 依赖项
请首先安装以下的依赖项：
请先安装以下的依赖项：
- [Git](https://git-scm.com/download/win)：安装期间，请选择 **add git to Path**
- [Visual Studio Community 2019](https://visualstudio.microsoft.com)：用于编译 C++ 和 CUDA 代码
@ -57,76 +143,57 @@ CC=clang CXX=clang++ CFLAGS='-stdlib=libc++' MMCV_WITH_OPS=1 pip install -e .
- [CUDA 10.2](https://developer.nvidia.com/cuda-10.2-download-archive)：如果只需要 CPU 版本可以不安装 CUDA，安装 CUDA 时，可根据需要进行自定义安装。如果已经安装新版本的显卡驱动，建议取消驱动程序的安装
```{note}
您需要知道如何在 Windows 上设置变量环境，尤其是 "PATH" 的设置，以下安装过程都会用到。
如果不清楚如何安装以上依赖，请参考[Windows 环境从零安装 mmcv-full](https://zhuanlan.zhihu.com/p/434491590)。
另外，你需要知道如何在 Windows 上设置变量环境，尤其是 "PATH" 的设置，以下安装过程都会用到。
```
#### 设置 Python 环境
##### 通用步骤
1. 从 Windows 菜单启动 Anaconda 命令行
```{note}
如 Miniconda 安装程序建议，不要使用原始的 `cmd.exe` 或是 `powershell.exe`。命令行有两个版本，一个基于 PowerShell，一个基于传统的 `cmd.exe`。请注意以下说明都是使用的基于 PowerShell
```
2. 创建一个新的 Conda 环境
```shell
conda create --name mmcv python=3.7 # 经测试，3.6, 3.7, 3.8 也能通过
conda activate mmcv # 确保做任何操作前先激活环境
```powershell
(base) PS C:\Users\xxx> conda create --name mmcv python=3.7
(base) PS C:\Users\xxx> conda activate mmcv # 确保做任何操作前先激活环境
```
3. 安装 PyTorch 时，可以根据需要安装支持 CUDA 或不支持 CUDA 的版本
```shell
```powershell
# CUDA version
conda install pytorch torchvision cudatoolkit=10.2 -c pytorch
(mmcv) PS C:\Users\xxx> conda install pytorch torchvision cudatoolkit=10.2 -c pytorch
# CPU version
conda install pytorch torchvision cpuonly -c pytorch
(mmcv) PS C:\Users\xxx> conda install install pytorch torchvision cpuonly -c pytorch
```
4. 准备 MMCV 源代码
4. 克隆代码仓库
```shell
git clone https://github.com/open-mmlab/mmcv.git
cd mmcv
```powershell
(mmcv) PS C:\Users\xxx> git clone https://github.com/open-mmlab/mmcv.git
(mmcv) PS C:\Users\xxx> cd mmcv
```
5. 安装所需 Python 依赖包
5. 安装 `ninja` 和 `psutil` 以加快编译速度
```shell
pip3 install -r requirements/runtime.txt
```powershell
(mmcv) PS C:\Users\xxx\mmcv> pip install -r requirements/optional.txt
```
6. 建议安装 `ninja` 以加快编译速度
6. 安装 mmcv 依赖
```bash
pip install -r requirements/optional.txt
```powershell
(mmcv) PS C:\Users\xxx\mmcv> pip install -r requirements/runtime.txt
```
#### 编译与安装 MMCV
MMCV 有三种安装的模式：
1. Lite 版本（不包含算子）
这种方式下，没有算子被编译，这种模式的 mmcv 是原生的 python 包
2. Full 版本（只包含 CPU 算子）
编译 CPU 算子，但只有 x86 将会被编译，并且编译版本只能在 CPU only 情况下运行
3. Full 版本（既包含 CPU 算子，又包含 CUDA 算子）
同时编译 CPU 和 CUDA 算子，`ops` 模块的 x86 与 CUDA 的代码都可以被编译。同时编译的版本可以在 CUDA 上调用 GPU
##### 通用步骤
1. 设置 MSVC 编译器
7. 设置 MSVC 编译器
设置环境变量。添加 `C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.27.29110\bin\Hostx86\x64` 到 `PATH`，则 `cl.exe` 可以在命令行中运行，如下所示。
```none
(base) PS C:\Users\xxx> cl
```powershell
(mmcv) PS C:\Users\xxx\mmcv> cl
Microsoft (R) C/C++ Optimizing Compiler Version 19.27.29111 for x64
Copyright (C) Microsoft Corporation. All rights reserved.
@ -137,57 +204,45 @@ MMCV 有三种安装的模式：
因为 PyTorch 将解析 `cl.exe` 的输出以检查其版本，只有 utf-8 将会被识别，你可能需要将系统语言更改为英语。控制面板 -> 地区-> 管理-> 非 Unicode 来进行语言转换。
##### 安装方式一：Lite version（不包含算子）
##### 编译与安装 mmcv-full
在完成上述的公共步骤后，从菜单打开 Anaconda 命令框，输入以下命令
mmcv-full 有两个版本：
```shell
# 激活环境
conda activate mmcv
# 切换到 mmcv 根目录
cd mmcv
# 安装
python setup.py develop
# 检查是否安装成功
pip list
- 只包含 CPU 算子的版本
编译 CPU 算子，但只有 x86 将会被编译，并且编译版本只能在 CPU only 情况下运行
- 既包含 CPU 算子，又包含 CUDA 算子的版本
同时编译 CPU 和 CUDA 算子，`ops` 模块的 x86 与 CUDA 的代码都可以被编译。同时编译的版本可以在 CUDA 上调用 GPU
###### CPU 版本
1. 设置环境变量
```powershell
(mmcv) PS C:\Users\xxx\mmcv> $env:MMCV_WITH_OPS = 1
```
##### 安装方式二：Full version（只编译 CPU 算子）
2. 编译安装
1. 完成上述的公共步骤
2. 设置环境变量
```shell
$env:MMCV_WITH_OPS = 1
$env:MAX_JOBS = 8 # 根据你可用CPU以及内存量进行设置
```powershell
(mmcv) PS C:\Users\xxx\mmcv> python setup.py build_ext # 如果成功, cl 将被启动用于编译算子
(mmcv) PS C:\Users\xxx\mmcv> python setup.py develop # 安装
```
3. 编译安装
###### GPU 版本
```shell
conda activate mmcv # 激活环境
cd mmcv # 改变路径
python setup.py build_ext # 如果成功, cl 将被启动用于编译算子
python setup.py develop # 安装
pip list # 检查是否安装成功
1. 设置环境变量
```powershell
(mmcv) PS C:\Users\xxx\mmcv> $env:MMCV_WITH_OPS = 1
```
##### 安装方式三：Full version（既编译 CPU 算子又编译 CUDA 算子）
2. 检查 `CUDA_PATH` 或者 `CUDA_HOME` 环境变量已经存在在 `envs` 之中
1. 完成上述的公共步骤
2. 设置环境变量
```shell
$env:MMCV_WITH_OPS = 1
$env:MAX_JOBS = 8 # 根据你可用CPU以及内存量进行设置
```
3. 检查 `CUDA_PATH` 或者 `CUDA_HOME` 环境变量已经存在在 `envs` 之中
```none
(base) PS C:\Users\WRH> ls env:
```powershell
(mmcv) PS C:\Users\xxx\mmcv> ls env:
Name Value
---- -----
@ -198,38 +253,91 @@ pip list
如果没有，你可以按照下面的步骤设置
```shell
$env:CUDA_HOME = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2"
```powershell
(mmcv) PS C:\Users\xxx\mmcv> $env:CUDA_HOME = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2"
# 或者
$env:CUDA_HOME = $env:CUDA_PATH_V10_2 # CUDA_PATH_V10_2 已经在环境变量中
(mmcv) PS C:\Users\xxx\mmcv> $env:CUDA_HOME = $env:CUDA_PATH_V10_2 # CUDA_PATH_V10_2 已经在环境变量中
```
4. 设置 CUDA 的目标架构
3. 设置 CUDA 的目标架构
```shell
$env:TORCH_CUDA_ARCH_LIST="6.1" # 支持 GTX 1080
# 或者用所有支持的版本，但可能会变得很慢
$env:TORCH_CUDA_ARCH_LIST="3.5 3.7 5.0 5.2 6.0 6.1 7.0 7.5"
```powershell
# 这里需要改成你的显卡对应的目标架构
(mmcv) PS C:\Users\xxx\mmcv> $env:TORCH_CUDA_ARCH_LIST="7.5"
```
:::{note}
可以点击 [cuda-gpus](https://developer.nvidia.com/cuda-gpus) 查看 GPU 的计算能力，也可以通过 CUDA 目录下的 deviceQuery.exe 工具查看
```powershell
(mmcv) PS C:\Users\xxx\mmcv> &"C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2\extras\demo_suite\deviceQuery.exe"
Device 0: "NVIDIA GeForce GTX 1660 SUPER"
CUDA Driver Version / Runtime Version 11.7 / 11.1
CUDA Capability Major/Minor version number: 7.5
```
上面的 7.5 表示目标架构。注意：需把上面命令的 v10.2 换成你的 CUDA 版本。
:::
4. 编译安装
```powershell
(mmcv) PS C:\Users\xxx\mmcv> python setup.py build_ext # 如果成功, cl 将被启动用于编译算子
(mmcv) PS C:\Users\xxx\mmcv> python setup.py develop # 安装
```
```{note}
我们可以在 [here](https://developer.nvidia.com/cuda-gpus) 查看 GPU 的计算能力
如果你的 PyTorch 版本是 1.6.0，你可能会遇到一些 [issue](https://github.com/pytorch/pytorch/issues/42467) 提到的错误，你可以参考这个 [pull request](https://github.com/pytorch/pytorch/pull/43380/files) 修改本地环境的 PyTorch 源代码
```
5. 编译安装
##### 验证安装
```shell
$env:MMCV_WITH_OPS = 1
$env:MAX_JOBS = 8 # 根据你可用CPU以及内存量进行设置
conda activate mmcv # 激活环境
cd mmcv # 改变路径
python setup.py build_ext # 如果成功, cl 将被启动用于编译算子
python setup.py develop # 安装
pip list # 检查是否安装成功
```powershell
(mmcv) PS C:\Users\xxx\mmcv> python .dev_scripts/check_installation.py
```
```{note}
如果你的 PyTorch 版本是 1.6.0，你可能会遇到一些这个 [issue](https://github.com/pytorch/pytorch/issues/42467) 提到的错误，则可以参考这个 [pull request](https://github.com/pytorch/pytorch/pull/43380/files) 修改 本地环境的 PyTorch 源代码
如果上述命令没有报错，说明安装成功。如有报错，请查看[问题解决页面](../faq.md)是否已经有解决方案。
如果没有找到解决方案，欢迎提 [issue](https://github.com/open-mmlab/mmcv/issues)。
### 编译 mmcv
如果你需要使用和 PyTorch 相关的模块，请确保 PyTorch 已经成功安装在环境中，可以参考 [PyTorch 官方安装文档](https://pytorch.org/get-started/locally/#start-locally)。
1. 克隆代码仓库
```bash
git clone https://github.com/open-mmlab/mmcv.git
cd mmcv
```
如果编译安装 mmcv 的过程中遇到了问题，你也许可以在 [Frequently Asked Question](../faq.html) 找到解决方法
2. 开始编译
```bash
pip install -e . -v
```
3. 验证安装
```bash
python -c 'import mmcv;print(mmcv.__version__)'
```
### 在 IPU 机器编译 mmcv
首先你需要有可用的 IPU 云机器，可以查看[这里](https://www.graphcore.ai/ipus-in-the-cloud)。
#### 选项1: 使用 Docker
1. 拉取镜像
```bash
docker pull graphcore/pytorch
```
2. 编译 mmcv
#### 选项2: 使用 SDK
1. 编译 mmcv
2. 参考 [IPU PyTorch document](https://docs.graphcore.ai/projects/poptorch-user-guide/en/latest/installation.html) 安装 sdk。

480
docs/zh_cn/get_started/installation.md
View File

@ -2,179 +2,369 @@
MMCV 有两个版本：
- **mmcv-full**: 完整版，包含所有的特性以及丰富的开箱即用的 CUDA 算子。注意完整版本可能需要更长时间来编译。
- **mmcv**: 精简版，不包含 CUDA 算子但包含其余所有特性和功能，类似 MMCV 1.0 之前的版本。如果你不需要使用 CUDA 算子的话，精简版可以作为一个考虑选项。
- **mmcv-full**: 完整版，包含所有的特性以及丰富的开箱即用的 CPU 和 CUDA 算子。注意，完整版本可能需要更长时间来编译。
- **mmcv**: 精简版，不包含 CPU 和 CUDA 算子但包含其余所有特性和功能，类似 MMCV 1.0 之前的版本。如果你不需要使用算子的话，精简版可以作为一个考虑选项。
```{warning}
请不要在同一个环境中安装两个版本，否则可能会遇到类似 `ModuleNotFound` 的错误。在安装一个版本之前，需要先卸载另一个。`如果CUDA可用，强烈推荐安装mmcv-full`。
```
a. 安装完整版
在安装 mmcv-full 之前，请确保 PyTorch 已经成功安装在环境中，可以参考 PyTorch 官方[文档](https://pytorch.org/)。
我们提供了 **Linux 和 Windows 平台** PyTorch 和 CUDA 版本组合的 mmcv-full 预编译包，可以大大简化用户安装编译过程。强烈推荐通过预编译包来安装。另外，安装完成后可以运行 [check_installation.py](https://github.com/open-mmlab/mmcv/.dev_scripts/check_installation.py) 脚本检查 mmcv-full 是否安装成功。
i. 安装最新版本
如下是安装最新版 `mmcv-full` 的命令
```shell
pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html
```
请将链接中的 `{cu_version}` 和 `{torch_version}` 根据自身需求替换成实际的版本号，例如想安装和 `CUDA 11.1`、`PyTorch 1.9.0` 兼容的最新版 `mmcv-full`，使用如下替换过的命令
```shell
pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html
```
### 安装 mmcv-full
```{note}
- 下述安装步骤仅适用于 Linux 和 Windows 平台，如需在 macOS 平台安装 mmcv-full，请参考[源码安装 mmcv-full](https://mmcv.readthedocs.io/zh_CN/latest/get_started/build.html#macos-mmcv-full)。
- 如需编译 ONNX Runtime 自定义算子，请参考[如何编译ONNX Runtime自定义算子](https://mmcv.readthedocs.io/zh_CN/latest/deployment/onnxruntime_op.html#id1)
- 如需编译 TensorRT 自定义，请参考[如何编译MMCV中的TensorRT插件](https://mmcv.readthedocs.io/zh_CN/latest/deployment/tensorrt_plugin.html#id3)
```
在安装 mmcv-full 之前，请确保 PyTorch 已经成功安装在环境中，可以参考 [PyTorch 官方安装文档](https://pytorch.org/get-started/locally/#start-locally)。可使用以下命令验证
```bash
python -c 'import torch;print(torch.__version__)'
```
如果输出版本信息，则表示 PyTorch 已安装。
#### 使用 mim 安装（推荐）
[mim](https://github.com/open-mmlab/mim) 是 OpenMMLab 项目的包管理工具，使用它可以很方便地安装 mmcv-full。
```bash
pip install -U openmim
mim install mmcv-full
```
如果发现上述的安装命令没有使用预编译包（以 `.whl` 结尾）而是使用源码包（以 `.tar.gz` 结尾）安装，则有可能是我们没有提供和当前环境的 PyTorch 版本、CUDA 版本相匹配的 mmcv-full 预编译包，此时，你可以[源码安装 mmcv-full](build.md)。
<details>
<summary>使用预编译包的安装日志</summary>
Looking in links: https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html<br />
Collecting mmcv-full<br />
<b>Downloading https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/mmcv_full-1.6.1-cp38-cp38-manylinux1_x86_64.whl</b>
</details>
<details>
<summary>使用源码包的安装日志</summary>
Looking in links: https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html<br />
Collecting mmcv-full==1.6.0<br />
<b>Downloading mmcv-full-1.6.0.tar.gz</b>
</details>
如需安装指定版本的 mmcv-full，例如安装 1.6.0 版本的 mmcv-full，可使用以下命令
```bash
mim install mmcv-full==1.6.0
```
:::{note}
如果你打算使用 `opencv-python-headless` 而不是 `opencv-python`，例如在一个很小的容器环境或者没有图形用户界面的服务器中，你可以先安装 `opencv-python-headless`，这样在安装 mmcv 依赖的过程中会跳过 `opencv-python`。
另外，如果安装依赖库的时间过长，可以指定 pypi 源
```bash
mim install mmcv-full -i https://pypi.tuna.tsinghua.edu.cn/simple
```
:::
安装完成后可以运行 [check_installation.py](https://github.com/open-mmlab/mmcv/.dev_scripts/check_installation.py) 脚本检查 mmcv-full 是否安装成功。
#### 使用 pip 安装
使用以下命令查看 CUDA 和 PyTorch 的版本
```bash
python -c 'import torch;print(torch.__version__);print(torch.version.cuda)'
```
根据系统的类型、CUDA 版本、PyTorch 版本以及 MMCV 版本选择相应的安装命令
<html>
<body>
<style>
select {
z-index: 1000;
position: absolute;
top: 10px;
width: 6.7rem;
}
#select-container {
position: relative;
height: 30px;
}
#select-cmd {
background-color: #f5f6f7;
font-size: 14px;
margin-top: 20px;
}
/* 让每一个都间隔1.3rem */
#select-os {
/* left: 1.375rem; */
left: 0;
}
#select-cuda {
/* left: 9.375rem; 9.375 = 1.375 + 6.7 + 1.3 */
left: 8rem;
}
#select-torch {
/* left: 17.375rem; 17.375 = 9.375 + 6.7 + 1.3 */
left: 16rem;
}
#select-mmcv {
/* left: 25.375rem; 25.375 = 17.375 + 6.7 + 1.3 */
left: 24rem;
}
</style>
<div id="select-container">
<select
onmousedown="handleSelectMouseDown(this.id)"
onblur="handleSelectBlur(this.id)"
onchange="changeOS(this.value)"
id="select-os">
</select>
<select
onmousedown="handleSelectMouseDown(this.id)"
onblur="handleSelectBlur(this.id)"
onchange="changeCUDA(this.value)"
id="select-cuda">
</select>
<select
onmousedown="handleSelectMouseDown(this.id)"
onblur="handleSelectBlur(this.id)"
onchange="changeTorch(this.value)"
id="select-torch">
</select>
<select
onmousedown="handleSelectMouseDown(this.id)"
onblur="handleSelectBlur(this.id)"
onchange="changeMMCV(this.value)"
id="select-mmcv">
</select>
</div>
<pre id="select-cmd"></pre>
</body>
<script>
// 各个select当前的值
let osVal, cudaVal, torchVal, mmcvVal;
function changeMMCV(val) {
mmcvVal = val;
change("select-mmcv");
}
function changeTorch(val) {
torchVal = val;
change("select-torch");
}
function changeCUDA(val) {
cudaVal = val;
change("select-cuda");
}
function changeOS(val) {
osVal = val;
change("select-os");
}
// 控制size大小相关的几个方法
function handleSelectMouseDown(id) {
const dom = document.getElementById(id);
if (!dom) return;
const len = dom?.options?.length;
if (len >= 9) {
dom.size = 10;
dom.style.zIndex = 100;
}
}
function handleSelectClick() {
const selects = Array.from(document.getElementsByTagName("select"));
selects.forEach(select => {
select.size = 1;
});
}
function handleSelectBlur(id) {
const dom = document.getElementById(id);
if (!dom) {
// 如果没有指定特定的id，那就直接把所有的select都设置成size = 1
handleSelectClick();
return;
}
dom.size = 1;
dom.style.zIndex = 1;
}
function changeCmd() {
const cmd = document.getElementById("select-cmd");
let cmdString = "pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html";
// e.g: pip install mmcv-full==1.6.0 -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9/index.html
const cudaVersion = `${cudaVal === "cpu" ? cudaVal : `cu${cudaVal.split(".").join("")}`}`;
const torchVersion = `torch${torchVal.substring(0, torchVal.length - 2)}`;
cmdString = cmdString.replace("{cu_version}", cudaVersion).replace("{mmcv_version}", mmcvVal).replace("{torch_version}", torchVersion);
cmd.textContent = cmdString;
}
// string数组去重
function unique(arr) {
if (!arr || !Array.isArray(arr)) return [];
return [...new Set(arr)];
}
// 根据string数组生成option的DocumentFragment
function genOptionFragment(data, id) {
const name = id.includes("-")? id.split("-")[1] : id;
const fragment = new DocumentFragment();
data.forEach(option => {
const ele = document.createElement("option");
let text = `${name} ${option}`;
if (name === "os" || option.toUpperCase() === "CPU") {
text = `${option}`;
}
ele.textContent = text;
// 添加value属性，方便下拉框选择时直接读到数据
ele.value = option;
// 添加点击事件监听
ele.addEventListener('click', handleSelectClick);
fragment.appendChild(ele);
});
return fragment;
}
// 在dom树中找到id对应的dom（select元素），并将生成的options添加到元素内
function findAndAppend(data, id) {
const fragment = genOptionFragment(data, id);
const dom = document.getElementById(id);
if (dom) dom.replaceChildren(fragment);
}
/**
* change方法的重点在于
* 1. 各个下拉框数据的联动
* OS ==> cuda ==> torch ==> mmcv
* 2. 命令行的修改
*/
function change(id) {
const order = ["select-mmcv", "select-torch", "select-cuda", "select-os"];
const idx = order.indexOf(id);
if (idx === -1) return;
const versionDetail = version[osVal];
if (idx >= 3) {
// 根据os修改cuda
let cuda = [];
versionDetail.forEach(v => {
cuda.push(v.cuda);
});
cuda = unique(cuda);
cudaVal = cuda[0];
findAndAppend(cuda, "select-cuda");
}
if (idx >= 2) {
// 根据cuda修改torch
const torch = [];
versionDetail.forEach(v => {
if (v.cuda === cudaVal) torch.push(v.torch);
});
torchVal = torch[0];
findAndAppend(torch, "select-torch");
}
if (idx >= 1) {
// 根据torch修改mmcv
let mmcv = [];
versionDetail.forEach(v => {
if (v.cuda === cudaVal && v.torch === torchVal) mmcv = v.mmcv;
});
mmcvVal = mmcv[0];
findAndAppend(mmcv, "select-mmcv");
}
changeCmd();
}
// 初始化，处理version数据，并调用findAndAppend
function init() {
// 增加一个全局的click事件监听，作为select onBlur事件失效的兜底
document.addEventListener("click", handleSelectBlur);
const version = window.version;
// OS
const os = Object.keys(version);
osVal = os[0];
findAndAppend(os, "select-os");
change("select-os");
changeCmd();
}
// 利用xhr获取本地version数据，如果作为html直接浏览的话需要使用本地服务器打开，否则会有跨域问题
window.onload = function () {
const url = "../_static/version.json"
// 申明一个XMLHttpRequest
const request = new XMLHttpRequest();
// 设置请求方法与路径
request.open("get", url);
// 不发送数据到服务器
request.send(null);
//XHR对象获取到返回信息后执行
request.onload = function () {
// 返回状态为200，即为数据获取成功
if (request.status !== 200) return;
const data = JSON.parse(request.responseText);
window.version = data;
init();
}
}
</script>
</html>
如果在上面的下拉框中没有找到对应的版本，则可能是没有对应 PyTorch 或者 CUDA 或者 mmcv-full 版本的预编译包，此时，你可以[源码安装 mmcv-full](../faq.md)。
:::{note}
PyTorch 在 1.x.0 和 1.x.1 之间通常是兼容的，故 mmcv-full 只提供 1.x.0 的编译包。如果你
的 PyTorch 版本是 1.x.1，你可以放心地安装在 1.x.0 版本编译的 mmcv-full。例如，如果你的
PyTorch 版本是 1.8.1、CUDA 版本是 11.1，你可以使用以下命令安装 mmcv-full。
PyTorch 版本是 1.8.1，你可以放心选择 1.8.x。
:::
`pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.8.0/index.html`
:::{note}
如果你打算使用 `opencv-python-headless` 而不是 `opencv-python`，例如在一个很小的容器环境或者没有图形用户界面的服务器中，你可以先安装 `opencv-python-headless`，这样在安装 mmcv 依赖的过程中会跳过 `opencv-python`。
另外，如果安装依赖库的时间过长，可以指定 pypi 源
```bash
pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html -i https://pypi.tuna.tsinghua.edu.cn/simple
```
如果想知道更多 CUDA 和 PyTorch 版本的命令，可以参考下面的表格，将链接中的 `=={mmcv_version}` 删去即可。
:::
ii. 安装特定的版本
安装完成后可以运行 [check_installation.py](https://github.com/open-mmlab/mmcv/.dev_scripts/check_installation.py) 脚本检查 mmcv-full 是否安装成功。
如下是安装特定版本 `mmcv-full` 的命令
#### 使用 docker 镜像
```shell
pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html
先将算法库克隆到本地再构建镜像
```bash
git clone https://github.com/open-mmlab/mmcv.git && cd mmcv
docker build -t mmcv -f docker/release/Dockerfile .
```
首先请参考版本发布信息找到想要安装的版本号，将 `{mmcv_version}` 替换成该版本号，例如 `1.3.9`。
然后将链接中的 `{cu_version}` 和 `{torch_version}` 根据自身需求替换成实际的版本号，例如想安装和 `CUDA 11.1`、`PyTorch 1.9.0` 兼容的 `mmcv-full` 1.3.9 版本，使用如下替换过的命令
也可以直接使用下面的命令构建镜像
```shell
pip install mmcv-full==1.3.9 -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html
```bash
docker build -t mmcv https://github.com/open-mmlab/mmcv.git#master:docker/release
```
对于更多的 PyTorch 和 CUDA 版本组合，请参考下表：
[Dockerfile](release/Dockerfile) 默认安装最新的 mmcv-full，如果你想要指定版本，可以使用下面的命令
<table class="docutils">
<tbody>
<tr>
<th width="80"> CUDA </th>
<th valign="bottom" align="left" width="120">torch 1.11</th>
<th valign="bottom" align="left" width="120">torch 1.10</th>
<th valign="bottom" align="left" width="120">torch 1.9</th>
<th valign="bottom" align="left" width="120">torch 1.8</th>
<th valign="bottom" align="left" width="120">torch 1.7</th>
<th valign="bottom" align="left" width="120">torch 1.6</th>
<th valign="bottom" align="left" width="120">torch 1.5</th>
</tr>
<tr>
<td align="left">11.5</td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu115/torch1.11.0/index.html</code></pre> </details> </td>
<td align="left"> </td>
<td align="left"></td>
<td align="left"></code></pre> </details> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
</tr>
<tr>
<td align="left">11.3</td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.11.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10.0/index.html</code></pre> </details> </td>
<td align="left"></td>
<td align="left"></code></pre> </details> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
</tr>
<tr>
<td align="left">11.1</td>
<td align="left"> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.10.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.8.0/index.html</code></pre> </details> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
</tr>
<tr>
<td align="left">11.0</td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu110/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"> </td>
<td align="left"> </td>
</tr>
<tr>
<td align="left">10.2</td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.11.0/index.html</code></pre> </details></td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.10.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.9.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.6.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.5.0/index.html</code></pre> </details> </td>
</tr>
<tr>
<td align="left">10.1</td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.8.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.6.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.5.0/index.html</code></pre> </details> </td>
</tr>
<tr>
<td align="left">9.2</td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.6.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.5.0/index.html</code></pre> </details> </td>
</tr>
<tr>
<td align="left">cpu</td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.11.0/index.html</code></pre> </details></td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.10.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.9.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.8.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.7.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.6.0/index.html</code></pre> </details> </td>
<td align="left"><details><summary> 安装 </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.5.0/index.html</code></pre> </details> </td>
</tr>
</tbody>
</table>
```{note}
以上提供的预编译包并不囊括所有的 mmcv-full 版本，我们可以点击对应链接查看支持的版本。例如，点击 [cu102-torch1.8.0](https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html)，可以看到 `cu102-torch1.8.0` 只提供了 1.3.0 及以上的 mmcv-full 版本。另外，从 `mmcv v1.3.17` 开始，我们不再提供`PyTorch 1.3 & 1.4` 对应的 mmcv-full 预编译包。你可以在 [这](./previous_versions.md) 找到 `PyTorch 1.3 & 1.4` 对应的预编包。虽然我们不再提供 `PyTorch 1.3 & 1.4` 对应的预编译包，但是我们依然在 CI 中保证对它们的兼容持续到下一年。
```bash
docker image build -t mmcv -f docker/release/Dockerfile --build-arg MMCV=1.5.0 .
```
```{note}
mmcv-full 没有提供 Windows 平台 `cu102-torch1.8.0` 和 `cu92-torch*` 的预编译包。
如果你想要使用其他版本的 PyTorch 和 CUDA，你可以在构建镜像时指定它们的版本。
例如指定 PyTorch 的版本是 1.11，CUDA 的版本是 11.3
```bash
docker build -t mmcv -f docker/release/Dockerfile \
--build-arg PYTORCH=1.11.0 \
--build-arg CUDA=11.3 \
--build-arg CUDNN=8 \
--build-arg MMCV=1.5.0 .
```
除了使用预编译包之外，另一种方式是在本地进行编译，直接运行下述命令
更多 PyTorch 和 CUDA 镜像可以点击 [dockerhub/pytorch](https://hub.docker.com/r/pytorch/pytorch/tags) 查看。
```python
pip install mmcv-full
```
### 安装 mmcv
但注意本地编译可能会耗时 10 分钟以上。
b. 安装精简版
如果你需要使用和 PyTorch 相关的模块，请确保 PyTorch 已经成功安装在环境中，可以参考 [PyTorch 官方安装文档](https://pytorch.org/get-started/locally/#start-locally)。
```python
pip install mmcv
```
c. 安装完整版并且编译 onnxruntime 的自定义算子
- 详细的指南请查看 [这里](https://mmcv.readthedocs.io/zh_CN/latest/deployment/onnxruntime_custom_ops.html)。
如果想从源码编译 MMCV，请参考[该文档](https://mmcv.readthedocs.io/zh_CN/latest/get_started/build.html)。

18
docs/zh_cn/get_started/introduction.md
View File

@ -21,15 +21,15 @@ MMCV 是一个面向计算机视觉的基础库，它支持了很多开源项目
- [MMGeneration](https://github.com/open-mmlab/mmgeneration): OpenMMLab 图片视频生成模型工具箱
- [MMDeploy](https://github.com/open-mmlab/mmdeploy): OpenMMLab 模型部署框架
MMCV 提供了如下众多功能：
MMCV 提供了以下功能：
- 通用的 IO 接口
- 图像和视频处理
- 图像和标注结果可视化
- 常用小工具（进度条，计时器等）
- 基于 PyTorch 的通用训练框架
- 多种 CNN 网络结构
- 高质量实现的常见 CUDA 算子
- [通用的 IO 接口](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/io.html)
- [图像和视频处理](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/data_process.html)
- [图像和标注结果可视化](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/visualization.html)
- [常用小工具（进度条，计时器等）](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/utils.html)
- [基于 PyTorch 的通用训练框架](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/runner.html)
- [多种 CNN 网络结构](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/cnn.html)
- [高质量实现的 CPU 和 CUDA 算子](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/ops.html)
MMCV 支持以下的系统：
@ -37,7 +37,7 @@ MMCV 支持以下的系统：
- Windows
- macOS
如想了解更多特性和使用，请参考[文档](https://mmcv.readthedocs.io/zh_CN/latest)。
欢迎查看[文档](http://mmcv.readthedocs.io/zh_CN/latest)了解更多特性和用法。
```{note}
MMCV 需要 Python 3.6 以上版本。

1
requirements/optional.txt
View File

@ -1 +1,2 @@
ninja
psutil