Wrapper into WrapperT with Wrapper class

aslily1234 · Sep 27, 2018 · 25a05f5 · 25a05f5
1 parent fd566ce
commit 25a05f5
Show file tree

Hide file tree

Showing 24 changed files with 195 additions and 178 deletions.
diff --git a/README.md b/README.md
@@ -101,9 +101,9 @@ Otherwise, check [doc/installation.md](doc/installation.md) for instructions on
 
 
 ## Quick Start
-Most users do not need the [OpenPose C++ API](#openpose-c-api), but they can simply use the basic [Demo](#demo) and/or [OpenPose Wrapper](#openpose-wrapper).
+Most users do not need the OpenPose C++/Python API, but can simply use the OpenPose Demo:
 
-- **Demo**: To easily process images/video/webcam and display/save the results. See [doc/demo_overview.md](doc/demo_overview.md). E.g. run OpenPose in a video with:
+- **OpenPose Demo**: To easily process images/video/webcam and display/save the results. See [doc/demo_overview.md](doc/demo_overview.md). E.g. run OpenPose in a video with:
 ```
 # Ubuntu
 ./build/examples/openpose/openpose.bin --video examples/media/video.avi
@@ -123,8 +123,6 @@ bin\OpenPoseDemo.exe --video examples\media\video.avi
     - **Face** keypoint detection **without body** keypoint detection: If you want to speed it up (but also reduce amount of detected faces), check the OpenCV-face-detector approach in [doc/standalone_face_or_hand_keypoint_detector.md](doc/standalone_face_or_hand_keypoint_detector.md).
     - **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). See [doc/standalone_face_or_hand_keypoint_detector.md](doc/standalone_face_or_hand_keypoint_detector.md).
 
-- **Library dependencies**: OpenPose uses default Caffe and OpenCV, as well as any Caffe dependency. The demos additionally use GFlags. It could easily be ported to other deep learning frameworks (Tensorflow, Torch, ...). Feel free to make a pull request if you implement any of those!
-
 
 
 ## Output

diff --git a/doc/installation.md b/doc/installation.md
@@ -4,7 +4,7 @@ OpenPose - Installation
 ## Contents
 1. [Windows Portable Demo](#windows-portable-demo)
 2. [Operating Systems](#operating-systems)
-3. [Requirements](#requirements)
+3. [Requirements and Dependencies](#requirements-and-dependencies)
 4. [Clone OpenPose](#clone-openpose)
 5. [Update OpenPose](#update-openpose)
 6. [Installation](#installation)
@@ -45,19 +45,23 @@ This installation section is only intended if you plan to modify the OpenPose co
 
 
 
-## Requirements
-Requirements for the default configuration (you might need more resources with a greater `--net_resolution` and/or `scale_number` or less resources by reducing the net resolution and/or using the MPI and MPI_4 models):
+## Requirements and Dependencies
+- **Requirements** for the default configuration (you might need more resources with a greater `--net_resolution` and/or `scale_number` or less resources by reducing the net resolution and/or using the MPI and MPI_4 models):
+    - Nvidia GPU version:
+        - NVIDIA graphics card with at least 1.6 GB available (the `nvidia-smi` command checks the available GPU memory in Ubuntu).
+        - At least 2.5 GB of free RAM memory for BODY_25 model or 2 GB for COCO model (assuming cuDNN installed).
+        - Highly recommended: cuDNN.
+     - AMD GPU version:
+        - Vega series graphics card
+        - At least 2 GB of free RAM memory.
+    - CPU version:
+        - Around 8GB of free RAM memory.
+    - Highly recommended: a CPU with at least 8 cores.
+- **Dependencies**:
+    - OpenCV (all 2.X and 3.X versions are compatible).
+    - Caffe and all its dependencies. Interesting in porting OpenPose to other DL frameworks (Tensorflow, Caffe2, Pytorch, ...)?. Email us ([email protected]) if you are interesting in joining the OpenPose team to do so or feel free to make a pull request if you implement any of those!
+    - The demo and tutorials additionally use GFlags.
 
-- Nvidia GPU version:
-    - NVIDIA graphics card with at least 1.6 GB available (the `nvidia-smi` command checks the available GPU memory in Ubuntu).
-    - At least 2.5 GB of free RAM memory for BODY_25 model or 2 GB for COCO model (assuming cuDNN installed).
-    - Highly recommended: cuDNN.
- - AMD GPU version:
-    - Vega series graphics card
-    - At least 2 GB of free RAM memory.
-- CPU version:
-    - Around 8GB of free RAM memory.
-- Highly recommended: a CPU with at least 8 cores.
 
 
 
@@ -348,7 +352,7 @@ After installation, check the [doc/modules/3d_reconstruction_module.md](./module
 
 
 #### Calibration Module
-The calibration module is included by default, but you must also enable `WITH_EIGEN` if you intend to use the extrinsic camera parameter estimation tool. You can set that flag to 2 different values: `APT_GET` or `BUILD`, check [Requirements](#requirements) for more information.
+The calibration module is included by default, but you must also enable `WITH_EIGEN` if you intend to use the extrinsic camera parameter estimation tool. You can set that flag to 2 different values: `APT_GET` or `BUILD`, check [Requirements and Dependencies](#requirements-and-dependencies) for more information.
 
 After installation, check the [doc/modules/calibration_module.md](./modules/calibration_module.md) instructions.
 

diff --git a/doc/installation_jetson_tx2.md b/doc/installation_jetson_tx2.md
@@ -3,13 +3,15 @@ OpenPose - Installation on Nvidia Jetson TX2
 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.
 
 
+
 ## Contents
-1. [Requirements](#requirements)
+1. [Requirements and Dependencies](#requirements-and-dependencies)
 2. [Installation](#installation)
 3. [Usage](#usage)
 
 
-## Requirements
+
+## Requirements and Dependencies
 Jetson TX2 just flashed with [JetPack 3.1](https://developer.nvidia.com/embedded/jetpack)
 
 Notes:
@@ -18,6 +20,13 @@ Notes:
 - If you are installing from a virtual machine host, installation may need to be done in two steps, please refer to [this solution](https://devtalk.nvidia.com/default/topic/1002081/jetson-tx2/jetpack-3-0-install-with-a-vm/).
 - Be sure to complete both OS flashing and CUDA / cuDNN installation parts before installation.
 
+**Dependencies**:
+
+    - OpenCV (all 2.X and 3.X versions are compatible).
+    - Caffe and all its dependencies.
+    - The demo and tutorials additionally use GFlags.
+
+
 
 ## Installation
 Use the following script for installation of both caffe and OpenPose: 

diff --git a/doc/library_add_new_module.md b/doc/library_add_new_module.md
@@ -5,12 +5,12 @@ OpenPose Library - Steps to Add a New Module
 In order to add a new module, these are the recommended steps in order to develop it:
 
 1. Create a folder with its name in the `experimental/` module, e.g. `experimental/hair/`.
-2. Implement all the functionality in one `Worker` (i.e. inherit from `Worker` and implement all the functionality on that class).
+2. Implement all the functionality in one `Worker`. I.e., inherit from `Worker` and implement all the functionality on that class (copy the examples from any Worker subclass).
     1. The first letter of the class name should be `W` (e.g. `WHairExtractor`).
     2. To initially simplify development:
-        1. Initialize the Worker class with the specific std::shared_ptr<std::vector<op::Datum>> instead of directly using a template class (following the `examples/tutorial_api_cpp` synchronous examples).
-        2. Use the whole op::Datum as unique argument of your auxiliary functions.
-        3. Use the OpenPose Wrapper in ThreadManagerMode::SingleThread mode (e.g. it allows you to directly use cv::imshow).
+        1. Optionally (higher debug info), you might initially create the Worker as a non-templated class, assuming it uses std::shared_ptr<std::vector<op::Datum>> instead of directly using a template class (following the `examples/tutorial_api_cpp` synchronous examples). While developing, templates provide more confusing debugging info. Turn the class into a template after being initially developed.
+        2. Optionally (for development speed), use op::Datum as unique argument of your auxiliary functions within that worker.
+        3. Use the OpenPose Wrapper class in ThreadManagerMode::SingleThread mode (e.g., it allows you to directly use cv::imshow).
         4. If you are using your own custom Caffe -> initially change the Caffe for your version. It should directly work.
     3. Copy the design from `pose/WPoseExtractor`.
 3. To test it:
@@ -23,10 +23,10 @@ In order to add a new module, these are the recommended steps in order to develo
 
 
 ## Release Steps
-In order to release the new module:
+After the code is running and ready to be merged, in order to officially release the new module:
 
 1. Move the functionality of each `Worker` class to the non-template class (e.g. `WHairExtractor` to `HairExtractor`). `WHairExtractor` will simply wrap `HairExtractor`. This will reduce compiling time for the user. See examples from other modules.
 2. If you are using a custom Caffe version, move the custom code into the OpenPose library and change back Caffe to the default (most updated) version.
 3. Move the module from `experimental/hair/` to `hair/`.
-4. Remove `experimental` namespaces (from `Wrapper` and `hair`) and turn Workers into template classes.
-5. Add a demo in `examples/openpose/` and tutorial examples in `examples/tutorial_`.
+4. Remove `experimental` namespaces (e.g., from `Wrapper` and `Hair`) and turn Workers into template classes.
+5. Integrate the new flags to the OpenPose Demo in `examples/openpose/` and optionally add some tutorial examples in `examples/tutorial_api_cpp`.
diff --git a/doc/release_notes.md b/doc/release_notes.md
@@ -265,7 +265,7 @@ OpenPose Library - Release Notes
     2. Greedy body part connector implemented in CUDA: +~30% speed up in Nvidia (CUDA) version with default flags and +~10% in maximum accuracy configuration. In addition, it provides a small 0.5% boost in accuracy (default flags).
     3. OpenPose can be built as Unity plugin: Added flag `BUILD_UNITY_SUPPORT` and special Unity code.
     4. If camera is unplugged, OpenPose GUI and command line will display a warning and try to reconnect it.
-    5. Wrapper classes simplified and renamed.
+    5. Wrapper classes simplified and renamed. Wrapper renamed as WrapperT, and created Wrapper as the non-templated class equivalent.
     6. API and examples improved:
         1. New header file `flags.hpp` that includes all OpenPose flags, removing the need to copy them repeatedly on each OpenPose example file.
         2. `tutorial_wrapper` renamed as `tutorial_api_cpp` as well as new examples were added.

diff --git a/examples/openpose/openpose.cpp b/examples/openpose/openpose.cpp
@@ -74,7 +74,7 @@ int openPoseDemo()
 
         // OpenPose wrapper
         op::log("Configuring OpenPose wrapper...", op::Priority::Low, __LINE__, __FUNCTION__, __FILE__);
-        op::Wrapper<std::vector<op::Datum>> opWrapper;
+        op::Wrapper opWrapper;
         // Pose configuration (use WrapperStructPose{} for default and recommended configuration)
         const op::WrapperStructPose wrapperStructPose{
             !FLAGS_body_disable, netInputSize, outputSize, keypointScale, FLAGS_num_gpu, FLAGS_num_gpu_start,

diff --git a/examples/tutorial_add_module/1_custom_post_processing.cpp b/examples/tutorial_add_module/1_custom_post_processing.cpp
@@ -78,7 +78,7 @@ int openPoseTutorialWrapper4()
 
         // OpenPose wrapper
         op::log("Configuring OpenPose wrapper...", op::Priority::Low, __LINE__, __FUNCTION__, __FILE__);
-        op::Wrapper<std::vector<op::UserDatum>> opWrapper;
+        op::WrapperT<std::vector<op::UserDatum>> opWrapper;
         // Pose configuration (use WrapperStructPose{} for default and recommended configuration)
         const op::WrapperStructPose wrapperStructPose{
             !FLAGS_body_disable, netInputSize, outputSize, keypointScale, FLAGS_num_gpu, FLAGS_num_gpu_start,

diff --git a/examples/tutorial_api_cpp/1_body_from_image.cpp b/examples/tutorial_api_cpp/1_body_from_image.cpp
@@ -1,4 +1,4 @@
-// ------------------------- OpenPose API Tutorial - Example 1 - Body from image -------------------------
+// ----------------------------- OpenPose C++ API Tutorial - Example 1 - Body from image -----------------------------
 // It reads an image, process it, and displays it with the pose keypoints.
 
 // Command-line user intraface
@@ -69,7 +69,7 @@ int bodyFromImage()
 
     // Configuring OpenPose
     op::log("Configuring OpenPose...", op::Priority::High);
-    op::Wrapper<std::vector<op::Datum>> opWrapper{op::ThreadManagerMode::Asynchronous};
+    op::Wrapper opWrapper{op::ThreadManagerMode::Asynchronous};
     // Set to single-thread (for sequential processing and/or debugging and/or reducing latency)
     if (FLAGS_disable_multi_thread)
         opWrapper.disableMultiThreading();

diff --git a/examples/tutorial_api_cpp/2_whole_body_from_image.cpp b/examples/tutorial_api_cpp/2_whole_body_from_image.cpp
@@ -1,4 +1,4 @@
-// ------------------------- OpenPose API Tutorial - Example 2 - Whole body from image -------------------------
+// -------------------------- OpenPose C++ API Tutorial - Example 2 - Whole body from image --------------------------
 // It reads an image, process it, and displays it with the pose, hand, and face keypoints.
 
 // Command-line user intraface
@@ -48,7 +48,7 @@ int wholeBodyFromImage()
 
     // Configuring OpenPose
     op::log("Configuring OpenPose...", op::Priority::High);
-    op::Wrapper<std::vector<op::Datum>> opWrapper{op::ThreadManagerMode::Asynchronous};
+    op::Wrapper opWrapper{op::ThreadManagerMode::Asynchronous};
     // Add hand and face
     opWrapper.configure(op::WrapperStructFace{true});
     opWrapper.configure(op::WrapperStructHand{true});

diff --git a/examples/tutorial_api_cpp/3_keypoints_from_image_configurable.cpp b/examples/tutorial_api_cpp/3_keypoints_from_image_configurable.cpp
@@ -1,4 +1,4 @@
-// ------------------------- OpenPose API Tutorial - Example 3 - Body from image configurable -------------------------
+// ----------------------- OpenPose C++ API Tutorial - Example 3 - Body from image configurable -----------------------
 // It reads an image, process it, and displays it with the pose (and optionally hand and face) keypoints. In addition,
 // it includes all the OpenPose configuration flags (enable/disable hand, face, output saving, etc.).
 
@@ -84,7 +84,7 @@ int wholeBodyFromImage()
 
     // Configuring OpenPose
     op::log("Configuring OpenPose...", op::Priority::High);
-    op::Wrapper<std::vector<op::Datum>> opWrapper{op::ThreadManagerMode::Asynchronous};
+    op::Wrapper opWrapper{op::ThreadManagerMode::Asynchronous};
     // Pose configuration (use WrapperStructPose{} for default and recommended configuration)
     const op::WrapperStructPose wrapperStructPose{
         !FLAGS_body_disable, netInputSize, outputSize, keypointScale, FLAGS_num_gpu, FLAGS_num_gpu_start,

diff --git a/examples/tutorial_api_cpp/4_asynchronous_loop_custom_input_and_output.cpp b/examples/tutorial_api_cpp/4_asynchronous_loop_custom_input_and_output.cpp
@@ -1,4 +1,4 @@
-// ------------------------- OpenPose Library Tutorial - Wrapper - Example 1 - Asynchronous -------------------------
+// ------------------------- OpenPose C++ API Tutorial - Example 4 - Custom Input and Output -------------------------
 // Asynchronous mode: ideal for fast prototyping when performance is not an issue. The user emplaces/pushes and pops frames from the OpenPose wrapper
 // when he desires to.
 
@@ -27,9 +27,9 @@
 DEFINE_string(image_dir, "examples/media/",
     "Process a directory of images. Read all standard formats (jpg, png, bmp, etc.).");
 
-// If the user needs his own variables, he can inherit the op::Datum struct and add them
-// UserDatum can be directly used by the OpenPose wrapper because it inherits from op::Datum, just define Wrapper<UserDatum> instead of
-// Wrapper<op::Datum>
+// If the user needs his own variables, he can inherit the op::Datum struct and add them in there.
+// UserDatum can be directly used by the OpenPose wrapper because it inherits from op::Datum, just define
+// WrapperT<std::vector<UserDatum>> instead of Wrapper (or equivalently WrapperT<std::vector<UserDatum>>)
 struct UserDatum : public op::Datum
 {
     bool boolThatUserNeedsForSomeReason;
@@ -176,7 +176,7 @@ class UserOutputClass
     }
 };
 
-int openPoseTutorialWrapper3()
+int example4()
 {
     try
     {
@@ -219,7 +219,7 @@ int openPoseTutorialWrapper3()
 
         // Configure OpenPose
         op::log("Configuring OpenPose wrapper...", op::Priority::Low, __LINE__, __FUNCTION__, __FILE__);
-        op::Wrapper<std::vector<UserDatum>> opWrapper{op::ThreadManagerMode::Asynchronous};
+        op::WrapperT<std::vector<UserDatum>> opWrapperT{op::ThreadManagerMode::Asynchronous};
         // Pose configuration (use WrapperStructPose{} for default and recommended configuration)
         const op::WrapperStructPose wrapperStructPose{
             !FLAGS_body_disable, netInputSize, outputSize, keypointScale, FLAGS_num_gpu, FLAGS_num_gpu_start,
@@ -250,14 +250,14 @@ int openPoseTutorialWrapper3()
             FLAGS_camera_fps, FLAGS_write_heatmaps, FLAGS_write_heatmaps_format, FLAGS_write_video_adam,
             FLAGS_write_bvh, FLAGS_udp_host, FLAGS_udp_port};
         // Configure wrapper
-        opWrapper.configure(wrapperStructPose, wrapperStructFace, wrapperStructHand, wrapperStructExtra,
+        opWrapperT.configure(wrapperStructPose, wrapperStructFace, wrapperStructHand, wrapperStructExtra,
                             op::WrapperStructInput{}, wrapperStructOutput);
         // Set to single-thread (for sequential processing and/or debugging and/or reducing latency)
         if (FLAGS_disable_multi_thread)
-           opWrapper.disableMultiThreading();
+           opWrapperT.disableMultiThreading();
 
         op::log("Starting thread(s)...", op::Priority::High);
-        opWrapper.start();
+        opWrapperT.start();
 
         // User processing
         UserInputClass userInputClass(FLAGS_image_dir);
@@ -269,10 +269,10 @@ int openPoseTutorialWrapper3()
             auto datumToProcess = userInputClass.createDatum();
             if (datumToProcess != nullptr)
             {
-                auto successfullyEmplaced = opWrapper.waitAndEmplace(datumToProcess);
+                auto successfullyEmplaced = opWrapperT.waitAndEmplace(datumToProcess);
                 // Pop frame
                 std::shared_ptr<std::vector<UserDatum>> datumProcessed;
-                if (successfullyEmplaced && opWrapper.waitAndPop(datumProcessed))
+                if (successfullyEmplaced && opWrapperT.waitAndPop(datumProcessed))
                 {
                     userWantsToExit = userOutputClass.display(datumProcessed);
                     userOutputClass.printKeypoints(datumProcessed);
@@ -284,7 +284,7 @@ int openPoseTutorialWrapper3()
         }
 
         op::log("Stopping thread(s)", op::Priority::High);
-        opWrapper.stop();
+        opWrapperT.stop();
 
         // Measuring total time
         const auto now = std::chrono::high_resolution_clock::now();
@@ -309,6 +309,6 @@ int main(int argc, char *argv[])
     // Parsing command line flags
     gflags::ParseCommandLineFlags(&argc, &argv, true);
 
-    // Running openPoseTutorialWrapper3
-    return openPoseTutorialWrapper3();
+    // Running example4
+    return example4();
 }