GistEstimatorSurfPMK.H

Go to the documentation of this file.
00001 /**
00002    \file Neuro/GistEstimatorSurfPMK.H
00003 
00004    \brief Implementation of ``SURF features for efficient robot
00005    localization with omnidirectional images'' by Murillo, et al.
00006 
00007    The GistEstimatorSurfPMK class implements the following paper
00008    within the INVT framework:
00009 
00010    Murillo, A. C., Guerrero, J. J., Sagues, C.
00011    SURF features for efficient robot localization with omnidirectional images
00012    ICRA, 2007.
00013 */
00014 
00015 // //////////////////////////////////////////////////////////////////// //
00016 // The iLab Neuromorphic Vision C++ Toolkit - Copyright (C) 2000-2005   //
00017 // by the University of Southern California (USC) and the iLab at USC.  //
00018 // See http://iLab.usc.edu for information about this project.          //
00019 // //////////////////////////////////////////////////////////////////// //
00020 // Major portions of the iLab Neuromorphic Vision Toolkit are protected //
00021 // under the U.S. patent ``Computation of Intrinsic Perceptual Saliency //
00022 // in Visual Environments, and Applications'' by Christof Koch and      //
00023 // Laurent Itti, California Institute of Technology, 2001 (patent       //
00024 // pending; application number 09/912,225 filed July 23, 2001; see      //
00025 // http://pair.uspto.gov/cgi-bin/final/home.pl for current status).     //
00026 // //////////////////////////////////////////////////////////////////// //
00027 // This file is part of the iLab Neuromorphic Vision C++ Toolkit.       //
00028 //                                                                      //
00029 // The iLab Neuromorphic Vision C++ Toolkit is free software; you can   //
00030 // redistribute it and/or modify it under the terms of the GNU General  //
00031 // Public License as published by the Free Software Foundation; either  //
00032 // version 2 of the License, or (at your option) any later version.     //
00033 //                                                                      //
00034 // The iLab Neuromorphic Vision C++ Toolkit is distributed in the hope  //
00035 // that it will be useful, but WITHOUT ANY WARRANTY; without even the   //
00036 // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR      //
00037 // PURPOSE.  See the GNU General Public License for more details.       //
00038 //                                                                      //
00039 // You should have received a copy of the GNU General Public License    //
00040 // along with the iLab Neuromorphic Vision C++ Toolkit; if not, write   //
00041 // to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,   //
00042 // Boston, MA 02111-1307 USA.                                           //
00043 // //////////////////////////////////////////////////////////////////// //
00044 //
00045 // Primary maintainer for this file: Manu Viswanathan <mviswana at usc dot edu>
00046 // $HeadURL: svn://isvn.usc.edu/software/invt/trunk/saliency/src/Neuro/GistEstimatorSurfPMK.H $
00047 // $Id: GistEstimatorSurfPMK.H 12068 2009-11-23 00:44:06Z mviswana $
00048 //
00049 
00050 #ifndef GE_SURF_PMK_H_DEFINED
00051 #define GE_SURF_PMK_H_DEFINED
00052 
00053 //--------------------------- LIBRARY CHECK -----------------------------
00054 
00055 #ifndef INVT_HAVE_LIBSURF
00056 
00057 // Gist specific headers
00058 #include "Neuro/GistEstimator.H"
00059 
00060 // Dummy class defnition
00061 class GistEstimatorSurfPMK : public GistEstimatorAdapter {
00062 public:
00063    GistEstimatorSurfPMK(OptionManager& mgr,
00064       const std::string& descrName = "GistEstimatorSurfPMK",
00065       const std::string& tagName   = "GistEstimatorSurfPMK") ;
00066    virtual ~GistEstimatorSurfPMK() ;
00067 
00068 protected:
00069    Image<double> getGist() {return Image<double>() ;}
00070 } ;
00071 
00072 #else // regular SURF-PMK gist estimator
00073 
00074 //------------------------------ HEADERS --------------------------------
00075 
00076 // Gist specific headers
00077 #include "Neuro/GistEstimator.H"
00078 
00079 // surf headers
00080 #include <opensurf/opensurf.hh>
00081 
00082 // Standard C++ headers
00083 #include <ostream>
00084 #include <list>
00085 #include <vector>
00086 #include <string>
00087 
00088 //------------------------- CLASS DEFINITION ----------------------------
00089 
00090 /**
00091    \class GistEstimatorSurfPMK
00092 
00093    \brief Gist estimator for ``SURF features for efficient robot
00094    localization with omnidirectional images'' by Murillo, et al.
00095 
00096    See the paper for the gory details.
00097 */
00098 class GistEstimatorSurfPMK : public GistEstimator {
00099 public:
00100    static const int GIST_VECTOR_SIZE ;
00101 
00102    /// The constructor expects to be passed an option manager, which it
00103    /// uses to set itself up within the INVT simulation framework.
00104    GistEstimatorSurfPMK(OptionManager& mgr,
00105       const std::string& descrName = "GistEstimatorSurfPMK",
00106       const std::string& tagName   = "GistEstimatorSurfPMK") ;
00107 
00108    /// Destructor
00109    virtual ~GistEstimatorSurfPMK() ;
00110 
00111    /// A SURF descriptor is just a vector of 64 numbers.
00112    static const int SURF_DESCRIPTOR_SIZE = 64 ;
00113 
00114    /// This type provides a convenient alias for a SURF descriptor's
00115    /// vector of 64 numbers.
00116    typedef opensurf::IPoint SurfDescriptor ;
00117 
00118    /// Like other gist estimators, this one too filters the input image.
00119    /// Its filteration process involves running SURF on the input image.
00120    /// The filteration results are returned as a grid of SURF
00121    /// descriptors. The following type is used to represent these
00122    /// results.
00123    typedef std::vector<SurfDescriptor> SurfKeypoints ;
00124 
00125    /// In order to compute a gist vector, this estimator needs to know
00126    /// the vocabulary, i.e., the ``prototypical'' SURF descriptors as
00127    /// extracted by the hierarchical K-means clustering of the training
00128    /// descriptors.
00129    typedef std::list<SurfDescriptor> Vocabulary ;
00130 
00131    /// This method should be called once during the client's
00132    /// initialization process prior to attempting to obtain gist
00133    /// vectors for input images. Thus, the clustering phase of the
00134    /// training must be complete before this estimator can be used to
00135    /// compute gist vectors.
00136    void setVocabulary(const Image<float>&) ;
00137 
00138    /// To assist with training, GistEstimatorSurfPMK can be configured
00139    /// to operate in a special training mode in which it does not have a
00140    /// vocabulary from which to form gist vectors but rather simply
00141    /// passes back (to its client) the grid of SURF descriptors for the
00142    /// input image, i.e., the results of the filteration step. The
00143    /// client may then store these descriptors, perform the clustering
00144    /// required to create the vocabulary necessary for subsequent normal
00145    /// use of this gist estimator, and then run the estimator in
00146    /// non-training mode to compute the actual gist vectors.
00147    ///
00148    /// Training mode is set by specifying a hook function that accepts
00149    /// the filteration results, i.e., the grid/Image of SURF
00150    /// descriptors.
00151    typedef void (*TrainingHook)(const SurfKeypoints&) ;
00152 
00153    /// This method should be called once during the client's
00154    /// initialization sequence to specify the training mode hook
00155    /// function to configure GistEstimatorSurfPMK to run in training
00156    /// mode. If this hook is not specified, the estimator will run in
00157    /// ``normal'' mode and compute gist vectors from the vocabulary.
00158    ///
00159    /// It is an error to not specify either the training hook or the
00160    /// vocabulary. If both are specified, the training hook takes
00161    /// precedence, i.e., the estimator runs in training mode, wherein it
00162    /// passes back filteration results (grid of SURF descriptors) to the
00163    /// client rather than computing gist vectors.
00164    void setTrainingHook(TrainingHook) ;
00165 
00166    /// Return the gist vector (useless in training mode).
00167    Image<double> getGist() ;
00168 
00169 protected:
00170   /// Callback for when a new input (retina) frame is available
00171   SIMCALLBACK_DECLARE(GistEstimatorSurfPMK, SimEventRetinaImage);
00172 
00173 private :
00174    Image<double> itsGistVector ; // gist feature vector
00175    Vocabulary    itsVocabulary ;
00176    TrainingHook  itsTrainingHook ;
00177 } ;
00178 
00179 //---------------------- MISCELLANEOUS FUNCTIONS ------------------------
00180 
00181 std::ostream& operator<<(std::ostream&,
00182                          const GistEstimatorSurfPMK::SurfDescriptor&) ;
00183 
00184 //-------------------- INLINE FUNCTION DEFINITIONS ----------------------
00185 
00186 inline Image<double> GistEstimatorSurfPMK::getGist()
00187 {
00188    return itsGistVector ;
00189 }
00190 
00191 inline void
00192 GistEstimatorSurfPMK::
00193 setTrainingHook(GistEstimatorSurfPMK::TrainingHook H)
00194 {
00195    itsTrainingHook = H ;
00196 }
00197 
00198 //-----------------------------------------------------------------------
00199 
00200 #endif // #ifndef INVT_HAVE_LIBSURF
00201 #endif // #ifndef GE_SURF_PMK_H_DEFINED
00202 
00203 /* So things look consistent in everyone's emacs... */
00204 /* Local Variables: */
00205 /* indent-tabs-mode: nil */
00206 /* End: */
Generated on Sun May 8 08:41:03 2011 for iLab Neuromorphic Vision Toolkit by  doxygen 1.6.3