-
Notifications
You must be signed in to change notification settings - Fork 275
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* refact: refact doc theme * refact: resolve `html_static_path` warning * fix: myst-parser warning * fix: NVIDIA naming * refact: C++ installation doc * fix: training setup * refact: refine yixiao's doc [training.install] * fix: ONNX link * fix: typo tl -> tf * refact: refine wording. thx Luo * refact: pin doc utility versions * fix: markdown style * refact: quick_start/prediction doc * refact: update logo in config * feat: auto glob tensorflow GraphDef input/output nodes * refact: doc - quick-start * refact: figure in docs -> center
- Loading branch information
Showing
17 changed files
with
431 additions
and
262 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,116 +1,149 @@ | ||
| # Python Training Library Installation | ||
|
|
||
| ## Prerequisites | ||
| * [Anaconda3](https://www.anaconda.com/products/individual):<br> | ||
| Anaconda is used to create virtual environment that facilitates building the running environment and ease the complexity of library depedencies. Here we mainly use it to create virtual python environment and install cuda run-time libraries. | ||
| * [CUDA](https://developer.nvidia.com/cuda-downloads):<br> | ||
| CUDA enviroment is essential to run deep learning neural networks on GPUs. The CUDA installation packages to download should match your system and your NVIDIA Driver version. | ||
| ## Configure CUDA environment | ||
|
|
||
| ## Configure environment | ||
|  There are two ways to install hyperpose python training library. | ||
| You can configure your CUDA either by Anaconda or your system setting. | ||
|
|
||
|  All the following instructions have been tested on the environments below:<br> | ||
| | OS | NVIDIA Driver | CUDA Toolkit | GPU | | ||
| | ------------ | ------------- | ------------ | -------------- | | ||
| | Ubuntu 18.04 | 410.79 | 10.0 | Tesla V100-DGX | | ||
| | Ubuntu 18.04 | 440.33.01 | 10.2 | Tesla V100-DGX | | ||
| | Ubuntu 18.04 | 430.64 | 10.1 | TITAN RTX | | ||
| | Ubuntu 18.04 | 430.26 | 10.2 | TITAN XP | | ||
| | Ubuntu 16.04 | 430.50 | 10.1 | RTX 2080Ti | | ||
| ### Using CUDA toolkits from Anaconda (RECOMMENDED) | ||
|
|
||
| :::{admonition} Prerequisites | ||
| - [Anaconda3](https://www.anaconda.com/products/individual) | ||
| - [NVidia Driver >= 410.79 (required by CUDA 10)](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html#driver-installation) | ||
| ::: | ||
|
|
||
| It is suggested to create new conda environment regarding the CUDA requirements. | ||
|
|
||
|  Before all, we recommend you to create anaconda virtual environment first, which could handle the possible conflicts between the libraries you already have in your computers and the libraries hyperpose need to install, and also handle the dependencies of the cudatoolkit and cudnn library in a very simple way.<br> | ||
|  To create the virtual environment, run the following command in bash: | ||
| ```bash | ||
| # >>> create virtual environment (choose yes) | ||
| conda create -n hyperpose python=3.7 | ||
| # >>> create virtual environment | ||
| conda create -n hyperpose python=3.7 -y | ||
| # >>> activate the virtual environment, start installation | ||
| conda activate hyperpose | ||
| # >>> install cudatoolkit and cudnn library using conda | ||
| conda install cudatoolkit=10.0.130 | ||
| conda install cudnn=7.6.0 | ||
| ``` | ||
|
|
||
| ::::{warning} | ||
| It is also possible to install CUDA dependencies without creating a new environment. | ||
| But it might introduce environment conflicts. | ||
|
|
||
| :::{code-block} bash | ||
| conda install cudatoolkit=10.0.130 | ||
| conda install cudnn=7.6.0 | ||
| ::: | ||
| :::: | ||
|
|
||
|
|
||
| ### Using system-wide CUDA toolkits | ||
|
|
||
| Users may also directly depend on the system-wide CUDA and CuDNN libraries. | ||
|
|
||
| HyperPose have been tested on the environments below: | ||
|
|
||
| | OS | NVIDIA Driver | CUDA Toolkit | GPU | | ||
| | ------------ | ------------- | ------------ | -------------- | | ||
| | Ubuntu 18.04 | 410.79 | 10.0 | Tesla V100-DGX | | ||
| | Ubuntu 18.04 | 440.33.01 | 10.2 | Tesla V100-DGX | | ||
| | Ubuntu 18.04 | 430.64 | 10.1 | TITAN RTX | | ||
| | Ubuntu 18.04 | 430.26 | 10.2 | TITAN XP | | ||
| | Ubuntu 16.04 | 430.50 | 10.1 | RTX 2080Ti | | ||
|
|
||
| ::::{admonition} Check CUDA/CuDNN versions | ||
|
|
||
|  After configuring and activating conda enviroment, we can then begin to install the hyperpose.<br> | ||
| To test CUDA version, run `nvcc --version`: the highlight line in the output indicates that you have CUDA 11.2 installed. | ||
| :::{code-block} bash | ||
| :emphasize-lines: 5 | ||
| nvcc --version | ||
| # ========== Valid output looks like ========== | ||
| # nvcc: NVIDIA (R) Cuda compiler driver | ||
| # Copyright (c) 2005-2020 NVIDIA Corporation | ||
| # Built on Mon_Nov_30_19:08:53_PST_2020 | ||
| # Cuda compilation tools, release 11.2, V11.2.67 | ||
| # Build cuda_11.2.r11.2/compiler.29373293_0 | ||
| ::: | ||
|
|
||
| ### (I)The first method to install is to put hyperpose python module in the working directory.(recommand)<br> | ||
|  After git-cloning the source [repository](https://github.com/tensorlayer/hyperpose.git), you can directly import hyperpose python library under the root directory of the cloned repository.<br> | ||
| To check your system-wide CuDNN version **on Linux**: the output (in the comment) shows that we have CuDNN 8.0.5. | ||
| :::{code-block} bash | ||
| ls /usr/local/cuda/lib64 | grep libcudnn.so | ||
| # === Valid output looks like === | ||
| # libcudnn.so | ||
| # libcudnn.so.8 | ||
| # libcudnn.so.8.0.5 | ||
| ::: | ||
| :::: | ||
|
|
||
|  To make importion available, you should install the prerequist dependencies as followed:<br> | ||
|  you can either install according to the requirements.txt in the [repository](https://github.com/tensorlayer/hyperpose.git) | ||
| ## Install HyperPose Python training library | ||
|
|
||
| ### Install with `pip` | ||
|
|
||
| To install a stable library from [Python Package Index](https://github.com/tensorlayer/hyperpose): | ||
|
|
||
| ```bash | ||
| # install according to the requirements.txt | ||
| pip install -r requirements.txt | ||
| pip install -U hyperpose | ||
| ``` | ||
|
|
||
|  or install libraries one by one | ||
| Or you can install a specific release of hyperpose from GitHub, for example: | ||
|
|
||
| ```bash | ||
| # >>> install tensorflow of version 2.3.1 | ||
| pip install tensorflow-gpu==2.3.1 | ||
| # >>> install tensorlayer of version 2.2.3 | ||
| pip install tensorlayer==2.2.3 | ||
| # >>> install other requirements (numpy<=17.0.0 because it has conflicts with pycocotools) | ||
| pip install opencv-python | ||
| pip install numpy==1.16.4 | ||
| pip install pycocotools | ||
| pip install matplotlib | ||
| export HYPERPOSE_VERSION="2.2.0-alpha" | ||
| pip install -U https://github.com/tensorlayer/hyperpose/archive/${HYPERPOSE_VERSION}.zip | ||
| ``` | ||
|
|
||
|  This method of installation use the latest source code and thus is less likely to meet compatibility problems.<br><br> | ||
| More GitHub releases and its version can be found [here](https://github.com/tensorlayer/hyperpose/releases). | ||
|
|
||
| ### (II)The second method to install is to use pypi repositories.<br> | ||
|  We have already upload hyperpose python library to pypi website so you can install it using pip, which gives you the last stable version. | ||
| ### Local installation | ||
|
|
||
| You can also install HyperPose by installing the raw GitHub repository, this is usually for developers. | ||
|
|
||
| ```bash | ||
| pip install hyperpose | ||
| # Install the source codes from GitHub | ||
| git clone https://github.com/tensorlayer/hyperpose.git | ||
| pip install -U -r hyperpose/requirements.txt | ||
|
|
||
| # Add `hyperpose/hyperpose` to `PYTHONPATH` to help python find it. | ||
| export HYPERPOSE_PYTHON_HOME=$(pwd)/hyperpose | ||
| export PYTHONPATH=$HYPERPOSE_PYTHON_HOME/python:${PYTHONPATH} | ||
| ``` | ||
|
|
||
|  This will download and install all dependencies automatically. | ||
| ## Check the installation | ||
|
|
||
| Let's check whether HyperPose is installed by running following commands: | ||
|
|
||
|  Now after installing dependent libraries and hyperpose itself, let's check whether the installation successes. | ||
| run following command in bash: | ||
| ```bash | ||
| # >>> now the configuration is done, check whether the GPU is avaliable. | ||
| python | ||
| >>> import tensorflow as tf | ||
| >>> import tensorlayer as tl | ||
| >>> tf.test.is_gpu_available() | ||
| # >>> if the output is True, congratulation! you can import and run hyperpose now | ||
| >>> from hyperpose import Config,Model,Dataset | ||
| python -c ' | ||
| import tensorflow as tf # Test TensorFlow installation | ||
| import tensorlayer as tl # Test TensorLayer installation | ||
| assert tf.test.is_gpu_available() # Test GPU availability | ||
| import hyperpose # Test HyperPose import | ||
| ' | ||
| ``` | ||
|
|
||
| ## Extra configuration for exporting model | ||
|  The hypeprose python training library handles the whole pipelines for developing the pose estimation system, including training, evaluating and testing. Its goal is to produce a **.npz** file that contains the well-trained model weights. | ||
| ## Optional Setup | ||
|
|
||
| ### Extra configurations for exporting models | ||
|
|
||
|  For the training platform, the enviroment configuration above is engough. However, most inference engine only accept .pb format or .onnx format model, such as [TensorRT](https://docs.nvidia.com/deeplearning/tensorrt/install-guide/index.html). | ||
| The hypeprose python training library handles the whole pipelines for developing the pose estimation system, including training, evaluating and testing. Its goal is to produce a **.npz** file that contains the well-trained model weights. | ||
|
|
||
|  Thus, one need to convert the trained model loaded with **.npz** file weight to **.pb** format or **.onnx** format for further deployment, which need extra configuration below:<br> | ||
| For the training platform, the enviroment configuration above is engough. However, most inference engine accepts ProtoBuf or [ONNX](https://onnx.ai/) format model. For example, the HyperPose C++ inference engine leverages [TensorRT](https://docs.nvidia.com/deeplearning/tensorrt/install-guide/index.html) as the DNN engine, which takes ONNX models as inputs. | ||
|
|
||
| ### (I)Convert to .pb format:<br> | ||
|  To convert the model into .pb format, we use *@tf.function* to decorate the *infer* function of each model class, so we can use the *get_concrete_function* function from tensorflow to consctruct the frozen model computation graph and then save it in .pb format. | ||
| Thus, one need to convert the trained model loaded with **.npz** file weight to **.pb** format or **.onnx** format for further deployment, which need extra configuration below: | ||
|
|
||
|  We already provide a script with cli to facilitate conversion, which located at [export_pb.py](https://github.com/tensorlayer/hyperpose/blob/master/export_pb.py). What we need here is only *tensorflow* library that we already installed. | ||
| #### Converting a ProtoBuf model | ||
|
|
||
| ### (II)Convert to .onnx format:<br> | ||
|  To convert the model in .onnx format, we need to first convert the model into .pb format, then convert it from .pb format into .onnx format. Two extra library are needed: | ||
| To convert the model into ProtoBuf format, we use `@tf.function` to decorate the `infer` function for each model class, and we then can use the `get_concrete_function` function from tensorflow to consctruct the frozen model computation graph and then save it with ProtoBuf format. | ||
|
|
||
| * [tf2onnx](https://github.com/onnx/tensorflow-onnx):<br> | ||
| *tf2onnx* is used to convert .pb format model into .onnx format model. more information see [here](https://github.com/onnx/tensorflow-onnx).<br> | ||
| install tf2onnx by running: | ||
| We provide [a commandline tool](https://github.com/tensorlayer/hyperpose/blob/master/export_pb.py) to facilitate the conversion. The prerequisite of this tool is a tensorflow library installed along with HyperPose's dependency. | ||
|
|
||
| ```bash | ||
| pip install -U tf2onnx | ||
| ``` | ||
| #### Converting a ONNX model | ||
|
|
||
| * [graph_transforms](https://github.com/tensorflow/tensorflow/tree/master/tensorflow/tools/graph_transforms#using-the-graph-transform-tool):<br> | ||
| *graph_transform* is used to check the input and output node of the .pb file if one doesn't know. when convert .pb file into .onnx file using tf2onnx, one is required to provide the input node name and output node name of the computation graph stored in .pb file, so he may need to use *graph_transform* to inspect the .pb file to get node names.<br> | ||
| build graph_transforms according to [tensorflow tools](https://github.com/tensorflow/tensorflow/tree/master/tensorflow/tools/graph_transforms#using-the-graph-transform-tool). | ||
| To convert a trained model into ONNX format, we need to first convert the model into ProtoBuf format, we then convert a ProtoBuf model into ONNX format, which requires an additional library: [**tf2onnx**](https://github.com/onnx/tensorflow-onnx) for converting TensorFlow's ProtoBuf model into ONNX format. | ||
|
|
||
| ## Extra configuration for parallel training | ||
|  The hyperpose python training library use the High performance distributed machine learning framework **Kungfu** for parallel training.<br> | ||
|  Thus to use the parallel training functionality of hyperpose, please install [Kungfu](https://github.com/lsds/KungFu) according to the official instructon it provides. | ||
| To install `tf2onnx`, we simply run: | ||
|
|
||
| ```bash | ||
| pip install -U tf2onnx | ||
| ``` | ||
|
|
||
| ### Extra configuration for distributed training with KungFu | ||
|
|
||
| The HyperPose python training library can also perform distributed training with [Kungfu](https://github.com/lsds/KungFu). To enable parallel training, please install [Kungfu](https://github.com/lsds/KungFu) according to its official instructon. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.