Add insert_image_chip (#2781)

* Add insert_image_chip to Python bindings

* Use interpolation

* remove commented code

* Add C++ implementation

* Fix compile error and improve variable namings

* Fix signed warning

dlib/image_transforms/interpolation.h

@@ -2001,6 +2001,50 @@ namespace dlib
         extract_image_chip(img, location, chip, interpolate_bilinear());
     }
 
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type1,
+        typename image_type2,
+        typename interpolation_type
+    >
+    void insert_image_chip (
+        image_type1& image,
+        const image_type2& chip,
+        const chip_details& location,
+        const interpolation_type& interp
+    )
+    {
+        image_view<image_type1> vimg(image);
+        const_image_view<image_type2> vchip(chip);
+        DLIB_CASSERT(static_cast<unsigned long>(vchip.nr()) == location.rows &&
+                     static_cast<unsigned long>(vchip.nc()) == location.cols,
+                     "The chip and the location do not have the same size.")
+        const auto tf = get_mapping_to_chip(location);
+        for (long r = 0; r < vimg.nr(); ++r)
+        {
+            for (long c = 0; c < vimg.nc(); ++c)
+            {
+                interp(vchip, tf(dlib::vector<double, 2>(c, r)), vimg[r][c]);
+            }
+        }
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type1,
+        typename image_type2
+    >
+    void insert_image_chip (
+        image_type1& image,
+        const image_type2& chip,
+        const chip_details& location
+    )
+    {
+        insert_image_chip(image, chip, location, interpolate_bilinear());
+    }
+
 // ----------------------------------------------------------------------------------------
 
     inline chip_details get_face_chip_details (

dlib/image_transforms/interpolation_abstract.h

@@ -1342,6 +1342,50 @@ namespace dlib
               above-defined extract_image_chip() function using bilinear interpolation.
     !*/
 
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type1,
+        typename image_type2,
+        typename interpolation_type
+    >
+    void insert_image_chip (
+        image_type1& image,
+        const image_type2& chip,
+        const chip_details& location,
+        const interpolation_type& interp
+    );
+    /*!
+        requires
+            - image_type1 == an image object that implements the interface defined in
+              dlib/image_processing/generic_image.h
+            - image_type2 == an image object that implements the interface defined in
+              dlib/image_processing/generic_image.h
+            - pixel_traits<typename image_traits<image_type1>::pixel_type>::has_alpha == false
+            - num_rows(chip) == location.rows && num_columns(chip) == location.cols
+            - interpolation_type == interpolate_nearest_neighbor, interpolate_bilinear, 
+              interpolate_quadratic, or a type with a compatible interface.
+        ensures
+            - This function inserts chip into the image according to the location and the
+              interpolation method supplied as a parameter.
+    !*/
+
+    template <
+        typename image_type1,
+        typename image_type2
+    >
+    void insert_image_chip (
+        image_type1& image,
+        const image_type2& chip,
+        const chip_details& location
+    );
+    /*!
+        ensures
+            - This function is a simple convenience / compatibility wrapper that calls the
+              above-defined insert_image_chip() function using bilinear interpolation.
+    !*/
+
+
 // ----------------------------------------------------------------------------------------
 
     template <

tools/python/src/image2.cpp

@@ -469,6 +469,18 @@ ensures \n\
 
 // ----------------------------------------------------------------------------------------
 
+template <typename T>
+void py_insert_image_chip (
+    numpy_image<T>& img,
+    const numpy_image<T>& chip,
+    const chip_details& chip_location
+)
+{
+    insert_image_chip(img, chip, chip_location);
+}
+
+// ----------------------------------------------------------------------------------------
+
 py::array py_tile_images (
     const py::list& images
 )
@@ -579,6 +591,37 @@ void bind_image_classes2(py::module& m)
 
     register_extract_image_chip(m);
 
+    m.def("insert_image_chip", &py_insert_image_chip<uint8_t>, py::arg("img"), py::arg("chip"), py::arg("chip_location"));
+    m.def("insert_image_chip", &py_insert_image_chip<uint16_t>, py::arg("img"), py::arg("chip"), py::arg("chip_location"));
+    m.def("insert_image_chip", &py_insert_image_chip<uint32_t>, py::arg("img"), py::arg("chip"), py::arg("chip_location"));
+    m.def("insert_image_chip", &py_insert_image_chip<uint64_t>, py::arg("img"), py::arg("chip"), py::arg("chip_location"));
+    m.def("insert_image_chip", &py_insert_image_chip<int8_t>, py::arg("img"), py::arg("chip"), py::arg("chip_location"));
+    m.def("insert_image_chip", &py_insert_image_chip<int16_t>, py::arg("img"), py::arg("chip"), py::arg("chip_location"));
+    m.def("insert_image_chip", &py_insert_image_chip<int32_t>, py::arg("img"), py::arg("chip"), py::arg("chip_location"));
+    m.def("insert_image_chip", &py_insert_image_chip<int64_t>, py::arg("img"), py::arg("chip"), py::arg("chip_location"));
+    m.def("insert_image_chip", &py_insert_image_chip<float>, py::arg("img"), py::arg("chip"), py::arg("chip_location"));
+    m.def("insert_image_chip", &py_insert_image_chip<double>, py::arg("img"), py::arg("chip"), py::arg("chip_location"));
+    m.def("insert_image_chip", &py_insert_image_chip<rgb_pixel>, py::arg("img"), py::arg("chip"), py::arg("chip_location"),
+        "Inserts chip into img applying the appropriate mapping using chip_location"
+"requires \n\
+    - img and chip numpy arrays that can be interpreted as images.  They \n\
+      must be the same type of image as well. \n\
+    - the number of rows and columns in chip match the ones in chip_location \n\
+ensures \n\
+    - This function takes the given chip and inserts it into img using an appropriate \n\
+      mapping, computed from chip_location."
+        /*!
+            requires
+                - img and chip numpy arrays that can be interpreted as images.  They
+                  must be the same type of image as well.
+                - the number of rows and columns in chip match the ones in chip_location.
+            ensures
+                - This function takes the given chip and inserts it into img using an appropriate
+                  mapping, computed from chip_location.
+        !*/
+        );
+
+
     m.def("sub_image", &py_sub_image, py::arg("img"), py::arg("rect"),
 "Returns a new numpy array that references the sub window in img defined by rect. \n\
 If rect is larger than img then rect is cropped so that it does not go outside img. \n\