merged

dlib/clustering.h

@@ -5,6 +5,7 @@
 
 #include "clustering/modularity_clustering.h"
 #include "clustering/chinese_whispers.h"
+#include "clustering/spectral_cluster.h"
 #include "svm/kkmeans.h"
 
 #endif // DLIB_CLuSTERING_

dlib/clustering/spectral_cluster.h

+// Copyright (C) 2015  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#ifndef DLIB_SPECTRAL_CLUSTEr_H_
+#define DLIB_SPECTRAL_CLUSTEr_H_
+
+#include "spectral_cluster_abstract.h"
+#include <vector>
+#include "../matrix.h"
+#include "../svm/kkmeans.h"
+
+namespace dlib
+{
+    template <
+        typename kernel_type,
+        typename vector_type
+        >
+    std::vector<unsigned long> spectral_cluster (
+        const kernel_type& k,
+        const vector_type& samples,
+        const unsigned long num_clusters
+    )
+    {
+        DLIB_CASSERT(num_clusters > 0, 
+            "\t std::vector<unsigned long> spectral_cluster(k,samples,num_clusters)"
+            << "\n\t num_clusters can't be 0."
+            );
+
+        if (num_clusters == 1)
+        {
+            // nothing to do, just assign everything to the 0 cluster.
+            return std::vector<unsigned long>(samples.size(), 0);
+        }
+
+        // compute the similarity matrix.
+        matrix<double> K(samples.size(), samples.size());
+        for (long r = 0; r < K.nr(); ++r)
+            for (long c = r+1; c < K.nc(); ++c)
+                K(r,c) = K(c,r) = (double)k(samples[r], samples[c]);
+        for (long r = 0; r < K.nr(); ++r)
+            K(r,r) = 0;
+
+        matrix<double,0,1> D(K.nr());
+        for (long r = 0; r < K.nr(); ++r)
+            D(r) = sum(rowm(K,r));
+        D = sqrt(reciprocal(D));
+        K = diagm(D)*K*diagm(D); 
+        matrix<double> u,w,v;
+        // Use the normal SVD routine unless the matrix is really big, then use the fast
+        // approximate version.
+        if (K.nr() < 1000)
+            svd3(K,u,w,v);
+        else
+            svd_fast(K,u,w,v, num_clusters+100, 5);
+        // Pick out the eigenvectors associated with the largest eigenvalues.
+        rsort_columns(v,w);
+        v = colm(v, range(0,num_clusters-1));
+        // Now build the normalized spectral vectors, one for each input vector.
+        std::vector<matrix<double,0,1> > spec_samps, centers;
+        for (long r = 0; r < v.nr(); ++r)
+        {
+            spec_samps.push_back(trans(rowm(v,r)));
+            spec_samps.back() /= length(spec_samps.back());
+        }
+        // Finally do the K-means clustering
+        pick_initial_centers(num_clusters, centers, spec_samps);
+        find_clusters_using_kmeans(spec_samps, centers);
+        // And then compute the cluster assignments based on the output of K-means.
+        std::vector<unsigned long> assignments;
+        for (unsigned long i = 0; i < spec_samps.size(); ++i)
+            assignments.push_back(nearest_center(centers, spec_samps[i]));
+
+        return assignments;
+    }
+
+}
+
+#endif // DLIB_SPECTRAL_CLUSTEr_H_
+

dlib/clustering/spectral_cluster_abstract.h

