Added make_bounding_box_regression_training_data()

dlib/image_processing/shape_predictor_trainer.h

@@ -7,6 +7,8 @@
 #include "shape_predictor.h"
 #include "../console_progress_indicator.h"
 #include "../threads.h"
+#include "../data_io/image_dataset_metadata.h"
+#include "box_overlap_testing.h"
 
 namespace dlib
 {
@@ -787,6 +789,51 @@ namespace dlib
         padding_mode_t _padding_mode;
     };
 
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename some_type_of_rectangle
+        >
+    image_dataset_metadata::dataset make_bounding_box_regression_training_data (
+        const image_dataset_metadata::dataset& truth,
+        const std::vector<std::vector<some_type_of_rectangle>>& detections
+    )
+    {
+        DLIB_CASSERT(truth.images.size() == detections.size(), 
+            "truth.images.size(): "<< truth.images.size() <<
+            "\tdetections.size(): "<< detections.size()
+        );
+        image_dataset_metadata::dataset result = truth;
+
+        for (size_t i = 0; i < truth.images.size(); ++i)
+        {
+            result.images[i].boxes.clear();
+            for (auto truth_box : truth.images[i].boxes)
+            {
+                if (truth_box.ignore)
+                    continue;
+
+                // Find the detection that best matches the current truth_box.
+                auto det = max_scoring_element(detections[i], [&truth_box](const rectangle& r) { return box_intersection_over_union(r, truth_box.rect); });
+                if (det.second > 0.5)
+                {
+                    // Remove any existing parts and replace them with the truth_box corners.
+                    truth_box.parts.clear();
+                    truth_box.parts["top_left"]     = truth_box.rect.tl_corner();
+                    truth_box.parts["top_right"]    = truth_box.rect.tr_corner();
+                    truth_box.parts["bottom_left"]  = truth_box.rect.bl_corner();
+                    truth_box.parts["bottom_right"] = truth_box.rect.br_corner();
+
+                    // Now replace the bounding truth_box with the detector's bounding truth_box.
+                    truth_box.rect = det.first;
+
+                    result.images[i].boxes.push_back(truth_box);
+                }
+            }
+        }
+        return result;
+    }
+
 // ----------------------------------------------------------------------------------------
 
 }

dlib/image_processing/shape_predictor_trainer_abstract.h

@@ -4,6 +4,7 @@
 #ifdef DLIB_SHAPE_PREDICToR_TRAINER_ABSTRACT_H_
 
 #include "shape_predictor_abstract.h"
+#include "../data_io/image_dataset_metadata.h"
 
 namespace dlib
 {
@@ -365,6 +366,43 @@ namespace dlib
         !*/
     };
 
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename some_type_of_rectangle
+        >
+    image_dataset_metadata::dataset make_bounding_box_regression_training_data (
+        const image_dataset_metadata::dataset& truth,
+        const std::vector<std::vector<some_type_of_rectangle>>& detections
+    );
+    /*!
+        requires
+            - truth.images.size() == detections.size()
+            - some_type_of_rectangle == rectangle, drectangle, mmod_rect, or any other type
+              that is convertible to a rectangle.
+        ensures
+            - Suppose you have an object detector that can roughly locate objects in an
+              image.  This means your detector draws boxes around objects, but these are
+              *rough* boxes in the sense that they aren't positioned super accurately.  For
+              instance, HOG based detectors usually have a stride of 8 pixels.  So the
+              positional accuracy is going to be, at best, +/-8 pixels.  
+              
+              If you want to get better positional accuracy one easy thing to do is train a
+              shape_predictor to give you the corners of the object.  The
+              make_bounding_box_regression_training_data() routine helps you do this by
+              creating an appropriate training dataset.  It does this by taking the dataset
+              you used to train your detector (the truth object), and combining that with
+              the output of your detector on each image in the training dataset (the
+              detections object).  In particular, it will create a new annotated dataset
+              where each object box is one of the rectangles from detections and that
+              object has 4 part annotations, the corners of the truth rectangle
+              corresponding to that detection rectangle.  You can then take the returned
+              dataset and train a shape_predictor on it.  The resulting shape_predictor can
+              then be used to do bounding box regression.
+            - We assume that detections[i] contains object detections corresponding to 
+              the image truth.images[i].
+    !*/
+
 // ----------------------------------------------------------------------------------------
 
 }