Skip to content

Latest commit

 

History

History
462 lines (319 loc) · 33.4 KB

0_index.md

File metadata and controls

462 lines (319 loc) · 33.4 KB
Raw

OpenPose Doc - Installation

Contents

  1. Operating Systems, Requirements, and Dependencies
  2. Windows Portable Demo
  3. Compiling and Running OpenPose from Source
    1. Problems and Errors Installing OpenPose
    2. Prerequisites
    3. Clone OpenPose
    4. CMake Configuration
    5. Compilation
    6. Running OpenPose
    7. Custom User Code
  4. Compiling and Running OpenPose from Source on ROS, Docker, and Google Colab - Community-Based Work
  5. Uninstalling, Reinstalling, or Updating OpenPose
  6. Advanced Additional Settings (Optional)
    1. Deploying or Exporting OpenPose to Other Projects
    2. Maximum Speed
    3. Faster CPU Version (Ubuntu Only)
    4. OpenCL Version
    5. COCO and MPI Models
    6. 3D Reconstruction Module
    7. Calibration Module
    8. Unity Compatible Version
    9. Compiling without cuDNN
    10. Custom Caffe
    11. Custom NVIDIA NVCaffe
    12. Custom OpenCV
    13. Doxygen Documentation Autogeneration (Ubuntu Only)
    14. CMake Command Line Configuration (Ubuntu Only)

Operating Systems, Requirements, and Dependencies

  • Operating Systems
  • Requirements for the default configuration
    • 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.
  • Advanced tip: 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.
  • Dependencies:
    • OpenCV (all 2.X and 3.X versions are compatible).
    • Caffe and all its dependencies. Have you ported OpenPose into another DL framework (Tensorflow, Caffe2, Pytorch, ...)?. Email us ([email protected]) or feel free to make a pull request if you implemented any of those!
    • The demo and tutorials additionally use GFlags.

Windows Portable Demo

If you just want to use OpenPose without compiling or writing any code, simply use the latest portable version of OpenPose for Windows.

  1. For maximum speed, you should use OpenPose in a machine with a Nvidia GPU version. If so, you must upgrade your Nvidia drivers to the latest version (in the Nvidia "GeForce Experience" software or its website).
  2. Download the latest OpenPose version from the Releases section.
  3. Follow the Instructions.txt file inside the downloaded zip file to download the models required by OpenPose (about 500 Mb).
  4. Then, you can run OpenPose from the PowerShell command-line by following doc/01_demo.md.