+// Copyright (C) 2015  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#undef DLIB_SPECTRAL_CLUSTEr_ABSTRACT_H_
+#ifdef DLIB_SPECTRAL_CLUSTEr_ABSTRACT_H_
+
+#include <vector>
+
+namespace dlib
+{
+    template <
+        typename kernel_type,
+        typename vector_type
+        >
+    std::vector<unsigned long> spectral_cluster (
+        const kernel_type& k,
+        const vector_type& samples,
+        const unsigned long num_clusters
+    );
+    /*!
+        requires
+            - samples must be something with an interface compatible with std::vector.
+            - The following expression must evaluate to a double or float:
+                k(samples[i], samples[j])
+            - num_clusters > 0
+        ensures
+            - Performs the spectral clustering algorithm described in the paper: 
+              On spectral clustering: Analysis and an algorithm by Ng, Jordan, and Weiss.
+              and returns the results.
+            - This function clusters the input data samples into num_clusters clusters and
+              returns a vector that indicates which cluster each sample falls into.  In
+              particular, we return an array A such that:
+                - A.size() == samples.size()
+                - A[i] == the cluster assignment of samples[i].
+                - for all valid i: 0 <= A[i] < num_clusters 
+            - The "similarity" of samples[i] with samples[j] is given by
+              k(samples[i],samples[j]).  This means that k() should output a number >= 0
+              and the number should be larger for samples that are more similar.
+    !*/
+}
+
+#endif // DLIB_SPECTRAL_CLUSTEr_ABSTRACT_H_
+
+

dlib/image_transforms/interpolation.h

