The OpenMMLab team released a new generation of training engine [MMEngine](https://github.com/open-mmlab/mmengine) at the World Artificial Intelligence Conference on September 1, 2022. It is a foundational library for training deep learning models. Compared with MMCV, it provides a universal and powerful runner, an open architecture with a more unified interface, and a more customizable training process.
MMCV v2.0.0 official version was released on April 6, 2023. In version 2.x, it removed components related to the training process and added a data transformation module. Also, starting from 2.x, it renamed the package names **mmcv** to **mmcv-lite** and **mmcv-full** to **mmcv**. For details, see [Compatibility Documentation](docs/en/compatibility.md).
MMCV will maintain both [1.x](https://github.com/open-mmlab/mmcv/tree/1.x)(corresponding to the original [master](https://github.com/open-mmlab/mmcv/tree/master) branch) and **2.x** (corresponding to the **main** branch, now the default branch) versions simultaneously. For details, see [Branch Maintenance Plan](README.md#branch-maintenance-plan).
## Introduction
MMCV is a foundational library for computer vision research and it provides the following functionalities:
-[High-quality implementation of common CPU and CUDA ops](https://mmcv.readthedocs.io/en/latest/understand_mmcv/ops.html)
It supports the following systems:
...
...
@@ -47,7 +63,7 @@ It supports the following systems:
- Windows
- macOS
See the [documentation](http://mmcv.readthedocs.io/en/2.x) for more features and usage.
See the [documentation](http://mmcv.readthedocs.io/en/latest) for more features and usage.
Note: MMCV requires Python 3.7+.
...
...
@@ -68,23 +84,23 @@ The command to install mmcv:
```bash
pip install-U openmim
mim install"mmcv>=2.0.0rc1"
mim install mmcv
```
If you need to specify the version of mmcv, you can use the following command:
```bash
mim install mmcv==2.0.0rc3
mim install mmcv==2.0.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 version, in which case you can [build mmcv from source](https://mmcv.readthedocs.io/en/2.x/get_started/build.html).
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 version, in which case you can [build mmcv 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/>
<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==2.0.0rc3<br/>
<b>Downloading mmcv-2.0.0rc3.tar.gz</b>
Collecting mmcv==2.0.0<br/>
<b>Downloading mmcv-2.0.0.tar.gz</b>
</details>
For more installation methods, please refer to the [Installation documentation](https://mmcv.readthedocs.io/en/2.x/get_started/installation.html).
For more installation methods, please refer to the [Installation documentation](https://mmcv.readthedocs.io/en/latest/get_started/installation.html).
### Install mmcv-lite
...
...
@@ -105,15 +121,15 @@ If you need to use PyTorch-related modules, make sure PyTorch has been successfu
```bash
pip install-U openmim
mim install"mmcv-lite>=2.0.0rc1"
mim install mmcv-lite
```
## 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/2.x/faq.html).
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/en/2.x/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).
If you face installation problems or runtime issues, you may first refer to this [Frequently Asked Questions](https://mmcv.readthedocs.io/en/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
...
...
@@ -136,6 +152,16 @@ We appreciate all contributions to improve MMCV. Please refer to [CONTRIBUTING.m
MMCV is released under the Apache 2.0 license, while some specific operations in this library are with other licenses. Please refer to [LICENSES.md](LICENSES.md) for the careful check, if you are using our code for commercial matters.
## Branch Maintenance Plan
MMCV currently has four branches, namely main, 1.x, master, and 2.x, where 2.x is an alias for the main branch, and master is an alias for the 1.x branch. The 2.x and master branches will be deleted in the future. MMCV's branches go through the following three stages:
| RC Period | 2022.9.1 - 2023.4.5 | Release candidate code (2.x version) will be released on 2.x branch. Default master branch is still 1.x version | Master and 2.x branches iterate normally |
| Compatibility Period | 2023.4.6 - 2023.12.31 | **The 2.x branch has been renamed to the main branch and set as the default branch**, and 1.x branch will correspond to 1.x version | We still maintain the old version 1.x, respond to user needs, but try not to introduce changes that break compatibility; main branch iterates normally |
| Maintenance Period | From 2024/1/1 | Default main branch corresponds to 2.x version and 1.x branch is 1.x version | 1.x branch is in maintenance phase, no more new feature support; main branch is iterating normally |
## Projects in OpenMMLab
-[MMEngine](https://github.com/open-mmlab/mmengine): OpenMMLab foundational library for training deep learning models.
After configuring the pre-commit, we should create a branch based on the master branch to develop the new feature or fix the bug. The proposed branch name is `username/pr_name`
After configuring the pre-commit, we should create a branch based on the main branch to develop the new feature or fix the bug. The proposed branch name is `username/pr_name`
```shell
git checkout -b yhc/refactor_contributing_doc
```
In subsequent development, if the master branch of the local repository is behind the master branch of "upstream", we need to pull the upstream for synchronization, and then execute the above command:
In subsequent development, if the main branch of the local repository is behind the main branch of "upstream", we need to pull the upstream for synchronization, and then execute the above command:
```shell
git pull upstream master
git pull upstream main
```
#### 4. Commit the code and pass the unit test
...
...
@@ -168,18 +168,18 @@ MMCV will run unit test for the posted Pull Request on different platforms (Linu
#### 7. Resolve conflicts
If your local branch conflicts with the latest master branch of "upstream", you'll need to resolove them. There are two ways to do this:
If your local branch conflicts with the latest main branch of "upstream", you'll need to resolove them. There are two ways to do this:
```shell
git fetch --all--prune
git rebase upstream/master
git rebase upstream/main
```
or
```shell
git fetch --all--prune
git merge upstream/master
git merge upstream/main
```
If you are very good at handling conflicts, then you can use rebase to resolve conflicts, as this will keep your commit logs tidy. If you are not familiar with `rebase`, then you can use `merge` to resolve conflicts.
...
...
@@ -188,7 +188,7 @@ If you are very good at handling conflicts, then you can use rebase to resolve c
#### Unit test
If you cannot run the unit test of some modules for lacking of some dependencies, such as [video](https://github.com/open-mmlab/mmcv/tree/master/mmcv/video) module, you can try to install the following dependencies:
If you cannot run the unit test of some modules for lacking of some dependencies, such as [video](https://github.com/open-mmlab/mmcv/tree/main/mmcv/video) module, you can try to install the following dependencies:
The OpenMMLab team released a new generation of training engine [MMEngine](https://github.com/open-mmlab/mmengine) at the World Artificial Intelligence Conference on September 1, 2022. It is a foundational library for training deep learning models. Compared with MMCV, it provides a universal and powerful runner, an open architecture with a more unified interface, and a more customizable training process.
The OpenMMLab team released MMCV v2.0.0 on April 6, 2023. In the 2.x version, it has the following significant changes:
(1) It removed the following components:
-`mmcv.fileio` module, removed in PR [#2179](https://github.com/open-mmlab/mmcv/pull/2179). FileIO module from mmengine will be used wherever required.
-`mmcv.runner`, `mmcv.parallel`, `mmcv. engine` and `mmcv.device`, removed in PR [#2216](https://github.com/open-mmlab/mmcv/pull/2216).
- All classes in `mmcv.utils` (eg `Config` and `Registry`) and many functions, removed in PR [#2217](https://github.com/open-mmlab/mmcv/pull/2217). Only a few functions related to mmcv are reserved.
-`mmcv.onnx`, `mmcv.tensorrt` modules and related functions, removed in PR [#2225](https://github.com/open-mmlab/mmcv/pull/2225).
- Removed all root registrars in MMCV and registered classes or functions to the [root registrar](https://github.com/open-mmlab/mmengine/blob/main/mmengine/registry/root.py) in MMEngine.
(2) It added the [`mmcv.transforms`](https://github.com/open-mmlab/mmcv/tree/main/mmcv/transforms) data transformation module.
(3) It renamed the package name **mmcv** to **mmcv-lite** and **mmcv-full** to **mmcv** in PR [#2235](https://github.com/open-mmlab/mmcv/pull/2235). Also, change the default value of the environment variable `MMCV_WITH_OPS` from 0 to 1.
<tableclass="docutils">
<thead>
<tr>
<thalign="center">MMCV <2.0</th>
<thalign="center">MMCV >= 2.0 </th>
<tbody>
<tr>
<tdvalign="top">
```bash
# Contains ops, because the highest version of mmcv-full is less than 2.0.0, so there is no need to add version restrictions
pip install openmim
mim install mmcv-full
# do not contain ops
pip install openmim
mim install"mmcv < 2.0.0"
```
</td>
<tdvalign="top">
```bash
# Contains ops
pip install openmim
mim install mmcv
# Ops are not included, because the starting version of mmcv-lite is 2.0.0rc1, so there is no need to add version restrictions
pip install openmim
mim install mmcv-lite
```
</td>
</tr>
</thead>
</table>
### v1.3.18
Some ops have different implementations on different devices. Lots of macros and type checks are scattered in several files, which makes the code hard to maintain. For example:
@@ -473,7 +473,7 @@ Read [PSANet: Point-wise Spatial Attention Network for Scene Parsing](https://hs
Filter out boxes has high IoU overlap with previously selected boxes or low score. Output the indices of valid boxes.
Note this definition is slightly different with [onnx: NonMaxSuppression](https://github.com/onnx/onnx/blob/master/docs/Operators.md#nonmaxsuppression)
Note this definition is slightly different with [onnx: NonMaxSuppression](https://github.com/onnx/onnx/blob/main/docs/Operators.md#nonmaxsuppression)
@@ -290,3 +290,60 @@ If you need to use PyTorch-related modules, make sure PyTorch has been successfu
```bash
python -c'import mmcv;print(mmcv.__version__)'
```
### Build mmcv-full on Cambricon MLU Devices
#### Install torch_mlu
##### Option1: Install mmcv-full based on Cambricon docker image
Firstly, install and pull Cambricon docker image (please email service@cambricon.com for the latest release docker):
```bash
docker pull ${docker image}
```
Run and attach to the docker, [Install mmcv-full on MLU device](#install-mmcv\-full-on-cambricon-mlu-device) and [make sure you've installed mmcv-full on MLU device successfully](#test-code)
##### Option2: Install mmcv-full from compiling Cambricon PyTorch source code
Please email service@cambricon.com or contact with Cambricon engineers for a suitable version of CATCH package. After you get the suitable version of CATCH package, please follow the steps in ${CATCH-path}/CONTRIBUTING.md to install Cambricon PyTorch.
#### Install mmcv-full on Cambricon MLU device
Clone the repo
```bash
git clone https://github.com/open-mmlab/mmcv.git
```
The mlu-ops library will be downloaded to the default directory (mmcv/mlu-ops) while building MMCV. You can also set `MMCV_MLU_OPS_PATH` to an existing mlu-ops library before building as follows:
```bash
export MMCV_MLU_OPS_PATH=/xxx/xxx/mlu-ops
```
Install mmcv-full
```bash
cd mmcv
export MMCV_WITH_OPS=1
export FORCE_MLU=1
python setup.py install
```
#### Test Code
After finishing previous steps, you can run the following python code to make sure that you've installed mmcv-full on MLU device successfully
@@ -25,7 +25,7 @@ If version information is output, then PyTorch is installed.
```bash
pip install-U openmim
mim install"mmcv>=2.0.0rc1"
mim install mmcv
```
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 version, in which case you can [build mmcv from source](build.md).
...
...
@@ -35,7 +35,7 @@ If you find that the above installation command does not use a pre-built package
Looking in links: https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html<br/>
You can run [check_installation.py](https://github.com/open-mmlab/mmcv/blob/2.x/.dev_scripts/check_installation.py) to check the installation of mmcv-full after running the installation commands.
You can run [check_installation.py](https://github.com/open-mmlab/mmcv/blob/main/.dev_scripts/check_installation.py) to check the installation of mmcv-full after running the installation commands.
#### Install with pip
...
...
@@ -297,12 +297,12 @@ you can first install it before installing MMCV to skip the installation of `ope
Alternatively, if it takes too long to install a dependency library, you can specify the pypi source
You can run [check_installation.py](https://github.com/open-mmlab/mmcv/blob/2.x/.dev_scripts/check_installation.py) to check the installation of mmcv after running the installation commands.
You can run [check_installation.py](https://github.com/open-mmlab/mmcv/blob/main/.dev_scripts/check_installation.py) to check the installation of mmcv after running the installation commands.
The [Dockerfile](release/Dockerfile) installs latest released version of mmcv-full by default, but you can specify mmcv versions to install expected versions.
The default links of the pre-trained models hosted on OpenMMLab AWS could be found [here](https://github.com/open-mmlab/mmcv/blob/master/mmcv/model_zoo/open_mmlab.json).
You may override default links by putting `open-mmlab.json` under `MMCV_HOME`. If `MMCV_HOME` is not found in your environment, `~/.cache/mmcv` will be used by default. You may use your own path with `export MMCV_HOME=/your/path`.
The external json files will be merged into default one. If the same key presents in both external json and default json, the external one will be used.
#### Load Checkpoint
The following types are supported for `filename` of `mmcv.load_checkpoint()`.
- filepath: The filepath of the checkpoint.
-`http://xxx` and `https://xxx`: The link to download the checkpoint. The `SHA256` postfix should be contained in the filename.
-`torchvision://xxx`: The model links in `torchvision.models`. Please refer to [torchvision](https://pytorch.org/docs/stable/torchvision/models.html) for details.
-`open-mmlab://xxx`: The model links or filepath provided in default and additional json files.
