Docker enhancement and update doc (#359)

* feat: enable pifpaf inference support * refact: rm comments * feat: openpifpaf decoder finalized * fix: ci * fix: license badge * fix: gcc7 compilation * fix: conflicts w/ master branch ++ * feat: pifpaf with larger resolution * feat: update model installation * refact: update C++ doc * refact: update dockerfile and doc

Author: ganler

.gitignore

@@ -1,3 +1,4 @@
+pre_installed_models
 __pycache__
 .DS_Store
 .idea

Dockerfile

@@ -5,8 +5,11 @@
 # Based on CUDA11.0 & CuDNN8
 FROM nvidia/cuda:10.2-devel-ubuntu18.04
 
+# Test connection
+RUN apt update --allow-unauthenticated && apt install -y wget && wget www.google.com
+
 # Install Non-GPU Dependencies.
-RUN apt update --allow-unauthenticated && version="7.0.0-1+cuda10.2" ; \
+RUN version="7.0.0-1+cuda10.2" ; \
  apt install -y \
  libnvinfer7=${version} libnvonnxparsers7=${version} libnvparsers7=${version} \
  libnvinfer-plugin7=${version} libnvinfer-dev=${version} libnvonnxparsers-dev=${version} \
@@ -15,6 +18,9 @@ RUN apt update --allow-unauthenticated && version="7.0.0-1+cuda10.2" ; \
  apt-mark hold \
  libnvinfer7 libnvonnxparsers7 libnvparsers7 libnvinfer-plugin7 libnvinfer-dev libnvonnxparsers-dev libnvparsers-dev libnvinfer-plugin-dev python-libnvinfer python3-libnvinfer
 
+# Set apt-get to automatically retry if a package download fails
+RUN echo 'Acquire::Retries "5";' > /etc/apt/apt.conf.d/99AcquireRetries
+
 # Install OpenCV Dependencies
 RUN apt install -y software-properties-common || apt install -y software-properties-common && \
  add-apt-repository "deb http://security.ubuntu.com/ubuntu xenial-security main" && \
@@ -23,8 +29,8 @@ RUN apt install -y software-properties-common || apt install -y software-propert
  python3 -m pip install numpy
 
 # Compile OpenCV
-RUN git clone --branch 4.4.0 https://github.com/opencv/opencv.git && \
- cd opencv && mkdir build && cd build && \
+RUN apt install -y zip && wget https://github.com/opencv/opencv/archive/refs/tags/4.4.0.zip && unzip 4.4.0.zip && \
+ cd opencv-4.4.0 && mkdir build && cd build && \
  cmake .. -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=/usr/local \
  -DWITH_TBB=ON \
@@ -38,7 +44,12 @@ RUN apt install -y python3-dev python3-pip subversion libgflags-dev
 
 COPY . /hyperpose
 
-# Download related data
+# Get models
+# NOTE: if you cannot install the models due to network issues:
+# 1 Manually install ONNX and UFF models through: https://drive.google.com/drive/folders/1w9EjMkrjxOmMw3Rf6fXXkiv_ge7M99jR
+# 2 Put all models into `${GIT_DIR}/pre_installed_models`
+# 3.1 `RUN /hyperpose/scripts/download-test-data.sh`
+# 3.2 `RUN mv /hyperpose/pre_installed_models /hyperpose/data/models`
 RUN for file in $(find /hyperpose/scripts -type f -iname 'download*.sh'); do sh $file; done
 
 # Build Repo
@@ -47,4 +58,4 @@ RUN cd hyperpose && mkdir build && cd build && \
 
 WORKDIR /hyperpose/build
 
-ENTRYPOINT ["./hyperpose-cli"]
+ENTRYPOINT ["./hyperpose-cli"]

README.md

@@ -50,7 +50,7 @@ Make sure you have [docker](https://docs.docker.com/get-docker/) with [nvidia-do
 
 ```bash
 # [Example 1]: Doing inference on given video, copy the output.avi to the local path. 
-docker run --name quick-start --gpus all tensorlayer/hyperpose --runtime=stream
+docker run --rm --name quick-start --gpus all tensorlayer/hyperpose --runtime=stream
 docker cp quick-start:/hyperpose/build/output.avi .
 docker rm quick-start
 
@@ -84,7 +84,7 @@ We compare the prediction performance of HyperPose with [OpenPose 1.6](https://g
 | OpenPose (TinyVGG) | 34.7 MB | 384 x 256 | **124.925 FPS** | N/A |
 | OpenPose (MobileNet) | 17.9 MB | 432 x 368 | **84.32 FPS** | 8.5 FPS (TF-Pose) |
 | OpenPose (ResNet18) | 45.0 MB | 432 x 368 | **62.52 FPS** | N/A |
-| OpenPifPaf (ResNet50) | 97.6 MB | 97 x 129 | **178.6 FPS** | 35.3  |
+| OpenPifPaf (ResNet50) | 97.6 MB | 432 x 368 | **44.16 FPS** | 14.5 FPS (OpenPifPaf) |
 
 ## Accuracy
 We evaluate accuracy of pose estimation models developed by hyperpose (mainly over Mscoco2017 dataset). the development environment is Ubuntu16.04, with 4 V100-DGXs and 24 Intel Xeon CPU. The training procedure takes 1~2 weeks using 1 V100-DGX for each model. (If you want to train from strach, loading the pretrained backbone weight is recommended.)

docs/markdown/install/prediction.md

@@ -1,6 +1,11 @@
 # C++ Prediction Library Installation
 
-## Docker Environment Installation
+Note that C++ prediction library requires NVidia GPU acceleration.
+ 
+Thought it is built to be platform-independent, the C++ library is mostly tested on Linux Platforms.
+So we recommend you to build it on Linux platforms. 
+
+## Docker Environment Installation (RECOMMENDED)
 
 To ease the installation, you can use HyperPose library in our docker image where the environment is pre-installed.
 
@@ -15,7 +20,7 @@ The official image is on [DockerHub](https://hub.docker.com/r/tensorlayer/hyperp
 docker pull tensorlayer/hyperpose
 
 # Dive into the image. (Connect local camera and imshow window)
-xhost +; docker run --gpus all -it -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix --device=/dev/video0:/dev/video0 --entrypoint /bin/bash tensorlayer/hyperpose
+xhost +; docker run --rm --gpus all -it -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix --device=/dev/video0:/dev/video0 --entrypoint /bin/bash tensorlayer/hyperpose
 # For users that cannot access a camera or X11 server. You may also use:
 # docker run --rm --gpus all -it --entrypoint /bin/bash tensorlayer/hyperpose
 ```
@@ -28,7 +33,7 @@ Note that the entry point is the [`hyperpose-cli`](https://hyperpose.readthedocs
 # Enter the repository folder.
 USER_DEF_NAME=my_hyperpose
 docker build -t $(USER_DEF_NAME) .
-docker run --gpus all $(USER_DEF_NAME)
+docker run --rm --gpus all $(USER_DEF_NAME)
 ```
 
 ## Build From Source
@@ -46,7 +51,7 @@ docker run --gpus all $(USER_DEF_NAME)
 
 > **About TensorRT installation**
 >
-> - For Linux users, you highly recommended to install it in a system-wide setting. You can install TensorRT7 via the [debian distributions](https://docs.nvidia.com/deeplearning/tensorrt/install-guide/index.html#installing-debian) or [NVIDIA network repo](https://docs.nvidia.com/deeplearning/tensorrt/install-guide/index.html#maclearn-net-repo-install)(CUDA and CuDNN dependency will be automatically installed).
+> - For Linux users, you are highly recommended to install it in a system-wide setting. You can install TensorRT7 via the [debian distributions](https://docs.nvidia.com/deeplearning/tensorrt/install-guide/index.html#installing-debian) or [NVIDIA network repo](https://docs.nvidia.com/deeplearning/tensorrt/install-guide/index.html#maclearn-net-repo-install)(CUDA and CuDNN dependency will be automatically installed).
 > - Different TensorRT version requires specific CUDA and CuDNN version. For specific CUDA and CuDNN requirements of TensorRT7, please refer to [this](https://docs.nvidia.com/deeplearning/tensorrt/support-matrix/index.html#platform-matrix).
 > - Also, for Ubuntu 18.04 users, this [3rd party blog](https://ddkang.github.io/2020/01/02/installing-tensorrt.html) may help you. 
 

docs/markdown/quick_start/prediction.md

@@ -27,10 +27,14 @@ sh scripts/download-test-data.sh
 # cd to the git repo. And download pre-trained models you want. 
 
 sh scripts/download-openpose-thin-model.sh # ~20 MB
-sh scripts/download-tinyvgg-model.sh # ~30 MB
+sh scripts/download-tinyvgg-model.sh # ~30 MB (UFF model)
 sh scripts/download-openpose-res50-model.sh # ~45 MB
 sh scripts/download-openpose-coco-model.sh # ~200 MB
-sh scripts/download-ppn-res50-model.sh # ~50 MB (PoseProposal Algorithm)
+sh scripts/download-openpose-mobile-model.sh
+sh scripts/download-tinyvgg-v2-model.sh
+sh scripts/download-openpose-mobile-model.sh
+sh scripts/download-openpifpaf-model.sh # ~98 MB (OpenPifPaf)
+sh scripts/download-ppn-res50-model.sh # ~50 MB (PoseProposal)
 ```
 
 > You can download them manually to `${HyperPose}/data/models/` via [LINK](https://drive.google.com/drive/folders/1w9EjMkrjxOmMw3Rf6fXXkiv_ge7M99jR?usp=sharing) **if the network is not working**.
@@ -77,20 +81,20 @@ Note that the entry point of our official docker image is also `hyperpose-cli` i
 ```bash
 ./hyperpose-cli --model ../data/models/openpose-thin-V2-HW=368x432.onnx --w 432 --h 368 
 
-./hyperpose-cli --model ../data/models/openpose-coco-V2-HW=368x656.onnx --w 656 --h 368 
+./hyperpose-cli --model ../data/models/openpose-coco-V2-HW=368x656.onnx --w 656 --h 368  
 ```
 
-### Use PoseProposal model
+### Use PifPaf model
 
 ```bash
-./hyperpose-cli --model ../data/models/ppn-resnet50-V2-HW=384x384.onnx --w 384 --h 384 --post=ppn
+./hyperpose-cli --model ../data/models/openpifpaf-resnet50-HW=368x432.onnx --w 368 --h 432 --post pifpaf
 ```
 
 ### Convert models into TensorRT Engine Protobuf format
 
 You may find that it takes one or two minutes before the real prediction starts. This is because TensorRT will try to profile the model to get a optimized runtime model. 
 
-To save the model conversion time, you can convert it in advance.
+To save the model conversion time, you can pre-compile it in advance.
 
 ```bash
 ./example.gen_serialized_engine --model_file ../data/models/openpose-coco-V2-HW=368x656.onnx --input_width 656 --input_height 368 --max_batch_size 20
@@ -124,4 +128,3 @@ The output video will be in the building folder.
 ./hyperpose-cli --source=camera
 # Note that camera mode is not compatible with Stream API. If you want to do inference on your camera in real time, the Operator API is designed for it.
 ```
-

docs/markdown/tutorial/prediction.md

@@ -57,7 +57,7 @@ using namespace hyperpose;
 
 // To use a Uff model, users needs to specify the input/output nodes.
 // Here, `image` is the input node name, and `outputs/conf` and `outputs/paf` are the output feature maps. (related to the PAF algorithm)
-const dnn::uff uff_model{ "../data/models/hao28-600000-256x384.uff", "image", {"outputs/conf", "outputs/paf"} };
+const dnn::uff uff_model{ "../data/models/TinyVGG-V1-HW=256x384.uff", "image", {"outputs/conf", "outputs/paf"} };
 ```
 
 ### Create Input / Output Stream
@@ -208,4 +208,4 @@ for (size_t i = 0; i < batch.size(); ++i) {
 
 ### Full example
 
-Full examples are available [here](../design/design.md).
+Full examples are available [here](../design/design.md).

scripts/download-openpifpaf-model.sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+
+set -e
+
+[ "$(command -v gdown)" ] || (echo "Downloading gdown via PIP" && python3 -m pip install gdown -U)
+
+model_name="openpifpaf-resnet50-HW=368x432.onnx"
+
+BASEDIR=$(realpath "$(dirname "$0")")
+cd "$BASEDIR"
+mkdir -p ../data/models
+cd ../data/models
+
+python3 "$BASEDIR/downloader.py" --model $model_name

scripts/download-openpose-coco-model.sh

@@ -2,12 +2,12 @@
 
 set -e
 
-[ $(which gdown) ] || (echo "Downloading gdown via PIP" && python3 -m pip install gdown -U)
+[ "$(command -v gdown)" ] || (echo "Downloading gdown via PIP" && python3 -m pip install gdown -U)
 
 model_name="openpose-coco-V2-HW=368x656.onnx"
 
-BASEDIR=$(realpath "$(dirname $0)")
-cd $BASEDIR
+BASEDIR=$(realpath "$(dirname "$0")")
+cd "$BASEDIR"
 mkdir -p ../data/models
 cd ../data/models
 

scripts/download-openpose-mobile-model.sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+
+set -e
+
+[ "$(command -v gdown)" ] || (echo "Downloading gdown via PIP" && python3 -m pip install gdown -U)
+
+model_name="openpose-mobile-HW=342x368.onnx"
+
+BASEDIR=$(realpath "$(dirname "$0")")
+cd "$BASEDIR"
+mkdir -p ../data/models
+cd ../data/models
+
+python3 "$BASEDIR/downloader.py" --model $model_name

scripts/download-openpose-res50-model.sh

@@ -2,12 +2,12 @@
 
 set -e
 
-[ $(which gdown) ] || (echo "Downloading gdown via PIP" && python3 -m pip install gdown -U)
+[ "$(command -v gdown)" ] || (echo "Downloading gdown via PIP" && python3 -m pip install gdown -U)
 
 model_name="lopps-resnet50-V2-HW=368x432.onnx"
 
-BASEDIR=$(realpath "$(dirname $0)")
-cd $BASEDIR
+BASEDIR=$(realpath "$(dirname "$0")")
+cd "$BASEDIR"
 mkdir -p ../data/models
 cd ../data/models