Added these new functions: remove_long_edges(), remove_percent_longest_edges(),

remove_short_edges(), and remove_percent_shortest_edges().   I also reworked
the graph creation functions to make them a little more versatile.  Now
you can use infinite distances to indicate that certain nodes are not
connected at all.

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

dlib/manifold_regularization/graph_creation_abstract.h

@@ -28,7 +28,6 @@ namespace dlib
     );
     /*!
         requires
-            - samples.size() > 1
             - 0 < percent <= 1
             - num > 0
             - random_seed must be convertible to a string by dlib::cast_to_string()
@@ -39,13 +38,14 @@ namespace dlib
               0 and samples.size()-1 inclusive.  For each of these pairs, (i,j), a
               sample_pair is created as follows:    
                 sample_pair(i, j, dist_funct(samples[i], samples[j]))
-              num such sample_pair objects are generated, duplicates are removed, and 
-              then the top percent of them with the smallest distance are stored into 
-              out.  
+              num such sample_pair objects are generated, duplicates and pairs with distance
+              values == infinity are removed, and then the top percent of them with the 
+              smallest distance are stored into out.  
             - #out.size() <= num*percent 
             - contains_duplicate_pairs(#out) == false
             - for all valid i:
                 - #out[i].distance() == dist_funct(samples[#out[i].index1()], samples[#out[i].index2()])
+                - #out[i].distance() < std::numeric_limits<float>::infinity()
             - random_seed is used to seed the random number generator used by this 
               function.
     !*/
@@ -68,7 +68,6 @@ namespace dlib
     );
     /*!
         requires
-            - samples.size() > 1
             - k > 0
             - num > 0
             - random_seed must be convertible to a string by dlib::cast_to_string()
@@ -84,9 +83,12 @@ namespace dlib
                 sample_pair(i, j, dist_funct(samples[i], samples[j]))
               num such sample_pair objects are generated and then exact k-nearest-neighbors
               is performed amongst these sample_pairs and the results are stored into #out.
+              Note that samples with an infinite distance between them are considered to 
+              be not connected at all.
             - contains_duplicate_pairs(#out) == false
             - for all valid i:
                 - #out[i].distance() == dist_funct(samples[#out[i].index1()], samples[#out[i].index2()])
+                - #out[i].distance() < std::numeric_limits<float>::infinity()
             - random_seed is used to seed the random number generator used by this 
               function.
     !*/
@@ -106,15 +108,17 @@ namespace dlib
     );
     /*!
         requires
-            - samples.size() > k
             - k > 0
             - dist_funct(samples[i], samples[j]) must be a valid expression that evaluates
               to a floating point number 
         ensures
-            - #out == a set of sample_pair objects that represent all the k nearest
-              neighbors in samples according to the given distance function dist_funct.
+            - #out == a set of sample_pair objects that represent all the k nearest 
+              neighbors in samples according to the given distance function dist_funct.  
+              Note that samples with an infinite distance between them are considered to 
+              be not connected at all.
             - for all valid i:
                 - #out[i].distance() == dist_funct(samples[#out[i].index1()], samples[#out[i].index2()])
+                - #out[i].distance() < std::numeric_limits<float>::infinity()
             - contains_duplicate_pairs(#out) == false
     !*/
 
@@ -158,6 +162,84 @@ namespace dlib
                     - for some j: pairs[j].index1()+1 == N || pairs[j].index2()+1 == N
     !*/
 
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename vector_type
+        >
+    void remove_long_edges (
+        vector_type& pairs,
+        float distance_threshold
+    );
+    /*!
+        requires
+            - vector_type == a type with an interface compatible with std::vector and 
+              it must in turn contain objects with an interface compatible with dlib::sample_pair
+        ensures
+            - Removes all elements of pairs that have a distance value greater than the
+              given threshold.
+            - #pairs.size() <= pairs.size()
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename vector_type
+        >
+    void remove_short_edges (
+        vector_type& pairs,
+        float distance_threshold
+    );
+    /*!
+        requires
+            - vector_type == a type with an interface compatible with std::vector and 
+              it must in turn contain objects with an interface compatible with dlib::sample_pair
+        ensures
+            - Removes all elements of pairs that have a distance value less than the
+              given threshold.
+            - #pairs.size() <= pairs.size()
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename vector_type
+        >
+    void remove_percent_longest_edges (
+        vector_type& pairs,
+        double percent 
+    );
+    /*!
+        requires
+            - 0 <= percent < 1
+            - vector_type == a type with an interface compatible with std::vector and 
+              it must in turn contain objects with an interface compatible with dlib::sample_pair
+        ensures
+            - Removes the given upper percentage of the longest edges in pairs.  I.e.
+              this function removes the long edges from pairs.
+            - #pairs.size() == (1-percent)*pairs.size()
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename vector_type
+        >
+    void remove_percent_shortest_edges (
+        vector_type& pairs,
+        double percent 
+    );
+    /*!
+        requires
+            - 0 <= percent < 1
+            - vector_type == a type with an interface compatible with std::vector and 
+              it must in turn contain objects with an interface compatible with dlib::sample_pair
+        ensures
+            - Removes the given upper percentage of the shortest edges in pairs.  I.e.
+              this function removes the short edges from pairs.
+            - #pairs.size() == (1-percent)*pairs.size()
+    !*/
+
 // ----------------------------------------------------------------------------------------
 
 }