Note: If you are using the GPU-accelerated version and are seeing Cuda check failed (3 vs. 0): initialization error when running OpenPose, you can fix it by doing one of these:

  • Upgrade your Nvidia drivers. If the error persists, make sure your machine does not contain any CUDA version (or if so, that it's the same than the OpenPose portable demo files). Otherwise, uninstall that CUDA version. If you need to keep that CUDA version installed, follow Compiling and Running OpenPose from Source for that particular CUDA version instead.
  • Download an older OpenPose version (v1.6.0 does not show this error).

Compiling and Running OpenPose from Source

The instructions in the following subsections describe the steps to build OpenPose using CMake-GUI. These instructions are only recommended if you plan to modify the OpenPose code or integrate it with another library or project. You can stop reading this document if you just wanted to run OpenPose on Windows without compiling or modifying any code.

Problems and Errors Installing OpenPose

Any problem installing OpenPose while following this guidelines? Check doc/05_faq.md and/or check existing GitHub issues. If you do you find your issue, post a new one. We will not respond to duplicated issues, as well as GitHub issues about Caffe, OpenCV or CUDA installation errors, as well as issues that do not fill all the information that the GitHub template asks for.

Prerequisites

Make sure to download and install the prerequisites for your particular operating system.

Clone OpenPose

The first step is to clone the OpenPose repository.

  1. Windows: You might use GitHub Desktop or clone it from Powershell.
  2. Ubuntu, Mac, or Windows Powershell:
git clone https://github.com/CMU-Perceptual-Computing-Lab/openpose
cd openpose/
git submodule update --init --recursive --remote

CMake Configuration

  1. Go to the OpenPose folder and open CMake-GUI from it. On Windows, double click on CMake-gui. On Ubuntu, Mac, or Windows Powershell:
cd {OpenPose_folder}
mkdir build/
cd build/
cmake-gui ..
  1. 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.

  1. Press the Configure button, keep the generator in Unix Makefiles (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 16 2019, and then you must manually choose x64 for the Optional platform for generator. See the following images as example.

  1. Enabling Python (optional step, only apply it if you plan to use the Python API): Enable the BUILD_PYTHON flag and click Configure again.

  2. Set the GPU_MODE flag to the proper value and click Configure again:

    1. If your machine has an Nvidia GPU, you should most probably not modify this flag and skip this step. Cases in which you might have to change it:
      • If you have a Nvidia GPU with 2GB of memory or less: Then you will have to follow some of the tricks in doc/06_maximizing_openpose_speed.md or change GPU_MODE back to CPU_ONLY.
      • If you cannot install CUDA, then you can also set GPU_MODE to CPU_ONLY.
    2. Mac OSX and machines with a non-Nvidia GPU (Intel or AMD GPUs): Set the GPU_MODE flag to CPU_ONLY (easier to install but slower runtime) or OPENCL (GPU-accelerated, it is harder to install but provides a faster runtime speed). For more details on OpenCV support, see doc/1_prerequisites.md and OpenCL Version.
    3. If your machine does not have any GPU, set the GPU_MODE flag to CPU_ONLY.

  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.

  1. Press the Generate button and proceed to Compilation. You can now close CMake.

Note: If you prefer to use your own custom Caffe or OpenCV versions, see Custom Caffe or Custom OpenCV respectively.

Compilation

Ubuntu

Run the following commands in your terminal.

cd build/
make -j`nproc`

Mac

Run the following commands in your terminal:

cd build/
make -j`sysctl -n hw.logicalcpu`

Advanced tip: Mac provides both logicalcpu and physicalcpu, but we want the logical number for maximum speed.

If the default compilation fails with Caffe errors, install Caffe separately and set BUILD_CAFFE to false in the CMake config. Steps:

  • Re-create the build folder: rm -rf build; mkdir build; cd build.
  • brew uninstall caffe to remove the version of Caffe previously installed via cmake.
  • brew install caffe to install Caffe separately.
  • Run cmake-gui and make the following adjustments to the cmake config:
    1. BUILD_CAFFE set to false.
    2. Caffe_INCLUDE_DIRS set to /usr/local/include/caffe.
    3. Caffe_LIBS set to /usr/local/lib/libcaffe.dylib.
    4. Run Configure and Generate from CMake GUI.

If you face an OpenCV error during compiling time similar to fatal error: 'opencv2/highgui/highgui.hpp' file not found, please apply the following patch (this error has been reported in the latest OSX 10.14):

cd 3rdparty/caffe; git apply ../../scripts/osx/mac_opencl_patch.txt

Windows

In order to build the project, select and run only one of the 2 following alternatives.

  • CMake-GUI alternative (recommended):

    1. Open the Visual Studio solution (Windows) by clicking in Open Project in CMake (or alternatively build/OpenPose.sln). Then, set the configuration from Debug to Release.
    2. Press F7 (or Build menu and click on Build Solution).
    3. Important for Python version: Make sure not to skip step 2, it is not enough to click on F5 (Run), you must also Build Solution for the Python bindings to be generated.
    4. After it has compiled, and if you have a webcam, you can press the green triangle icon (alternatively F5) to run the OpenPose demo with the default settings on the webcam.

  • Command-line build alternative (not recommended). NOTE: The command line alternative is not officially supported, but it was added in GitHub issue #1198. For any questions or bug report about this command-line version, comment in that GitHub issue.

    1. Run "MSVS 2019 Developer Command Console"
    openpose\mkdir  build
cd build
cmake .. -G "Visual Studio 16 2019" -A x64 -T v142
cmake --build . --config Release
copy x64\Release\*  bin\
    1. 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.

If you are facing errors with these instructions, these are a set of alternative instructions created by the community:

We welcome users to send us their installation videos (e.g., sharing them as GitHub issue or doing a pull request) and we will post them here.

Running OpenPose

Check OpenPose was properly installed by running any demo example: doc/01_demo.md.

Custom User Code

You can quickly add your custom code so that quick prototypes can be easily tested without having to create a whole new project just for it. See examples/user_code/README.md for more details.

Compiling and Running OpenPose from Source on ROS, Docker, and Google Colab - Community-Based Work

If you do not want to use the Windows portable binaries nor compile it from source code, we add links to some community-based work based on OpenPose. Note: We do not support them, and we will remove new GitHub issues opened asking about them as well as block those users from posting again. If you face any issue, comment only in the GitHub issues links especified below, or ask the owner of them.

Uninstalling, Reinstalling, or Updating OpenPose

OpenPose can be easily uninstalled:

  1. (Ubuntu and Mac) If you ran sudo make install (which we do not recommend), then run sudo make uninstall in build/.
  2. Remove the OpenPose folder.

In order to update it or reinstall it:

  1. Follow the above steps to uninstall it.
  2. Follow the Compiling and Running OpenPose from Source steps again.

Advanced Additional Settings (Optional)

Deploying or Exporting OpenPose to Other Projects

See doc/advanced/deployment.md.

Maximum Speed

Check the OpenPose Benchmark as well as some hints to speed up and/or reduce the memory requirements to run OpenPose on doc/06_maximizing_openpose_speed.md.

Faster CPU Version (Ubuntu Only)

NOTE: The accuracy of the CPU/OpenCL versions is a bit lower than CUDA version, so the results will very slightly vary. In practice, the different is barely noticeable, so you are safe using these.

This step is only supported for Intel CPUs on Ubuntu versions 16 and 14. It does not compile on Ubuntu 20, and we have not tested it on Ubuntu 18.

After setting the GPU_MODE flag to CPU_ONLY and clicking Configured, search for USE_MKL and set it to true. Then, click Configure again. This way, OpenPose will link against the Intel MKL version (Math Kernel Library) of Caffe. This speeds up CPU version on Ubuntu roughly about 2-3x, making it as fast as the Windows CPU-only version.

The default CPU version takes about 0.2 images per second on Ubuntu (~50x slower than GPU) while the MKL version provides a roughly 2x speedup at ~0.4 images per second. As of now OpenPose does not support MKL on Windows but will at a later date. Also, MKL version does not support unfixed resolution. So a folder of images of different resolutions requires a fixed net resolution (e.g., --net_resolution 656x368).

For MKL, the user can configure the environmental variables MKL_NUM_THREADS and OMP_NUM_THREADS. They are set at an optimum parameter level by default (i.e., to the number of threads of the machine). However, they can be tweak by running the following commands into the terminal window, right before running any OpenPose application. Eg:

# Optimal number = Number of threads (used by default)
export MKL_NUM_THREADS="8"
export OMP_NUM_THREADS="8"

Increasing the number of threads results in a higher RAM memory usage. You can check the doc/06_maximizing_openpose_speed.md for more information about speed and memory requirements in several CPUs and GPUs.

OpenCL Version

NOTE: The accuracy of the CPU/OpenCL versions is a bit lower than CUDA version, so the results will very slightly vary. In practice, the different is not barely noticeable, so you are safe using these.

If you have an AMD graphics card, you can compile OpenPose with the OpenCL option. To manually select the OpenCL Version, open CMake GUI mentioned above, and set the GPU_MODE flag to OPENCL (or non-UI CMake with GPU_MODE=OPENCL). Very important: If you compiled previously the CPU-only or CUDA versions on that same OpenPose folder, you will have to manually delete the build directory and run the installation steps from scratch. Otherwise, many weird errors will appear.

The OpenCL version has been tested on Ubuntu, Windows and OSX. This has been tested only on AMD Vega series and NVIDIA 10 series graphics cards. Please email us if you have issues with other operating systems or graphics cards. Running on OSX on a Mac with an AMD graphics card requires special instructions which can be seen in the section below.

Lastly, OpenCL version does not support unfixed --net_resolution. So a folder of images of different resolutions with OpenPose, requires the --net_resolution 656x368 flag for example. This should be fixed by the Caffe author in a future patch.

COCO and MPI Models

By default, the body COCO and MPI models are not downloaded (they are slower and less accurate than BODY_25, so not useful in most cases!). But you can download them by turning on the DOWNLOAD_BODY_COCO_MODEL or DOWNLOAD_BODY_MPI_MODEL flags. Check the differences between these models in doc/05_faq.md#difference-between-body_25-vs-coco-vs-mpi.

3D Reconstruction Module

You can include the 3D reconstruction module by:

  1. Install the FLIR camera software, Spinnaker SDK. It is a propietary software, so we cannot provide direct download link. Note: You might skip this step if you intend to use the 3-D OpenPose module with a different camera brand.
    1. Ubuntu: Get and install the latest Spinnaker SKD version in their default path. OpenPose will automatically find it. Otherwise, set the right path with CMake.
    2. Windows: Donwload the latest Spinnaker SKD version from https://www.ptgrey.com/support/downloads.
      • Copy {PointGreyParentDirectory}\Point Grey Research\Spinnaker\bin64\vs2015\ as {OpenPoseDirectory}\3rdparty\windows\spinnaker\bin\. You can remove all the *.exe files.
      • Copy {PointGreyParentDirectory}\Point Grey Research\Spinnaker\include\ as {OpenPoseDirectory}\3rdparty\windows\spinnaker\include\.
      • Copy Spinnaker_v140.lib and Spinnakerd_v140.lib from {PointGreyParentDirectory}\Point Grey Research\Spinnaker\lib64\vs2015\ into {OpenPoseDirectory}\3rdparty\windows\spinnaker\lib\.
      • (Optional) Spinnaker SDK overview: https://www.ptgrey.com/spinnaker-sdk.
  2. Install the 3D visualizer, FreeGLUT:
    1. Ubuntu: run sudo apt-get update && sudo apt-get install build-essential freeglut3 freeglut3-dev libxmu-dev libxi-dev and reboot your PC.
    2. Windows:
      1. It is automatically downloaded by the CMake installer.
      2. Alternatively, if you prefer to download it yourself, you could either:
        1. Double click on 3rdparty\windows\getFreeglut.bat.
        2. Download this version from our server and unzip it in {OpenPoseDirectory}\3rdparty\windows\freeglut\.
        3. Download the latest MSVC Package from http://www.transmissionzero.co.uk/software/freeglut-devel/.
          • Copy {freeglutParentDirectory}\freeglut\bin\x64\ as {OpenPoseDirectory}\3rdparty\windows\freeglut\bin\.
          • Copy {freeglutParentDirectory}\freeglut\include\ as {OpenPoseDirectory}\3rdparty\windows\freeglut\include\.
          • Copy {freeglutParentDirectory}\freeglut\lib\x64\ as {OpenPoseDirectory}\3rdparty\windows\freeglut\lib\.
  3. Follow the CMake installation steps. In addition, set the WITH_FLIR_CAMERA (only if Spinnaker was installed) and WITH_3D_RENDERER options.
  4. Increased accuracy with Ceres solver (Ubuntu only): For extra 3-D reconstruction accuracy, run sudo apt-get install libeigen3-dev, install Ceres solver, and enable WITH_CERES in CMake when installing OpenPose. Ceres is harder to install in Windows, so we have not tested it so far in there. Feel free to make a pull request if you do.

After installation, check the doc/advanced/3d_reconstruction_module.md instructions.

Calibration Module

The instrinsic camera calibration toolbox is included by default.

To enable the extrinsic camera parameter estimation toolbox, you must also enable WITH_EIGEN in CMake during CMake Configuration. You can perform any of the 3 following options (but only 1 of them!)

  • Recommended: Simply set the WITH_EIGEN flag to AUTOBUILD. CMake will automatically download Eigen and configure OpenPose to use it. If you prefer to download it manually (or if your firewall blocks CMake from downloading it):
  • Advanced (not recommended): If you set WITH_EIGEN to FIND, 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 (make sure that Eigen version is compatible with CUDA!):
    • Run sudo apt-get install libeigen3-dev and link CMake to the right CMake.
  • Advanced (not recommended): Or you could also use your own version of Eigen by setting WITH_EIGEN to AUTOBUILD, click Configure to let CMake download the zip file, and replace 3rdparty/eigen/ by your own version.

After installation, check the doc/advanced/calibration_module.md instructions.

Unity Compatible Version

Check Unity Plugin.

However, the OpenPose Unity version will crash if if faces an error while it is not used inside Unity. Thus, do not use it without Unity. Although this version would work as long as no errors occur.

Compiling without cuDNN

The cuDNN library is not mandatory, but required for full keypoint detection accuracy. In case your graphics card is not compatible with cuDNN, you can disable it by unchecking USE_CUDNN in CMake.

Then, you would have to reduce the --net_resolution flag to fit the model into the GPU memory. You can try values like 640x320, 320x240, 320x160, or 160x80 to see your GPU memory capabilities. After finding the maximum approximate resolution that your GPU can handle without throwing an out-of-memory error, adjust the net_resolution ratio to your image or video to be processed (see the --net_resolution explanation from doc/advanced/demo_advanced.md), or use -1 (e.g., --net_resolution -1x320).

Custom Caffe

OpenPose uses a custom fork of Caffe (rather than the official Caffe master). Our custom fork is only updated if it works on our machines, but we try to keep it updated with the latest Caffe version. This version works on a newly formatted machine (Ubuntu 16.04 LTS) and in all our machines (CUDA 8 and 10 tested). The default GPU version is the master branch, which it is also compatible with CUDA 10 without changes (official Caffe version might require some changes for it). We also use the OpenCL and CPU tags if their CMake flags are selected. We only modified some Caffe compilation flags and minor details.

Alternatively, you can use your own Caffe distribution on Ubuntu/Mac by 1) disabling BUILD_CAFFE, 2) setting Caffe_INCLUDE_DIRS to {CAFFE_PATH}/include/caffe, and 3) setting Caffe_LIBS to {CAFFE_PATH}/build/lib/libcaffe.so, as shown in the image below. Note that cuDNN-compatible Caffe version is required in order to get the maximum possible accuracy in OpenPose.

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.

For questions and issues, please only post on the related Pull Request #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.

In addition, peter-uhrig.de/openpose-with-nvcaffe-in-a-singularity-container-with-support-for-multiple-architectures/ contains a detailed step-by-step guide to install a portable container with NVCaffe and support for multiple NVidia cards as well as CPU.

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 --

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 --

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.

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 ..
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.

cmake -DOpenCV_INCLUDE_DIRS=/home/"${USER}"/softwares/opencv/build/install/include \
  -DOpenCV_LIBS_DIR=/home/"${USER}"/softwares/opencv/build/install/lib ..
cmake -DOpenCV_CONFIG_FILE=/home/"${USER}"/softwares/opencv/build/install/share/OpenCV/OpenCVConfig.cmake ..

Any Other Scenario

You can check the CMake online documentation to check all the options that CMake provides and its analogs to the CMake-gui ones that we show on this document.