openpose/doc/prerequisites.md

OpenPose - Prerequisites

Contents

1. General Tips
2. Ubuntu Prerequisites
3. Mac OS Prerequisites
4. Windows Prerequisites

General Tips

Very important: New Nvidia model GPUs (e.g., Nvidia V, GTX 2080, v100, any Nvidia with Volta or Turing architecture, etc.) require (at least) CUDA 10. CUDA 8 would fail!

In addition, CMake automatically downloads all the OpenPose models. However, some firewall or company networks block these downloads. You might prefer to download them manually:

- [BODY_25 model](http://posefs1.perception.cs.cmu.edu/OpenPose/models/pose/body_25/pose_iter_584000.caffemodel): download in `models/pose/body_25/`.
- [COCO model](http://posefs1.perception.cs.cmu.edu/OpenPose/models/pose/coco/pose_iter_440000.caffemodel): download in `models/pose/coco/`.
- [MPI model](http://posefs1.perception.cs.cmu.edu/OpenPose/models/pose/mpi/pose_iter_160000.caffemodel): download in `models/pose/mpi/`.
- [Face model](http://posefs1.perception.cs.cmu.edu/OpenPose/models/face/pose_iter_116000.caffemodel): download in `models/face/`.
- [Hands model](http://posefs1.perception.cs.cmu.edu/OpenPose/models/hand/pose_iter_102000.caffemodel): download in `models/hand/`.

Finally, if some weird/obscure errors about Caffe and/or Pybind appear, run the following command. It will ensure that all submodules are iniatilised. Reason: OpenPose runs that command through CMake, but some firewalls might block it and we have to run it manually.

git submodule update --init --recursive --remote

Ubuntu Prerequisites

1. Ubuntu - Anaconda should not be installed on your system. Anaconda includes a Protobuf version that is incompatible with Caffe. Either you uninstall anaconda and install protobuf via apt-get, or you compile your own Caffe and link it to OpenPose.
2. Install CMake GUI:
   • Ubuntu 14 or 16: run the command sudo apt-get install cmake-qt-gui. Note: If you prefer to use CMake through the command line, see doc/installation.md#CMake Command Line Configuration (Ubuntu Only).
   • Ubuntu 18: Download and compile CMake-gui from source. The default CMake-gui version (3.10) installed via sudo apt-get install cmake-qt-gui provokes some compiling errors. Required CMake version >= 3.12.
     • Uninstall your current Cmake-gui version by running sudo apt purge cmake-qt-gui.
     • Run sudo apt-get install qtbase5-dev.
     • Download the Latest Release of CMake Unix/Linux Source from the CMake download website, called cmake-X.X.X.tar.gz.
     • Unzip it and go inside that folder from the terminal.
     • Run ./configure --qt-gui. Make sure no error occurred.
     • Run ./bootstrap && make -j`nproc` && sudo make install -j`nproc` . Make sure no error occurred.
     • Assuming your CMake downloaded folder is in {CMAKE_FOLDER_PATH}, everytime these instructions mentions cmake-gui, you will have to replace that line by {CMAKE_FOLDER_PATH}/bin/cmake-gui.
3. Nvidia GPU version prerequisites:
   1. Note: OpenPose has been tested extensively with CUDA 8.0 (cuDNN 5.1) and CUDA 10.0 (cuDNN 7.5). We highly recommend using those versions to minimize potential installation issues. Other versions should also work, but we do not provide support about any CUDA/cuDNN installation/compilation issue, as well as problems relate dto their integration into OpenPose.
   2. CUDA:
      • Ubuntu 14 or 16 (CUDA 8 or 10): Run sudo ./scripts/ubuntu/install_cuda.sh (if Ubuntu 16 or 14 and for Graphic cards up to 10XX) or alternatively download and install it from their website.
      • Ubuntu 18 (CUDA 10): Download the latest Nvidia CUDA version from their official website.
        • Select "Linux" -> "x86_64" -> "Ubuntu" -> "18.04" -> "runfile (local)", and download it.
        • Follow the Nvidia website installation instructions. Make sure to enable the symbolic link in usr/local/cuda to minimize potential future errors.
   3. cuDNN:
      • Ubuntu 14 or 16 (cuDNN 5.1 or 7.2): Run sudo ./scripts/ubuntu/install_cudnn.sh (if Ubuntu 16 or 14 and for Graphic cards up to 10XX) or alternatively download and install it from their website.
      • Ubuntu 18 (cuDNN 7.5): Download and install it from the Nvidia website.
      • In order to manually install it (any version), just unzip it and copy (merge) the contents on the CUDA folder, usually /usr/local/cuda/ in Ubuntu and C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v8.0 in Windows.
4. AMD GPU version prerequisites:
   1. Ubuntu 14 or 16:
      1. Download 3rd party ROCM driver for Ubuntu from AMD - OpenCL.
      2. Install sudo apt-get install libviennacl-dev.
   2. Ubuntu 18: Not tested and not officially supported. Try at your risk.
5. Install Caffe, OpenCV, and Caffe prerequisites:
   • Caffe prerequisites: By default, OpenPose uses Caffe under the hood. If you have not used Caffe previously, install its dependencies by running sudo bash ./scripts/ubuntu/install_deps_and_cuda.sh (if Ubuntu 16 or 14 and for Graphic cards up to 10XX) or run sudo bash ./scripts/ubuntu/install_deps.sh after installing your desired CUDA and cuDNN versions.
   • OpenCV must be already installed on your machine. It can be installed with sudo apt-get install libopencv-dev. You can also use your own compiled OpenCV version.
6. Eigen prerequisite (optional, only required for some specific extra functionality, such as extrinsic camera calibration):
   • If you enable the WITH_EIGEN flag when running CMake, you must have Eigen already installed in your system. Note that Eigen <= 3.3.6 is not supported by CUDA >=9.1. In order to install it, you can perform any of the 3 following options (but only 1 of them!), while making sure that Eigen version is compatible with CUDA:
     1. Do not do anything if you set the WITH_EIGEN flag to BUILD, CMake will automatically download Eigen. Alternatively, you might prefer to download it manually:
        • Eigen3: Unzip as 3rdparty/eigen/.
     2. Run sudo apt-get install libeigen3-dev if you prefer to set WITH_EIGEN to FIND.
     3. Use your own version of Eigen by setting WITH_EIGEN to BUILD, run CMake so that OpenPose downloads the zip file, and then replace the contents of 3rdparty/eigen/ by your own version.

Mac OS Prerequisites

1. If you don't have brew, install it by running bash scripts/osx/install_brew.sh on your terminal.
2. Install CMake GUI: Run the command brew cask install cmake.
3. Install Caffe, OpenCV, and Caffe prerequisites: Run bash scripts/osx/install_deps.sh.
4. Eigen prerequisite (optional, only required for some specific extra functionality, such as extrinsic camera calibration):
   • Enable the WITH_EIGEN flag when running CMake, and set it to BUILD.
   • CMake will automatically download Eigen.
   • Alternatively, you can manually download it from the Eigen3 website, and unzip as 3rdparty/eigen/.

Windows Prerequisites

NOTE: These instructions are only required when compiling OpenPose brom source. If you simply wanna use the OpenPose binaries for Windows, skip this step.

1. Install CMake GUI: Download and install the Latest Release of CMake Windows win64-x64 Installer from the CMake download website, called cmake-X.X.X-win64-x64.msi.
2. Install Microsoft Visual Studio (VS) 2017 Enterprise or VS 2015 Enterprise Update 3:
   • IMPORTANT: Enable all C++-related flags when selecting the components to install.
   • Different VS versions:
     • If Visual Studio 2017 Community is desired, we do not officially support it, but it should run similarly to VS 2017 Enterprise.
     • VS 2015 Community and Enterprise Update 1 might give some compiler errors. They have not been tested and they are totally not supported (use VS 2017 Community instead).
3. Nvidia GPU version prerequisites:
   1. Note: OpenPose has been tested extensively with CUDA 10.0 / cuDNN 7.5 for VS2017 and CUDA 8.0 / cuDNN 5.1 for VS 2015. We highly recommend using those versions to minimize potential installation issues. Other versions should also work, but we do not provide support about any CUDA/cuDNN installation/compilation issue, as well as problems related to their integration into OpenPose.
   2. CUDA 10 or CUDA 8:
      • Install CUDA 8.0/10.0 after Visual Studio 2015/2017 is installed to assure that the CUDA installation will generate all necessary files for VS. If CUDA was already installed, re-install it.
      • Important installation tips:
        • (Windows issue, reported Sep 2018): If your computer hangs when installing CUDA drivers, try installing first the Nvidia drivers, and then installing CUDA without the Graphics Driver flag.
        • If CMake returns and error message similar to CUDA_TOOLKIT_ROOT_DIR not found or specified or any other CUDA component missing, then: 1) Re-install Visual Studio 2015; 2) Reboot your PC; 3) Re-install CUDA (in this order!).
   3. cuDNN 7.5 or cuDNN 5.1:
      • In order to manually install it, just unzip it and copy (merge) the contents on the CUDA folder, usually C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v8.0 in Windows and /usr/local/cuda/ in Ubuntu.
4. AMD GPU version prerequisites:
   1. Download official AMD drivers for Windows from AMD - Windows.
   2. The libviennacl package comes packaged inside OpenPose for Windows (i.e., no further action required).
5. Caffe, OpenCV, and Caffe prerequisites:
   • CMake automatically downloads all the Windows DLLs. Alternatively, you might prefer to download them manually:
     • Dependencies:
       • Note: Leave the zip files in 3rdparty/windows/ so that CMake does not try to download them again.
       • Caffe (if you are not sure which one you need, donwload the default one):
         • CUDA Caffe (Default): Unzip as 3rdparty/windows/caffe/.
         • CPU Caffe: Unzip as 3rdparty/windows/caffe_cpu/.
         • OpenCL Caffe: Unzip as 3rdparty/windows/caffe_opencl/.
       • Caffe dependencies: Unzip as 3rdparty/windows/caffe3rdparty/.
       • OpenCV 4.1.1: Unzip as 3rdparty/windows/opencv/.
6. Eigen prerequisite (optional, only required for some specific extra functionality, such as extrinsic camera calibration):
   • Enable the WITH_EIGEN flag when running CMake, and set it to BUILD.
   • CMake will automatically download Eigen.
   • Alternatively, you can manually download it from the Eigen3 website, run CMake so that OpenPose downloads the zip file, and then replace the contents of 3rdparty/eigen/ by your own version.