diff --git a/docs/install.md b/docs/install.md index de227359bc..37afe5d399 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,16 +1,18 @@ -## Installation +# Installation - [Requirements](#requirements) +- [Prepare Environment](#prepare-environment) - [Install MMPose](#install-mmpose) +- [Install with CPU only](#install-with-cpu-only) - [A from-scratch setup script](#a-from-scratch-setup-script) - [Another option: Docker Image](#another-option-docker-image) - [Developing with multiple MMPose versions](#developing-with-multiple-mmpose-versions) -### Requirements +## Requirements - Linux (Windows is not officially supported) - Python 3.6+ @@ -30,7 +32,7 @@ Optional: - [pyrender](https://pyrender.readthedocs.io/en/latest/install/index.html) (to run 3d mesh demos) - [smplx](https://github.com/vchoutas/smplx) (to run 3d mesh demos) -### Install MMPose +## Prepare environment a. Create a conda virtual environment and activate it. @@ -48,35 +50,36 @@ conda install pytorch torchvision -c pytorch Note: Make sure that your compilation CUDA version and runtime CUDA version match. You can check the supported CUDA version for precompiled packages on the [PyTorch website](https://pytorch.org/). -`E.g.1` If you have CUDA 10.1 installed under `/usr/local/cuda` and would like to install PyTorch 1.5, -you need to install the prebuilt PyTorch with CUDA 10.1. +`E.g.1` If you have CUDA 10.2 installed under `/usr/local/cuda` and would like to install PyTorch 1.8.0, +you need to install the prebuilt PyTorch with CUDA 10.2. ```shell -conda install pytorch cudatoolkit=10.1 torchvision -c pytorch +conda install pytorch==1.8.0 torchvision==0.9.0 cudatoolkit=10.2 -c pytorch ``` -`E.g.2` If you have CUDA 9.2 installed under `/usr/local/cuda` and would like to install PyTorch 1.3.1., +`E.g.2` If you have CUDA 9.2 installed under `/usr/local/cuda` and would like to install PyTorch 1.7.0., you need to install the prebuilt PyTorch with CUDA 9.2. ```shell -conda install pytorch=1.3.1 cudatoolkit=9.2 torchvision=0.4.2 -c pytorch +conda install pytorch==1.7.0 torchvision==0.8.0 cudatoolkit=9.2 -c pytorch ``` -If you build PyTorch from source instead of installing the prebuilt package, you can use more CUDA versions such as 9.0. +If you build PyTorch from source instead of installing the pre-built package, you can use more CUDA versions such as 9.0. -c. Install mmcv, we recommend you to install the pre-build mmcv as below. +## Install MMPose + +a. Install mmcv, we recommend you to install the pre-built mmcv as below. ```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`` and ``PyTorch 1.7.0``, use the following command: +Please replace ``{cu_version}`` and ``{torch_version}`` in the url to your desired one. For example, to install the latest ``mmcv-full`` with ``CUDA 10.2`` and ``PyTorch 1.8.0``, use the following command: ```shell -pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu110/torch1.7.0/index.html +pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html ``` -If it compiles during installation, then please check that the cuda version and pytorch version **exactly"" matches the version in the mmcv-full installation command. For example, pytorch 1.7.0 and 1.7.1 are treated differently. See [here](https://github.com/open-mmlab/mmcv#installation) for different versions of MMCV compatible to different PyTorch and CUDA versions. Optionally you can choose to compile mmcv from source by the following command @@ -89,32 +92,38 @@ MMCV_WITH_OPS=1 pip install -e . # package mmcv-full, which contains cuda ops, cd .. ``` -Or directly run - -```shell -pip install mmcv-full -# alternative: pip install mmcv -``` - **Important:** You need to run `pip uninstall mmcv` first if you have mmcv installed. If mmcv and mmcv-full are both installed, there will be `ModuleNotFoundError`. -d. Clone the mmpose repository +b. Clone the mmpose repository ```shell git clone git@github.com:open-mmlab/mmpose.git cd mmpose ``` -e. Install build requirements and then install mmpose +c. Install build requirements and then install mmpose ```shell pip install -r requirements.txt -python setup.py develop +pip install -v -e . # or "python setup.py develop" ``` +If you build MMPose on macOS, replace the last command with + +```shell +CC=clang CXX=clang++ CFLAGS='-stdlib=libc++' pip install -e . +``` + +d. Install optional modules + +- [mmdet](https://github.com/open-mmlab/mmdetection) (to run pose demos) +- [mmtrack](https://github.com/open-mmlab/mmtracking) (to run pose tracking demos) +- [pyrender](https://pyrender.readthedocs.io/en/latest/install/index.html) (to run 3d mesh demos) +- [smplx](https://github.com/vchoutas/smplx) (to run 3d mesh demos) + Note: -1. The git commit id will be written to the version number with step d, e.g. 0.6.0+2e7045c. The version will also be saved in trained models. +1. The git commit id will be written to the version number with step c, e.g. 0.6.0+2e7045c. The version will also be saved in trained models. It is recommended that you run step d each time you pull some updates from github. If C++/CUDA codes are modified, then this step is compulsory. 1. Following the above instructions, mmpose is installed on `dev` mode, any local modifications made to the code will take effect without the need to reinstall it (unless you submit some commits and want to update the version number). @@ -124,7 +133,18 @@ Note: 1. If you have `mmcv` installed, you need to firstly uninstall `mmcv`, and then install `mmcv-full`. -### A from-scratch setup script +1. Some dependencies are optional. Running `python setup.py develop` will only install the minimum runtime requirements. + To use optional dependencies like `smplx`, either install them with `pip install -r requirements/optional.txt` + or specify desired extras when calling `pip` (e.g. `pip install -v -e .[optional]`, + valid keys for the `[optional]` field are `all`, `tests`, `build`, and `optional`) like `pip install -v -e .[tests,build]`. + +## Install with CPU only + +The code can be built for CPU only environment (where CUDA isn't available). + +In CPU mode you can run the demo/demo.py for example. + +## A from-scratch setup script Here is a full script for setting up mmpose with conda and link the dataset path (supposing that your COCO dataset path is $COCO_ROOT). @@ -135,8 +155,10 @@ conda activate open-mmlab # install latest pytorch prebuilt with the default prebuilt CUDA version (usually the latest) conda install -c pytorch pytorch torchvision -y -# install the latest mmcv-full or mmcv, here we take mmcv-full as example -pip install mmcv-full +# install the latest mmcv-full +# Please replace ``{cu_version}`` and ``{torch_version}`` in the url to your desired one. +# See [here](https://github.com/open-mmlab/mmcv#installation) for different versions of MMCV compatible to different PyTorch and CUDA versions. +pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html # install mmpose git clone git@github.com:open-mmlab/mmpose.git @@ -144,9 +166,11 @@ cd mmpose pip install -r requirements.txt python setup.py develop +mkdir data +ln -s $COCO_ROOT data/coco ``` -### Another option: Docker Image +## Another option: Docker Image We provide a [Dockerfile](/docker/Dockerfile) to build an image. @@ -165,7 +189,7 @@ docker run --gpus all\ -it -v {DATA_DIR}:/mmpose/data mmpose ``` -### Developing with multiple MMPose versions +## Developing with multiple MMPose versions The train and test scripts already modify the `PYTHONPATH` to ensure the script use the MMPose in the current directory. diff --git a/docs_zh-CN/install.md b/docs_zh-CN/install.md index 9b7824adcf..5048c47c72 100644 --- a/docs_zh-CN/install.md +++ b/docs_zh-CN/install.md @@ -1,3 +1,204 @@ -## 安装 +# 安装 -内容建设中…… +本文档提供了安装 MMPose 的相关步骤。 + + + +- [安装依赖包](#安装依赖包) +- [准备环境](#准备环境) +- [MMPose 的安装步骤](#MMPose-的安装步骤) +- [CPU 环境下的安装步骤](#CPU-环境下的安装步骤) +- [利用 Docker 镜像安装 MMPose](#利用-Docker-镜像安装-MMPose) +- [源码安装 MMPose](#源码安装-MMPose) +- [在多个 MMPose 版本下进行开发](#在多个-MMPose-版本下进行开发) + + + +## 安装依赖包 + +- Linux (Windows 系统暂未有官方支持) +- Python 3.6+ +- PyTorch 1.3+ +- CUDA 9.2+ (如果从源码编译 PyTorch,则可以兼容 CUDA 9.0 版本) +- GCC 5+ +- [mmcv](https://github.com/open-mmlab/mmcv) 请安装最新版本的 mmcv-full +- Numpy +- cv2 +- json_tricks +- [xtcocotools](https://github.com/jin-s13/xtcocoapi) + +可选项: + +- [mmdet](https://github.com/open-mmlab/mmdetection) (用于“姿态估计”) +- [mmtrack](https://github.com/open-mmlab/mmtracking) (用于“姿态跟踪”) +- [pyrender](https://pyrender.readthedocs.io/en/latest/install/index.html) (用于“三维人体形状恢复”) +- [smplx](https://github.com/vchoutas/smplx) (用于“三维人体形状恢复”) + +## 准备环境 + +a. 创建并激活 conda 虚拟环境,如: + +```shell +conda create -n open-mmlab python=3.7 -y +conda activate open-mmlab +``` + +b. 参考 [官方文档](https://pytorch.org/) 安装 PyTorch 和 torchvision ,如: + +```shell +conda install pytorch torchvision -c pytorch +``` + +**注**:确保 CUDA 的编译版本和 CUDA 的运行版本相匹配。 +用户可以参照 [PyTorch 官网](https://pytorch.org/) 对预编译包所支持的 CUDA 版本进行核对。 + +`例 1`:如果用户的 `/usr/local/cuda` 文件夹下已安装 CUDA 10.2 版本,并且想要安装 PyTorch 1.8.0 版本, +则需要安装 CUDA 10.2 下预编译的 PyTorch。 + +```shell +conda install pytorch==1.8.0 torchvision==0.9.0 cudatoolkit=10.2 -c pytorch +``` + +`例 2`:如果用户的 `/usr/local/cuda` 文件夹下已安装 CUDA 9.2 版本,并且想要安装 PyTorch 1.7.0 版本, +则需要安装 CUDA 9.2 下预编译的 PyTorch。 + +```shell +conda install pytorch==1.7.0 torchvision==0.8.0 cudatoolkit=9.2 -c pytorch +``` + +如果 PyTorch 是由源码进行编译安装(而非直接下载预编译好的安装包),则可以使用更多的 CUDA 版本(如 9.0 版本)。 + +## MMPose 的安装步骤 + +a. 安装最新版本的 mmcv-full。MMPose 推荐用户使用如下的命令安装预编译好的 mmcv。 + +```shell +pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html +``` + +其中,命令里 url 的 ``{cu_version}`` 和 ``{torch_version}`` 变量需由用户进行指定。 +例如,如果想要安装 ``CUDA 10.2`` 和 ``PyTorch 1.8.0`` 下的最新版 ``mmcv-full``,可使用以下命令: + +```shell +pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html +``` + +可查阅 [这里](https://github.com/open-mmlab/mmcv#installation) 以参考不同版本的 MMCV 所兼容的 PyTorch 和 CUDA 版本。 + +另外,用户也可以通过使用以下命令从源码进行编译: + +```shell +git clone https://github.com/open-mmlab/mmcv.git +cd mmcv +MMCV_WITH_OPS=1 pip install -e . # mmcv-full 包含一些 cuda 算子,执行该步骤会安装 mmcv-full(而非 mmcv) +# 或者使用 pip install -e . # 这个命令安装的 mmcv 将不包含 cuda ops,通常适配 CPU(无 GPU)环境 +cd .. +``` + +**注意**:如果之前安装过 mmcv,那么需要先使用 `pip uninstall mmcv` 命令进行卸载。如果 mmcv 和 mmcv-full 同时被安装, 会报 `ModuleNotFoundError` 的错误。 + +b. 克隆 MMPose 库。 + +```shell +git clone https://github.com/open-mmlab/mmpose.git +cd mmpose +``` + +c. 安装依赖包和 MMPose。 + +```shell +pip install -r requirements.txt +pip install -v -e . # or "python setup.py develop" +``` + +如果是在 macOS 环境安装 MMPose,则需使用如下命令: + +```shell +CC=clang CXX=clang++ CFLAGS='-stdlib=libc++' pip install -e . +``` + +d. 安装其他可选依赖。 + +如果用户不需要做相关任务,这部分步骤可以选择跳过。 + +可选项: + +- [mmdet](https://github.com/open-mmlab/mmdetection) (用于“姿态估计”) +- [mmtrack](https://github.com/open-mmlab/mmtracking) (用于“姿态跟踪”) +- [pyrender](https://pyrender.readthedocs.io/en/latest/install/index.html) (用于“三维人体形状恢复”) +- [smplx](https://github.com/vchoutas/smplx) (用于“三维人体形状恢复”) + +注意: + +1. 在步骤 c 中,git commit 的 id 将会被写到版本号中,如 0.6.0+2e7045c。这个版本号也会被保存到训练好的模型中。 + 这里推荐用户每次在步骤 b 中对本地代码和 github 上的源码进行同步。如果 C++/CUDA 代码被修改,就必须进行这一步骤。 + +1. 根据上述步骤,MMPose 就会以 `dev` 模式被安装,任何本地的代码修改都会立刻生效,不需要再重新安装一遍(除非用户提交了 commits,并且想更新版本号)。 + +1. 如果用户想使用 `opencv-python-headless` 而不是 `opencv-python`,可再安装 MMCV 前安装 `opencv-python-headless`。 + +1. 如果 mmcv 已经被安装,用户需要使用 `pip uninstall mmcv` 命令进行卸载。如果 mmcv 和 mmcv-full 同时被安装, 会报 `ModuleNotFoundError` 的错误。 + +1. 一些依赖包是可选的。运行 `python setup.py develop` 将只会安装运行代码所需的最小要求依赖包。 + 要想使用一些可选的依赖包,如 `smplx`,用户需要通过 `pip install -r requirements/optional.txt` 进行安装, + 或者通过调用 `pip`(如 `pip install -v -e .[optional]`,这里的 `[optional]` 可替换为 `all`,`tests`,`build` 或 `optional`) 指定安装对应的依赖包,如 `pip install -v -e .[tests,build]`。 + +## CPU 环境下的安装步骤 + +MMPose 可以在只有 CPU 的环境下安装(即无法使用 GPU 的环境)。 + +在 CPU 模式下,用户可以运行 `demo/demo.py` 的代码。 + +## 源码安装 MMPose + +这里提供了 conda 下安装 MMPose 并链接 COCO 数据集路径的完整脚本(假设 COCO 数据的路径在 $COCO_ROOT)。 + +```shell +conda create -n open-mmlab python=3.7 -y +conda activate open-mmlab + +# 安装最新的,使用默认版本的 CUDA 版本(一般为最新版本)预编译的 PyTorch 包 +conda install -c pytorch pytorch torchvision -y + +# 安装 mmcv-full。其中,命令里 url 的 ``{cu_version}`` 和 ``{torch_version}`` 变量需由用户进行指定。 +# 可查阅 [这里](https://github.com/open-mmlab/mmcv#installation) 以参考不同版本的 MMCV 所兼容的 PyTorch 和 CUDA 版本。 +pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html + +# 安装 mmpose +git clone git@github.com:open-mmlab/mmpose.git +cd mmpose +pip install -r requirements.txt +python setup.py develop + +mkdir data +ln -s $COCO_ROOT data/coco +``` + +## 利用 Docker 镜像安装 MMPose + +MMPose 提供一个 [Dockerfile](/docker/Dockerfile) 用户创建 docker 镜像。 + +```shell +# 创建拥有 PyTorch 1.6.0, CUDA 10.1, CUDNN 7 配置的 docker 镜像. +docker build -f ./docker/Dockerfile --rm -t mmpose . +``` + +**注意**:用户需要确保已经安装了 [nvidia-container-toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#docker)。 + +运行以下命令: + +```shell +docker run --gpus all\ + --shm-size=8g \ + -it -v {DATA_DIR}:/mmpose/data mmpose +``` + +## 在多个 MMPose 版本下进行开发 + +MMPose 的训练和测试脚本已经修改了 `PYTHONPATH` 变量,以确保其能够运行当前目录下的 MMPose。 + +如果想要运行环境下默认的 MMPose,用户需要在训练和测试脚本中去除这一行: + +```shell +PYTHONPATH="$(dirname $0)/..":$PYTHONPATH +```