Added doc to save heatmaps in floating format #1333

doc/demo_overview.md

@@ -248,7 +248,7 @@ Each flag is divided into flag name, default value, and description.
 - 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.");
+- 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_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/output.md

@@ -7,10 +7,11 @@ OpenPose Demo - Output
 1. [Output Format](#output-format)
     1. [Keypoint Ordering](#keypoint-ordering)
     2. [Heatmap Ordering](#heatmap-ordering)
-    3. [Face and Hands](#face-and-hands)
-    4. [Pose Output Format](#pose-output-format)
-    5. [Face Output Format](#face-output-format)
-    6. [Hand Output Format](#hand-output-format)
+    3. [Heatmap Saving in Float Format](#heatmap-saving-in-float-format)
+    4. [Face and Hands](#face-and-hands)
+    5. [Pose Output Format](#pose-output-format)
+    6. [Face Output Format](#face-output-format)
+    7. [Hand Output Format](#hand-output-format)
 3. [Reading Saved Results](#reading-saved-results)
 4. [Keypoint Format in the C++ API](#keypoint-format-in-the-c-api)
 
@@ -114,7 +115,7 @@ const auto& poseBodyPartMappingMpi = getPoseBodyPartMapping(PoseModel::MPI_15);
 
 
 ### Heatmap Ordering
-For the **heat maps storing format**, instead of saving each of the 67 heatmaps (18 body parts + background + 2 x 19 PAFs) individually, the library concatenates them into a huge (width x #heat maps) x (height) matrix (i.e., concatenated by columns). E.g., columns [0, individual heat map width] contains the first heat map, columns [individual heat map width + 1, 2 * individual heat map width] contains the second heat map, etc. Note that some image viewers are not able to display the resulting images due to the size. However, Chrome and Firefox are able to properly open them.
+For the **heat maps storing format**, instead of saving each of the 67 heatmaps (18 body parts + background + 2 x 19 PAFs) individually, the library concatenates them into a huge (width x #heat maps) x (height) matrix (i.e., concatenated by columns). E.g., columns [0, individual heat map width] contain the first heat map, columns [individual heat map width + 1, 2 * individual heat map width] contain the second heat map, etc. Note that some image viewers are not able to display the resulting images due to the size. However, Chrome and Firefox are able to properly open them.
 
 The saving order is body parts + background + PAFs. Any of them can be disabled with program flags. If background is disabled, then the final image will be body parts + PAFs. The body parts and background follow the order of `getPoseBodyPartMapping(const PoseModel poseModel)`.
 
@@ -136,6 +137,22 @@ const auto& posePartPairsMpi = getPosePartPairs(PoseModel::MPI_15);
 
 
 
+### Heatmap Saving in Float Format
+If you save the heatmaps in floating format by using the flag `--write_heatmaps_format float`, you can later read them in Python with:
+```
+# Load custom float format - Example in Python, assuming a (18 x 300 x 500) size Array
+x = np.fromfile(heatMapFullPath, dtype=np.float32)
+assert x[0] == 3 # First parameter saves the number of dimensions (18x300x500 = 3 dimensions)
+shape_x = x[1:1+int(x[0])]
+assert len(shape_x[0]) == 3 # Number of dimensions
+assert shape_x[0] == 18 # Size of the first dimension
+assert shape_x[1] == 300 # Size of the second dimension
+assert shape_x[2] == 500 # Size of the third dimension
+arrayData = x[1+int(round(x[0])):]
+```
+
+
+
 ### Face and Hands
 The output format is analogous for hand (`hand_left_keypoints`, `hand_right_keypoints`) and face (`face_keypoints`) JSON files.
 

include/openpose/flags.hpp

@@ -256,7 +256,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.");
+                                                        " floating values. See `doc/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,"