Added the setup_hashed_features() helper routine for configuring

a scan_image_pyramid when it is used with a hashed_feature_image
and projection_function.

dlib/image_processing.h

@@ -8,6 +8,7 @@
 #include "image_processing/detection_template_tools.h"
 #include "image_processing/object_detector.h"
 #include "image_processing/box_overlap_testing.h"
+#include "image_processing/scan_image_pyramid_tools.h"
 
 #endif // DLIB_IMAGE_PROCESSInG_H___
 

dlib/image_processing/scan_image_pyramid_tools.h

+// Copyright (C) 2011  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#ifndef DLIB_SCAN_IMaGE_PYRAMID_TOOLS_H__
+#define DLIB_SCAN_IMaGE_PYRAMID_TOOLS_H__
+
+#include "scan_image_pyramid_tools_abstract.h"
+#include "scan_image_pyramid.h"
+#include "../lsh.h"
+#include "../statistics.h"
+#include "../image_keypoint.h"
+
+namespace dlib
+{
+
+// ----------------------------------------------------------------------------------------
+
+    class image_hash_construction_failure : public error
+    {
+    public:
+        image_hash_construction_failure(
+            const std::string& a
+        ): error(a) {}
+    };
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_array,
+        typename pyramid,
+        typename feature_extractor
+        >
+    void setup_hashed_features (
+        scan_image_pyramid<pyramid, hashed_feature_image<feature_extractor, projection_hash> >& scanner,
+        const image_array& images,
+        const feature_extractor& fe,
+        int bits,
+        unsigned long num_samples = 200000
+    )
+    {
+        // make sure requires clause is not broken
+        DLIB_ASSERT(0 < bits && bits <= 32 &&
+                    num_samples > 1 && 
+                    images.size() > 0,
+            "\t void setup_hashed_features()"
+            << "\n\t Invalid inputs were given to this function. "
+            << "\n\t bits:          " << bits 
+            << "\n\t num_samples:   " << num_samples 
+            << "\n\t images.size(): " << images.size() 
+            );
+
+        const random_subset_selector<typename feature_extractor::descriptor_type>& samps = 
+            randomly_sample_image_features(images, pyramid(), fe, num_samples);
+
+        if (samps.size() <= 1)
+            throw dlib::image_hash_construction_failure("Images too small, not able to gather enough samples to make hash");
+
+        projection_hash phash = create_random_projection_hash(samps, bits);
+
+        hashed_feature_image<feature_extractor, projection_hash> hfe;
+        hfe.set_hash(phash);
+        scanner.copy_configuration(hfe);
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_array,
+        typename pyramid,
+        typename feature_extractor
+        >
+    void setup_hashed_features (
+        scan_image_pyramid<pyramid, hashed_feature_image<feature_extractor, projection_hash> >& scanner,
+        const image_array& images,
+        int bits,
+        unsigned long num_samples = 200000
+    )
+    {
+        // make sure requires clause is not broken
+        DLIB_ASSERT(0 < bits && bits <= 32 &&
+                    num_samples > 1 && 
+                    images.size() > 0,
+            "\t void setup_hashed_features()"
+            << "\n\t Invalid inputs were given to this function. "
+            << "\n\t bits:          " << bits 
+            << "\n\t num_samples:   " << num_samples 
+            << "\n\t images.size(): " << images.size() 
+            );
+
+        setup_hashed_features(scanner, images, feature_extractor(), bits, num_samples);
+    }
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_SCAN_IMaGE_PYRAMID_TOOLS_H__
+

dlib/image_processing/scan_image_pyramid_tools_abstract.h

+// Copyright (C) 2011  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#undef DLIB_SCAN_IMaGE_PYRAMID_TOOLS_ABSTRACT_H__
+#ifdef DLIB_SCAN_IMaGE_PYRAMID_TOOLS_ABSTRACT_H__
+
+#include "scan_image_pyramid_abstract.h"
+#include "../lsh/projection_hash_abstract.h"
+#include "../image_keypoint/hashed_feature_image_abstract.h"
+
+namespace dlib
+{
+
+// ----------------------------------------------------------------------------------------
+
+    class image_hash_construction_failure : public error
+    {
+        /*!
+            WHAT THIS OBJECT REPRESENTS
+                This is the exception object used by the routines in this file.
+        !*/
+    };
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_array,
+        typename pyramid,
+        typename feature_extractor
+        >
+    void setup_hashed_features (
+        scan_image_pyramid<pyramid, hashed_feature_image<feature_extractor, projection_hash> >& scanner,
+        const image_array& images,
+        const feature_extractor& fe,
+        int bits,
+        unsigned long num_samples = 200000
+    );
+    /*!
+        requires
+            - 0 < bits <= 32
+            - num_samples > 1
+            - images.size() > 0
+            - it must be valid to pass images[0] into scanner.load().
+              (also, image_array must be an implementation of dlib/array/array_kernel_abstract.h)
+        ensures
+            - Creates a projection_hash suitable for hashing the feature vectors produced by
+              fe and then configures scanner to use this hash function.
+            - The hash function will map vectors into integers in the range [0, pow(2,bits))
+            - The hash function will be setup so that it hashes a random sample of num_samples
+              vectors from fe such that each bin ends up with roughly the same number of 
+              elements in it.
+        throws
+            - image_hash_construction_failure
+              This exception is thrown if there is a problem creating the projection_hash.
+              This should only happen the images are so small they contain less than 2
+              feature vectors.
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_array,
+        typename pyramid,
+        typename feature_extractor
+        >
+    void setup_hashed_features (
+        scan_image_pyramid<pyramid, hashed_feature_image<feature_extractor, projection_hash> >& scanner,
+        const image_array& images,
+        int bits,
+        unsigned long num_samples = 200000
+    );
+    /*!
+        requires
+            - 0 < bits <= 32
+            - num_samples > 1
+            - images.size() > 0
+            - it must be valid to pass images[0] into scanner.load().
+              (also, image_array must be an implementation of dlib/array/array_kernel_abstract.h)
+        ensures
+            - performs: setup_hashed_features(scanner, images, feature_extractor(), bits, num_samples)
+        throws
+            - image_hash_construction_failure
+              This exception is thrown if there is a problem creating the projection_hash.
+              This should only happen the images are so small they contain less than 2
+              feature vectors.
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_SCAN_IMaGE_PYRAMID_TOOLS_ABSTRACT_H__
+