Skip to content

Commit

Permalink
[Doc] review installation.md (open-mmlab#1642)
Browse files Browse the repository at this point in the history 
* minor modifications to installation.md

* refine installation and faq

* add zh_cn/installation.md

Co-authored-by: liqikai <tiger19971215@sjtu.edu.cn>
  • Loading branch information
@ly015 @liqikai9
ly015 and liqikai9 committed Sep 8, 2022
1 parent bc63ee3 commit 19d456d
Show file tree
Hide file tree
Showing 4 changed files with 243 additions and 313 deletions.
35 changes: 16 additions & 19 deletions docs/en/installation.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,4 @@
# Installation

- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [MMPose Installation](#mmpose-installation)
- [Best Practices](#best-practices)
- [Verify the installation](#verify-the-installation)
- [Customize Installation](#customize-installation)
Expand All @@ -19,9 +16,9 @@

In this section we demonstrate how to prepare an environment with PyTorch.

MMPose works on Linux, Windows and macOS. It requires Python 3.6+, CUDA 9.2+ and PyTorch 1.5+.
MMPose works on Linux, Windows and macOS. It requires Python 3.6+, CUDA 9.2+ and PyTorch 1.6+.

If you are experienced with PyTorch and have already installed it, just skip this part and jump to the [next section](#installation). Otherwise, you can follow these steps for the preparation.
If you are experienced with PyTorch and have already installed it, you can skip this part and jump to the [MMPose Installation](#installation). Otherwise, you can follow these steps for the preparation.

**Step 0.** Download and install Miniconda from the [official website](https://docs.conda.io/en/latest/miniconda.html).

Expand Down Expand Up @@ -50,13 +47,13 @@ On CPU platforms:
conda install pytorch torchvision cpuonly -c pytorch
```

## Install MMPose
# MMPose Installation

We recommend that users follow our best practices to install MMPose. However, the whole process is highly customizable. See [Customize Installation](#customize-installation) section for more information.

### Best Practices

**Step 0.** Install [MMEngine](https://github.com/open-mmlab/mmengine) and [MMCV](https://github.com/open-mmlab/mmcv) using [MIM](https://github.com/open-mmlab/mim).
**Step 0.** Install [MMEngine](https://github.com/open-mmlab/mmengine) and [MMCV](https://github.com/open-mmlab/mmcv/tree/2.x) using [MIM](https://github.com/open-mmlab/mim).

```shell
pip install -U openmim
Expand All @@ -66,11 +63,11 @@ mim install "mmcv>=2.0.0rc1"

**Step 1.** Install MMPose.

Case a: If you develop and run mmpose directly, install it from source:
Case A: To develop and run mmpose directly, install it from source:

```shell
git clone https://github.com/open-mmlab/mmpose.git -b dev-1.x
# "-b dev-1.x" means checkout to the `dev-1.x` branch.
git clone https://github.com/open-mmlab/mmpose.git -b 1.x
# "-b 1.x" means checkout to the `1.x` branch.
cd mmpose
pip install -r requirements.txt
pip install -v -e .
Expand All @@ -79,7 +76,7 @@ pip install -v -e .
# thus any local modifications made to the code will take effect without reinstallation.
```

Case b: If you use mmpose as a dependency or third-party package, install it with pip:
Case B: To use mmpose as a dependency or third-party package, install it with pip:

```shell
mim install "mmpose>=1.0.0b0"
Expand Down Expand Up @@ -116,17 +113,17 @@ pip install mmengine

MMCV contains C++ and CUDA extensions, thus depending on PyTorch in a complex way. MIM solves such dependencies automatically and makes the installation easier. However, it is not a must.

To install MMCV with pip instead of MIM, please follow [MMCV installation guides](https://mmcv.readthedocs.io/en/latest/get_started/installation.html). This requires manually specifying a find-url based on PyTorch version and its CUDA version.
To install MMCV with pip instead of MIM, please follow [MMCV installation guides](https://mmcv.readthedocs.io/en/2.x/get_started/installation.html). This requires manually specifying a find-url based on PyTorch version and its CUDA version.

For example, the following command install mmcv-full built for PyTorch 1.10.x and CUDA 11.3.
For example, the following command install mmcv built for PyTorch 1.10.x and CUDA 11.3.

```shell
pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html
pip install 'mmcv>=2.0.0rc1' -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html
```

#### Install on CPU-only platforms

MMPose can be built for CPU only environment. In CPU mode you can train (requires MMCV version >= 1.4.4), test or inference a model.
MMPose can be built for CPU only environment. In CPU mode you can train, test or inference a model.

However, some functionalities are missing in this mode, usually GPU-compiled ops like `Deformable Convolution`. Most models in MMPose don't depend on these ops, but if you try to train/test/infer a model containing these ops, an error will be raised.

Expand All @@ -135,7 +132,7 @@ However, some functionalities are missing in this mode, usually GPU-compiled ops
[Google Colab](https://colab.research.google.com/) usually has PyTorch installed,
thus we only need to install MMEngine, MMCV and MMPose with the following commands.

**Step 1.** Install [MMEngine](https://github.com/open-mmlab/mmengine) and [MMCV](https://github.com/open-mmlab/mmcv) using [MIM](https://github.com/open-mmlab/mim).
**Step 1.** Install [MMEngine](https://github.com/open-mmlab/mmengine) and [MMCV](https://github.com/open-mmlab/mmcv/tree/2.x) using [MIM](https://github.com/open-mmlab/mim).

```shell
!pip3 install openmim
Expand All @@ -146,7 +143,7 @@ thus we only need to install MMEngine, MMCV and MMPose with the following comman
**Step 2.** Install MMPose from the source.

```shell
!git clone https://github.com/open-mmlab/mmpose.git -b dev-1.x
!git clone https://github.com/open-mmlab/mmpose.git -b 1.x
%cd mmpose
!pip install -e .
```
Expand All @@ -156,7 +153,7 @@ thus we only need to install MMEngine, MMCV and MMPose with the following comman
```python
import mmpose
print(mmpose.__version__)
# Example output: 1.0.0
# Example output: 1.0.0b0
```

```{note}
Expand Down
35 changes: 22 additions & 13 deletions docs/en/notes/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ Compatible MMPose and MMCV versions are shown as below. Please choose the correc

### MMPose 1.x

| MMPose version | MMCV version |
| :------------: | :-------------------------------: |
| dev-1.x | mmcv-full>=2.0.0, mmengine>=0.0.1 |
| MMPose version | MMCV version |
| :------------: | :-----------------------------: |
| 1.0.0b0 | mmcv>=2.0.0rc1, mmengine>=0.0.1 |

### MMPose 0.x

Expand Down Expand Up @@ -69,7 +69,7 @@ Compatible MMPose and MMCV versions are shown as below. Please choose the correc
- **"No module named 'mmcv.ops'"; "No module named 'mmcv.\_ext'"**

1. Uninstall existing mmcv in the environment using `pip uninstall mmcv`.
2. Install mmcv-full following the [installation instruction](https://mmcv.readthedocs.io/en/latest/#installation).
2. Install mmcv following [mmcv installation instruction](https://mmcv.readthedocs.io/en/2.x/get_started/installation.html).

## Data

Expand All @@ -87,8 +87,11 @@ Compatible MMPose and MMCV versions are shown as below. Please choose the correc

- **RuntimeError: Address already in use**

Set the environment variables `MASTER_PORT=XXX`. For example,
`MASTER_PORT=29517 GPUS=16 GPUS_PER_NODE=8 CPUS_PER_TASK=2 ./tools/slurm_train.sh Test res50 configs/body_2d_keypoint/topdown_regression/coco/td-reg_res50_8xb64-210e_coco-256x192.py work_dirs/res50_coco_256x192`
Set the environment variables `MASTER_PORT=XXX`. For example:

```shell
MASTER_PORT=29517 GPUS=16 GPUS_PER_NODE=8 CPUS_PER_TASK=2 ./tools/slurm_train.sh train res50 configs/body_2d_keypoint/topdown_regression/coco/td-reg_res50_8xb64-210e_coco-256x192.py work_dirs/res50_coco_256x192
```

- **"Unexpected keys in source state dict" when loading pre-trained weights**

Expand All @@ -102,17 +105,23 @@ Compatible MMPose and MMCV versions are shown as below. Please choose the correc
- **How to visualize the training accuracy/loss curves in real-time ?**
Use `TensorboardLoggerHook` in `log_config` like
Modify `vis_backends` in config file like:
```python
log_config=dict(interval=20, hooks=[dict(type='TensorboardLoggerHook')])
vis_backends = [
dict(type='LocalVisBackend'),
dict(type='TensorboardVisBackend')
]
```
You can refer to [user_guides/visualization.md](../user_guides/visualization.md).

- **Log info is NOT printed**
Use smaller log interval. For example, change `interval=50` to `interval=1` in the config.
Use smaller log interval. For example, change `interval=50` to `interval=1` in the config:
```python
# hooks
default_hooks = dict(logger=dict(interval=1))
```
## Evaluation
Expand All @@ -133,5 +142,5 @@ Compatible MMPose and MMCV versions are shown as below. Please choose the correc
For top-down models, try to edit the config file. For example,
1. set `flip_test=False` in `init_cfg` in the config file.
2. use faster human bounding box detector, see [MMDetection](https://mmdetection.readthedocs.io/en/latest/model_zoo.html).
1. set `flip_test=False` in `test_cfg` in the config file.
2. use faster human bounding box detector, see [MMDetection](https://mmdetection.readthedocs.io/en/3.x/model_zoo.html).
Loading

0 comments on commit 19d456d

Please sign in to comment.