Doxygen to 1.9; doc reordered, renamed & modified to adapt to GH pages/doxygen

Signed-off-by: NGines Hidalgo <gineshidalgo99@gmail.com>

scripts/doc_autogeneration.doxygen → .doc_autogeneration.doxygen

@@ -864,7 +864,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../README.md ../doc/ ../include/openpose/
+INPUT                  = README.md doc/ include/openpose/
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1061,7 +1061,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = ../README.md
+USE_MDFILE_AS_MAINPAGE = README.md
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing

.github/CI_deprecated/.travis.yml

@@ -8,7 +8,7 @@
 # # Environment variables + OS + other parameters
 # global:
 #   - GH_REPO_NAME: openpose
-#   - DOXYFILE: $CI_BUILD_DIR/scripts/doc_autogeneration.doxygen
+#   - DOXYFILE: $CI_BUILD_DIR/.doc_autogeneration.doxygen
 #   # Set this in Environment Variables on travis-ci.org
 #   # - GH_REPO_REF: github.com/<user_name>/openpose.git
 # matrix:

.github/CI_deprecated/Readme_Travis_badges_table_and_backup_instructions.md

 In order to recover Travis:
 1. Uncomment all the lines of code in ".travis.yml" and move it back to the main folder (e.g., at the same level than the global README.md and CMakeLists.txt files).
-2. Re-add the table of badges in the README.md:
+2. Move `generate_gh_pages.sh` back to `scripts/generate_gh_pages.sh`.
+3. Re-add the table of badges in the README.md:
 
 |                  |`Default Config`  |`CUDA (+Python)`  |`CPU (+Python)`   |`OpenCL (+Python)`| `Debug`          | `Unity`          |
 | :---:            | :---:            | :---:            | :---:            | :---:            | :---:            | :---:            |

scripts/generate_gh_pages.sh → .github/CI_deprecated/generate_gh_pages.sh

@@ -71,8 +71,6 @@ echo "" > .nojekyll
 ##### Generate the Doxygen code documentation and log the output.          #####
 echo 'Generating Doxygen code documentation...'
 # Redirect both stderr and stdout to the log file AND the console.
-echo "INPUT                  = ${CI_BUILD_DIR}/README.md ${CI_BUILD_DIR}/include/openpose/" >> $DOXYFILE
-echo "USE_MDFILE_AS_MAINPAGE = ${CI_BUILD_DIR}/README.md" >> $DOXYFILE
 echo "OUTPUT_DIRECTORY       = " >> $DOXYFILE
 doxygen $DOXYFILE 2>&1 | tee doxygen.log
 

.github/issue_template.md

 ### Posting rules
 1. **No duplicated posts, only 1 new post opened a day, and up to 2 opened a week**. Otherwise, extrict user bans will occur.
