Added an additional stopping condition to the kkmeans object. It is now

possible to tell it to top when a certain fraction of centers don't change.

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

dlib/svm/kkmeans.h

@@ -31,7 +31,8 @@ namespace dlib
         kkmeans (
             const kcentroid<kernel_type>& kc_ 
         ):
-            kc(kc_)
+            kc(kc_),
+            min_change(0.01)
         {
             set_number_of_centers(1);
         }
@@ -127,6 +128,19 @@ namespace dlib
             return label;
         }
 
+        void set_min_change (
+            scalar_type min_change_
+        )
+        {
+            min_change = min_change_;
+        }
+
+        const scalar_type get_min_change (
+        ) const
+        {
+            return min_change;
+        }
+
         void swap (
             kkmeans& item
         )
@@ -134,6 +148,7 @@ namespace dlib
             centers.swap(item.centers);
             kc.swap(item.kc);
             assignments.swap(item.assignments);
+            exchange(min_change, item.min_change);
         }
 
         friend void serialize(const kkmeans& item, std::ostream& out)
@@ -144,7 +159,7 @@ namespace dlib
                 serialize(*item.centers[i], out);
             }
             serialize(item.kc, out);
-            serialize(item.assignments, out);
+            serialize(item.min_change, out);
         }
 
         friend void deserialize(kkmeans& item, std::istream& in)
@@ -160,7 +175,7 @@ namespace dlib
             }
 
             deserialize(item.kc, in);
-            deserialize(item.assignments, in);
+            deserialize(item.min_change, in);
         }
 
     private:
@@ -246,6 +261,7 @@ namespace dlib
 
         typename array<scoped_ptr<kcentroid<kernel_type> > >::expand_1b_c centers;
         kcentroid<kernel_type> kc;
+        scalar_type min_change;
 
         // temp variables
         array<unsigned long>::expand_1b_c assignments;

dlib/svm/kkmeans_abstract.h

@@ -25,6 +25,7 @@ namespace dlib
 
             INITIAL VALUE
                 - number_of_centers() == 1
+                - get_min_change() == 0.01
 
             WHAT THIS OBJECT REPRESENTS
                 This is an implementation of a kernelized k-means clustering algorithm.  
@@ -42,6 +43,7 @@ namespace dlib
         /*!
             ensures
                 - #number_of_centers() == 1
+                - #get_min_change() == 0.01
                 - #get_kcentroid(0) == a copy of kc_
         !*/
 
@@ -105,7 +107,7 @@ namespace dlib
         void train (
             const matrix_type& samples,
             const matrix_type2& initial_centers,
-            long max_iter = 1000000
+            long max_iter = 1000
         );
         /*!
             requires
@@ -119,8 +121,9 @@ namespace dlib
             ensures
                 - performs k-means clustering of the given set of samples.  The initial center points
                   are taken from the initial_centers argument.
-                - loops over the data and continues to refine the clustering until either the cluster centers
-                  don't move or we have done max_iter iterations over the data.
+                - loops over the data and continues to refine the clustering until either less than 
+                  get_min_change() fraction of the cluster centers move or we have done max_iter iterations 
+                  over the data.
                 - After this function finishes you can call the operator() function below
                   to determine which centroid a given sample is closest to.
         !*/
@@ -136,6 +139,24 @@ namespace dlib
                       sample.
         !*/
 
+        void set_min_change (
+            scalar_type min_change
+        );
+        /*!
+            requires
+                - 0 <= min_change < 1
+            ensures
+                - #get_min_change() == min_change
+        !*/
+
+        const scalar_type get_min_change (
+        ) const;
+        /*!
+            ensures
+                - returns the minimum fraction of centers that need to change
+                  in an iteration of kmeans for the algorithm to keep going.
+        !*/
+
         void swap (
             kkmeans& item
         );