Added another version of get_transformation_to()

--HG--
extra : convert_revision : svn%3Afdd8eb12-d10e-0410-9acb-85c331704f74/trunk%403623

dlib/svm/empirical_kernel_map.h

@@ -199,6 +199,55 @@ namespace dlib
             return target.weights * kernel_matrix(target.get_kernel(),target.basis, basis)*trans(weights);
         }
 
+        void get_transformation_to (
+            const empirical_kernel_map& target,
+            matrix<scalar_type, 0, 0, mem_manager_type>& tmat,
+            projection_function<kernel_type>& partial_projection
+        ) const
+        {
+            // make sure requires clause is not broken
+            DLIB_ASSERT(out_vector_size() != 0 && 
+                        target.out_vector_size() != 0 &&
+                        get_kernel() == target.get_kernel() &&
+                        basis_size() < target.basis_size(),
+                "\t void empirical_kernel_map::get_transformation_to(target, tmat, partial_projection)"
+                << "\n\t Invalid inputs were given to this function"
+                << "\n\t out_vector_size():                 " << out_vector_size() 
+                << "\n\t target.out_vector_size():          " << target.out_vector_size() 
+                << "\n\t basis_size():                      " << basis_size() 
+                << "\n\t target.basis_size():               " << target.basis_size() 
+                << "\n\t get_kernel()==target.get_kernel(): " << (get_kernel()==target.get_kernel())
+                << "\n\t this: " << this
+                );
+
+#ifdef ENABLE_ASSERTS
+            for (unsigned long i = 0; i < basis_size(); ++i)
+            {
+                DLIB_ASSERT(dlib::equal((*this)[i], target[i]), 
+                    "\t const matrix empirical_kernel_map::get_transformation_to(target, tmat, partial_projection)"
+                    << "\n\t target must contain a superset of the basis vectors in *this"
+                    << "\n\t i: " << i
+                    << "\n\t this: " << this
+                    );
+            }
+#endif
+
+            const unsigned long num1 = basis.size();
+            const unsigned long num2 = target.basis.size();
+
+            tmat = colm(target.weights, range(0,num1-1))*kernel_matrix(kernel, basis)*trans(weights);
+
+            empirical_kernel_map temp_ekm;
+            temp_ekm.load(kernel, rowm(vector_to_matrix(target.basis), range(num1,num2-1)));
+
+            partial_projection = temp_ekm.get_projection_function();
+
+            partial_projection.weights = colm(target.weights,range(num1,num2-1))*
+                                   kernel_matrix(kernel, temp_ekm.basis)*
+                                   trans(temp_ekm.weights)*
+                                   partial_projection.weights;
+        }
+
         const matrix<scalar_type,0,1,mem_manager_type>& project (
             const sample_type& samp
         ) const

dlib/svm/empirical_kernel_map_abstract.h

@@ -197,7 +197,7 @@ namespace dlib
         /*!
             ensures
                 - returns the number of basis vectors in projection_functions created
-                  by this obect.  This is also equal to the number of basis vectors
+                  by this object.  This is also equal to the number of basis vectors
                   given to the load() function.
         !*/
 
@@ -330,7 +330,7 @@ namespace dlib
                 - A point in the kernel feature space defined by the kernel get_kernel() typically
                   has different representations with respect to different empirical_kernel_maps.
                   This function lets you obtain a transformation matrix that will allow you
-                  to map between these different representations. That is, this function returns 
+                  to project between these different representations. That is, this function returns 
                   a matrix M with the following properties:    
                     - M maps vectors represented according to *this into the representation used by target. 
                     - M.nr() == target.out_vector_size()
@@ -349,6 +349,35 @@ namespace dlib
                       used by *this then the equality will always be exact (within rounding error).
         !*/
 
+        void get_transformation_to (
+            const empirical_kernel_map& target,
+            matrix<scalar_type, 0, 0, mem_manager_type>& tmat,
+            projection_function<kernel_type>& partial_projection
+        ) const;
+        /*!
+            requires
+                - get_kernel() == target.get_kernel()
+                - out_vector_size() != 0
+                - target.out_vector_size() != 0
+                - basis_size() < target.basis_size()
+                - for all i < basis_size(): (*this)[i] == target[i]
+                  i.e. target must contain a superset of the basis vectors contained in *this.  Moreover,
+                  it must contain them in the same order.
+            ensures
+                - The single argument version of get_transformation_to() allows you to project 
+                  vectors from one empirical_kernel_map representation to another.  This version
+                  provides a somewhat different capability.  Assuming target's basis vectors form a
+                  superset of *this's basis vectors then this form of get_transformation_to() allows
+                  you to reuse a vector from *this ekm to speed up the projection performed by target.
+                  The defining relation is given below.
+                - for any sample S: 
+                    - target.project(S) == #tmat * this->project(S) + #partial_projection(S)
+                      (this is always true to within rounding error for any S)
+                - #partial_projection.basis_vectors.size() == target.basis_vectors.size() - this->basis_vectors.size()
+                - #tmat.nr() == target.out_vector_size()
+                - #tmat.nc() == this->out_vector_size()
+        !*/
+
         void swap (
             empirical_kernel_map& item
         );