Added the nearest_neighbor_feature_image object.

dlib/image_keypoint.h

@@ -7,6 +7,7 @@
 #include "image_keypoint/hessian_pyramid.h"
 #include "image_keypoint/hog.h"
 #include "image_keypoint/hashed_feature_image.h"
+#include "image_keypoint/nearest_neighbor_feature_image.h"
 
 #endif // DLIB_IMAGE_KEYPOINt_H_
 

dlib/image_keypoint/nearest_neighbor_feature_image.h

+// Copyright (C) 2011  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#ifndef DLIB_NEAREST_NEIGHBOR_FeATURE_IMAGE_H__
+#define DLIB_NEAREST_NEIGHBOR_FeATURE_IMAGE_H__
+
+#include "nearest_neighbor_feature_image_abstract.h"
+#include <vector>
+#include "../algs.h"
+#include "../matrix.h"
+#include "../statistics.h"
+
+namespace dlib
+{
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    class nearest_neighbor_feature_image : noncopyable
+    {
+        /*!
+            INITIAL VALUE
+                - nn_feats.size() == 1
+
+            CONVENTION
+                - nn_feats.size() == 1
+
+        !*/
+
+    public:
+
+        typedef std::vector<std::pair<unsigned int,double> > descriptor_type;
+
+        nearest_neighbor_feature_image (
+        ); 
+
+        void clear (
+        );
+
+        void copy_configuration (
+            const feature_extractor& item
+        );
+
+        void copy_configuration (
+            const nearest_neighbor_feature_image& item
+        );
+
+        template <
+            typename image_type
+            >
+        inline void load (
+            const image_type& img
+        );
+
+        inline unsigned long size (
+        ) const;
+
+        inline long nr (
+        ) const;
+
+        inline long nc (
+        ) const;
+
+        inline long get_num_dimensions (
+        ) const;
+
+        template <typename vector_type>
+        void set_basis (
+            const vector_type& new_basis
+        );
+
+        inline const descriptor_type& operator() (
+            long row,
+            long col
+        ) const;
+
+        inline const rectangle get_block_rect (
+            long row,
+            long col
+        ) const;
+
+        inline const point image_to_feat_space (
+            const point& p
+        ) const;
+
+        inline const rectangle image_to_feat_space (
+            const rectangle& rect
+        ) const;
+
+        inline const point feat_to_image_space (
+            const point& p
+        ) const;
+
+        inline const rectangle feat_to_image_space (
+            const rectangle& rect
+        ) const;
+
+        template <typename T>
+        friend void serialize (
+            const nearest_neighbor_feature_image<T>& item,
+            std::ostream& out
+        );
+
+        template <typename T>
+        friend void deserialize (
+            nearest_neighbor_feature_image<T>& item,
+            std::istream& in 
+        );
+
+    private:
+
+        array2d<unsigned long> feats;
+        feature_extractor fe;
+        std::vector<typename feature_extractor::descriptor_type> basis;
+
+        // This is a transient variable.  It is just here so it doesn't have to be
+        // reallocated over and over inside operator()
+        mutable descriptor_type nn_feats;
+
+    };
+
+// ----------------------------------------------------------------------------------------
+
+    template <typename T>
+    void serialize (
+        const nearest_neighbor_feature_image<T>& item,
+        std::ostream& out
+    )
+    {
+        serialize(item.feats, out);
+        serialize(item.fe, out);
+        serialize(item.basis, out);
+    }
+
+    template <typename T>
+    void deserialize (
+        nearest_neighbor_feature_image<T>& item,
+        std::istream& in 
+    )
+    {
+        deserialize(item.feats, in);
+        deserialize(item.fe, in);
+        deserialize(item.basis, in);
+    }
+
+// ----------------------------------------------------------------------------------------
+// ----------------------------------------------------------------------------------------
+//                        nearest_neighbor_feature_image member functions
+// ----------------------------------------------------------------------------------------
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    nearest_neighbor_feature_image<feature_extractor>::
+    nearest_neighbor_feature_image (
+    )  
+    {
+        nn_feats.resize(1);
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    void nearest_neighbor_feature_image<feature_extractor>::
+    clear (
+    )
+    {
+        feats.clear();
+        fe.clear();
+        basis.clear();
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    void nearest_neighbor_feature_image<feature_extractor>::
+    copy_configuration (
+        const feature_extractor& item
+    )
+    {
+        fe.copy_configuration(item);
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    void nearest_neighbor_feature_image<feature_extractor>::
+    copy_configuration (
+        const nearest_neighbor_feature_image& item
+    )
+    {
+        fe.copy_configuration(item.fe);
+        basis = item.basis;
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    template <
+        typename image_type
+        >
+    void nearest_neighbor_feature_image<feature_extractor>::
+    load (
+        const image_type& img
+    )
+    {
+        fe.load(img);
+
+        feats.set_size(fe.nr(), fe.nc());
+
+        // find the nearest neighbor for each feature vector and store the
+        // result in feats.
+        for (long r = 0; r < feats.nr(); ++r)
+        {
+            for (long c = 0; c < feats.nc(); ++c)
+            {
+                const typename feature_extractor::descriptor_type& local_feat = fe(r,c);
+
+                double best_dist = std::numeric_limits<double>::infinity();
+                unsigned long best_idx = 0;
+                for (unsigned long i = 0; i < basis.size(); ++i)
+                {
+                    double dist = length_squared(local_feat - basis[i]);
+                    if (dist < best_dist)
+                    {
+                        best_dist = dist;
+                        best_idx = i;
+                    }
+                }
+
+                feats[r][c] = best_idx;
+            }
+        }
+
+        fe.unload();
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    unsigned long nearest_neighbor_feature_image<feature_extractor>::
+    size (
+    ) const
+    {
+        return feats.size();
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    long nearest_neighbor_feature_image<feature_extractor>::
+    nr (
+    ) const
+    {
+        return feats.nr();
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    long nearest_neighbor_feature_image<feature_extractor>::
+    nc (
+    ) const
+    {
+        return feats.nc();
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    long nearest_neighbor_feature_image<feature_extractor>::
+    get_num_dimensions (
+    ) const
+    {
+        return basis.size();
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <typename feature_extractor>
+    template <typename vector_type>
+    void nearest_neighbor_feature_image<feature_extractor>::
+    set_basis (
+        const vector_type& new_basis
+    )
+    {
+        basis.assign(new_basis.begin(), new_basis.end());
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    const typename nearest_neighbor_feature_image<feature_extractor>::descriptor_type& 
+    nearest_neighbor_feature_image<feature_extractor>::
+    operator() (
+        long row,
+        long col
+    ) const
+    {
+        // make sure requires clause is not broken
+        DLIB_ASSERT(0 <= row && row < nr() &&
+                    0 <= col && col < nc(),
+            "\t descriptor_type nearest_neighbor_feature_image::operator(row,col)"
+            << "\n\t Invalid inputs were given to this function"
+            << "\n\t row:  " << row
+            << "\n\t col:  " << col 
+            << "\n\t nr(): " << nr()
+            << "\n\t nc(): " << nc()
+            << "\n\t this: " << this
+            );
+
+        nn_feats[0] = std::make_pair(feats[row][col],1);
+        return nn_feats;
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    const rectangle nearest_neighbor_feature_image<feature_extractor>::
+    get_block_rect (
+        long row,
+        long col
+    ) const
+    {
+        return fe.get_block_rect(row,col);
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    const point nearest_neighbor_feature_image<feature_extractor>::
+    image_to_feat_space (
+        const point& p
+    ) const
+    {
+        return fe.image_to_feat_space(p);
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    const rectangle nearest_neighbor_feature_image<feature_extractor>::
+    image_to_feat_space (
+        const rectangle& rect
+    ) const
+    {
+        return fe.image_to_feat_space(rect);
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    const point nearest_neighbor_feature_image<feature_extractor>::
+    feat_to_image_space (
+        const point& p
+    ) const
+    {
+        return fe.feat_to_image_space(p);
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    const rectangle nearest_neighbor_feature_image<feature_extractor>::
+    feat_to_image_space (
+        const rectangle& rect
+    ) const 
+    {
+        return fe.feat_to_image_space(rect);
+    }
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_NEAREST_NEIGHBOR_FeATURE_IMAGE_H__
+
+

dlib/image_keypoint/nearest_neighbor_feature_image_abstract.h

+// Copyright (C) 2011  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#undef DLIB_NEAREST_NEIGHBOR_FeATURE_IMAGE_ABSTRACT_H__
+#ifdef DLIB_NEAREST_NEIGHBOR_FeATURE_IMAGE_ABSTRACT_H__
+
+#include <vector>
+#include "../algs.h"
+
+namespace dlib
+{
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    class nearest_neighbor_feature_image : noncopyable
+    {
+        /*!
+            REQUIREMENTS ON feature_extractor 
+                - must be an object with an interface compatible with dlib::hog_image
+
+            INITIAL VALUE
+                 - size() == 0
+                 - get_num_dimensions() == 0
+
+            WHAT THIS OBJECT REPRESENTS
+                This object is a tool for performing image feature extraction.  In
+                particular, it wraps another image feature extractor and converts
+                the wrapped image feature vectors into sparse indicator vectors.  It does
+                this by finding the nearest neighbor for each feature vector and returning an
+                indicator vector that is zero everywhere except for the position indicated by 
+                the nearest neighbor.  
+
+
+            THREAD SAFETY
+                Concurrent access to an instance of this object is not safe and should be protected
+                by a mutex lock except for the case where you are copying the configuration 
+                (via copy_configuration()) of a nearest_neighbor_feature_image object to many other 
+                threads.  In this case, it is safe to copy the configuration of a shared object so 
+                long as no other operations are performed on it.
+
+
+            NOTATION 
+                let BASE_FE denote the base feature_extractor object contained inside 
+                the nearest_neighbor_feature_image.
+        !*/
+
+    public:
+
+        typedef std::vector<std::pair<unsigned int,double> > descriptor_type;
+
+        nearest_neighbor_feature_image (
+        ); 
+        /*!
+            ensures
+                - this object is properly initialized
+        !*/
+
+        void clear (
+        );
+        /*!
+            ensures
+                - this object will have its initial value
+        !*/
+
+        void copy_configuration (
+            const feature_extractor& item
+        );
+        /*!
+            ensures
+                - performs BASE_FE.copy_configuration(item)
+        !*/
+
+        void copy_configuration (
+            const nearest_neighbor_feature_image& item
+        );
+        /*!
+            ensures
+                - copies all the state information of item into *this, except for state 
+                  information populated by load().  More precisely, given two 
+                  nearest_neighbor_feature_image objects H1 and H2, the following sequence 
+                  of instructions should always result in both of them having the exact 
+                  same state.
+                    H2.copy_configuration(H1);
+                    H1.load(img);
+                    H2.load(img);
+        !*/
+
+        template <
+            typename image_type
+            >
+        inline void load (
+            const image_type& img
+        );
+        /*!
+            requires
+                - image_type == any type that can be supplied to feature_extractor::load() 
+            ensures
+                - performs BASE_FE.load(img)
+                  i.e. does feature extraction.  The features can be accessed using
+                  operator() as defined below.
+        !*/
+
+        inline unsigned long size (
+        ) const;
+        /*!
+            ensures
+                - returns BASE_FE.size() 
+        !*/
+
+        inline long nr (
+        ) const;
+        /*!
+            ensures
+                - returns BASE_FE.nr() 
+        !*/
+
+        inline long nc (
+        ) const;
+        /*!
+            ensures
+                - returns BASE_FE.nc() 
+        !*/
+
+        inline long get_num_dimensions (
+        ) const;
+        /*!
+            ensures
+                - returns the dimensionality of the feature vectors returned by operator().  
+                  In this case, this is the number of basis elements.  That is, it is the number
+                  of vectors given to the set_basis() member function.
+        !*/
+
+        template <typename vector_type>
+        void set_basis (
+            const vector_type& new_basis
+        );
+        /*!
+            ensures
+                - #get_num_dimensions() == new_basis.size()
+                - The operator() member function defined below will use new_basis to 
+                  determine nearest neighbors.
+        !*/
+
+        inline const descriptor_type& operator() (
+            long row,
+            long col
+        ) const;
+        /*!
+            requires
+                - 0 <= row < nr()
+                - 0 <= col < nc()
+                - get_num_dimensions() > 0
+            ensures
+                - determines which basis element is nearest to BASE_FE(row,col) and returns a sparse
+                  indicator vector identifying the nearest neighbor. 
+                - To be precise, this function returns a sparse vector V such that:
+                    - V.size() == 1 
+                    - V[0].first == The basis element index for the basis vector nearest to BASE_FE(row,col).
+                      "nearness" is determined using Euclidean distance.
+                    - V[0].second == 1 
+        !*/
+
+        inline const rectangle get_block_rect (
+            long row,
+            long col
+        ) const;
+        /*!
+            ensures
+                - returns BASE_FE.get_block_rect(row,col)
+                  I.e. returns a rectangle that tells you what part of the original image is associated
+                  with a particular feature vector.
+        !*/
+
+        inline const point image_to_feat_space (
+            const point& p
+        ) const;
+        /*!
+            ensures
+                - returns BASE_FE.image_to_feat_space(p)
+                  I.e. Each local feature is extracted from a certain point in the input image.
+                  This function returns the identity of the local feature corresponding
+                  to the image location p.  Or in other words, let P == image_to_feat_space(p), 
+                  then (*this)(P.y(),P.x()) == the local feature closest to, or centered at, 
+                  the point p in the input image.  Note that some image points might not have 
+                  corresponding feature locations.  E.g. border points or points outside the 
+                  image.  In these cases the returned point will be outside get_rect(*this).
+        !*/
+
+        inline const rectangle image_to_feat_space (
+            const rectangle& rect
+        ) const;
+        /*!
+            ensures
+                - returns BASE_FE.image_to_feat_space(rect)
+                  I.e. returns rectangle(image_to_feat_space(rect.tl_corner()), image_to_feat_space(rect.br_corner()));
+                  (i.e. maps a rectangle from image space to feature space)
+        !*/
+
+        inline const point feat_to_image_space (
+            const point& p
+        ) const;
+        /*!
+            ensures
+                - returns BASE_FE.feat_to_image_space(p)
+                  I.e. returns the location in the input image space corresponding to the center
+                  of the local feature at point p.  In other words, this function computes
+                  the inverse of image_to_feat_space().  Note that it may only do so approximately, 
+                  since more than one image location might correspond to the same local feature.  
+                  That is, image_to_feat_space() might not be invertible so this function gives 
+                  the closest possible result.
+        !*/
+
+        inline const rectangle feat_to_image_space (
+            const rectangle& rect
+        ) const;
+        /*!
+            ensures
+                - returns BASE_FE.feat_to_image_space(rect)
+                  I.e. return rectangle(feat_to_image_space(rect.tl_corner()), feat_to_image_space(rect.br_corner()));
+                  (i.e. maps a rectangle from feature space to image space)
+        !*/
+
+    };
+
+// ----------------------------------------------------------------------------------------
+
+    template <typename T>
+    void serialize (
+        const nearest_neighbor_feature_image<T>& item,
+        std::ostream& out
+    );
+    /*!
+        provides serialization support 
+    !*/
+
+    template <typename T>
+    void deserialize (
+        nearest_neighbor_feature_image<T>& item,
+        std::istream& in 
+    );
+    /*!
+        provides deserialization support 
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_NEAREST_NEIGHBOR_FeATURE_IMAGE_ABSTRACT_H__
+
+
+