Just renamed get_scales() to get_hash_bin_sizes() to make things more clear.

dlib/image_keypoint/hashed_feature_image.h

@@ -21,11 +21,11 @@ namespace dlib
     {
         /*!
             INITIAL VALUE
-                - scales == logspace(-1, 1, 3)
+                - inv_bin_sizes == logspace(-1, 1, 3)
                 - num_dims == 1000
 
             CONVENTION
-                - scales.size() > 0
+                - inv_bin_sizes.size() > 0
                 - num_dims == get_num_dimensions()
                 - if (has_image_statistics()) then
                     - rs[i] == the statistics of feature element i.  I.e. the stats of fe(r,c)(i)
@@ -44,11 +44,11 @@ namespace dlib
         void clear (
         );
 
-        void set_scales (
-            const matrix<double,1,0>& new_scales
+        void set_hash_bin_sizes (
+            const matrix<double,1,0>& bin_sizes 
         );
 
-        const matrix<double,1,0>& get_scales (
+        const matrix<double,1,0> get_hash_bin_sizes (
         ) const;
 
         template <
@@ -136,7 +136,7 @@ namespace dlib
         feature_extractor fe;
         typename feature_extractor::descriptor_type inv_stddev;
         std::vector<running_stats<double> > rs;
-        matrix<double,1,0> scales;
+        matrix<double,1,0> inv_bin_sizes;
         long num_dims;
 
         // Transient variables.  These are here just so they don't have to get constructed over
@@ -159,7 +159,7 @@ namespace dlib
         serialize(item.fe, out);
         serialize(item.inv_stddev, out);
         serialize(item.rs, out);
-        serialize(item.scales, out);
+        serialize(item.inv_bin_sizes, out);
         serialize(item.num_dims, out);
     }
 
@@ -172,7 +172,7 @@ namespace dlib
         deserialize(item.fe, in);
         deserialize(item.inv_stddev, in);
         deserialize(item.rs, in);
-        deserialize(item.scales, in);
+        deserialize(item.inv_bin_sizes, in);
         deserialize(item.num_dims, in);
     }
 
@@ -190,7 +190,7 @@ namespace dlib
     ) : 
         num_dims(1000) 
     {
-        scales = logspace(-1,1,3);
+        inv_bin_sizes = logspace(-1,1,3);
     }
 
 // ----------------------------------------------------------------------------------------
@@ -204,7 +204,7 @@ namespace dlib
     {
         fe.clear();
         inv_stddev = 0;
-        scales = logspace(-1,1,3);
+        inv_bin_sizes = logspace(-1,1,3);
         rs.clear();
         num_dims = 1000;
     }
@@ -215,18 +215,24 @@ namespace dlib
         typename feature_extractor
         >
     void hashed_feature_image<feature_extractor>::
-    set_scales (
-        const matrix<double,1,0>& new_scales
+    set_hash_bin_sizes (
+        const matrix<double,1,0>& bin_sizes 
     )
     {
         // make sure requires clause is not broken
-        DLIB_ASSERT(new_scales.size() > 0,
-            "\t void hashed_feature_image::set_scales()"
+        DLIB_ASSERT(bin_sizes.size() > 0,
+            "\t void hashed_feature_image::set_hash_bin_sizes()"
             << "\n\t size of new_scales should not be zero"
             << "\n\t this: " << this
             );
+        DLIB_ASSERT(min(bin_sizes) > 0,
+            "\t void hashed_feature_image::set_hash_bin_sizes()"
+            << "\n\t All bins must have sizes greater than zero."
+            << "\n\t min(bin_sizes): " << min(bin_sizes) 
+            << "\n\t this: " << this
+            );
 
-        scales = new_scales;
+        inv_bin_sizes = reciprocal(bin_sizes);
     }
 
 // ----------------------------------------------------------------------------------------
@@ -234,11 +240,11 @@ namespace dlib
     template <
         typename feature_extractor
         >
-    const matrix<double,1,0>& hashed_feature_image<feature_extractor>::
-    get_scales (
+    const matrix<double,1,0> hashed_feature_image<feature_extractor>::
+    get_hash_bin_sizes (
     ) const
     {
-        return scales;
+        return reciprocal(inv_bin_sizes);
     }
 
 // ----------------------------------------------------------------------------------------
@@ -313,7 +319,7 @@ namespace dlib
     {
         rs = item.rs;
         inv_stddev = item.inv_stddev;
-        scales = item.scales;
+        inv_bin_sizes = item.inv_bin_sizes;
         fe.copy_configuration(item.fe);
         num_dims = item.num_dims;
     }
@@ -441,15 +447,15 @@ namespace dlib
             << "\n\t this: " << this
             );
 
-        hash_feats.resize(scales.size());
+        hash_feats.resize(inv_bin_sizes.size());
         if (has_image_statistics())
             scaled_feats = pointwise_multiply(fe(row,col), inv_stddev);
         else
             scaled_feats = fe(row,col);
 
-        for (long i = 0; i < scales.size(); ++i)
+        for (long i = 0; i < inv_bin_sizes.size(); ++i)
         {
-            quantized_feats = matrix_cast<int32>(scales(i)*scaled_feats);
+            quantized_feats = matrix_cast<int32>(inv_bin_sizes(i)*scaled_feats);
             hash_feats[i] = std::make_pair(hash(quantized_feats)%num_dims,1);
         }
         return hash_feats;

dlib/image_keypoint/hashed_feature_image_abstract.h

@@ -24,7 +24,7 @@ namespace dlib
             INITIAL VALUE
                  - size() == 0
                  - get_num_dimensions() == 1000
-                 - get_scales() == logspace(-1,1,3)
+                 - get_hash_bin_sizes() == logspace(-1,1,3)
 
             WHAT THIS OBJECT REPRESENTS
                 This object is a tool for performing image feature extraction.  In
@@ -68,30 +68,31 @@ namespace dlib
                 - this object will have its initial value
         !*/
 
-        void set_scales (
-            const matrix<double,1,0>& new_scales
+        void set_hash_bin_sizes (
+            const matrix<double,1,0>& bin_sizes 
         );
         /*!
             requires
-                - new_scales.size() > 0
+                - bin_sizes.size() > 0
+                - min(bin_sizes) > 0
             ensures
-                - #get_scales() == new_scales
+                - #get_hash_bin_sizes() == bin_sizes 
         !*/
 
-        const matrix<double,1,0>& get_scales (
+        const matrix<double,1,0> get_hash_bin_sizes (
         ) const;
         /*!
             ensures
                 - When a feature vector from BASE_FE is hashed, it is hashed into exactly 
-                  get_scales().size() hash bins.  Each hash is computed as follows:
+                  get_hash_bin_sizes().size() hash bins.  Each hash is computed as follows:
                     - First normalize the feature vector.
-                    - Then multiply it by an element of get_scales().
+                    - Then divide it by an element of get_hash_bin_sizes().
                     - Then convert the resulting vector to a vector of dlib::int32.
                     - Finally, hash the integer vector into a hash bin.
-                - The size of the numbers in get_scales() determines how "big" the hash bins are.  
-                  A very small scale value would result in all input vectors being hashed into the 
-                  same bin, while larger scale values would result in only similar vectors 
-                  falling into the same bins.  However, a scale value too large would result in
+                - The size of the numbers in get_hash_bin_sizes() determines how big the hash 
+                  bins are.  A very large value would result in all input vectors being hashed 
+                  into the same bin, while smaller values would result in only similar vectors 
+                  falling into the same bins.  However, a value too small would result in
                   all vectors going into different bins.  In this case, the bins are too fine 
                   grained.
         !*/
@@ -199,7 +200,7 @@ namespace dlib
             ensures
                 - hashes BASE_FE(row,col) and returns the resulting indicator vector. 
                 - Returns a vector V such that:
-                    - V.size() == get_scales().size()
+                    - V.size() == get_hash_bin_sizes().size()
                     - for all valid i: 0 <= V[i].first < get_num_dimensions()
                     - if (BASE_FE(row,col) hashes into bin B) then
                         - V contains an element with .first == B and .second == 1