added get_face_chip_details()

dlib/image_transforms/interpolation.h

@@ -1613,6 +1613,61 @@ namespace dlib
         swap(chips[0], chip);
     }
 
+// ----------------------------------------------------------------------------------------
+
+    inline chip_details get_face_chip_details (
+        const full_object_detection& det,
+        const unsigned long size = 100,
+        const double padding = 0.2
+    )
+    {
+        DLIB_CASSERT(det.num_parts() == 68,
+            "\t chip_details get_face_chip_details()"
+            << "\n\t You must give a detection with exactly 68 parts in it."
+            << "\n\t det.num_parts(): " << det.num_parts()
+        );
+        DLIB_CASSERT(padding >= 0 && size > 0,
+            "\t chip_details get_face_chip_details()"
+            << "\n\t Invalid inputs were given to this function."
+            << "\n\t padding: " << padding 
+            << "\n\t size:    " << size 
+            );
+
+        // Average positions of face points 17-67
+        const double mean_face_shape_x[] = {
+            0.000213256, 0.0752622, 0.18113, 0.29077, 0.393397, 0.586856, 0.689483, 0.799124,
+            0.904991, 0.98004, 0.490127, 0.490127, 0.490127, 0.490127, 0.36688, 0.426036,
+            0.490127, 0.554217, 0.613373, 0.121737, 0.187122, 0.265825, 0.334606, 0.260918,
+            0.182743, 0.645647, 0.714428, 0.793132, 0.858516, 0.79751, 0.719335, 0.254149,
+            0.340985, 0.428858, 0.490127, 0.551395, 0.639268, 0.726104, 0.642159, 0.556721,
+            0.490127, 0.423532, 0.338094, 0.290379, 0.428096, 0.490127, 0.552157, 0.689874,
+            0.553364, 0.490127, 0.42689
+        };
+        const double mean_face_shape_y[] = {
+            0.106454, 0.038915, 0.0187482, 0.0344891, 0.0773906, 0.0773906, 0.0344891,
+            0.0187482, 0.038915, 0.106454, 0.203352, 0.307009, 0.409805, 0.515625, 0.587326,
+            0.609345, 0.628106, 0.609345, 0.587326, 0.216423, 0.178758, 0.179852, 0.231733,
+            0.245099, 0.244077, 0.231733, 0.179852, 0.178758, 0.216423, 0.244077, 0.245099,
+            0.780233, 0.745405, 0.727388, 0.742578, 0.727388, 0.745405, 0.780233, 0.864805,
+            0.902192, 0.909281, 0.902192, 0.864805, 0.784792, 0.778746, 0.785343, 0.778746,
+            0.784792, 0.824182, 0.831803, 0.824182
+        };
+
+        COMPILE_TIME_ASSERT(sizeof(mean_face_shape_x)/sizeof(double) == 68-17);
+
+        std::vector<dlib::vector<double,2> > from_points, to_points;
+        for (unsigned long i = 17; i < det.num_parts(); ++i)
+        {
+            dlib::vector<double,2> p;
+            p.x() = (padding+mean_face_shape_x[i-17])/(2*padding+1);
+            p.y() = (padding+mean_face_shape_y[i-17])/(2*padding+1);
+            from_points.push_back(p*size);
+            to_points.push_back(det.part(i));
+        }
+
+        return chip_details(from_points, to_points, chip_dims(size,size));
+    }
+
 // ----------------------------------------------------------------------------------------
 
 }

dlib/image_transforms/interpolation_abstract.h

@@ -1095,6 +1095,31 @@ namespace dlib
               and stores the single output chip into #chip.
     !*/
 
+// ----------------------------------------------------------------------------------------
+
+    chip_details get_face_chip_details (
+        const full_object_detection& det,
+        const unsigned long size = 100,
+        const double padding = 0.2
+    );
+    /*!
+        requires
+            - det.num_parts() == 68
+            - size > 0
+            - padding >= 0
+        ensures
+            - This function assumes det contains a human face detection with face parts
+              annotated using the annotation scheme from the iBUG 300-W face landmark
+              dataset.  Given these assumptions, it creates a chip_details object that will
+              extract a copy of the face that has been rotated upright, centered, and
+              scaled to a standard size when given to extract_image_chip(). 
+            - The extracted chips will have size rows and columns in them.
+            - if padding == 0 then the chip will be closely cropped around the face.
+              Setting larger padding values will result a looser cropping.  In particular,
+              a padding of 0.5 would double the width of the cropped area, a value of 1
+              would tripple it, and so forth.
+    !*/
+
 // ----------------------------------------------------------------------------------------
 // ----------------------------------------------------------------------------------------