diff --git a/CMakeLists.txt b/CMakeLists.txt index 6d853c947b08879c648b7180129112b4e146c5e9..cd73979b70de853a2ec891b022afadcd11d604d4 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -730,7 +730,7 @@ if (UNIX OR APPLE) set(CAFFE_CPU_ONLY OFF) if (${GPU_MODE} MATCHES "CUDA") # execute_process(COMMAND git checkout master WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/3rdparty/caffe) - execute_process(COMMAND git checkout c95002f WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/3rdparty/caffe) + execute_process(COMMAND git checkout b846ff9 WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/3rdparty/caffe) elseif (${GPU_MODE} MATCHES "CPU_ONLY") if (USE_MKL) #execute_process(COMMAND git checkout intel WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/3rdparty/caffe) @@ -766,7 +766,7 @@ if (UNIX OR APPLE) ) else (USE_MKL) # execute_process(COMMAND git checkout master WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/3rdparty/caffe) - execute_process(COMMAND git checkout c95002f WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/3rdparty/caffe) + execute_process(COMMAND git checkout b846ff9 WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/3rdparty/caffe) endif (USE_MKL) set(CAFFE_CPU_ONLY ON) set(USE_CUDNN OFF) diff --git a/cmake/Cuda.cmake b/cmake/Cuda.cmake index acd193a57fb32ace9198df46be351a9504b1d099..1448fdc195b11beb551b7d12d6d3bd09f4576e60 100644 --- a/cmake/Cuda.cmake +++ b/cmake/Cuda.cmake @@ -234,7 +234,11 @@ function(detect_cuDNN) set(HAVE_CUDNN TRUE PARENT_SCOPE) set(CUDNN_FOUND TRUE PARENT_SCOPE) - file(READ ${CUDNN_INCLUDE}/cudnn.h CUDNN_VERSION_FILE_CONTENTS) + if(EXISTS "${CUDNN_INCLUDE}/cudnn_version.h") + file(READ ${CUDNN_INCLUDE}/cudnn_version.h CUDNN_VERSION_FILE_CONTENTS) + else() + file(READ ${CUDNN_INCLUDE}/cudnn.h CUDNN_VERSION_FILE_CONTENTS) + endif() # cuDNN v3 and beyond string(REGEX MATCH "define CUDNN_MAJOR * +([0-9]+)" diff --git a/cmake/Modules/FindCuDNN.cmake b/cmake/Modules/FindCuDNN.cmake index 82ee365a6e12c56661587ca2b02a870022123eb4..182ee271c398a2f4c905d1f8b2b63a18c51b2d05 100644 --- a/cmake/Modules/FindCuDNN.cmake +++ b/cmake/Modules/FindCuDNN.cmake @@ -14,7 +14,11 @@ if(CUDNN_INCLUDE AND CUDNN_LIBRARY) set(HAVE_CUDNN TRUE) set(CUDNN_FOUND TRUE) - file(READ ${CUDNN_INCLUDE}/cudnn.h CUDNN_VERSION_FILE_CONTENTS) + if(EXISTS "${CUDNN_INCLUDE}/cudnn_version.h") + file(READ ${CUDNN_INCLUDE}/cudnn_version.h CUDNN_VERSION_FILE_CONTENTS) + else() + file(READ ${CUDNN_INCLUDE}/cudnn.h CUDNN_VERSION_FILE_CONTENTS) + endif() # cuDNN v3 and beyond string(REGEX MATCH "define CUDNN_MAJOR * +([0-9]+)" diff --git a/doc/faq.md b/doc/faq.md index 731acff57565777fe38bdad8f1c9376149e41a94..ec73ee9a316ad3dfdbfed7866533d98c6393de8e 100644 --- a/doc/faq.md +++ b/doc/faq.md @@ -194,7 +194,10 @@ git submodule update #### Obscure CMake Error about Caffe or Pybind **Q:** There appear some weird and obscure errors on CMake about Caffe and/or Pybind. -**A**: Check [doc/prerequisites.md#general-tips](./prerequisites.md#general-tips) to run the `git submodule` command. +**A**: Check [doc/installation.md](./installation.md) to run the `git submodule` command, i.e., +``` +git submodule update --init --recursive --remote +``` diff --git a/doc/installation.md b/doc/installation.md index c0af3d9bc3c56d93a29170f710393bbb847a5125..b497826bdfca206188229618c287e90d5d31a23a 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -2,19 +2,19 @@ OpenPose - Installation ========================== ## Contents -1. [Windows Portable Demo](#windows-portable-demo) -2. [Installation Video Tutorials](#windows-portable-demo) -3. [Operating Systems](#operating-systems) -4. [Community-Based Work](#community-based-work) -5. [Requirements and Dependencies](#requirements-and-dependencies) -6. [Clone OpenPose](#clone-openpose) -7. [Update OpenPose](#update-openpose) -8. [Installation](#installation) -9. [Alternative Windows Instructions](#alternative-windows-instructions) -10. [Reinstallation](#reinstallation) -11. [Uninstallation](#uninstallation) -12. [Deploying OpenPose (Exporting OpenPose to Other Projects)](#deploying-openpose-exporting-openpose-to-other-projects) -13. [Optional Settings](#optional-settings) +1. [Operating Systems, Requirements, and Dependencies](#operating-systems-requirements-and-dependencies) +2. [Windows Portable Demo](#windows-portable-demo) +3. [Compiling and Running OpenPose from Source on Windows, Ubuntu, and Mac](#compiling-and-running-openpose-from-source-on-windows-ubuntu-and-mac) + 1. [Problems and Errors Installing OpenPose](#problems-and-errors-installing-openpose) + 2. [Clone OpenPose](#clone-openpose) + 3. [Prerequisites](#prerequisites) + 4. [CMake Configuration](#cmake-configuration) + 5. [Compilation](#compilation) + 6. [Running OpenPose](#running-openpose) +4. [Compiling and Running OpenPose from Source on ROS, Docker, and Google Colab - Community-Based Work](#compiling-and-running-openpose-from-source-on-ros-docker-and-google-colab-community-based-work) +5. [Uninstalling, Reinstalling, or Updating OpenPose](#Uninstalling-reinstalling-or-updating-openpose) +6. [Deploying or Exporting OpenPose to Other Projects](#deploying-or-exporting-openpose-to-other-projects) +7. [Advanced Settings](#advanced-settings) 1. [Maximum Speed](#maximum-speed) 2. [COCO and MPI Models](#coco-and-mpi-models) 3. [Python API](#python-api) @@ -33,63 +33,18 @@ OpenPose - Installation -## Windows Portable Demo -**If you just want to use the OpenPose demo in Windows**, simply use the latest version of the OpenPose portable binaries which you can download in the [Releases](https://github.com/CMU-Perceptual-Computing-Lab/openpose/releases) section. Read the `Instructions.txt` inside the downloaded files to learn to download the models required by OpenPose (about 500 Mb). - -The installation documentation in the following sections is only intended 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. - - - - -## Installation Video Tutorials -User-created tutorial videos: -- OpenPose + Visual Studio 2017 + CUDA 10.0 + cuDNN 7.5 (no portable demo): [https://youtu.be/QC9GTb6Wsb4](https://youtu.be/QC9GTb6Wsb4). For questions, post in GitHub issue #1426. - -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. - - - -## 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 examples: - - [ROS example 1](https://github.com/ravijo/ros_openpose). For questions and more details, read and post ONLY on [issue thread #891](https://github.com/CMU-Perceptual-Computing-Lab/openpose/issues/891). - - [ROS example 2](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: - - Option 1: - - 1. (if necessary) Install the latest version of docker (There are extra steps, but if you're on Ubuntu, the main one is `sudo apt-get install docker-ce`. Other steps can be found [here](https://phoenixnap.com/kb/how-to-install-docker-on-ubuntu-18-04) ) - - 2. `docker pull exsidius/openpose` - [Guide](https://github.com/gormonn/openpose-docker/blob/master/README.md) - - 3. [more details](https://cloud.docker.com/repository/docker/exsidius/openpose/general) - - [Link 2](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 3](https://github.com/ExSidius/openpose-docker/blob/master/Dockerfile). - - [Link 4](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): +## Operating Systems, Requirements, and Dependencies +- Operating Systems + - **Windows 10**. + - **Ubuntu 20**. + - **Mac OSX** Mavericks and above. + - **Ubuntu 14, 16 and 18** as well as **Windows 7 and 8** are no longer officially maintained. However, they should still work (but might require minor changes). + - **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 **CentOS** and other **Nvidia Jetson (TK1)** embedded systems. However, we do not officially support them at the moment. +- **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). @@ -100,6 +55,7 @@ We add links to some community-based work based on OpenPose. Note: We do not sup - 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 (gines@alumni.cmu.edu) or feel free to make a pull request if you implemented any of those! @@ -109,45 +65,33 @@ We add links to some community-based work based on OpenPose. Note: We do not sup - -## Clone OpenPose -The first step is to clone the OpenPose repository. - -1. Windows: You might use [GitHub Desktop](https://desktop.github.com/). -2. Ubuntu/Mac: -```bash -git clone https://github.com/CMU-Perceptual-Computing-Lab/openpose -``` - - - +## Windows Portable Demo +**If you just want to use OpenPose in Windows** without compiling or writing any code, simply download and use the latest portable version of OpenPose. You can download it in the [Releases](https://github.com/CMU-Perceptual-Computing-Lab/openpose/releases) section. Read the `Instructions.txt` inside the downloaded files to learn to download the models required by OpenPose (about 500 Mb). -## 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. +## Compiling and Running OpenPose from Source on Windows, Ubuntu, and Mac +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. -## Installation -The instructions in this section describe the steps to build OpenPose using CMake (GUI). There are 3 main steps: +### Problems and Errors Installing OpenPose +Any problem installing OpenPose while following this guidelines? 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. -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) +### Clone OpenPose +The first step is to clone the OpenPose repository. -### 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. +1. Windows: You might use [GitHub Desktop](https://desktop.github.com/). +2. Ubuntu/Mac: +```bash +git clone https://github.com/CMU-Perceptual-Computing-Lab/openpose +cd openpose/ +git submodule update --init --recursive --remote +``` @@ -156,46 +100,54 @@ Make sure to download and install the prerequisites for your particular operatin -### 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`. +### CMake Configuration +1. Go to the OpenPose folder and open CMake-GUI from it: +``` +cd {OpenPose_folder} +mkdir build/ +cd build/ +cmake-gui .. +``` +2. 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. 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 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. 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. +5. Press the `Generate` button and proceed to [Compilation](#compilation). 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 +### Compilation #### Ubuntu -Build the project by running the following commands. +Run the following commands in your terminal. ```bash cd build/ make -j`nproc` ``` #### Mac -Build the project by running the following commands (note that Mac provides both `logicalcpu` and `physicalcpu`, but we want the logical number for maximum speed). +Run the following commands in your terminal: ```bash 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. #### Windows In order to build the project, select and run only one of the 2 following alternatives. @@ -220,58 +172,83 @@ In order to build the project, select and run only one of the 2 following altern **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: +- OpenPose for Windows 10, Visual Studio 2019, CMake, and Nvidia GPU: [https://github.com/quickgrid/Build-Guide/blob/master/README.md#windows-10-cmu-openpose-setup-visual-studio-2019-cmake-nvidia-gpu](https://github.com/quickgrid/Build-Guide/blob/master/README.md#windows-10-cmu-openpose-setup-visual-studio-2019-cmake-nvidia-gpu). +- Video-tutorial: OpenPose + Visual Studio 2017 + CUDA 10.0 + cuDNN 7.5 (no portable demo): [https://youtu.be/QC9GTb6Wsb4](https://youtu.be/QC9GTb6Wsb4). For questions, post in GitHub issue #1426. + +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. -### Run OpenPose + +### Running 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). -## Alternative Windows Instructions -If you are facing errors with these instructions, these are a set of alternative instructions created by the community for Windows 10, Visual Studio 2019, CMake, and Nvidia GPU: [https://github.com/quickgrid/Build-Guide/blob/master/README.md#windows-10-cmu-openpose-setup-visual-studio-2019-cmake-nvidia-gpu](https://github.com/quickgrid/Build-Guide/blob/master/README.md#windows-10-cmu-openpose-setup-visual-studio-2019-cmake-nvidia-gpu). +### Compiling and Running OpenPose from Source on ROS, Docker, and Google Colab - Community-Based Work +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. + +- ROS examples: + - [ROS example 1](https://github.com/ravijo/ros_openpose). For questions and more details, read and post ONLY on [issue thread #891](https://github.com/CMU-Perceptual-Computing-Lab/openpose/issues/891). + - [ROS example 2](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: + - Option 1: + - 1. (if necessary) Install the latest version of docker (There are extra steps, but if you're on Ubuntu, the main one is `sudo apt-get install docker-ce`. Other steps can be found [here](https://phoenixnap.com/kb/how-to-install-docker-on-ubuntu-18-04) ) + - 2. `docker pull exsidius/openpose` - [Guide](https://github.com/gormonn/openpose-docker/blob/master/README.md) + - 3. [more details](https://cloud.docker.com/repository/docker/exsidius/openpose/general) + - [Link 2](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 3](https://github.com/ExSidius/openpose-docker/blob/master/Dockerfile). + - [Link 4](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). -## Reinstallation -In order to re-install OpenPose: -1. (Ubuntu and Mac) If you ran `sudo make install`, then run `sudo make uninstall` in `build/`. -2. Delete the `build/` folder. -3. In CMake GUI, click on `File` --> `Delete Cache`. -4. Follow the [Installation](#installation) steps again. -## Uninstallation -In order to uninstall OpenPose: -1. (Ubuntu and Mac) If you ran `sudo make install`, then run `sudo make uninstall` in `build/`. +## 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 on Windows, Ubuntu, and Mac](#compiling-and-running-openpose-from-source-on-windows-ubuntu-and-mac) steps again. + + + -## Deploying OpenPose (Exporting OpenPose to Other Projects) +## Deploying or Exporting OpenPose to Other Projects See [doc/deployment.md](./deployment.md). -### Optional Settings -#### Maximum Speed +## Advanced Settings +### Maximum Speed Check the OpenPose Benchmark as well as some hints to speed up and/or reduce the memory requirements for OpenPose on [doc/speed_up_openpose.md](./speed_up_openpose.md). -#### COCO and MPI Models +### COCO and MPI Models By default, the body COCO and MPI models are not downloaded. You can download them by turning on the `DOWNLOAD_BODY_COCO_MODEL` or `DOWNLOAD_BODY_MPI_MODEL` flags. It's slightly faster but less accurate and has less keypoints than the COCO body model. Note: Check the differences between these models in [doc/faq.md#difference-between-body_25-vs-coco-vs-mpi](./faq.md#difference-between-body_25-vs-coco-vs-mpi). -#### Python API +### Python API To install the Python API, ensure that the `BUILD_PYTHON` flag is turned on while running CMake GUI and follow the standard installation steps. After the installation, check [doc/modules/python_module.md](./modules/python_module.md) for further details. -#### CPU Version +### CPU Version To manually select the CPU Version, open CMake GUI mentioned above, and set the `GPU_MODE` flag to `CPU_ONLY`. **NOTE: Accuracy of the CPU version is ~1% higher than CUDA version, so the results will vary.** - On Ubuntu, OpenPose will link against the Intel MKL version (Math Kernel Library) of Caffe. Alternatively, the user can choose his own Caffe version, by unselecting `USE_MKL` and selecting his own Caffe path. @@ -291,7 +268,7 @@ Do note that increasing the number of threads results in more memory use. You ca -#### OpenCL Version +### OpenCL Version 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`. **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. @@ -300,7 +277,7 @@ Lastly, OpenCL version does not support unfixed `--net_resolution`. So a folder -#### Mac OSX Version +### Mac OSX Version Mac OSX Version compiles similarly to the Ubuntu version. Take a look at the prerequisites section. For GPU acceleration, OpenPose may be built with OpenCL support (check [OpenCL Version](#opencl-version) or add in CMake`GPU_MODE=OPENCL`). If you have a Mac with an inbuilt AMD graphics card, you have to manually select your AMD GPU. To do that, first note which device your Graphics card is set under: ```bash @@ -335,7 +312,7 @@ cd 3rdparty/caffe; git apply ../../scripts/osx/mac_opencl_patch.txt ``` -#### 3D Reconstruction Module +### 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. @@ -363,28 +340,28 @@ After installation, check the [doc/modules/3d_reconstruction_module.md](./module -#### Calibration Module +### Calibration Module The calibration module is included by default, but you must also enable `WITH_EIGEN` if you intend to use the extrinsic camera parameter estimation tool. You can set that flag to 2 different values: `BUILD` or `FIND`, check [Requirements and Dependencies](#requirements-and-dependencies) for more information. After installation, check the [doc/modules/calibration_module.md](./modules/calibration_module.md) instructions. -#### Unity Compatible Version +### Unity Compatible Version Check [**Unity Plugin**](https://github.com/CMU-Perceptual-Computing-Lab/openpose_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 +### Compiling without cuDNN The [cuDNN](https://developer.nvidia.com/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/demo_overview.md](./demo_overview.md)), or use `-1` (e.g., `--net_resolution -1x320`). -#### Custom Caffe +### Custom Caffe OpenPose uses a [custom fork of Caffe](https://github.com/CMU-Perceptual-Computing-Lab/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. @@ -396,7 +373,7 @@ For Windows, simply replace the OpenCV DLLs and include folder for your custom o -#### Custom NVIDIA NVCaffe +### 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). @@ -415,17 +392,17 @@ In addition, [peter-uhrig.de/openpose-with-nvcaffe-in-a-singularity-container-wi -#### Custom OpenCV +### 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) +### 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) +### 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 -- @@ -437,13 +414,13 @@ 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` +#### 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 +#### 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 \ @@ -458,7 +435,7 @@ cmake -DOpenCV_CONFIG_FILE=/home/"${USER}"/softwares/opencv/build/install/share/ -DCaffe_LIBS=/home/"${USER}"/softwares/caffe/build/install/lib/libcaffe.so -DBUILD_CAFFE=OFF .. ``` -##### Scenario 3 - OpenCV already installed +#### 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 \ @@ -469,5 +446,5 @@ cmake -DOpenCV_INCLUDE_DIRS=/home/"${USER}"/softwares/opencv/build/install/inclu cmake -DOpenCV_CONFIG_FILE=/home/"${USER}"/softwares/opencv/build/install/share/OpenCV/OpenCVConfig.cmake .. ``` -##### Any Other Scenario +#### 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. diff --git a/doc/installation_deprecated.md b/doc/installation_deprecated.md index 1a839d48b89baacc2d511b774ae0c7c647b9c766..4728aa5ecdd2f1c4ed13e094a69a3483f55f5ce7 100644 --- a/doc/installation_deprecated.md +++ b/doc/installation_deprecated.md @@ -174,11 +174,7 @@ If you updated some software that our library or 3rdparty use, or you simply wan ## Doxygen Documentation Autogeneration -You can generate the documentation by running the following command. 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). -``` -cd doc/ -doxygen doc_autogeneration.doxygen -``` +See [doc/installation.md#doxygen-documentation-autogeneration-ubuntu-only](./installation.md#doxygen-documentation-autogeneration-ubuntu-only). @@ -200,9 +196,4 @@ We only modified some Caffe compilation flags and minor details. You can use you ## Compiling without cuDNN -The [cuDNN](https://developer.nvidia.com/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: - -- Ubuntu: Disable `USE_CUDNN` in the `Makefile.config` file in `3rdparty/caffe`, and recompiling Caffe. -- Windows: Compiling Caffe by your own with without cuDNN support and replacing the [3rdparty/windows/caffe](../3rdparty/windows/caffe)) folder by your own implementation. - -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/demo_overview.md](./demo_overview.md)). +See [doc/installation.md#compiling-without-cudnn](./installation.md#compiling-without-cudnn). diff --git a/doc/prerequisites.md b/doc/prerequisites.md index 9877295849f571b5b5dc4d9eb80f3718b1a9275c..cfb2be7cb515e08f4ba1c977ee6bbbd5ef8142ac 100644 --- a/doc/prerequisites.md +++ b/doc/prerequisites.md @@ -21,17 +21,12 @@ You might prefer to download them manually: - [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)](./installation.md#cmake-command-line-configuration-ubuntu-only). + - Ubuntu 20: Run the command `sudo apt-get install cmake-qt-gui`. - 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`. - Install OpenSSL for building CMake by running `sudo apt install libssl-dev`. @@ -41,25 +36,28 @@ git submodule update --init --recursive --remote - 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`. + - 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)](./installation.md#cmake-command-line-configuration-ubuntu-only). 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. + 1. **Note: OpenPose has been tested extensively with CUDA 8.0 (cuDNN 5.1) for Ubuntu 14 and 16, CUDA 10.1 (cuDNN 7.5) for Ubuntu 18, and CUDA 11 for Ubuntu 20**. We highly recommend using those versions for those Operating Systems 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**: + - Ubuntu 20 ([**CUDA 11.1**](https://developer.nvidia.com/cuda-downloads)): Download CUDA 11.1 from their [official website](https://developer.nvidia.com/cuda-downloads). Most Ubuntu computers use the `Architecture` named `x86_64`, and we personally recommend the `Installer Type` named `runfile (local)`. Then, follow the Nvidia website installation instructions. When installing, make sure to enable the symbolic link in `usr/local/cuda` to minimize potential future errors. + - Ubuntu 18 ([**CUDA 10.1**](https://developer.nvidia.com/cuda-10.1-download-archive-base)): Analog to the instructions for Ubuntu 20, but using CUDA version 10.1. - Ubuntu 14 or 16 ([**CUDA 8**](https://developer.nvidia.com/cuda-80-ga2-download-archive) **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**](https://developer.nvidia.com/cuda-downloads)): Download the latest Nvidia CUDA version from their [official website](https://developer.nvidia.com/cuda-downloads). - - 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**](https://developer.nvidia.com/rdp/cudnn-archive) **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**](https://developer.nvidia.com/cudnn)): Download and install it from the [Nvidia website](https://developer.nvidia.com/cudnn). - - 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. -5. AMD GPU version prerequisites: - 1. Ubuntu 14 or 16: + - Download it (usually called `cuDNN Library for Linux (x86_64)`): + - Ubuntu 20: [**cuDNN 8.0.4**](https://developer.nvidia.com/cudnn). + - Ubuntu 18: [**cuDNN 7.5**](https://developer.nvidia.com/rdp/cudnn-archive). + - 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 it from their website](https://developer.nvidia.com/rdp/cudnn-archive). + - And install it: + - In order to manually install it (any version), just unzip it and copy (merge) its contents on the CUDA folder, usually `/usr/local/cuda-{version}/` in Ubuntu and `C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v{version}\` in Windows. +5. AMD GPU version prerequisites (only if you do not have an Nvidia GPU and want to run on AMD graphic cards): + - Ubuntu 20 or 18: Not tested and not officially supported. Try at your own risk. You might want to use the CPU version if no Nvidia GPU is available. + - Ubuntu 14 or 16: 1. Download 3rd party ROCM driver for Ubuntu from [**AMD - OpenCL**](https://rocm.github.io/ROCmInstall.html). 2. Install `sudo apt-get install libviennacl-dev`. - 2. Ubuntu 18: Not tested and not officially supported. Try at your risk. 6. 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. + - OpenCV must be already installed on your machine. It can be installed with `sudo apt-get install libopencv-dev`. You could also use your own compiled OpenCV version. + - 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.sh` after installing your desired CUDA and cuDNN versions. If you are using Ubuntu 14 or 16, you can simply run `sudo bash ./scripts/ubuntu/install_deps_and_cuda.sh` (if Ubuntu 16 or 14 and for Graphic cards up to 10XX). 7. **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](https://bitbucket.org/eigen/eigen/commits/034b6c3e101792a3cc3ccabd9bfaddcabe85bb58?at=default). 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: diff --git a/doc/release_notes.md b/doc/release_notes.md index 1111f9df62d7b466147d9a5041e75c39749efb1d..358294392239eaf0ddd2bec8e21959302418e345 100644 --- a/doc/release_notes.md +++ b/doc/release_notes.md @@ -418,6 +418,9 @@ OpenPose Library - Release Notes 1. Main improvements: 1. Some parts of the documentation have been explained better. 2. Added `DOWNLOAD_SERVER` variable to CMake. It specifies the link where the models and 3rd party libraries will be downloaded from. + 3. Added Asynchronous mode to Python API. + 4. Added compatibility with Ubuntu 20.04, CUDA 11.X, and cuDNN 8.0.X. + 5. Installation documentation highly simplified and improved. 2. Functions or parameters renamed: 3. Main bugs fixed: 1. 90 and 270-degree rotations working again.