-    - Check the [FAQ](https://github.com/CMU-Perceptual-Computing-Lab/openpose/blob/master/doc/faq.md) section, other GitHub issues, and general documentation before posting. E.g., **low-speed, out-of-memory, output format, 0-people detected, installation issues, ...**).
+    - Check the [FAQ](https://github.com/CMU-Perceptual-Computing-Lab/openpose/blob/master/doc/4_faq.md) section, other GitHub issues, and general documentation before posting. E.g., **low-speed, out-of-memory, output format, 0-people detected, installation issues, ...**).
     - Keep posting all your issues in the same post.
     - No bans if you are unsure whether the post is duplicated!
 2. **Fill all** the **Your System Configuration section** if you are facing an error or unexpected behavior. Some posts (e.g., feature requests) might not require it.
@@ -82,4 +82,4 @@ Select the topic(s) on your post, delete the rest:
     - Portable demo or compiled library?
 
 10. If **speed performance** issue:
-    - Report OpenPose timing speed based on [this link](https://github.com/CMU-Perceptual-Computing-Lab/openpose/blob/master/doc/maximizing_openpose_speed.md#profiling-speed).
+    - Report OpenPose timing speed based on [this link](https://github.com/CMU-Perceptual-Computing-Lab/openpose/blob/master/doc/5_maximizing_openpose_speed.md#profiling-speed).

.github/workflows/main.yml

@@ -4,7 +4,7 @@ on: [push, pull_request]
 
 env:
   GH_REPO_NAME: ${{ github.event.repository.name }}
-  DOXYFILE: ${{ github.workspace }}/scripts/doc_autogeneration.doxygen
+  DOXYFILE: ${{ github.workspace }}/.doc_autogeneration.doxygen
   GH_REPO_REF: ${{ github.repositoryUrl }}
 
 jobs:
@@ -51,7 +51,6 @@ jobs:
               WITH_CUDNN: false
               WITH_PYTHON: true
               CI_OS_NAME: linux
-            DOCS: true
           # Ubuntu 20.04 - Python - CMake - CPU
           - os: ubuntu-20.04
             os_name: linux
@@ -241,9 +240,6 @@ jobs:
       with:
         python-version: 2.x
       if: ${{ matrix.env.WITH_PYTHON }}
-    - name: Docs APT packages
-      run: sudo apt-get -yq install doxygen doxygen-doc doxygen-latex doxygen-gui graphviz
-      if: ${{ matrix.DOCS }}
     - name: Install (Linux)
       run: scripts/CI/install_deps_ubuntu.sh
       if: ${{ matrix.os_name == 'linux' }}
@@ -257,22 +253,37 @@ jobs:
       run: scripts/CI/run_make.sh
     - name: Tests
       run: scripts/CI/run_tests.sh
+
+    - name: Docs APT packages
+      # The Doxygen apt-get version for Ubuntu 20 is 1.8.17, which has some bugs fixed in 1.9.1
+      # run: sudo apt-get -yq install doxygen doxygen-doc doxygen-latex doxygen-gui graphviz
+      run: |
+        git clone https://github.com/doxygen/doxygen.git && cd doxygen && git checkout Release_1_9_1
+        mkdir build && cd build
+        cmake -G "Unix Makefiles" ..
+        make -j`nproc`
+        sudo make install
+      if: ${{ matrix.DOCS }}
     - name: Generate docs
       run: |
         cd ${{ github.workspace }}
         echo 'Generating Doxygen code documentation...'
-        echo "INPUT                  = ${{ github.workspace }}/README.md ${{ github.workspace }}/include/openpose/" >> $DOXYFILE
-        echo "USE_MDFILE_AS_MAINPAGE = ${{ github.workspace }}/README.md" >> $DOXYFILE
-        echo "OUTPUT_DIRECTORY       = " >> $DOXYFILE
         doxygen $DOXYFILE 2>&1 | tee doxygen.log
-        echo "" > html/.nojekyll
-        cp doxygen.log html/doxygen.log
+        echo 'Creating .nojekyll and copying log...'
+        echo "" > doxygen/html/.nojekyll
+        cp doxygen.log doxygen/html/doxygen.log
+        # Required in order to link .github/media/ images with doc without modifying doc links. Remove if using `publish_dir: doxygen/html/`
+        mkdir -p doxygen_final/web/html/ && mv doxygen/html doxygen_final/web/html/doc
+        mkdir -p doxygen_final/web/.github/media/ && cp -rf .github/media/ doxygen_final/web/.github/
+        mkdir -p doxygen_final/web/html/.github/media/ && cp -rf .github/media/ doxygen_final/web/html/.github/
+        mkdir -p doxygen_final/web/html/doc/.github/media/ && cp -rf .github/media/ doxygen_final/web/html/doc/.github/
       if: ${{ matrix.DOCS }}
     - name: Deploy Docs
       uses: peaceiris/actions-gh-pages@v3
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: html
+        publish_dir: doxygen_final/
+        # publish_dir: doxygen/html/ # Original one, it would turn [...].github.io/openpose/web/html/doc/ into [...].github.io/openpose/, but images would not work
         destination_dir: .
         enable_jekyll: false
         force_orphan: true

CMakeLists.txt

@@ -1022,7 +1022,7 @@ if (UNIX OR APPLE)
     find_package(Doxygen)
     if (DOXYGEN_FOUND)
       # Set input and output files
-      set(DOXYGEN_FILE ${CMAKE_SOURCE_DIR}/scripts/doc_autogeneration.doxygen)
+      set(DOXYGEN_FILE ${CMAKE_SOURCE_DIR}/.doc_autogeneration.doxygen)
 
       # Custom target to build the documentation
       add_custom_target(doc_doxygen ALL

README.md

 <div align="center">
-    <img src=".github/Logo_main_black.png", width="300">
+    <img src=".github/Logo_main_black.png" width="300">
 </div>
 
 -----------------
@@ -10,12 +10,12 @@
 
 [**OpenPose**](https://github.com/CMU-Perceptual-Computing-Lab/openpose) has represented the **first real-time multi-person system to jointly detect human body, hand, facial, and foot keypoints (in total 135 keypoints) on single images**.
 
-It is **authored by [Ginés Hidalgo](https://www.gineshidalgo.com), [Zhe Cao](https://people.eecs.berkeley.edu/~zhecao), [Tomas Simon](http://www.cs.cmu.edu/~tsimon), [Shih-En Wei](https://scholar.google.com/citations?user=sFQD3k4AAAAJ&hl=en), [Hanbyul Joo](https://jhugestar.github.io), and [Yaser Sheikh](http://www.cs.cmu.edu/~yaser)**, and **maintained by [Ginés Hidalgo](https://www.gineshidalgo.com) and [Yaadhav Raaj](https://www.raaj.tech)**. OpenPose would not be possible without the [**CMU Panoptic Studio dataset**](http://domedb.perception.cs.cmu.edu). We would also like to thank all the people who helped OpenPose in any way ([doc/authors_and_contributors.md](doc/authors_and_contributors.md)).
+It is **authored by** [**Ginés Hidalgo**](https://www.gineshidalgo.com), [**Zhe Cao**](https://people.eecs.berkeley.edu/~zhecao), [**Tomas Simon**](http://www.cs.cmu.edu/~tsimon), [**Shih-En Wei**](https://scholar.google.com/citations?user=sFQD3k4AAAAJ&hl=en), [**Hanbyul Joo**](https://jhugestar.github.io), **and** [**Yaser Sheikh**](http://www.cs.cmu.edu/~yaser). It is **maintained by** [**Ginés Hidalgo**](https://www.gineshidalgo.com) **and** [**Yaadhav Raaj**](https://www.raaj.tech). OpenPose would not be possible without the [**CMU Panoptic Studio dataset**](http://domedb.perception.cs.cmu.edu). We would also like to thank all the people who [has helped OpenPose in any way](doc/8_authors_and_contributors.md).
 
 
 
 <p align="center">
-    <img src=".github/media/pose_face_hands.gif", width="480">
+    <img src=".github/media/pose_face_hands.gif" width="480">
     <br>
     <sup>Authors <a href="https://www.gineshidalgo.com" target="_blank">Ginés Hidalgo</a> (left) and <a href="https://jhugestar.github.io" target="_blank">Hanbyul Joo</a> (right) in front of the <a href="http://domedb.perception.cs.cmu.edu" target="_blank">CMU Panoptic Studio</a></sup>
 </p>
@@ -37,39 +37,39 @@ It is **authored by [Ginés Hidalgo](https://www.gineshidalgo.com), [Zhe Cao](ht
 ## Results
 ### Body and Foot Estimation
 <p align="center">
-    <img src=".github/media/dance_foot.gif", width="360">
+    <img src=".github/media/dance_foot.gif" width="360">
     <br>
     <sup>Testing the <a href="https://www.youtube.com/watch?v=2DiQUX11YaY" target="_blank"><i>Crazy Uptown Funk flashmob in Sydney</i></a> video sequence with OpenPose</sup>
 </p>
 
 ### 3D Reconstruction Module (Body, Foot, Face, and Hands)
 <p align="center">
-    <img src=".github/media/openpose3d.gif", width="360">
+    <img src=".github/media/openpose3d.gif" width="360">
     <br>
     <sup>Testing the 3D Reconstruction Module of OpenPose</sup>
 </p>
 
 ### Body, Foot, Face, and Hands Estimation
 <p align="center">
-    <img src=".github/media/pose_face.gif", width="360">
-    <img src=".github/media/pose_hands.gif", width="360">
+    <img src=".github/media/pose_face.gif" width="360">
+    <img src=".github/media/pose_hands.gif" width="360">
     <br>
     <sup>Authors <a href="https://www.gineshidalgo.com" target="_blank">Ginés Hidalgo</a> (left image) and <a href="http://www.cs.cmu.edu/~tsimon" target="_blank">Tomas Simon</a> (right image) testing OpenPose</sup>
 </p>
 
 ### Unity Plugin
 <p align="center">
-    <img src=".github/media/unity_main.png", width="240">
-    <img src=".github/media/unity_body_foot.png", width="240">
-    <img src=".github/media/unity_hand_face.png", width="240">
+    <img src=".github/media/unity_main.png" width="240">
+    <img src=".github/media/unity_body_foot.png" width="240">
+    <img src=".github/media/unity_hand_face.png" width="240">
     <br>
-    <sup><a href="http://tianyizhao.com" target="_blank">Tianyi Zhao</a> and <a href="https://www.gineshidalgo.com" target="_blank">Ginés Hidalgo</a> testing the <a href="https://github.com/CMU-Perceptual-Computing-Lab/openpose_unity_plugin" target="_blank">OpenPose Unity Plugin</a></sup>
+    <sup><a href="https://ziutinyat.github.io/" target="_blank">Tianyi Zhao</a> and <a href="https://www.gineshidalgo.com" target="_blank">Ginés Hidalgo</a> testing the <a href="https://github.com/CMU-Perceptual-Computing-Lab/openpose_unity_plugin" target="_blank">OpenPose Unity Plugin</a></sup>
 </p>
 
 ### Runtime Analysis
 We show an inference time comparison between the 3 available pose estimation libraries (same hardware and conditions): OpenPose, Alpha-Pose (fast Pytorch version), and Mask R-CNN. The OpenPose runtime is constant, while the runtime of Alpha-Pose and Mask R-CNN grow linearly with the number of people. More details [**here**](https://arxiv.org/abs/1812.08008).
 <p align="center">
-    <img src=".github/media/openpose_vs_competition.png", width="360">
+    <img src=".github/media/openpose_vs_competition.png" width="360">
 </p>
 
 
@@ -91,10 +91,10 @@ We show an inference time comparison between the 3 available pose estimation lib
 - **OS**: Ubuntu (20, 18, 16, 14), Windows (10, 8), Mac OSX, Nvidia TX2.
 - **Hardware compatibility**: CUDA (Nvidia GPU), OpenCL (AMD GPU), and non-GPU (CPU-only) versions.
 - **Usage Alternatives**:
-    - [**Command-line demo**](doc/demo_quick_start.md) for built-in functionality.
-    - [**C++ API**](examples/tutorial_api_cpp/) and [**Python API**](doc/python_api.md) for custom functionality. E.g., adding your custom inputs, pre-processing, post-posprocessing, and output steps.
+    - [**Command-line demo**](doc/1_demo.md) for built-in functionality.
+    - [**C++ API**](examples/tutorial_api_cpp/) and [**Python API**](doc/3_python_api.md) for custom functionality. E.g., adding your custom inputs, pre-processing, post-posprocessing, and output steps.
 
-For further details, check the [major released features](doc/major_released_features.md) and [release notes](doc/release_notes.md) docs.
+For further details, check the [major released features](doc/6_major_released_features.md) and [release notes](doc/7_release_notes.md) docs.
 
 
 
@@ -107,9 +107,9 @@ For further details, check the [major released features](doc/major_released_feat
 
 
 ## Installation
-If you want to use OpenPose without compiling or writing any code, simply [download and use the latest Windows portable version of OpenPose](doc/installation/README.md#windows-portable-demo)! Otherwise, you can also [build OpenPose from source](doc/installation/README.md#compiling-and-running-openpose-from-source).
+If you want to use OpenPose without compiling or writing any code, simply [download and use the latest Windows portable version of OpenPose](doc/installation/0_index.md#windows-portable-demo)! Otherwise, you can also [build OpenPose from source](doc/installation/0_index.md#compiling-and-running-openpose-from-source).
 
-See [doc/installation/README.md](doc/installation/README.md) for more details.
+See [doc/installation/0_index.md](doc/installation/0_index.md) for more details.
 
 
 
@@ -134,7 +134,7 @@ You can also add any of the available flags in any order. Do you also want to ad
 bin\OpenPoseDemo.exe --video examples\media\video.avi --face --hand --write_json output_json_folder/
 ```
 
-After [installing](#installation) OpenPose, check [doc/README.md](doc/README.md) for a quick overview of all the alternatives and tutorials.
+After [installing](#installation) OpenPose, check [doc/0_index.md](doc/0_index.md) for a quick overview of all the alternatives and tutorials.
 
 
 
@@ -191,4 +191,4 @@ Paper links:
 
 
 ## License
-OpenPose is freely available for free non-commercial use, and may be redistributed under these conditions. Please, see the [license](LICENSE) for further details. Interested in a commercial license? Check this [FlintBox link](https://cmu.flintbox.com/#technologies/b820c21d-8443-4aa2-a49f-8919d93a8740). For commercial queries, use the `Contact` section from the [FlintBox link](https://cmu.flintbox.com/#technologies/b820c21d-8443-4aa2-a49f-8919d93a8740) and also send a copy of that message to [Yaser Sheikh](mailto:yaser@cs.cmu.edu).
+OpenPose is freely available for free non-commercial use, and may be redistributed under these conditions. Please, see the [license](./LICENSE) for further details. Interested in a commercial license? Check this [FlintBox link](https://cmu.flintbox.com/#technologies/b820c21d-8443-4aa2-a49f-8919d93a8740). For commercial queries, use the `Contact` section from the [FlintBox link](https://cmu.flintbox.com/#technologies/b820c21d-8443-4aa2-a49f-8919d93a8740) and also send a copy of that message to [Yaser Sheikh](mailto:yaser@cs.cmu.edu).

doc/0_index.md

+OpenPose Doc
+==========================
+
+The OpenPose documentation is available in 2 different formats, choose your preferred one!
+- As a traditional website (recommended): [cmu-perceptual-computing-lab.github.io/openpose/web/html/doc](https://cmu-perceptual-computing-lab.github.io/openpose/web/html/doc/).
+- As markdown files: [github.com/CMU-Perceptual-Computing-Lab/openpose/blob/master/doc/0_index.md](https://github.com/CMU-Perceptual-Computing-Lab/openpose/blob/master/doc/0_index.md).
+
+Most users can simply use the OpenPose Demo without reading any C++/Python code. Users that need to add additional functionality (new inputs, outputs, etc) should check the C++/Python APIs:
+
+- If you face issues with any of these steps, keep in mind to check the [FAQ](installation/4_faq.md) section.
+
+- The first step for any software, [install it](installation/0_index.md)!
+
+- [OpenPose Demo](1_demo.md): Choose your input (e.g., images, video, webcam), set of algorithms (body, hand, face), output (e.g., display, JSON keypoint saving, image+keypoints), and run OpenPose from your terminal or PowerShell!
+    - E.g.: Given an input video (`--video`), extract body (by default), face (`--face`) and hand (`--hand`) keypoints, save the keypoints in a JSON file (`--write_json`), and display (by default) the results in the screen. You can remove any of the flags to remove that particular functionality or add any other.
+```
+# Ubuntu
+./build/examples/openpose/openpose.bin --video examples/media/video.avi --face --hand --write_json output_json_folder/
+
+:: Windows - Portable Demo
+bin\OpenPoseDemo.exe --video examples\media\video.avi --face --hand --write_json output_json_folder/
+```
+
+- [Output information](2_output.md): Learn about the output format, keypoint index ordering, etc.
+
+- [OpenPose Python API](3_python_api.md): Almost all the OpenPose functionality, but in Python!
+
+- [OpenPose C++ API](../examples/tutorial_api_cpp/): If you want to read a specific input, and/or add your custom post-processing function, and/or implement your own display/saving.
+    - You should be familiar with the [OpenPose Demo](1_demo.md) and the main OpenPose flags before trying to read the C++ or Python API examples. Otherwise, it will be way harder to follow.
+    - For quick prototyping: You can easily **create your custom code** on [examples/user_code/](../examples/user_code/) and CMake will automatically compile it together with the whole OpenPose project. See [examples/user_code/README.md](../examples/user_code/README.md) for more details.
+
+- [Maximizing OpenPose speed and benchmark](5_maximizing_openpose_speed.md): Check the OpenPose Benchmark as well as some hints to speed up and/or reduce the memory requirements for OpenPose.
+
+- [Calibration toolbox](advanced/calibration_module.md) and [3D OpenPose](advanced/3d_reconstruction_module.md): Calibrate your cameras for 3D OpenPose (or any other stereo vision tasks) and start obtaining 3D keypoints!
+
+- [Standalone face or hand detector](advanced/standalone_face_or_hand_keypoint_detector.md) is useful if you want to do any of the following:
+    - **Face** keypoint detection **without body** keypoint detection: Pros: Speedup and RAM/GPU memory reduction. Cons: Worse accuracy and less detected number of faces).
+    - **Use your own face/hand detector**: You can use the hand and/or face keypoint detectors with your own face or hand detectors, rather than using the body detector. E.g., useful for camera views at which the hands are visible but not the body (OpenPose detector would fail).

doc/demo_quick_start.md → doc/1_demo.md

-OpenPose Doc - Demo - Quick Start
+OpenPose Doc - Demo
 ====================================
 
 Forget about the OpenPose code, just download the portable Windows binaries (or compile the code from source) and use the demo by following this tutorial!
@@ -30,7 +30,7 @@ Forget about the OpenPose code, just download the portable Windows binaries (or
 ## Quick Start
 In Ubuntu, Mac, and other Unix systems, use `Terminal` or `Terminator`. In Windows, the `Windows PowerShell`. Watch any Youtube video tutorial if you are not familiar with these tools. Make sure that you are in the **root directory of the project** when running any command (i.e., in the OpenPose folder, not inside `build/` nor `windows/` nor `bin/`). In addition, `examples/media/video.avi` and `examples/media` exist, so there is no need to change any lines of code.
 
-Test OpenPose by running the following. The expected visual result should look like [doc/output.md#ui-and-visual-output](output.md#ui-and-visual-output).
+Test OpenPose by running the following. The expected visual result should look like [doc/2_output.md#ui-and-visual-output](2_output.md#ui-and-visual-output).
 ```
 # Ubuntu and Mac
 ./build/examples/openpose/openpose.bin --video examples/media/video.avi
@@ -40,9 +40,9 @@ Test OpenPose by running the following. The expected visual result should look l
 bin\OpenPoseDemo.exe --video examples/media/video.avi
 ```
 
-If you are only using the OpenPose demo, we highly recommend using [the latest Windows portable version of OpenPose](doc/installation/README.md#windows-portable-demo). If you still want to use the demo with Visual Studio, you can copy the `bin/*.dll` files into the final DLL bin location following [doc/installation/README.md#windows](installation/README.md#windows), or you could also simply modify the default flag values from [include/flags.hpp](../include/flags.hpp). If you have copied the DLLs, you can execute this:
+If you are only using the OpenPose demo, we highly recommend using [the latest Windows portable version of OpenPose](doc/installation/0_index.md#windows-portable-demo). If you still want to use the demo with Visual Studio, you can copy the `bin/*.dll` files into the final DLL bin location following [doc/installation/0_index.md#windows](installation/0_index.md#windows), or you could also simply modify the default flag values from [include/flags.hpp](../include/flags.hpp). If you have copied the DLLs, you can execute this:
 ```
-:: Windows - Library - Assuming you have copied the DLLs following doc/installation/README.md#windows
+:: Windows - Library - Assuming you have copied the DLLs following doc/installation/0_index.md#windows
 build\x64\Release\OpenPoseDemo.exe --video examples/media/video.avi
 ```
 
@@ -108,7 +108,7 @@ bin\OpenPoseDemo.exe --face --hand
 ## Different Outputs (JSON, Images, Video, UI)
 All the output options are complementary to each other. E.g., whether you display the images with the skeletons on the UI (or not) is independent on whether you save them on disk (or not).
 
-- Save the skeletons in a set of JSON files with `--write_json {OUTPUT_JSON_PATH}`, see [doc/output.md](output.md) to understand its format.
+- Save the skeletons in a set of JSON files with `--write_json {OUTPUT_JSON_PATH}`, see [doc/2_output.md](2_output.md) to understand its format.
 ```
 # Ubuntu and Mac (same flags for Windows)
 ./build/examples/openpose/openpose.bin --image_dir examples/media/ --write_json output_jsons/
@@ -288,7 +288,7 @@ Since the Windows 10 Anniversary, Kinect 2.0 can be read as a normal webcam. All
 
 
 ### Main Flags
-These are the most common flags, but check [doc/demo_not_quick_start.md](demo_not_quick_start.md) for a full list and description of all of them.
+These are the most common flags, but check [doc/advanced/demo_advanced.md](advanced/demo_advanced.md) for a full list and description of all of them.
 
 - `--face`: Enables face keypoint detection.
 - `--hand`: Enables hand keypoint detection.
@@ -312,7 +312,7 @@ These are the most common flags, but check [doc/demo_not_quick_start.md](demo_no
 
 
 ## Advanced Quick Start
-In order to learn about many more flags, check [doc/demo_not_quick_start.md](demo_not_quick_start.md).
+In order to learn about many more flags, check [doc/advanced/demo_advanced.md](advanced/demo_advanced.md).
 
 
 
@@ -365,4 +365,4 @@ If you only have an integrated Intel Graphics card, then it will most probably b
 
 
 ### FAQ
-Check [doc/faq.md](faq.md) to see if you can find your error, issue, or concern.
+Check [doc/4_faq.md](4_faq.md) to see if you can find your error, issue, or concern.

doc/output.md → doc/2_output.md

@@ -25,8 +25,9 @@ OpenPose Doc - Output
 
 ## UI and Visual Output
 The visual GUI should show the original image with the poses blended on it, similarly to the pose of this gif:
+
 <p align="center">
-    <img src="../.github/media/shake.gif", width="720">
+    <img src="../.github/media/shake.gif" width="720">
 </p>
 
 
@@ -38,28 +39,28 @@ The output of the JSON files consist of a set of keypoints, whose ordering is re
 
 ### Pose Output Format (BODY_25)
 <p align="center">
-    <img src="../.github/media/keypoints_pose_25.png", width="480">
+    <img src="../.github/media/keypoints_pose_25.png" width="480">
 </p>
 
 
 
 ### Pose Output Format (COCO)
 <p align="center">
-    <img src="../.github/media/keypoints_pose_18.png", width="480">
+    <img src="../.github/media/keypoints_pose_18.png" width="480">
 </p>
 
 
 
 ### Face Output Format
 <p align="center">
-    <img src="../.github/media/keypoints_face.png", width="480">
+    <img src="../.github/media/keypoints_face.png" width="480">
 </p>
 
 
 
 ### Hand Output Format
 <p align="center">
-    <img src="../.github/media/keypoints_hand.png", width="480">
+    <img src="../.github/media/keypoints_hand.png" width="480">
 </p>
 
 
@@ -260,4 +261,4 @@ If you need to use the camera calibration or 3D modules, the camera matrix outpu
 
 
 ### Heatmaps
-If you need to use heatmaps, check [doc/output_advanced_heatmaps.md](output_advanced_heatmaps.md).
+If you need to use heatmaps, check [doc/advanced/heatmap_output.md](advanced/heatmap_output.md).

doc/python_api.md → doc/3_python_api.md

@@ -3,15 +3,21 @@ OpenPose Doc - Python API
 
 ## Contents
 1. [Introduction](#introduction)
-2. [Compatibility](#compatibility)
-3. [Installation](#installation)
-4. [Testing](#testing)
-5. [Exporting Python OpenPose](#exporting-python-openpose)
-6. [Common Issues](#common-issues)
+2. [Advance Introduction (Optional)](#advance-introduction-optional)
+3. [Compatibility](#compatibility)
+4. [Installation](#installation)
+5. [Testing And Developing](#testing-and-developing)
+6. [Exporting Python OpenPose](#exporting-python-openpose)
+7. [Common Issues](#common-issues)
 
 
 
 ## Introduction
+Almost all the OpenPose functionality, but in Python! You should be familiar with the [**OpenPose Demo**](1_demo.md) and the main OpenPose flags before trying to read the C++ or Python API examples. Otherwise, it will be way harder to follow.
+
+
+
+## Advance Introduction (Optional)
 This module exposes a Python API for OpenPose. It is effectively a wrapper that replicates most of the functionality of the [op::Wrapper class](https://github.com/CMU-Perceptual-Computing-Lab/openpose/blob/master/include/openpose/wrapper/wrapper.hpp) and allows you to populate and retrieve data from the [op::Datum class](https://github.com/CMU-Perceptual-Computing-Lab/openpose/blob/master/include/openpose/core/datum.hpp) using standard Python and Numpy constructs.
 
 The Python API is analagous to the C++ function calls. You may find them in [python/openpose/openpose_python.cpp#L194](https://github.com/CMU-Perceptual-Computing-Lab/openpose/blob/master/python/openpose/openpose_python.cpp#L194).
@@ -51,11 +57,11 @@ If run via the command line, you may need to run cmake twice in order for this c
 
 
 ## Installation
-Make sure you followed the Python steps in [doc/installation/README.md#cmake-configuration](installation/README.md#cmake-configuration).
+Make sure you followed the Python steps in [doc/installation/0_index.md#cmake-configuration](installation/0_index.md#cmake-configuration).
 
 
 
-## Testing
+## Testing And Developing
 All the Python examples from the Tutorial API Python module can be found in `build/examples/tutorial_api_python` in your build folder. Navigate directly to this path to run examples.
 
 ```
@@ -73,6 +79,10 @@ python2 02_whole_body_from_image.py
 # python2 [any_other_python_example.py]
 ```
 
+For quick prototyping, you can simply duplicate and rename any of the existing sample files in `build/examples/tutorial_api_python` within that same folder and start building in there. These files are copied from [existing example files](../examples/tutorial_api_python/) on compiling time. 2 alternatives:
+- You can either duplicate and create your files in [examples/tutorial_api_python/](../examples/tutorial_api_python/), but you will have to recompile OpenPose every time you make changes to your Python files so they are copied over the `build/` folder.
+- Or you can directly edit them in `build/examples/tutorial_api_python`. This does not require rebuilding, but cleaning OpenPose will remove the whole `build/` folder, so make sure to back your files up!
+
 
 
 ## Exporting Python OpenPose

doc/faq.md → doc/4_faq.md

-OpenPose Doc - Frequently Asked Question (FAQ)
+OpenPose Doc - Frequently Asked Questions (FAQ)
 ============================================
 
 ## Contents
@@ -42,7 +42,7 @@ OpenPose Doc - Frequently Asked Question (FAQ)
 ### Errors
 #### Download Server Down
 **Q: The download server is down, Download Hash missmatch, Error 502: Bad Gateway, etc. I.e., I cannot download the OpenPose models and/or 3rd party libraries.**
-**A**: The are 2 alternatives. Option 1 (recommended): Download the links from [1602#issuecomment-641653411](https://github.com/CMU-Perceptual-Computing-Lab/openpose/issues/1602#issuecomment-641653411) and download them in the places indicated by [doc/prerequisites.md](prerequisites.md). Option 2: If you downloaded the models and dependencies to some local server, you could set the advanced CMake property `DOWNLOAD_SERVER` to link OpenPose to your local mirror server instead.
+**A**: The are 2 alternatives. Option 1 (recommended): Download the links from [1602#issuecomment-641653411](https://github.com/CMU-Perceptual-Computing-Lab/openpose/issues/1602#issuecomment-641653411) and download them in the places indicated by [doc/1_prerequisites.md](1_prerequisites.md). Option 2: If you downloaded the models and dependencies to some local server, you could set the advanced CMake property `DOWNLOAD_SERVER` to link OpenPose to your local mirror server instead.
 
 
 
@@ -67,7 +67,7 @@ Also, hands and face increases the GPU memory requeriments, and 4 GB GPUs might
 #### Cannot Find OpenPose.dll Error (Windows)
 **Q: System cannot find the file specified (Openpose.dll) error when trying to release** - Using a folder with images does work, but the video and/or the webcam do not. Note: often on Windows.
 
-**A**: Visual Studio (VS) and the [doc/installation/README.md](installation/README.md) section is only intended if you plan to modify the OpenPose code or integrate it with another library or project. If you just want to use the OpenPose demo, simply follow [doc/installation/README.md#windows-portable-demo](installation/README.md#windows-portable-demo) and download the OpenPose binaries in the [Releases](https://github.com/CMU-Perceptual-Computing-Lab/openpose/releases) section.
+**A**: Visual Studio (VS) and the [doc/installation/0_index.md](installation/0_index.md) section is only intended if you plan to modify the OpenPose code or integrate it with another library or project. If you just want to use the OpenPose demo, simply follow [doc/installation/0_index.md#windows-portable-demo](installation/0_index.md#windows-portable-demo) and download the OpenPose binaries in the [Releases](https://github.com/CMU-Perceptual-Computing-Lab/openpose/releases) section.
 
 If you need to compile it with Visual Studio (VS), then keep reading. In this error, VS is simply saying that there were errors while compiling the OpenPose library. Try compiling only the OpenPose library (not the demo), by right clicking on it, then `Set as StartUp Project`, and finally right click + `Build`. Then, at the bottom left part of VS, press `Error list` and then you should see which errors VS encountered while compiling. In that way, VS gives you the exact error so you can know it and share the exact issue.
 
@@ -96,12 +96,12 @@ Note: OpenPose library is not an executable, but a library. So instead clicking
 
 **A**: This answer assumes that never a single person is detected. If in your case it works sometimes, then check [Always Zero People Detected](#always-zero-people-detected). This always-0-people problem usually occurs in 2 situations: 1) When you selection `--num_gpu 0`, and 2) when the caffemodel has not been properly downloaded. E.g., if the connection drops when downloading the models.
 
-For problem 1, setting `--num_gpu 0` means that no processing is done, so you can use this setting e.g., to record webcam. This functionality is kept for back-compatibility. You are most probably trying to run on CPU-only mode, for that, install OpenPose in CPU-only mode following [doc/installation/README.md](installation/README.md).
+For problem 1, setting `--num_gpu 0` means that no processing is done, so you can use this setting e.g., to record webcam. This functionality is kept for back-compatibility. You are most probably trying to run on CPU-only mode, for that, install OpenPose in CPU-only mode following [doc/installation/0_index.md](installation/0_index.md).
 
 For problem 2, try the following solutions (in this order):
 
 1. Assuming that default OpenPose (i.e., BODY_25 model) failed, try with `--model_pose COCO` and `--model_pose MPII` models. If any of them work, the `caffemodel` files of the other models were corrupted while being downloaded. Otherwise, it will most probably be a Caffe/protobuf issue.
-2. Assuming that the model is corrupted, remove the current models in the model folder, and download them manually from the links in [doc/installation/README.md](installation/README.md). Alternatively, remove them and re-run Cmake again. If this does not work, try downloading the COCO_25 model from the browser following the download link on this [Dropbox link](https://www.dropbox.com/s/03r8pa8sikrqv62/pose_iter_584000.caffemodel).
+2. Assuming that the model is corrupted, remove the current models in the model folder, and download them manually from the links in [doc/installation/0_index.md](installation/0_index.md). Alternatively, remove them and re-run Cmake again. If this does not work, try downloading the COCO_25 model from the browser following the download link on this [Dropbox link](https://www.dropbox.com/s/03r8pa8sikrqv62/pose_iter_584000.caffemodel).
 3. If none of the OpenPose models are working, make sure Caffe is working properly and that you can run the Caffe examples with other caffemodel / prototxt files.
 
 
@@ -109,7 +109,7 @@ For problem 2, try the following solutions (in this order):
 #### Very Few People Detected
 **Q: Low detection rate. It can detect the person on some images (usually higher contrast, with bigger people), but it will fail for most of images with low resolution or small people.**
 
-**A**: Images with low resolution, or with people too tiny will simply not work too well. However, it can be highly improved by using the maximum accuracy configuration detailed in [doc/demo_quick_start.md#maximum-accuracy-configuration](demo_quick_start.md#maximum-accuracy-configuration).
+**A**: Images with low resolution, or with people too tiny will simply not work too well. However, it can be highly improved by using the maximum accuracy configuration detailed in [doc/1_demo.md#maximum-accuracy-configuration](1_demo.md#maximum-accuracy-configuration).
 
 
 
@@ -136,7 +136,7 @@ F0821 14:26:29.665053 22812 upgrade_proto.cpp:97] Check failed: ReadProtoFromBin
 
 **A**: This error has been solved in the latest OpenPose versions. Completely remove OpenPose and re-download the latest version (just cleaning the compilation or removing the `build/` folder will not work).
 
-If you wanna use your custom Caffe and it has this error: This error only happens in some Ubuntu machines. Following #787, compile your own Caffe with an older version of it. The hacky (quick but not recommended way) is to follow [#787#issuecomment-415476837](https://github.com/CMU-Perceptual-Computing-Lab/openpose/issues/787#issuecomment-415476837), the elegant way (compatible with future OpenPose versions) is to build your own Caffe independently, following [doc/installation/README.md#custom-caffe-ubuntu-only](installation/README.md#custom-caffe-ubuntu-only).
+If you wanna use your custom Caffe and it has this error: This error only happens in some Ubuntu machines. Following #787, compile your own Caffe with an older version of it. The hacky (quick but not recommended way) is to follow [#787#issuecomment-415476837](https://github.com/CMU-Perceptual-Computing-Lab/openpose/issues/787#issuecomment-415476837), the elegant way (compatible with future OpenPose versions) is to build your own Caffe independently, following [doc/installation/0_index.md#custom-caffe-ubuntu-only](installation/0_index.md#custom-caffe-ubuntu-only).
 
 
 
@@ -156,7 +156,7 @@ CUDA_cublas_device_LIBRARY (ADVANCED)
     linked by target "caffe" in directory /home/jakebmalis/Documents/openpose/3rdparty/caffe/src/caffe
 ```
 
-**A**: Make sure to download and install CMake-GUI following the [doc/prerequisites.md](prerequisites.md) section. This is a known problem with CMake-GUI versions from 3.8 to 3.11 (unfortunately, default Ubuntu 18 CMake-GUI uses 3.10). You will need a CMake version >= 3.12.
+**A**: Make sure to download and install CMake-GUI following the [doc/1_prerequisites.md](1_prerequisites.md) section. This is a known problem with CMake-GUI versions from 3.8 to 3.11 (unfortunately, default Ubuntu 18 CMake-GUI uses 3.10). You will need a CMake version >= 3.12.
 
 
 
@@ -194,7 +194,7 @@ 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/installation/README.md](installation/README.md) to run the `git submodule` command, i.e.,
+**A**: Check [doc/installation/0_index.md](installation/0_index.md) to run the `git submodule` command, i.e.,
 ```
 git submodule update --init --recursive --remote
 ```
@@ -207,33 +207,33 @@ git submodule update --init --recursive --remote
 #### Speed Up, Memory Reduction, and Benchmark
 **Q: Low speed** - OpenPose is quite slow, is it normal? How can I speed it up?
 
-**A**: Check [doc/maximizing_openpose_speed.md](maximizing_openpose_speed.md) to discover the approximate speed of your graphics card and some speed tips.
+**A**: Check [doc/5_maximizing_openpose_speed.md](5_maximizing_openpose_speed.md) to discover the approximate speed of your graphics card and some speed tips.
 
 
 
 #### How to Measure the Latency Time?
 **Q: How to measure/calculate/estimate the latency/lag time?**
 
-**A**: [Profile](https://github.com/CMU-Perceptual-Computing-Lab/openpose/blob/master/doc/maximizing_openpose_speed.md#profiling-speed) the OpenPose speed. For 1-GPU or CPU-only systems (use `--disable_multi_thread` for simplicity in multi-GPU systems for latency measurement), the latency will be roughly the sum of all the reported measurements.
+**A**: [Profile](https://github.com/CMU-Perceptual-Computing-Lab/openpose/blob/master/doc/5_maximizing_openpose_speed.md#profiling-speed) the OpenPose speed. For 1-GPU or CPU-only systems (use `--disable_multi_thread` for simplicity in multi-GPU systems for latency measurement), the latency will be roughly the sum of all the reported measurements.
 
 
 
 #### CPU Version Too Slow
 **Q: The CPU version is insanely slow compared to the GPU version.**
 
-**A**: Check [doc/maximizing_openpose_speed.md#cpu-version](maximizing_openpose_speed.md#cpu-version) to discover the approximate speed and some speed tips.
+**A**: Check [doc/5_maximizing_openpose_speed.md#cpu-version](5_maximizing_openpose_speed.md#cpu-version) to discover the approximate speed and some speed tips.
 
 
 
 #### Profiling Speed and Estimating FPS without Display
-Check the [doc/maximizing_openpose_speed.md#profiling-speed](maximizing_openpose_speed.md#profiling-speed) section.
+Check the [doc/5_maximizing_openpose_speed.md#profiling-speed](5_maximizing_openpose_speed.md#profiling-speed) section.
 
 
 
 #### Webcam Slower than Images
 **Q: Webcam is slow** - Using a folder with images matches the speed FPS benchmarks, but the webcam has lower FPS. Note: often on Windows.
 
-**A**: OpenCV has some issues with some camera drivers (specially on Windows). The first step should be to compile OpenCV by your own and re-compile OpenPose after that (following the [doc/installation/README.md#reinstallation](installation/README.md#reinstallation) section). If the speed is still slower, you can better debug it by running a webcam OpenCV example (e.g. [this C++ example](http://answers.opencv.org/question/1/how-can-i-get-frames-from-my-webcam/)). If you are able to get the proper FPS with the OpenCV demo but OpenPose is still low, then let us know!
+**A**: OpenCV has some issues with some camera drivers (specially on Windows). The first step should be to compile OpenCV by your own and re-compile OpenPose after that (following the [doc/installation/0_index.md#reinstallation](installation/0_index.md#reinstallation) section). If the speed is still slower, you can better debug it by running a webcam OpenCV example (e.g. [this C++ example](http://answers.opencv.org/question/1/how-can-i-get-frames-from-my-webcam/)). If you are able to get the proper FPS with the OpenCV demo but OpenPose is still low, then let us know!
 
 
 
@@ -241,7 +241,7 @@ Check the [doc/maximizing_openpose_speed.md#profiling-speed](maximizing_openpose
 
 ### Accuracy Issues
 #### Is Maximum Accuracy Configuration Possible on Lower End GPUs?
-**Q**: I've read that this command provides the most accurate results possible on Openpose so far: https://github.com/CMU-Perceptual-Computing-Lab/openpose/blob/master/doc/demo_quick_start.md#maximum-accuracy-configuration. However, a 8GB GPU (e.g., 1080 or 2080) will run out of memory, is there any method to achieve the same accuracy on GPU using less memory even if it meant sacrificing speed?
+**Q**: I've read that this command provides the most accurate results possible on Openpose so far: https://github.com/CMU-Perceptual-Computing-Lab/openpose/blob/master/doc/1_demo.md#maximum-accuracy-configuration. However, a 8GB GPU (e.g., 1080 or 2080) will run out of memory, is there any method to achieve the same accuracy on GPU using less memory even if it meant sacrificing speed?
 
 **A**: Unfortunately no, there is no way at the moment. Caffe just takes so much memory doing that. You can try with `--scale_number 3` instead of 4, reducing a bit the `net_resolution` (e.g. `720` vs. `736`) and starting the computer without GUI (which also takes about 1GB of memory just to keep the computer GUI running).
 

doc/maximizing_openpose_speed.md → doc/5_maximizing_openpose_speed.md

@@ -20,7 +20,7 @@ Check the [OpenPose Benchmark](https://docs.google.com/spreadsheets/d/1-DynFGvoS
 ### CPU Version
 The CPU version runs at about 0.3 FPS on the COCO model, and at about 0.1 FPS (i.e., about 15 sec / frame) on the default BODY_25 model. Switch to COCO model and/or reduce the `net_resolution` as indicated above. Contradictory fact: BODY_25 model is about 5x slower than COCO on CPU-only version, but it is about 40% faster on GPU version.
 
-On Ubuntu (for OS versions older than 20), you can also boost CPU-only speed by 2-3x by following [installation/README.md#faster-cpu-version-ubuntu-only](installation/README.md#faster-cpu-version-ubuntu-only).
+On Ubuntu (for OS versions older than 20), you can also boost CPU-only speed by 2-3x by following [installation/0_index.md#faster-cpu-version-ubuntu-only](installation/0_index.md#faster-cpu-version-ubuntu-only).
 
 
 
@@ -48,7 +48,7 @@ Some speed tips to maximize the OpenPose runtime speed while preserving the accu
 ## Speed Up and Memory Reduction
 Some speed tips to highly maximize the OpenPose speed, but keep in mind the accuracy trade-off:
 
-    1. Reduce the `--net_resolution` (e.g., to 320x176) (lower accuracy). Note: For maximum accuracy, follow [doc/demo_quick_start.md#maximum-accuracy-configuration](demo_quick_start.md#maximum-accuracy-configuration).
+    1. Reduce the `--net_resolution` (e.g., to 320x176) (lower accuracy). Note: For maximum accuracy, follow [doc/1_demo.md#maximum-accuracy-configuration](1_demo.md#maximum-accuracy-configuration).
     2. For face, reduce the `--face_net_resolution`. The resolution 320x320 usually works pretty decently.
     3. Points 1-2 will also reduce the GPU memory usage (or RAM memory for CPU version).
     4. Use the `BODY_25` model for maximum speed. Use `MPI_4_layers` model for minimum GPU memory usage (but lower accuracy, speed, and number of parts).

doc/major_released_features.md → doc/6_major_released_features.md

@@ -2,23 +2,23 @@ OpenPose Doc - Major Released Features
 ====================================
 
 - Nov 2020: [**Python API improved and included on Windows portable binaries**](https://github.com/CMU-Perceptual-Computing-Lab/openpose/releases)!
-- Nov 2020: [Compatibility with Nvidia 30XX cards, CUDA 11, and Ubuntu 20](installation/README.md)!
+- Nov 2020: [Compatibility with Nvidia 30XX cards, CUDA 11, and Ubuntu 20](installation/0_index.md)!
 - Sep 2019: [**Training code released**](https://github.com/CMU-Perceptual-Computing-Lab/openpose_train)!
 - Jan 2019: [**Unity plugin released**](https://github.com/CMU-Perceptual-Computing-Lab/openpose_unity_plugin)!
-- Jan 2019: [**Improved Python API**](doc/python_api.md) released! Including body, face, hands, and all the functionality of the C++ API!
+- Jan 2019: [**Improved Python API**](doc/3_python_api.md) released! Including body, face, hands, and all the functionality of the C++ API!
 - Dec 2018: [**Foot dataset released**](https://cmu-perceptual-computing-lab.github.io/foot_keypoint_dataset) and [**new paper released**](https://arxiv.org/abs/1812.08008)!
-- Sep 2018: [**Experimental tracker**](demo_quick_start.md#tracking)!
-- Jun 2018: [**Combined body-foot model released! 40% faster and 5% more accurate**](installation/README.md)!
-- Jun 2018: [**Python API**](python_api.md) released!
-- Jun 2018: [**OpenCL/AMD graphic card version**](installation/README.md) released!
+- Sep 2018: [**Experimental tracker**](1_demo.md#tracking)!
+- Jun 2018: [**Combined body-foot model released! 40% faster and 5% more accurate**](installation/0_index.md)!
+- Jun 2018: [**Python API**](3_python_api.md) released!
+- Jun 2018: [**OpenCL/AMD graphic card version**](installation/0_index.md) released!
 - Jun 2018: [**Calibration toolbox**](advanced/calibration_module.md) released!
-- Jun 2018: [**Mac OSX version (CPU)**](installation/README.md) released!
-- Mar 2018: [**CPU version**](installation/README.md)!
+- Jun 2018: [**Mac OSX version (CPU)**](installation/0_index.md) released!
+- Mar 2018: [**CPU version**](installation/0_index.md)!
 - Mar 2018: [**3-D keypoint reconstruction module**](advanced/3d_reconstruction_module.md) (from multiple camera views)!
-- Sep 2017: [**CMake**](installation/README.md) installer and **IP camera** support!
+- Sep 2017: [**CMake**](installation/0_index.md) installer and **IP camera** support!
 - Jul 2017: [**Windows portable binaries and demo**](https://github.com/CMU-Perceptual-Computing-Lab/openpose/releases)!
 - Jul 2017: **Hands** released!
 - Jun 2017: **Face** released!
 - May 2017: **Windows** version!
 - Apr 2017: **Body** released!
-For further details, check the [release notes](release_notes.md).
+For further details, check the [release notes](7_release_notes.md).

doc/release_notes.md → doc/7_release_notes.md

@@ -446,9 +446,10 @@ OpenPose Doc - Release Notes
         3. More examples added to the demo quick start documentation.
     6. Calibration doc links to included chessboard pdf.
     7. Deprecated examples directories `tutorial_add_module` and `tutorial_api_thread` (and renamed as `deprecated`). They still compile, but we no longer support them.
-    8. GitHub Pages autogenerated into https://cmu-perceptual-computing-lab.github.io/openpose with README.md, doc/ and include/openpose folders.
+    8. GitHub Pages autogenerated into https://cmu-perceptual-computing-lab.github.io/openpose/web/html/doc/ with README.md, doc/ and include/openpose folders.
 2. Functions or parameters renamed:
     1. Added GitHub Actions (Workspaces) to test Ubuntu and Mac OSX versions (rather than the deprecated Travis). Travis was giving many issues, that were not OpenPose errors, making Travis not usable. Its code has been left for now (but commented out).
+    2. Doc highly reordered and renamed in order to fit the Doxygen and GitHub Markdown styles simultaneously.
 3. Main bugs fixed:
     1. Eigen working again on Windows.
     2. OpenPose links to the right OpenCV DLL Files on Windows (it was wrongly linking to v14 rather than v15).

doc/authors_and_contributors.md → doc/8_authors_and_contributors.md

@@ -4,17 +4,20 @@ OpenPose Doc - Authors and Contributors
 
 
 ### Authors
-OpenPose is authored by [Ginés Hidalgo](https://www.gineshidalgo.com/), [Zhe Cao](http://www.andrew.cmu.edu/user/zhecao), [Tomas Simon](http://www.cs.cmu.edu/~tsimon/), [Shih-En Wei](https://scholar.google.com/citations?user=sFQD3k4AAAAJ&hl=en), [Hanbyul Joo](http://www.cs.cmu.edu/~hanbyulj/), and [Yaser Sheikh](http://www.cs.cmu.edu/~yaser/). The body pose estimation work is based on the following and original 2 repositories: [CVPR 2017 repository](https://github.com/ZheC/Multi-Person-Pose-Estimation) and [ECCV 2016 repository](https://github.com/CMU-Perceptual-Computing-Lab/caffe_rtpose).
+OpenPose is authored by [Ginés Hidalgo](https://www.gineshidalgo.com), [Zhe Cao](https://people.eecs.berkeley.edu/~zhecao), [Tomas Simon](http://www.cs.cmu.edu/~tsimon), [Shih-En Wei](https://scholar.google.com/citations?user=sFQD3k4AAAAJ&hl=en), [Hanbyul Joo](https://jhugestar.github.io), and [Yaser Sheikh](http://www.cs.cmu.edu/~yaser). It is maintained by [Ginés Hidalgo](https://www.gineshidalgo.com) and [Yaadhav Raaj](https://www.raaj.tech).
 
+OpenPose would not be possible without the [**CMU Panoptic Studio dataset**](http://domedb.perception.cs.cmu.edu). The body pose estimation work is based on the following and original 2 repositories: [CVPR 2017 repository](https://github.com/ZheC/Multi-Person-Pose-Estimation) and [ECCV 2016 repository](https://github.com/CMU-Perceptual-Computing-Lab/caffe_rtpose).
 
 
-### Contributors
-We would also like to thank the following people who have highly contributed to OpenPose:
 
+### Contributors
+We would also like to thank the following people, who have contributed to key components of OpenPose:
 1. [Yaadhav Raaj](https://www.raaj.tech): OpenPose maintainer, CPU version, OpenCL version, Mac version, Python API, and person tracker.
 2. [Bikramjot Hanzra](https://www.linkedin.com/in/bikz05): Former OpenPose maintainer, CMake (Ubuntu and Windows) version, and initial Travis Build version for Ubuntu.
 3. [Donglai Xiang](https://xiangdonglai.github.io): Camera calibration toolbox improvement, including the implementation of its bundle adjustment algorithm.
 4. [Luis Fernando Fraga](https://github.com/fragalfernando): Implementation of Lukas-Kanade algorith and person ID extractor.
 5. [Akash Patwal](https://www.linkedin.com/in/akash-patwal-63a12012a): Speedup of the CUDA image resize and visual skeleton rendering, as well as extension that allows OpenPose to speedup linearly to more than 4 GPUs.
-6. [Helen Medina](https://github.com/helen-medina): Initial Windows version.
-7. [Matthijs van der Burgh](https://github.com/MatthijsBurgh): Initial GitHub Actions CI version for Ubuntu and Mac, and ported all the deprecated Travis CI tests into the new CI system.
+6. [Helen Medina](https://github.com/helen-medina): First Windows version.
+7. [Matthijs van der Burgh](https://github.com/MatthijsBurgh): First GitHub Actions CI version for Ubuntu and Mac, and ported all the deprecated Travis CI tests into the new CI system.
+
+We would also like to thank all the people who [has helped OpenPose in any way](https://github.com/CMU-Perceptual-Computing-Lab/openpose/graphs/contributors).

doc/README.md

-OpenPose Doc
-==========================
-
-Most users can simply use the OpenPose Demo without reading any C++/Python code. Users that need to add additional functionality (new inputs, outputs, etc) should check the C++/Python APIs:
-
-- The first step for any software, [installing](installation/README.md) it!
-
-- [**Output information**](output.md): Learn about the output format, keypoint index ordering, etc.
-
-- [**OpenPose Demo**](demo_quick_start.md) for your terminal or PowerShell: Choose your input (e.g., images, video, webcam), set of algorithms (body, hand, face), and output (e.g., display, JSON keypoint saving, image+keypoints).
-    - E.g.: Given an input video (`--video`), extract body (by default), face (`--face`) and hand (`--hand`) keypoints, save the keypoints in a JSON file (`--write_json`), and display (by default) the results in the screen. You can remove any of the flags to remove that particular functionality or add any other.
-```
-# Ubuntu
-./build/examples/openpose/openpose.bin --video examples/media/video.avi --face --hand --write_json output_json_folder/
-
-:: Windows - Portable Demo
-bin\OpenPoseDemo.exe --video examples\media\video.avi --face --hand --write_json output_json_folder/
-```
-
-- [**OpenPose C++ API**](../examples/tutorial_api_cpp/): If you want to read a specific input, and/or add your custom post-processing function, and/or implement your own display/saving.
-	- You should be familiar with the [**OpenPose Demo**](demo_quick_start.md) and the main OpenPose flags before trying to read the C++ or Python API examples. Otherwise, it will be way harder to follow.
-    - For quick prototyping: You can easily **create your custom code** on [examples/user_code/](../examples/user_code/) and CMake will automatically compile it together with the whole OpenPose project. See [examples/user_code/README.md](../examples/user_code/README.md) for more details.
-
-- [**OpenPose Python API**](../examples/tutorial_api_python/): Almost the exact same functionality than the C++ API, but in Python!
-	- You should be familiar with the [**OpenPose Demo**](demo_quick_start.md) and the main OpenPose flags before trying to read the C++ or Python API examples. Otherwise, it will be way harder to follow.
-    - For quick prototyping: You can simply duplicate and rename any of the [existing example files](../examples/tutorial_api_python/) within that same folder.
-
-- [**Speeding up OpenPose and benchmark**](maximizing_openpose_speed.md): Check the OpenPose Benchmark as well as some hints to speed up and/or reduce the memory requirements for OpenPose.
-
-- [**Calibration toolbox**](advanced/calibration_module.md) and [**3D OpenPose**](advanced/3d_reconstruction_module.md): Calibrate your cameras for 3D OpenPose (or any other stereo vision tasks) and start obtaining 3D keypoints!
-
-- [**Standalone face or hand detector**](advanced/standalone_face_or_hand_keypoint_detector.md) is useful if you want to do any of the following:
-    - **Face** keypoint detection **without body** keypoint detection: Pros: Speedup and RAM/GPU memory reduction. Cons: Worse accuracy and less detected number of faces).
-    - **Use your own face/hand detector**: You can use the hand and/or face keypoint detectors with your own face or hand detectors, rather than using the body detector. E.g., useful for camera views at which the hands are visible but not the body (OpenPose detector would fail).
+The OpenPose documentation is available in 2 different formats, choose your preferred one!
+- As a traditional website (recommended): [cmu-perceptual-computing-lab.github.io/openpose/web/html/doc/](https://cmu-perceptual-computing-lab.github.io/openpose/web/html/doc/).
+- As markdown files: [github.com/CMU-Perceptual-Computing-Lab/openpose/tree/master/doc](https://github.com/CMU-Perceptual-Computing-Lab/openpose/tree/master/doc).

doc/advanced/3d_reconstruction_module.md

-OpenPose Doc - Advanced Doc - OpenPose 3-D Reconstruction Module and Demo
+OpenPose Advanced Doc - 3-D Reconstruction Module and Demo
 =============================================
 
 ## Contents
@@ -23,13 +23,13 @@ This module performs 3-D keypoint (body, face, and hand) reconstruction and rend
 
 
 ## Installation
-Check [doc/installation/README.md#3d-reconstruction-module](../installation/README.md#3d-reconstruction-module) for installation steps.
+Check [doc/installation/0_index.md#3d-reconstruction-module](../installation/0_index.md#3d-reconstruction-module) for installation steps.
 
 
 
 
 ## Non Linear Optimization
-In order to increase the 3-D reconstruction accuracy, OpenPose optionally performs non-linear optimization if Ceres solver support is enabled (only available in Ubuntu for now). To enable it, check [doc/installation/README.md#3d-reconstruction-module](../installation/README.md#3d-reconstruction-module) for more details.
+In order to increase the 3-D reconstruction accuracy, OpenPose optionally performs non-linear optimization if Ceres solver support is enabled (only available in Ubuntu for now). To enable it, check [doc/installation/0_index.md#3d-reconstruction-module](../installation/0_index.md#3d-reconstruction-module) for more details.
 
 
 
@@ -86,7 +86,7 @@ OpenPose will display the cameras sorted by serial number, starting in the left
 
 
 ## Quick Start
-Check the [doc/demo_quick_start.md#3-d-reconstruction](../demo_quick_start.md#3-d-reconstruction) for basic examples.
+Check the [doc/1_demo.md#3-d-reconstruction](../1_demo.md#3-d-reconstruction) for basic examples.
 
 
 
@@ -101,6 +101,8 @@ It should be similar to the following image.
 
 <p align="center">
     <img src="../../.github/media/openpose3d.gif">
+    <br>
+    <sup><a href="https://ziutinyat.github.io/" target="_blank">Tianyi Zhao</a> testing the 3-D Module</a></sup>
 </p>
 
 

doc/advanced/calibration_module.md

-OpenPose Doc - Advanced Doc - OpenPose Calibration Module and Demo
+OpenPose Advanced Doc - Calibration Module and Demo
 =============================================
 
 ## Contents
@@ -31,7 +31,7 @@ Note: We are not aiming to have the best calibration toolbox, but the simplest o
 
 
 ## Installing the Calibration Module
-Check [doc/installation/README.md#calibration-module](../installation/README.md#calibration-module) for installation steps.
+Check [doc/installation/0_index.md#calibration-module](../installation/0_index.md#calibration-module) for installation steps.
 
 
 

doc/demo_not_quick_start.md → doc/advanced/demo_advanced.md

-OpenPose Doc - Demo - Not Quick Start
+OpenPose Advanced Doc - Demo - Advanced
 ====================================
 
-This document is a more detailed continuation of [doc/demo_quick_start.md](demo_quick_start.md), and it assumes the user is quite familiar with the OpenPose demo and the contents of [doc/demo_quick_start.md](demo_quick_start.md).
+This document is a more detailed continuation of [doc/1_demo.md](../1_demo.md), and it assumes the user is quite familiar with the OpenPose demo and the contents of [doc/1_demo.md](../1_demo.md).
 
 
 
@@ -25,7 +25,7 @@ This document is a more detailed continuation of [doc/demo_quick_start.md](demo_
 In general, there are 3 ways to reduce the latency (with some drawbacks each one):
 
 - Reducing `--output_resolution`: It will slightly reduce the latency and increase the FPS. But the quality of the displayed image will deteriorate.
-- Reducing `--net_resolution` and/or `--face_net_resolution` and/or `--hand_net_resolution`: It will increase the FPS and reduce the latency. But the accuracy will drop, specially for small people in the image. Note: For maximum accuracy, follow [doc/demo_quick_start.md#maximum-accuracy-configuration](demo_quick_start.md#maximum-accuracy-configuration).
+- Reducing `--net_resolution` and/or `--face_net_resolution` and/or `--hand_net_resolution`: It will increase the FPS and reduce the latency. But the accuracy will drop, specially for small people in the image. Note: For maximum accuracy, follow [doc/1_demo.md#maximum-accuracy-configuration](../1_demo.md#maximum-accuracy-configuration).
 - Enabling `--disable_multi_thread`: The latency should be reduced. But the speed will drop to 1-GPU speed (as it will only use 1 GPU). Note that it's practical only for body, if hands and face are also extracted, it's usually not worth it.
 
 
@@ -65,7 +65,7 @@ In general, there are 3 ways to reduce the latency (with some drawbacks each one
 
 
 ### Heat Maps Storing
-The following command will save all the body part heat maps, background heat map and Part Affinity Fields (PAFs) in the folder `output_heatmaps_folder`. It will save them on PNG format. Instead of individually saving each of the 67 heatmaps (18 body parts + background + 2 x 19 PAFs) individually, the library concatenate them vertically into a huge (width x #heatmaps) x (height) matrix. The PAFs channels are multiplied by 2 because there is one heatmpa for the x-coordinates and one for the y-coordinates. The order is body parts + bkg + PAFs. It will follow the sequence on POSE_BODY_PART_MAPPING in [include/openpose/pose/poseParameters.hpp](../include/openpose/pose/poseParameters.hpp).
+The following command will save all the body part heat maps, background heat map and Part Affinity Fields (PAFs) in the folder `output_heatmaps_folder`. It will save them on PNG format. Instead of individually saving each of the 67 heatmaps (18 body parts + background + 2 x 19 PAFs) individually, the library concatenate them vertically into a huge (width x #heatmaps) x (height) matrix. The PAFs channels are multiplied by 2 because there is one heatmpa for the x-coordinates and one for the y-coordinates. The order is body parts + bkg + PAFs. It will follow the sequence on POSE_BODY_PART_MAPPING in [include/openpose/pose/poseParameters.hpp](../../include/openpose/pose/poseParameters.hpp).
 ```
 ./build/examples/openpose/openpose.bin --video examples/media/video.avi --heatmaps_add_parts --heatmaps_add_bkg --heatmaps_add_PAFs --write_heatmaps output_heatmaps_folder/
 ```
@@ -217,7 +217,7 @@ Now that you are more familiar with OpenPose, this is a list with all the availa
 - DEFINE_int32(write_coco_json_variants,  1,              "Add 1 for body, add 2 for foot, 4 for face, and/or 8 for hands. Use 0 to use all the possible candidates. E.g., 7 would mean body+foot+face COCO JSON.");
 - DEFINE_int32(write_coco_json_variant,   0,              "Currently, this option is experimental and only makes effect on car JSON generation. It selects the COCO variant for cocoJsonSaver.");
 - DEFINE_string(write_heatmaps,           "",             "Directory to write body pose heatmaps in PNG format. At least 1 `add_heatmaps_X` flag must be enabled.");
-- DEFINE_string(write_heatmaps_format,    "png",          "File extension and format for `write_heatmaps`, analogous to `write_images_format`. For lossless compression, recommended `png` for integer `heatmaps_scale` and `float` for floating values. See `doc/output.md` for more details.");
+- DEFINE_string(write_heatmaps_format,    "png",          "File extension and format for `write_heatmaps`, analogous to `write_images_format`. For lossless compression, recommended `png` for integer `heatmaps_scale` and `float` for floating values. See `doc/2_output.md` for more details.");
 - DEFINE_string(write_keypoint,           "",             "(Deprecated, use `write_json`) Directory to write the people pose keypoint data. Set format with `write_keypoint_format`.");
 - DEFINE_string(write_keypoint_format,    "yml",          "(Deprecated, use `write_json`) File extension and format for `write_keypoint`: json, xml, yaml & yml. Json not available for OpenCV < 3.0, use `write_json` instead.");
 

doc/advanced/deployment.md

-OpenPose Doc - Advanced Doc - Deploying OpenPose (Exporting OpenPose to Other Projects)
+OpenPose Advanced Doc - Deploying/Exporting OpenPose to Other Projects
 ==========================
 
 ## Contents
@@ -18,7 +18,7 @@ Starting in OpenPose 1.6.0 (GitHub code in or after October 2019), OpenPose has
 
 
 ### Third-Party Libraries
-While compiling OpenPose from source, the static library files (`*.a` for Ubuntu, `*.lib` for Windows, etc.) and `include/` directories of all the third-party libraries detailed in [doc/installation/README.md](../installation/README.md) are required (GFlags, Glog, OpenCV, Caffe, etc.). However, when deploying OpenPose, fewer dependencies are required:
+While compiling OpenPose from source, the static library files (`*.a` for Ubuntu, `*.lib` for Windows, etc.) and `include/` directories of all the third-party libraries detailed in [doc/installation/0_index.md](../installation/0_index.md) are required (GFlags, Glog, OpenCV, Caffe, etc.). However, when deploying OpenPose, fewer dependencies are required:
 - GFLags and Glog are required only if the `include/openpose/flags.hpp` file is going to be used (e.g., when intenting to use the command-line interface).
 - OpenCV can be optionally included if your project already uses it (but make sure to use the same binaries and include directory of OpenCV for both OpenPose and your project or weird runtime crashes will occur!). Including OpenCV does not increase the functionality of OpenPose, but it makes it easier to use by adding some functions that directly take cv::Mat matrices as input (rather than raw pointers). However, it is optional starting in OpenPose 1.6.0.
 - Caffe or any other 3rd-party libraries are not required.

doc/output_advanced_heatmaps.md → doc/advanced/heatmap_output.md

-OpenPose Doc - Output - Heatmaps (Advanced)
+OpenPose Advanced Doc - Heatmap Output
 ====================================
 
 
@@ -15,7 +15,7 @@ OpenPose Doc - Output - Heatmaps (Advanced)
 
 
 ## Keypoints
-Check [doc/output_keypoints.md](output_keypoints.md) for the basic output information. This document is for users that want to use the heatmaps.
+Check [doc/output_keypoints.md](../2_output.md) for the basic output information. This document is for users that want to use the heatmaps.
 
 
 
@@ -24,11 +24,11 @@ Check [doc/output_keypoints.md](output_keypoints.md) for the basic output inform
 ## UI and Visual Heatmap Output
 If you choose to visualize a body part or a PAF (Part Affinity Field) heat map with the command option `--part_to_show`, the visual GUI should show something similar to one of the following images:
 <p align="center">
-    <img src="../.github/media/body_heat_maps.png", width="720">
+    <img src="../.github/media/body_heat_maps.png" width="720">
 </p>
 
 <p align="center">
-    <img src="../.github/media/paf_heat_maps.png", width="720">
+    <img src="../.github/media/paf_heat_maps.png" width="720">
 </p>
 
 

doc/advanced/library_structure/library_how_to_develop.md

-OpenPose Doc - Advanced Doc - Library Structure - How to Develop OpenPose
-======================================================
-
-
-
-
-
-## OpenPose Coding Style
-1. Error-prone mistakes:
-    1. Do never use std::mutex.lock and/or std::mutex.unlock. Use std::unique_lock<std::mutex> if unlock required or std::lock_guard<std::mutex> otherwise.
-    2. Do never use the new keyword with std::shared_ptr, but rather: std::make_shared<>.
-2. Naming:
-    1. Class parameters should start with `m`, class pointers with `p`, shared_ptrs with `sp`, unique_ptrs with `up`, static parameters with `s`.
-    2. Function and class parameters coding style is the same other than the previous point.
-    3. Any parameters should not contain special characters, simply letters and numbers (preferred only letters) separated with upper case. E.g., `mThisIsAParameter`, `thisIsAParameter`.
-    4. In addition, the names should be self-explanatory and not abbreviated. Good examples: `counter`, `thisIs`. Bad examples: `ctr`, `var`.
-3. Length:
-    1. Lines should contain up to 120 characters.
-4. Comments:
-    1. Only `//` comments are allowed in the code, `/* */` should not be used.
-    2. There should be a (at least) 1-line comment for each block of code inside each function.
-5. Loops and statements:
-    1. There should be a space between the keyword (`if`, `for`, etc) and the parenthesis, e.g., `if (true)`. Wrong: `if(true)`. Note: So they can be easily located with Ctrl + F.
-    2. Braces should be added in the following line with respect to the loop/statement keyword. See example in point 3.
-    3. 1-line loops/statements should not contain braces. E.g.,
-```
-if (booleanParameter)
-    anotherParameter = 25;
-else
-{
-    anotherParameter = 2;
-    differentParameter = 3;
-}
-```
-
-6. Includes:
-    1. There cannot be any include to a 3rd party in the headers (other than OpenCV core: `opencv2/core/core.hpp`).
-        1. PImpl idiom can be checked (e.g., in `include/openpose/pose/poseExtractorCaffe.hpp`) for an idea of how to avoid it.
-        2. Otherwise the defining class examples in `include/openpose/core/macros.hpp` (point 1 is highly preferred).
-    2. They should be sorted in this order:
-        1. Std libraries.
-        2. OS libraries.
-        3. 3rd party libraries (e.g., Caffe, OpenCV).
-        4. OpenPose libraries.
-        5. If it is a cpp file, the last one should be its own hpp.
-    3. Inside each of the previous groups, it should be sorted alphabetically.
-7. Functions arguments:
-    1. It should first include the variables to be edited, and secondly the const variables.
-    2. Any variable that is not gonna be modified must be added with `const`.
-8. Pointers:
-    1. Pointers must be avoided if possible.
-    2. If a pointer must be used, std::unique_ptr must be always be used.
-    3. If the pointer must be shared, then std::shared_ptr.
-    4. No `delete` keyword is allowed in OpenPose.
-
-
-
-
-
-## Debugging C++ Code
-### Finding Segmentation Faults
-This is the faster method to debug a segmentation fault problem. Usual scenario: You are editing OpenPose source code and suddenly OpenPose returns segmentation fault when executed. In order to find where it occurs:
-
-    1. Select one of the 2 options:
-        1. Switch to debug mode.
-        2. Go to `openpose/utilities/errorAndLog.hpp` and modify `dLog`:
-            1. Comment `#ifndef NDEBUG` and its else and endif.
-    2. Call OpenPose with `--logging_level 0 --disable_multi_thread`.
-    3. At this point you have an idea of in which file class the segmentation fault is coming from. Now you can further isolate the error by iteratively adding the following line all over the code until you find the exact position of the segmentation fault: `opLog("", Priority::Low, __LINE__, __FUNCTION__, __FILE__);`
-    4. After you have found the segmentation fault, remember to remove all the extra `opLog()` calls that you temporarily added.
-
-
-
-
-
-## Speed
-### Measuring Runtime Speed
-1. Enable `PROFILER_ENABLED` with CMake or in the `Makefile.config` file.
-2. By default, it should print out average runtime info after 1000 frames. You can change this number with `--profile_speed`, e.g., `--profile_speed 100`.
-
-
-
-
-
-## Accuracy
-### Checking OpenPose Accuracy Quantitatively
-1. Download OpenPose training code: https://github.com/CMU-Perceptual-Computing-Lab/openpose_train
-2. Download val2017 set from COCO: http://images.cocodataset.org/zips/val2017.zip
-3. Get JSONs in OpenPose: examples/tests/pose_accuracy_coco_val.sh
-4. Get accuracy (Matlab): validation/f_getValidations.m
-
-### Checking Ground-Truth Labels
-From the [COCO dataset](http://cocodataset.org/#download):
-1. Download 2014 or 2017 Train/Val annotations.
-2. Download the [COCO API](https://github.com/cocodataset/cocoapi).
-3. With the COCO API (either Python, Matlab, or LUA ones), you can check any image with the image ID (equivalent to the number in the image name).

doc/advanced/standalone_face_or_hand_keypoint_detector.md

-OpenPose Doc - Advanced Doc - Standalone Face Or Hand Keypoint Detector
+OpenPose Advanced Doc - Standalone Face or Hand Keypoint Detector
 ====================================
 
 In case of hand camera views at which the hands are visible but not the rest of the body, or if you do not need the body keypoint detector and want to speed up the process, you can use the OpenPose face or hand keypoint detectors with your own face or hand detectors, rather than using the body keypoint detector as initial detector for those.

doc/installation/prerequisites.md → doc/installation/1_prerequisites.md

@@ -9,7 +9,7 @@ OpenPose Doc - Installation - Prerequisites
 
 
 
-### General Tips
+## General Tips
 These tips are **very important** and avoid many bugs:
 - Install the latest CUDA version or make sure your GPU is compatible with the CUDA version you have in your system. E.g., Nvidia 30XX GPUs require at least CUDA 11, others (GTX 20XX, V100, Volta or Turing GPUs) require at least CUDA 10.
 - CMake automatically downloads all the OpenPose models. However, **some firewall or company networks block these downloads**. If so, you might need to download them manually:
@@ -21,7 +21,7 @@ These tips are **very important** and avoid many bugs:
 
 
 
-### Ubuntu Prerequisites
+## 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 20: Run the command `sudo apt-get install cmake-qt-gui`.
@@ -34,7 +34,7 @@ These tips are **very important** and avoid many bugs:
         - 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/README.md#CMake-Command-Line-Configuration-(Ubuntu-Only)](README.md#cmake-command-line-configuration-ubuntu-only).
+    - 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/0_index.md#CMake-Command-Line-Configuration-(Ubuntu-Only)](0_index.md#cmake-command-line-configuration-ubuntu-only).
 3. Nvidia GPU version prerequisites:
     1. **Note: OpenPose has been tested extensively with CUDA 11.1.1 (cuDNN 8.0.5) for Ubuntu 20**. Older OpenPose versions (v1.6.X and v1.5.X) were tested with **CUDA 10.1 (cuDNN 7.5.1) for Ubuntu 18 and CUDA 8.0 (cuDNN 5.1) for Ubuntu 14 and 16**. We highly recommend using those combinations to minimize potential installation issues. Other combinations should also work, but we do not provide any support about installation/compilation issues related to CUDA/cuDNN or their integration with OpenPose.
     2. Upgrade your Nvidia drivers to the latest version.
@@ -70,14 +70,14 @@ sudo pip install numpy opencv-python
 
 
 
-### Mac OS Prerequisites
+## Mac OS Prerequisites
 1. If you don't have `brew`, install it by running `bash scripts/osx/install_brew.sh` on your terminal.
 2. Install **CMake GUI**: Run the command `brew cask install cmake`.
 3. Install **Caffe, OpenCV, and Caffe prerequisites**: Run `bash scripts/osx/install_deps.sh`.
 
 
 
-### Windows Prerequisites
+## Windows Prerequisites
 NOTE: These instructions are only required when compiling OpenPose brom source. If you simply wanna use the OpenPose binaries for Windows, skip this step.
 
 1. Install **CMake GUI**: Download and install the `Latest Release` of CMake `Windows win64-x64 Installer` from the [CMake download website](https://cmake.org/download/), called `cmake-X.X.X-win64-x64.msi`.

doc/installation/deprecated/installation_deprecated.md

 OpenPose Doc - Installation (deprecated)
 ======================================
 
+NOTE: Do not use this document, see [doc/installation/0_index.md](../0_index.md) instead. This deprecated installation document is kept just for backwards compatibility, but it should not be used.
+
 ## Contents
 1. [Operating Systems](#operating-systems)
 2. [Requirements](#requirements)
@@ -15,28 +17,28 @@ OpenPose Doc - Installation (deprecated)
 
 
 ## Operating Systems
-See [doc/installation/README.md#operating-systems](../README.md#operating-systems).
+See [doc/installation/0_index.md#operating-systems](../0_index.md#operating-systems).
 
 
 
 ## Requirements
-See [doc/installation/README.md#requirements](../README.md#requirements).
+See [doc/installation/0_index.md#requirements](../0_index.md#requirements).
 
 
 
 ## Clone OpenPose
-See [doc/installation/README.md#clone-openpose](../README.md#clone-openpose).
+See [doc/installation/0_index.md#clone-openpose](../0_index.md#clone-openpose).
 
 
 
 ## Update OpenPose
-See [doc/installation/README.md#update-openpose](../README.md#update-openpose).
+See [doc/installation/0_index.md#update-openpose](../0_index.md#update-openpose).
 
 
 
 ## Ubuntu
 ### Installation - CMake
-Recommended installation method, it is simpler and offers more customization settings. See [doc/installation/README.md](../README.md).
+Recommended installation method, it is simpler and offers more customization settings. See [doc/installation/0_index.md](../0_index.md).
 
 
 
@@ -56,7 +58,7 @@ Build Caffe & the OpenPose library + download the required Caffe models for Ubun
 ```bash
 bash scripts/ubuntu_deprecated/install_caffe_and_openpose_if_cuda8.sh
 ```
-**Highly important**: This script only works with CUDA 8 and Ubuntu 14 or 16. Otherwise, see [doc/installation/README.md](../README.md) or [Installation - Manual Compilation](#installation---manual-compilation).
+**Highly important**: This script only works with CUDA 8 and Ubuntu 14 or 16. Otherwise, see [doc/installation/0_index.md](../0_index.md) or [Installation - Manual Compilation](#installation---manual-compilation).
 
 
 
@@ -126,7 +128,7 @@ You just need to remove the OpenPose folder, by default called `openpose/`. E.g.
     3. [**cuDNN 5.1**](https://developer.nvidia.com/cudnn): Once you have downloaded it, just unzip it and copy (merge) the contents on the CUDA folder, `C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v8.0`.
 
 #### CMake Installer
-Recommended installation method, it is simpler and offers more customization settings. See [doc/installation/README.md](../README.md). Note that it is a beta version, post in GitHub any issue you find.
+Recommended installation method, it is simpler and offers more customization settings. See [doc/installation/0_index.md](../0_index.md). Note that it is a beta version, post in GitHub any issue you find.
 
 
 #### Deprecated Windows Installer
@@ -154,7 +156,7 @@ Note: This installer will not incorporate any new features, we recommend to use
     3. Open the Windows cmd (Windows button + <kbd>X</kbd>, then <kbd>A</kbd>).
     4. Go to the OpenPose directory, assuming OpenPose has been downloaded on `C:\openpose`: `cd C:\openpose\`.
     5. Run the tutorial commands.
-6. Check OpenPose was properly installed by running it on the default images, video or webcam: [doc/demo_quick_start.md](../../demo_quick_start.md).
+6. Check OpenPose was properly installed by running it on the default images, video or webcam: [doc/1_demo.md](../../1_demo.md).
 
 
 
@@ -174,7 +176,7 @@ If you updated some software that our library or 3rdparty use, or you simply wan
 
 
 ## Doxygen Documentation Autogeneration
-See [doc/installation/README.md#doxygen-documentation-autogeneration-ubuntu-only](../README.md#doxygen-documentation-autogeneration-ubuntu-only).
+See [doc/installation/0_index.md#doxygen-documentation-autogeneration-ubuntu-only](../0_index.md#doxygen-documentation-autogeneration-ubuntu-only).
 
 
 
@@ -196,4 +198,4 @@ We only modified some Caffe compilation flags and minor details. You can use you
 
 
 ## Compiling without cuDNN
-See [doc/installation/README.md#compiling-without-cudnn](../README.md#compiling-without-cudnn).
+See [doc/installation/0_index.md#compiling-without-cudnn](../0_index.md#compiling-without-cudnn).

doc/installation/jetson_tx/installation_jetson_tx1.md

-OpenPose Doc - Installation - Installation on Nvidia Jetson TX1
+OpenPose Doc - Installation on Nvidia Jetson TX1
 ====================================
 ## Introduction
 We do not officially support TX1, but thanks to @dreinsdo, we have these instructions about how he made it work in his TX1. We would like to thank @dreinsdo, who added this documentation in [this GitHub issue post](https://github.com/CMU-Perceptual-Computing-Lab/openpose/issues/1124#issuecomment-474090671). If you face any issue, feel free to post on that issue post.

doc/installation/jetson_tx/installation_jetson_tx2_jetpack3.1.md

-OpenPose Doc - Installation - Installation on Nvidia Jetson TX2 JetPack 3.1
+OpenPose Doc - Installation on Nvidia Jetson TX2 JetPack 3.1
 ====================================
 Note that OpenPose for Nvidia Jetson TX2 was developed and it is maintained by the community. The OpenPose authors will not be able to provide official support for it.
 

doc/installation/jetson_tx/installation_jetson_tx2_jetpack3.3.md

-OpenPose Doc - Installation - Installation on Nvidia Jetson TX2 JetPack 3.3
+OpenPose Doc - Installation on Nvidia Jetson TX2 JetPack 3.3
 ====================================
 Note that OpenPose for Nvidia Jetson TX2 was developed and it is maintained by the community. The OpenPose authors will not be able to provide official support for it.
 

doc/advanced/library_structure/README.md → doc/very_advanced/library_structure/0_index.md

-OpenPose Doc - Advanced Doc - Library Structure
+OpenPose Very Advanced Doc - Library Structure
 ====================================
 
 As a user, you do not need to know anything about this section! This section is intended for OpenPose internal developpers. It is exposed publicly, but you can skip this whole folder if you are just trying to use OpenPose or create new code/demos using OpenPose.
@@ -6,8 +6,8 @@ As a user, you do not need to know anything about this section! This section is
 Even if you want to e.g., change internal functions and/or extend the OpenPose functionality, the easiest solution as a user is to follow the [examples/tutorial_api_cpp](../../examples/tutorial_api_cpp) examples. If the new functionality is cool, make a pull request so we can add it to OpenPose!
 
 In order to learn the basics about how OpenPose works internally:
-1. Take a look at the [library Quick Start section](../../README.md#quick-start) from the main README.
-2. OpenPose Overview: Learn the basics about the library source code in [doc/advanced/library_structure/library_overview.md](library_overview.md).
-3. Extending Functionality: Learn how to extend the library in [doc/advanced/library_structure/library_extend_functionality.md](library_extend_functionality.md).
-4. Adding An Extra Module: Learn how to add an extra module in [doc/advanced/library_structure/library_add_new_module.md](library_add_new_module.md).
-5. See the Doxygen documentation on [http://cmu-perceptual-computing-lab.github.io/openpose/html/index.html](http://cmu-perceptual-computing-lab.github.io/openpose/html/index.html) or build it from the source code.
+1. See the Doxygen documentation on [http://cmu-perceptual-computing-lab.github.io/openpose/web/html/doc/](http://cmu-perceptual-computing-lab.github.io/openpose/web/html/doc/) or build that Doxygen doc from the source code.
+2. Take a look at the [library Quick Start section](../../README.md#quick-start) from the main README (or its Doxygen analog).
+3. OpenPose Overview: Learn the basics about the library source code in [doc/very_advanced/library_structure/1_library_deep_overview.md](1_library_deep_overview.md).
+4. Extending Functionality: Learn how to extend the library in [doc/very_advanced/library_structure/2_library_extend_functionality.md](2_library_extend_functionality.md).
+5. Adding An Extra Module: Learn how to add an extra module in [doc/very_advanced/library_structure/3_library_add_new_module.md](3_library_add_new_module.md).

doc/advanced/library_structure/library_overview.md → doc/very_advanced/library_structure/1_library_deep_overview.md

-OpenPose Doc - Advanced Doc - Library Structure - Basic Overview
+OpenPose Very Advanced Doc - Library Structure - Deep Overview
 ====================================
 
 
 
-Note: Read [doc/advanced/library_structure/README.md](README.md) before this page.
+Note: Read [doc/very_advanced/library_structure/0_index.md](0_index.md) before this page.
 
 
 
 ## Modules Diagram
 <p align="center">
-    <img src="./UML/1_0_0rc3/UML.png", width="720">
+    <img src="./UML/1_0_0rc3/UML.png" width="720">
 </p>
 
 
 
+## Debugging C++ Code
+### Finding Segmentation Faults
+This is the faster method to debug a segmentation fault problem. Usual scenario: You are editing OpenPose source code and suddenly OpenPose returns segmentation fault when executed. In order to find where it occurs:
+
+1. Select one of the 2 options:
+    1. Switch to debug mode.
+    2. Go to `openpose/utilities/errorAndLog.hpp` and modify `dLog`:
+        1. Comment `#ifndef NDEBUG` and its else and endif.
+2. Call OpenPose with `--logging_level 0 --disable_multi_thread`.
+3. At this point you have an idea of in which file class the segmentation fault is coming from. Now you can further isolate the error by iteratively adding the following line all over the code until you find the exact position of the segmentation fault: `opLog("", Priority::Low, __LINE__, __FUNCTION__, __FILE__);`
+4. After you have found the segmentation fault, remember to remove all the extra `opLog()` calls that you temporarily added.
+
+
+
+## Accuracy
+### Checking OpenPose Accuracy Quantitatively
+1. Download OpenPose training code: https://github.com/CMU-Perceptual-Computing-Lab/openpose_train
+2. Download val2017 set from COCO: http://images.cocodataset.org/zips/val2017.zip
+3. Get JSONs in OpenPose: examples/tests/pose_accuracy_coco_val.sh
+4. Get accuracy (Matlab): validation/f_getValidations.m
+
+### Checking Ground-Truth Labels
+From the [COCO dataset](http://cocodataset.org/#download):
+1. Download 2014 or 2017 Train/Val annotations.
+2. Download the [COCO API](https://github.com/cocodataset/cocoapi).
+3. With the COCO API (either Python, Matlab, or LUA ones), you can check any image with the image ID (equivalent to the number in the image name).
+
+
+
+## OpenPose Coding Style
+1. Error-prone mistakes:
+    1. Do never use std::mutex.lock and/or std::mutex.unlock. Use std::unique_lock<std::mutex> if unlock required or std::lock_guard<std::mutex> otherwise.
+    2. Do never use the new keyword with std::shared_ptr, but rather: std::make_shared<>.
+2. Naming:
+    1. Class parameters should start with `m`, class pointers with `p`, shared_ptrs with `sp`, unique_ptrs with `up`, static parameters with `s`.
+    2. Function and class parameters coding style is the same other than the previous point.
+    3. Any parameters should not contain special characters, simply letters and numbers (preferred only letters) separated with upper case. E.g., `mThisIsAParameter`, `thisIsAParameter`.
+    4. In addition, the names should be self-explanatory and not abbreviated. Good examples: `counter`, `thisIs`. Bad examples: `ctr`, `var`.
+3. Length:
+    1. Lines should contain up to 120 characters.
+4. Comments:
+    1. Only `//` comments are allowed in the code, `/* */` should not be used.
+    2. There should be a (at least) 1-line comment for each block of code inside each function.
+5. Loops and statements:
+    1. There should be a space between the keyword (`if`, `for`, etc) and the parenthesis, e.g., `if (true)`. Wrong: `if(true)`. Note: So they can be easily located with Ctrl + F.
+    2. Braces should be added in the following line with respect to the loop/statement keyword. See example in point 3.
+    3. 1-line loops/statements should not contain braces. E.g.,
+```
+if (booleanParameter)
+    anotherParameter = 25;
+else
+{
+    anotherParameter = 2;
+    differentParameter = 3;
+}
+```
+
+6. Includes:
+    1. There cannot be any include to a 3rd party in the headers (other than OpenCV core: `opencv2/core/core.hpp`).
+        1. PImpl idiom can be checked (e.g., in `include/openpose/pose/poseExtractorCaffe.hpp`) for an idea of how to avoid it.
+        2. Otherwise the defining class examples in `include/openpose/core/macros.hpp` (point 1 is highly preferred).
+    2. They should be sorted in this order:
+        1. Std libraries.
+        2. OS libraries.
+        3. 3rd party libraries (e.g., Caffe, OpenCV).
+        4. OpenPose libraries.
+        5. If it is a cpp file, the last one should be its own hpp.
+    3. Inside each of the previous groups, it should be sorted alphabetically.
+7. Functions arguments:
+    1. It should first include the variables to be edited, and secondly the const variables.
+    2. Any variable that is not gonna be modified must be added with `const`.
+8. Pointers:
+    1. Pointers must be avoided if possible.
+    2. If a pointer must be used, std::unique_ptr must be always be used.
+    3. If the pointer must be shared, then std::shared_ptr.
+    4. No `delete` keyword is allowed in OpenPose.
+
+
+
 ## Main Modules
-In order to use and/or slightly extend the OpenPose library, we try to explain the 2 main components on this section. [doc/advanced/library_structure/UML](UML/) contains the class diagram of all these modules.
+In order to use and/or slightly extend the OpenPose library, we try to explain the 2 main components on this section. [doc/very_advanced/library_structure/UML](UML/) contains the class diagram of all these modules.
 
 1. The basic module: `core`.
 
@@ -192,7 +271,7 @@ In order to be initialized, `PoseExtractorCaffe` has the following constructor a
 
 3. `outputSize` is the final desired resolution to be used. The human pose keypoint locations will be scaled to this output size. However, the heat-maps will have the `netOutputSize` size due to performance.
 
-4. `scaleNumber` and `scaleGap` specify the multi-scale parameters. Explained in [doc/demo_not_quick_start.md](../../demo_not_quick_start.md).
+4. `scaleNumber` and `scaleGap` specify the multi-scale parameters. Explained in [doc/advanced/demo_advanced.md](../../advanced/demo_advanced.md).
 
 5. `poseModel` specifies the model to load (e.g., COCO or MPI).
 

doc/advanced/library_structure/library_extend_functionality.md → doc/very_advanced/library_structure/2_library_extend_functionality.md

-OpenPose Doc - Advanced Doc - Library Structure - How to Extend Functionality
+OpenPose Very Advanced Doc - Library Structure - How to Extend Functionality
 ====================================
 
 If you intend to extend the functionality of our library:
 
 1. Read the [README.md](../../../README.md) page.
-2. Check the basic library overview doc on [doc/advanced/library_structure/library_overview.md](library_overview.md).
+2. Check the basic library overview doc on [doc/very_advanced/library_structure/1_library_deep_overview.md](1_library_deep_overview.md).
 3. Read, understand and play with the basic real time pose demo source code [examples/openpose/openpose.cpp](../../../examples/openpose/openpose.cpp) and [examples/tutorial_api_cpp](../../../examples/tutorial_api_cpp). It includes all the functionality of our library, and it has been properly commented.
 4. Read, understand and play with the other tutorials in [examples/](../../../examples/). It includes more specific examples.
-5. Check the basic UML diagram on the [doc/advanced/library_structure/UML](UML/) to get an idea of each module relations.
+5. Check the basic UML diagram on the [doc/very_advanced/library_structure/UML](UML/) to get an idea of each module relations.
 6. Take a look to the stucuture of the already existing modules.
 7. The C++ headers files add documentation in [Doxygen](http://www.doxygen.org/) format. Create this documentation by compiling the [include](../../../include/) folder with Doxygen. This documentation is slowly but continuously improved.
 8. You can also take a look to the source code or ask us on GitHub.

doc/advanced/library_structure/library_add_new_module.md → doc/very_advanced/library_structure/3_library_add_new_module.md

-OpenPose Doc - Advanced Doc - Library Structure - Steps to Add a New Module
+OpenPose Very Advanced Doc - Library Structure - Steps to Add a New Module
 ====================================
 
 ## Developing Steps

include/openpose/core/datum.hpp

@@ -112,7 +112,7 @@ namespace op
          * Order heatmaps: body parts + background (as appears in POSE_BODY_PART_MAPPING) + (x,y) channel of each PAF
          * (sorted as appears in POSE_BODY_PART_PAIRS). See `pose/poseParameters.hpp`.
          * The user can choose the heatmaps normalization: ranges [0, 1], [-1, 1] or [0, 255]. Check the
-         * `heatmaps_scale` flag in {OpenPose_path}doc/demo_not_quick_start.md for more details.
+         * `heatmaps_scale` flag in {OpenPose_path}/doc/advanced/demo_advanced.md for more details.
          * Size: #heatmaps x output_net_height x output_net_width
          */
         Array<float> poseHeatMaps;

include/openpose/flags.hpp

@@ -265,7 +265,7 @@ DEFINE_string(write_heatmaps,           "",             "Directory to write body
                                                         " must be enabled.");
 DEFINE_string(write_heatmaps_format,    "png",          "File extension and format for `write_heatmaps`, analogous to `write_images_format`."
                                                         " For lossless compression, recommended `png` for integer `heatmaps_scale` and `float` for"
-                                                        " floating values. See `doc/output.md` for more details.");
+                                                        " floating values. See `doc/2_output.md` for more details.");
 DEFINE_string(write_keypoint,           "",             "(Deprecated, use `write_json`) Directory to write the people pose keypoint data. Set format"
                                                         " with `write_keypoint_format`.");
 DEFINE_string(write_keypoint_format,    "yml",          "(Deprecated, use `write_json`) File extension and format for `write_keypoint`: json, xml,"

python/openpose/openpose_python.cpp

@@ -321,7 +321,7 @@ namespace op
         m.def("get_images_on_directory", &getImagesFromDirectory, "Get Images On Directory");
 
         // Pose Mapping
-        // Code example in doc/output.md, section Keypoint Ordering in C++/Python
+        // Code example in doc/2_output.md, section Keypoint Ordering in C++/Python
         m.def("getPoseBodyPartMapping", &getPoseBodyPartMapping, "getPoseBodyPartMapping");
         m.def("getPoseNumberBodyParts", &getPoseNumberBodyParts, "getPoseNumberBodyParts");
         m.def("getPosePartPairs", &getPosePartPairs, "getPosePartPairs");