OpenPose - Installation ========================== ## Contents 1. [Windows Portable Demo](#windows-portable-demo) 2. [Operating Systems](#operating-systems) 3. [Community-Based Work](#community-based-work) 4. [Requirements and Dependencies](#requirements-and-dependencies) 5. [Clone OpenPose](#clone-openpose) 6. [Update OpenPose](#update-openpose) 7. [Installation](#installation) 8. [Reinstallation](#reinstallation) 9. [Uninstallation](#uninstallation) 10. [Optional Settings](#optional-settings) 1. [Maximum Speed](#maximum-speed) 2. [COCO and MPI Models](#coco-and-mpi-models) 3. [Python API](#python-api) 4. [CPU Version](#cpu-version) 5. [OpenCL Version](#opencl-version) 6. [Mac OSX Version](#mac-osx-version) 7. [3D Reconstruction Module](#3d-reconstruction-module) 8. [Calibration Module](#calibration-module) 9. [Compiling without cuDNN](#compiling-without-cudnn) 10. [Custom Caffe](#custom-caffe) 11. [Custom NVIDIA NVCaffe](#custom-nvidia-nvcaffe) 12. [Custom OpenCV](#custom-opencv) 13. [Doxygen Documentation Autogeneration (Ubuntu Only)](#doxygen-documentation-autogeneration-ubuntu-only) 14. [CMake Command Line Configuration (Ubuntu Only)](#cmake-command-line-configuration-ubuntu-only) ## Windows Portable Demo This installation section is only intended if you plan to modify the OpenPose code or integrate it with another library or project. If you just want to use the OpenPose demo in Windows, simply use the latest version of the OpenPose binaries which you can find in the [Releases](https://github.com/CMU-Perceptual-Computing-Lab/openpose/releases) section. **NOTE**: Read the `Instructions.txt` to learn to download the models required by OpenPose (about 500 Mb). ## Operating Systems - **Ubuntu** 14, 16, 18. - **Windows** 7, 8, 10. - **Mac OSX** Mavericks and above. - **Nvidia Jetson TX1** (for JetPack 3.1), installation instructions in [doc/installation_jetson_tx1.md](./installation_jetson_tx1.md). - **Nvidia Jetson TX2** (for JetPack 3.1 or 3.3), installation instructions in [doc/installation_jetson_tx2_jetpack3.1.md](./installation_jetson_tx2_jetpack3.1.md) and [doc/installation_jetson_tx2_jetpack3.3.md](./installation_jetson_tx2_jetpack3.3.md) respectively. - OpenPose has also been used on **Windows 7**, **CentOS**, and **Nvidia Jetson (TK1 and TX1)** embedded systems. However, we do not officially support them at the moment. ## Community-Based Work We add links to some community-based work based on OpenPose. Note: We do not support them, and we will remove GitHub issues opened asking about them as well as block those users from posting again. If you face any issue, comment only in the comment IDs especified below and/or on their respective GitHubs. - [ROS example](https://github.com/firephinx/openpose_ros) (based on a very old OpenPose version). For questions and more details, read and post ONLY on [issue thread #51](https://github.com/CMU-Perceptual-Computing-Lab/openpose/issues/51). - Docker Images. For questions and more details, read and post ONLY on [issue thread #347](https://github.com/CMU-Perceptual-Computing-Lab/openpose/issues/347). - Dockerfile working also with CUDA 10: - [Link 1](https://github.com/esemeniuc/openpose-docker), it claims to also include Python support. Read and post ONLY on [issue thread #1102](https://github.com/CMU-Perceptual-Computing-Lab/openpose/issues/1102). - [Link 2](https://github.com/ExSidius/openpose-docker/blob/master/Dockerfile). - [Link 3](https://cloud.docker.com/repository/docker/exsidius/openpose/general). - Dockerfile working only with CUDA 8: - [Dockerfile - OpenPose v1.4.0, OpenCV, CUDA 8, CuDNN 5, Python2.7](https://github.com/tlkh/openpose). Read and post ONLY on [issue thread #1102](https://github.com/CMU-Perceptual-Computing-Lab/openpose/issues/1102). - [Dockerfile - OpenPose v1.4.0, OpenCV, CUDA 8, CuDNN 6, Python2.7](https://gist.github.com/moiseevigor/11c02c694fc0c22fccd59521793aeaa6). - [Dockerfile - OpenPose v1.2.1](https://gist.github.com/sberryman/6770363f02336af82cb175a83b79de33). - [Google Colab helper script](https://github.com/CMU-Perceptual-Computing-Lab/openpose/issues/949#issue-387855863): Script to install OpenPose on Google Colab. Really useful when access to a computer powerful enough to run OpenPose is not possible, so one possible way to use OpenPose is to build it on a GPU-enabled Colab runtime and then run the programs there. For questions and more details, read and post ONLY on [issue thread #949](https://github.com/CMU-Perceptual-Computing-Lab/openpose/issues/949). ## Requirements and Dependencies - **Requirements** for the default configuration (you might need more resources with a greater `--net_resolution` and/or `scale_number` or less resources by reducing the net resolution and/or using the MPI and MPI_4 models): - CUDA (Nvidia GPU) version: - NVIDIA graphics card with at least 1.6 GB available (the `nvidia-smi` command checks the available GPU memory in Ubuntu). - At least 2.5 GB of free RAM memory for BODY_25 model or 2 GB for COCO model (assuming cuDNN installed). - Highly recommended: cuDNN. - OpenCL (AMD GPU) version: - Vega series graphics card - At least 2 GB of free RAM memory. - CPU-only (no GPU) version: - Around 8GB of free RAM memory. - Highly recommended: a CPU with at least 8 cores. - **Dependencies**: - OpenCV (all 2.X and 3.X versions are compatible). - Caffe and all its dependencies. Interesting in porting OpenPose to other DL frameworks (Tensorflow, Caffe2, Pytorch, ...)?. Email us (gines@cmu.edu) if you are interesting in joining the OpenPose team to do so or feel free to make a pull request if you implement any of those! - The demo and tutorials additionally use GFlags. ## Clone OpenPose The first step is to clone the OpenPose repository. 1. Windows: You might use [GitHub Desktop](https://desktop.github.com/). 2. Ubuntu: ```bash git clone https://github.com/CMU-Perceptual-Computing-Lab/openpose ``` ## Update OpenPose OpenPose can be easily updated by: 1. Download the latest changes: 1. Windows: Clicking the `synchronization` button at the top-right part in GitHub Desktop in Windows. 2. Ubuntu: running `git pull origin master`. 2. Perform the [Reinstallation](#reinstallation) section described below. ## Installation The instructions in this section describe the steps to build OpenPose using CMake (GUI). There are 3 main steps: 1. [Problems and Errors Installing](#problems-and-errors-installing) 2. [Prerequisites](#prerequisites) 3. [OpenPose Configuration](#openpose-configuration) 4. [OpenPose Building](#openpose-building) 5. [Run OpenPose](#run-openpose) 6. [OpenPose from other Projects (Ubuntu and Mac)](#openpose-from-other-projects-ubuntu-and-mac) ### Problems and Errors Installing Any problem installing OpenPose? Check [doc/faq.md](./faq.md) and/or post a GitHub issue. We will not respond more GitHub issues about Caffe, OpenCV or CUDA errors. ### Prerequisites Make sure to download and install the prerequisites for your particular operating system following [doc/prerequisites.md](./prerequisites.md). ### OpenPose Configuration 1. Open CMake GUI and select the OpenPose directory as project source directory, and a non-existing or empty sub-directory (e.g., `build`) where the Makefile files (Ubuntu) or Visual Studio solution (Windows) will be generated. If `build` does not exist, it will ask you whether to create it. Press `Yes`.
2. Press the `Configure` button, keep the generator in `Unix Makefile` (Ubuntu) or set it to your 64-bit Visual Studio version (Windows), and press `Finish`. Note for Windows users: CMake-GUI has changed their design after version 14. For versions older than 14, you usually select `Visual Studio XX 20XX Win64` as the generator (`X` depends on your VS version), while the `Optional toolset to use` must be empty. However, new CMake versions require you to select only the VS version as the generator, e.g., `Visual Studio 15 2017`, and then you must manually choose `x64` for the `Optional platform for generator`. See the following images as example.
3. If this step is successful, the `Configuring done` text will appear in the bottom box in the last line. Otherwise, some red text will appear in that same bottom box.
4. Press the `Generate` button and proceed to [OpenPose Building](#openpose-building). You can now close CMake. Note: If you prefer to use your own custom Caffe or OpenCV versions, see [Custom Caffe](#custom-caffe) or [Custom OpenCV](#custom-opencv) respectively. ### OpenPose Building #### Ubuntu and Mac Finally, build the project by running the following commands. ``` cd build/ make -j`nproc` ``` #### Windows In order to build the project, select and run only one of the 2 following alternatives. 1. **CMake-GUI alternative (recommended)**: Open the Visual Studio solution (Windows), called `build/OpenPose.sln`. Then, set the configuration from `Debug` to `Release` and press the green triangle icon (alternatively press F5). 2. Command-line build alternative (not recommended). NOTE: The command line alternative is not officially supported, but it was added in [GitHub issue #1198](https://github.com/CMU-Perceptual-Computing-Lab/openpose/issues/1198). For any questions or bug report about this command-line version, comment in that GitHub issue. 1. Run "MSVS 2017 Developer Command Console" ``` openpose\mkdir build cd build cmake .. -G "Visual Studio 15 2017 Win64" -T v140 cmake --build . --config Release copy x64\Release\* bin\ ``` 2. If you want to clean build ``` cmake --clean-first . cmake --build . --config Release copy x64\Release\* bin\ ``` **VERY IMPORTANT NOTE**: In order to use OpenPose outside Visual Studio, and assuming you have not unchecked the `BUILD_BIN_FOLDER` flag in CMake, copy all DLLs from `{build_directory}/bin` into the folder where the generated `openpose.dll` and `*.exe` demos are, e.g., `{build_directory}x64/Release` for the 64-bit release version. ### Run OpenPose Check OpenPose was properly installed by running it on the default images, video, or webcam: [doc/quick_start.md#quick-start](./quick_start.md#quick-start). ### OpenPose from other Projects (Ubuntu and Mac) If you only intend to use the OpenPose demo, you might skip this step. This step is only recommended if you plan to use the OpenPose API from other projects. To install the OpenPose headers and libraries into the system environment path (e.g., `/usr/local/` or `/usr/`), run the following command. ``` cd build/ sudo make install ``` Once the installation is completed, you can use OpenPose in your other project using the `find_package` cmake command. Below, is a small example `CMakeLists.txt`. In order to use this script, you also need to copy `FindGFlags.cmake` and `FindGlog.cmake` into your `
For Windows, simply replace the OpenCV DLLs and include folder for your custom one. #### Custom NVIDIA NVCaffe This functionality was added by the community, and we do not officially support it. New pull requests with additional functionality or fixing any bug are welcome! It has been tested with the official Nvidia Docker image [nvcr.io/nvidia/caffe:18.12-py2](https://ngc.nvidia.com/catalog/containers/nvidia:caffe). For questions and issues, please only post on the related [Pull Request #1169](https://github.com/CMU-Perceptual-Computing-Lab/openpose/pull/1169). New GitHub issues about this topic (i.e., outside PR #1169) will be automatically closed with no answer. Windows support has not been added. Replace `set_property(CACHE DL_FRAMEWORK PROPERTY STRINGS CAFFE)` by `set_property(CACHE DL_FRAMEWORK PROPERTY STRINGS CAFFE NV_CAFFE)` in `CMakeLists.txt` if you intend to use it for Windows, and feel free to do a pull request of it working! To use a NVIDIA's NVCaffe docker image instead of the standard Caffe, set the following CMake flags: 1. Set the `DL_FRAMEWORK` variable to `NV_CAFFE`. 2. Set the `BUILD_CAFFE` variable to `OFF`. 3. Set the correct `Caffe_INCLUDE_DIRS` and `Caffe_LIBS` paths following [Custom Caffe](#custom-caffe). #### Custom OpenCV If you have built OpenCV from source and OpenPose cannot find it automatically, you can set the `OPENCV_DIR` variable to the directory where you build OpenCV (Ubuntu and Mac). For Windows, simply replace the OpenCV DLLs and include folder for your custom one. #### Doxygen Documentation Autogeneration (Ubuntu Only) You can generate the documentation by setting the `BUILD_DOCS` flag. The documentation will be generated in `doc/doxygen/html/index.html`. You can simply open it with double-click (your default browser should automatically display it). #### CMake Command Line Configuration (Ubuntu Only) Note that this step is unnecessary if you already used the CMake GUI alternative. Create a `build` folder in the root OpenPose folder, where you will build the library -- ```bash cd openpose mkdir build cd build ``` The next step is to generate the Makefiles. Now there can be multiple scenarios based on what the user already has e.x. Caffe might be already installed and the user might be interested in building OpenPose against that version of Caffe instead of requiring OpenPose to build Caffe from scratch. ##### SCENARIO 1 -- Caffe not installed and OpenCV installed using `apt-get` In the build directory, run the below command -- ```bash cmake .. ``` ##### SCENARIO 2 -- Caffe installed and OpenCV build from source In this example, we assume that Caffe and OpenCV are already present. The user needs to supply the paths of the libraries and the include directories to CMake. For OpenCV, specify the include directories and the libraries directory using `OpenCV_INCLUDE_DIRS` and `OpenCV_LIBS_DIR` variables respectively. Alternatively, the user can also specify the path to the `OpenCVConfig.cmake` file by setting the `OpenCV_CONFIG_FILE` variable. For Caffe, specify the include directory and library using the `Caffe_INCLUDE_DIRS` and `Caffe_LIBS` variables. This will be where you installed Caffe. Below is an example of the same. ```bash cmake -DOpenCV_INCLUDE_DIRS=/home/"${USER}"/softwares/opencv/build/install/include \ -DOpenCV_LIBS_DIR=/home/"${USER}"/softwares/opencv/build/install/lib \ -DCaffe_INCLUDE_DIRS=/home/"${USER}"/softwares/caffe/build/install/include \ -DCaffe_LIBS=/home/"${USER}"/softwares/caffe/build/install/lib/libcaffe.so -DBUILD_CAFFE=OFF .. ``` ```bash cmake -DOpenCV_CONFIG_FILE=/home/"${USER}"/softwares/opencv/build/install/share/OpenCV/OpenCVConfig.cmake \ -DCaffe_INCLUDE_DIRS=/home/"${USER}"/softwares/caffe/build/install/include \ -DCaffe_LIBS=/home/"${USER}"/softwares/caffe/build/install/lib/libcaffe.so -DBUILD_CAFFE=OFF .. ``` ##### SCENARIO 3 -- OpenCV already installed If Caffe is not already present but OpenCV is, then use the below command. ```bash cmake -DOpenCV_INCLUDE_DIRS=/home/"${USER}"/softwares/opencv/build/install/include \ -DOpenCV_LIBS_DIR=/home/"${USER}"/softwares/opencv/build/install/lib .. ``` ```bash cmake -DOpenCV_CONFIG_FILE=/home/"${USER}"/softwares/opencv/build/install/share/OpenCV/OpenCVConfig.cmake .. ```