Add padding argument support for Python compute_face_descriptor methods (#1578)

python_examples/face_recognition.py

@@ -99,7 +99,7 @@ for f in glob.glob(os.path.join(faces_folder_path, "*.jpg")):
         face_descriptor = facerec.compute_face_descriptor(img, shape)
         print(face_descriptor)
         # It should also be noted that you can also call this function like this:
-        #  face_descriptor = facerec.compute_face_descriptor(img, shape, 100)
+        #  face_descriptor = facerec.compute_face_descriptor(img, shape, 100, 0.25)
         # The version of the call without the 100 gets 99.13% accuracy on LFW
         # while the version with 100 gets 99.38%.  However, the 100 makes the
         # call 100x slower to execute, so choose whatever version you like.  To
@@ -109,6 +109,10 @@ for f in glob.glob(os.path.join(faces_folder_path, "*.jpg")):
         # the face and returns the average result.  You could also pick a more
         # middle value, such as 10, which is only 10x slower but still gets an
         # LFW accuracy of 99.3%.
+        # 4th value (0.25) is padding around the face. 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 triple it, and so forth.
 
 
         dlib.hit_enter_to_continue()

tools/python/src/face_recognition.cpp

@@ -35,28 +35,31 @@ public:
     matrix<double,0,1> compute_face_descriptor (
         numpy_image<rgb_pixel> img,
         const full_object_detection& face,
-        const int num_jitters
+        const int num_jitters,
+        float padding = 0.25
     )
     {
         std::vector<full_object_detection> faces(1, face);
-        return compute_face_descriptors(img, faces, num_jitters)[0];
+        return compute_face_descriptors(img, faces, num_jitters, padding)[0];
     }
 
     std::vector<matrix<double,0,1>> compute_face_descriptors (
         numpy_image<rgb_pixel> img,
         const std::vector<full_object_detection>& faces,
-        const int num_jitters
+        const int num_jitters,
+        float padding = 0.25
     )
     {
         std::vector<numpy_image<rgb_pixel>> batch_img(1, img);
         std::vector<std::vector<full_object_detection>> batch_faces(1, faces);
-        return batch_compute_face_descriptors(batch_img, batch_faces, num_jitters)[0];
+        return batch_compute_face_descriptors(batch_img, batch_faces, num_jitters, padding)[0];
     }
 
     std::vector<std::vector<matrix<double,0,1>>> batch_compute_face_descriptors (
         const std::vector<numpy_image<rgb_pixel>>& batch_imgs,
         const std::vector<std::vector<full_object_detection>>& batch_faces,
-        const int num_jitters
+        const int num_jitters,
+        float padding = 0.25
     )
     {
 
@@ -83,7 +86,7 @@ public:
 
             std::vector<chip_details> dets;
             for (const auto& f : faces)
-                dets.push_back(get_face_chip_details(f, 150, 0.25));
+                dets.push_back(get_face_chip_details(f, 150, padding));
             dlib::array<matrix<rgb_pixel>> this_img_face_chips;
             extract_image_chips(img, dets, this_img_face_chips);
 
@@ -261,18 +264,24 @@ void bind_face_recognition(py::module &m)
     {
     py::class_<face_recognition_model_v1>(m, "face_recognition_model_v1", "This object maps human faces into 128D vectors where pictures of the same person are mapped near to each other and pictures of different people are mapped far apart.  The constructor loads the face recognition model from a file. The model file is available here: http://dlib.net/files/dlib_face_recognition_resnet_model_v1.dat.bz2")
         .def(py::init<std::string>())
-        .def("compute_face_descriptor", &face_recognition_model_v1::compute_face_descriptor, py::arg("img"),py::arg("face"),py::arg("num_jitters")=0,
+        .def("compute_face_descriptor", &face_recognition_model_v1::compute_face_descriptor,
+            py::arg("img"), py::arg("face"), py::arg("num_jitters")=0, py::arg("padding")=0.25,
             "Takes an image and a full_object_detection that references a face in that image and converts it into a 128D face descriptor. "
-            "If num_jitters>1 then each face will be randomly jittered slightly num_jitters times, each run through the 128D projection, and the average used as the face descriptor."
+            "If num_jitters>1 then each face will be randomly jittered slightly num_jitters times, each run through the 128D projection, and the average used as the face descriptor. "
+            "Optionally allows to override default padding of 0.25 around the face."
             )
-        .def("compute_face_descriptor", &face_recognition_model_v1::compute_face_descriptors, py::arg("img"),py::arg("faces"),py::arg("num_jitters")=0,
+        .def("compute_face_descriptor", &face_recognition_model_v1::compute_face_descriptors,
+            py::arg("img"), py::arg("faces"), py::arg("num_jitters")=0, py::arg("padding")=0.25,
             "Takes an image and an array of full_object_detections that reference faces in that image and converts them into 128D face descriptors.  "
-            "If num_jitters>1 then each face will be randomly jittered slightly num_jitters times, each run through the 128D projection, and the average used as the face descriptor."
+            "If num_jitters>1 then each face will be randomly jittered slightly num_jitters times, each run through the 128D projection, and the average used as the face descriptor. "
+            "Optionally allows to override default padding of 0.25 around the face."
             )
-        .def("compute_face_descriptor", &face_recognition_model_v1::batch_compute_face_descriptors, py::arg("batch_img"),py::arg("batch_faces"),py::arg("num_jitters")=0,
+        .def("compute_face_descriptor", &face_recognition_model_v1::batch_compute_face_descriptors,
+            py::arg("batch_img"), py::arg("batch_faces"), py::arg("num_jitters")=0, py::arg("padding")=0.25,
             "Takes an array of images and an array of arrays of full_object_detections. `batch_faces[i]` must be an array of full_object_detections corresponding to the image `batch_img[i]`, "
             "referencing faces in that image. Every face will be converting into 128D face descriptors.  "
-            "If num_jitters>1 then each face will be randomly jittered slightly num_jitters times, each run through the 128D projection, and the average used as the face descriptor."
+            "If num_jitters>1 then each face will be randomly jittered slightly num_jitters times, each run through the 128D projection, and the average used as the face descriptor. "
+            "Optionally allows to override default padding of 0.25 around the face."
             );
     }