@@ -14,6 +14,80 @@
 namespace dlib
 {
 
+// ----------------------------------------------------------------------------------------
+
+    template <typename T>
+    struct sub_image_proxy
+    {
+        sub_image_proxy (
+            T& img_,
+            const rectangle& rect_
+        ) : img(img_), rect(rect_.intersect(get_rect(img_)))
+        {}
+
+        T& img;
+        const rectangle rect;
+    };
+
+    template <typename T>
+    struct image_traits<sub_image_proxy<T> >
+    {
+        typedef typename image_traits<T>::pixel_type pixel_type;
+    };
+    template <typename T>
+    struct image_traits<const sub_image_proxy<T> >
+    {
+        typedef typename image_traits<T>::pixel_type pixel_type;
+    };
+
+    template <typename T>
+    inline long num_rows( const sub_image_proxy<T>& img) { return img.rect.height(); }
+    template <typename T>
+    inline long num_columns( const sub_image_proxy<T>& img) { return img.rect.width(); }
+
+    template <typename T>
+    inline void* image_data( sub_image_proxy<T>& img) 
+    { 
+        typedef typename image_traits<T>::pixel_type pixel_type;
+        return (char*)image_data(img.img) + sizeof(pixel_type)*img.rect.left() + img.rect.top()*width_step(img); 
+    } 
+    template <typename T>
+    inline const void* image_data( const sub_image_proxy<T>& img) 
+    {
+        typedef typename image_traits<T>::pixel_type pixel_type;
+        return (const char*)image_data(img.img) + sizeof(pixel_type)*img.rect.left() + img.rect.top()*width_step(img); 
+    }
+
+    template <typename T>
+    inline long width_step(
+        const sub_image_proxy<T>& img
+    ) 
+    { 
+        return width_step(img.img);
+    }
+
+    template <
+        typename image_type
+        >
+    sub_image_proxy<image_type> sub_image (
+        image_type& img,
+        const rectangle& rect
+    )
+    {
+        return sub_image_proxy<image_type>(img,rect);
+    }
+
+    template <
+        typename image_type
+        >
+    const sub_image_proxy<const image_type> sub_image (
+        const image_type& img,
+        const rectangle& rect
+    )
+    {
+        return sub_image_proxy<const image_type>(img,rect);
+    }
+
 // ----------------------------------------------------------------------------------------
 
     class interpolate_nearest_neighbor
@@ -1426,6 +1500,7 @@ namespace dlib
     struct chip_details
     {
         chip_details() : angle(0), rows(0), cols(0) {}
+        chip_details(const rectangle& rect_) : rect(rect_),angle(0), rows(rect_.height()), cols(rect_.width()) {}
         chip_details(const drectangle& rect_) : rect(rect_),angle(0), rows(rect_.height()), cols(rect_.width()) {}
         chip_details(const drectangle& rect_, unsigned long size) : rect(rect_),angle(0) 
         { compute_dims_from_size(size); }

dlib/image_transforms/interpolation_abstract.h

@@ -934,6 +934,18 @@ namespace dlib
                 - #cols == rect_.width()
         !*/
 
+        chip_details(
+            const rectangle& rect_
+        );
+        /*!
+            ensures
+                - #rect == rect_
+                - #size() == rect_.area()
+                - #angle == 0
+                - #rows == rect_.height()
+                - #cols == rect_.width()
+        !*/
+
         chip_details(
             const drectangle& rect_, 
             unsigned long size_
@@ -1125,6 +1137,71 @@ namespace dlib
               and stores the single output chip into #chip.
     !*/
 
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type
+        >
+    struct sub_image_proxy
+    {
+        /*!
+            REQUIREMENTS ON image_type
+                - image_type == an image object that implements the interface defined in
+                  dlib/image_processing/generic_image.h 
+
+            WHAT THIS OBJECT REPRESENTS
+                This is a lightweight image object for referencing a subwindow of an image.
+                It implements the generic image interface and can therefore be used with
+                any function that expects a generic image, excepting that you cannot change
+                the size of a sub_image_proxy.  
+                
+                Note that it only stores a pointer to the image given to its constructor
+                and therefore does not perform a copy.  Moreover, this means that an
+                instance of this object becomes invalid after the image it references is
+                destroyed.
+        !*/
+        sub_image_proxy (
+            T& img,
+            const rectangle& rect
+        );
+        /*!
+            ensures
+                - This object is an image that represents the part of img contained within
+                  rect.  If rect is larger than img then rect is cropped so that it does
+                  not go outside img.
+        !*/
+    };
+
+    template <
+        typename image_type
+        >
+    sub_image_proxy<image_type> sub_image (
+        image_type& img,
+        const rectangle& rect
+    );
+    /*!
+        requires
+            - image_type == an image object that implements the interface defined in
+              dlib/image_processing/generic_image.h 
+        ensures
+            - returns sub_image_proxy<image_type>(img,rect)
+    !*/
+
+    template <
+        typename image_type
+        >
+    const sub_image_proxy<const image_type> sub_image (
+        const image_type& img,
+        const rectangle& rect
+    );
+    /*!
+        requires
+            - image_type == an image object that implements the interface defined in
+              dlib/image_processing/generic_image.h 
+        ensures
+            - returns sub_image_proxy<const image_type>(img,rect)
+    !*/
+
 // ----------------------------------------------------------------------------------------
 
     chip_details get_face_chip_details (

docs/docs/imaging.xml

@@ -214,6 +214,7 @@
          <item>flip_image_dataset_left_right</item> 
          <item>rotate_image_dataset</item> 
          <item>extract_image_chips</item> 
+         <item>sub_image</item> 
       </section>
 
       <section>
@@ -1629,6 +1630,19 @@
          </description>
       </component>
 
+   <!-- ************************************************************************* -->
+
+      <component>
+         <name>sub_image</name>
+         <file>dlib/image_transforms.h</file>
+         <spec_file link="true">dlib/image_transforms/interpolation_abstract.h</spec_file>
+         <description>        
+            This function returns a lightweight sub-image of another image.  In particular,
+            the returned sub-image simply holds a pointer to the original image, meaning there
+            is no overhead for using or creating the sub-image.
+         </description>
+      </component>
+
    <!-- ************************************************************************* -->
 
       <component>

docs/docs/ml.xml

@@ -113,6 +113,7 @@ Davis E. King. <a href="http://jmlr.csail.mit.edu/papers/volume10/king09a/king09
          <item>find_clusters_using_kmeans</item> 
          <item>nearest_center</item> 
          <item>newman_cluster</item> 
+         <item>spectral_cluster</item> 
          <item>chinese_whispers</item> 
          <item>modularity</item> 
       </section>
@@ -297,6 +298,22 @@ Davis E. King. <a href="http://jmlr.csail.mit.edu/papers/volume10/king09a/king09
                                  
       </component>
 
+   <!-- ************************************************************************* -->
+
+      <component>
+         <name>spectral_cluster</name>
+         <file>dlib/clustering.h</file>
+         <spec_file link="true">dlib/clustering/spectral_cluster_abstract.h</spec_file>
+         <description>
+             This function performs the clustering algorithm described in the paper
+             <blockquote>On spectral clustering: Analysis and an algorithm by Ng, Jordan, and Weiss.</blockquote> 
+         </description>
+         <examples>
+            <example>kkmeans_ex.cpp.html</example>
+         </examples>
+                                 
+      </component>
+
    <!-- ************************************************************************* -->
 
       <component>

docs/docs/term_index.xml

@@ -413,6 +413,7 @@
          <term file="ml.html" name="find_clusters_using_kmeans"                     include="dlib/clustering.h"/>
          <term file="ml.html" name="nearest_center"                                 include="dlib/clustering.h"/>
          <term file="ml.html" name="newman_cluster"                                 include="dlib/clustering.h"/>
+         <term file="ml.html" name="spectral_cluster"                               include="dlib/clustering.h"/>
          <term file="ml.html" name="chinese_whispers"                               include="dlib/clustering.h"/>
          <term file="ml.html" name="modularity"                                     include="dlib/clustering.h"/>
          <term file="ml.html" name="pick_initial_centers"                           include="dlib/clustering.h"/>
@@ -1264,6 +1265,8 @@
          <term file="imaging.html" name="rotate_image"            include="dlib/image_transforms.h"/>
          <term file="imaging.html" name="resize_image"            include="dlib/image_transforms.h"/>
          <term file="imaging.html" name="extract_image_chips"     include="dlib/image_transforms.h"/>
+         <term file="imaging.html" name="sub_image"               include="dlib/image_transforms.h"/>
+         <term file="dlib/image_transforms/interpolation_abstract.h.html" name="sub_image_proxy"     include="dlib/image_transforms.h"/>
          <term file="dlib/image_transforms/interpolation_abstract.h.html" name="extract_image_chip"     include="dlib/image_transforms.h"/>
          <term file="dlib/image_transforms/interpolation_abstract.h.html" name="chip_details"           include="dlib/image_transforms.h"/>
          <term file="dlib/image_transforms/interpolation_abstract.h.html" name="get_face_chip_details"  include="dlib/image_transforms.h"/>

examples/kkmeans_ex.cpp

 // The contents of this file are in the public domain. See LICENSE_FOR_EXAMPLE_PROGRAMS.txt
 /*
     This is an example illustrating the use of the kkmeans object 
-    from the dlib C++ Library.
+    and spectral_cluster() routine from the dlib C++ Library.
 
     The kkmeans object is an implementation of a kernelized k-means clustering 
     algorithm.  It is implemented by using the kcentroid object to represent 
@@ -11,7 +11,8 @@
     a svm classifier finds non-linear decision surfaces.  
     
     This example will make points from 3 classes and perform kernelized k-means 
-    clustering on those points.
+    clustering on those points.  It will also do the same thing using spectral 
+    clustering.
 
     The classes are as follows:
         - points very close to the origin
@@ -141,6 +142,13 @@ int main()
     cout << "num dictionary vectors for center 1: " << test.get_kcentroid(1).dictionary_size() << endl;
     cout << "num dictionary vectors for center 2: " << test.get_kcentroid(2).dictionary_size() << endl;
 
+
+    // Finally, we can also solve the same kind of non-linear clustering problem with
+    // spectral_cluster().  The output is a vector that indicates which cluster each sample
+    // belongs to.  Just like with kkmeans, it assigns each point to the correct cluster.
+    std::vector<unsigned long> assignments = spectral_cluster(kernel_type(0.1), samples, 3);
+    cout << mat(assignments) << endl;
+
 }