Changed the xcorr functions so they take the complex conjugate of the right

hand arguments if they are complex numbers.  This way they do a proper
cross-correlation and also mirror the behavior of MATLAB.

dlib/matrix/matrix_conv.h

@@ -9,6 +9,16 @@
 namespace dlib
 {
 
+// ----------------------------------------------------------------------------------------
+
+    namespace impl
+    {
+        template <typename T>
+        const T& conj(const T& item) { return item; }
+        template <typename T>
+        std::complex<T> conj(const std::complex<T>& item) { return std::conj(item); }
+    }
+
 // ----------------------------------------------------------------------------------------
 // ----------------------------------------------------------------------------------------
 
@@ -55,7 +65,7 @@ namespace dlib
                 for (long cc = min_cc; cc <= max_cc; ++cc)
                 {
                     if (flip_m2)
-                        temp += m1(rr,cc)*m2(m2.nr()-r+rr-1, m2.nc()-c+cc-1);
+                        temp += m1(rr,cc)*dlib::impl::conj(m2(m2.nr()-r+rr-1, m2.nc()-c+cc-1));
                     else
                         temp += m1(rr,cc)*m2(r-rr,c-cc);
                 }
@@ -147,7 +157,7 @@ namespace dlib
                 for (long cc = min_cc; cc <= max_cc; ++cc)
                 {
                     if (flip_m2)
-                        temp += m1(rr,cc)*m2(m2.nr()-r+rr-1, m2.nc()-c+cc-1);
+                        temp += m1(rr,cc)*dlib::impl::conj(m2(m2.nr()-r+rr-1, m2.nc()-c+cc-1));
                     else
                         temp += m1(rr,cc)*m2(r-rr,c-cc);
                 }
@@ -242,7 +252,7 @@ namespace dlib
                 for (long cc = min_cc; cc <= max_cc; ++cc)
                 {
                     if (flip_m2)
-                        temp += m1(rr,cc)*m2(m2.nr()-r+rr-1, m2.nc()-c+cc-1);
+                        temp += m1(rr,cc)*dlib::impl::conj(m2(m2.nr()-r+rr-1, m2.nc()-c+cc-1));
                     else
                         temp += m1(rr,cc)*m2(r-rr,c-cc);
                 }

dlib/matrix/matrix_conv_abstract.h

@@ -38,7 +38,8 @@ namespace dlib
         ensures
             - returns a matrix R such that:
                 - R is the cross-correlation of m1 with m2.  In particular, this
-                  function returns conv(m1,flip(m2)).
+                  function returns conv(m1,flip(m2)) if the matrices contain real
+                  elements and conv(m1,flip(conj(m2))) if they are complex.
                 - R::type == the same type that was in m1 and m2.
                 - R.nr() == m1.nr()+m2.nr()-1
                 - R.nc() == m1.nc()+m2.nc()-1
@@ -77,7 +78,8 @@ namespace dlib
         ensures
             - returns a matrix R such that:
                 - R is the cross-correlation of m1 with m2.  In particular, this
-                  function returns conv_same(m1,flip(m2)).
+                  function returns conv_same(m1,flip(m2)) if the matrices contain real
+                  elements and conv_same(m1,flip(conj(m2))) if they are complex.
                 - R::type == the same type that was in m1 and m2.
                 - R.nr() == m1.nr()
                 - R.nc() == m1.nc()
@@ -119,7 +121,8 @@ namespace dlib
         ensures
             - returns a matrix R such that:
                 - R is the cross-correlation of m1 with m2.  In particular, this
-                  function returns conv_valid(m1,flip(m2)).
+                  function returns conv_valid(m1,flip(m2)) if the matrices contain real
+                  elements and conv_valid(m1,flip(conj(m2))) if they are complex.
                 - R::type == the same type that was in m1 and m2.
                 - if (m1 has larger dimensions than m2) then
                     - R.nr() == m1.nr()-m2.nr()+1

dlib/test/matrix4.cpp

@@ -760,6 +760,19 @@ namespace
         DLIB_TEST(temp3 == temp);
 
 
+        for (int i = 0; i < 3; ++i)
+        {
+            dlib::rand rnd;
+            matrix<complex<int> > a, b;
+            a = complex_matrix(matrix_cast<int>(round(20*randm(2,7,rnd))), 
+                               matrix_cast<int>(round(20*randm(2,7,rnd))));
+            b = complex_matrix(matrix_cast<int>(round(20*randm(3,2,rnd))), 
+                               matrix_cast<int>(round(20*randm(3,2,rnd))));
+
+            DLIB_TEST(xcorr(a,b)       == conv(a, flip(conj(b))));
+            DLIB_TEST(xcorr_valid(a,b) == conv_valid(a, flip(conj(b))));
+            DLIB_TEST(xcorr_same(a,b)  == conv_same(a, flip(conj(b))));
+        }
     }