PyrBuilder.H

Go to the documentation of this file.
00001 /*!@file Image/PyrBuilder.H Classes for building dyadic pyramids */
00002 
00003 // //////////////////////////////////////////////////////////////////// //
00004 // The iLab Neuromorphic Vision C++ Toolkit - Copyright (C) 2001 by the //
00005 // University of Southern California (USC) and the iLab at USC.         //
00006 // See http://iLab.usc.edu for information about this project.          //
00007 // //////////////////////////////////////////////////////////////////// //
00008 // Major portions of the iLab Neuromorphic Vision Toolkit are protected //
00009 // under the U.S. patent ``Computation of Intrinsic Perceptual Saliency //
00010 // in Visual Environments, and Applications'' by Christof Koch and      //
00011 // Laurent Itti, California Institute of Technology, 2001 (patent       //
00012 // pending; application number 09/912,225 filed July 23, 2001; see      //
00013 // http://pair.uspto.gov/cgi-bin/final/home.pl for current status).     //
00014 // //////////////////////////////////////////////////////////////////// //
00015 // This file is part of the iLab Neuromorphic Vision C++ Toolkit.       //
00016 //                                                                      //
00017 // The iLab Neuromorphic Vision C++ Toolkit is free software; you can   //
00018 // redistribute it and/or modify it under the terms of the GNU General  //
00019 // Public License as published by the Free Software Foundation; either  //
00020 // version 2 of the License, or (at your option) any later version.     //
00021 //                                                                      //
00022 // The iLab Neuromorphic Vision C++ Toolkit is distributed in the hope  //
00023 // that it will be useful, but WITHOUT ANY WARRANTY; without even the   //
00024 // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR      //
00025 // PURPOSE.  See the GNU General Public License for more details.       //
00026 //                                                                      //
00027 // You should have received a copy of the GNU General Public License    //
00028 // along with the iLab Neuromorphic Vision C++ Toolkit; if not, write   //
00029 // to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,   //
00030 // Boston, MA 02111-1307 USA.                                           //
00031 // //////////////////////////////////////////////////////////////////// //
00032 //
00033 // Primary maintainer for this file: Laurent Itti <itti@usc.edu>
00034 // $HeadURL: svn://isvn.usc.edu/software/invt/trunk/saliency/src/Image/PyrBuilder.H $
00035 // $Id: PyrBuilder.H 14471 2011-02-03 01:24:37Z dberg $
00036 //
00037 
00038 #ifndef PYRBUILDER_H_DEFINED
00039 #define PYRBUILDER_H_DEFINED
00040 
00041 #include "Image/Convolutions.H"
00042 #include "Image/Image.H"
00043 #include "Image/PyramidTypes.H"
00044 
00045 #include <deque>
00046 
00047 template <class T> class ImageSet;
00048 template <class T> class PixRGB;
00049 template <class T> class PyramidCache;
00050 
00051 // ######################################################################
00052 //! An interface class for creating dyadic pyramids from input images.
00053 /*! A dyadic image pyramid is an array of images such that the next image
00054     is obtained from the previous one by applying some filter and
00055     decimating the image by a factor 2 horizontally and vertically.
00056 
00057     The PyrBuilder classes essentially wrap one of the buildPyr*()
00058     functions, binding preset values to all of the trailing arguments. This
00059     allows all of the buildPyr*() functions to be presented behind a
00060     uniform interface.
00061 
00062     PyrBuilder defers the actual handling of input images through the
00063     abstract function build(). Different subclasses may implement this to
00064     apply different filters (e.g., gaussian, laplacian, gabor) before
00065     decimation. GenericPyrBuilder offers a generic implementation, while
00066     GaussianPyrBuilder, LaplacianPyrBuilder, and OrientedPyrBuilder are
00067     specialized for single filter types.
00068 */
00069 template <class T>
00070 class PyrBuilder
00071 {
00072 public:
00073   //! Create an empty PyrBuilder
00074   PyrBuilder();
00075 
00076   // default copy contructor and assignment are okay
00077 
00078   //! Virtual destructor for safe inheritance.
00079   virtual ~PyrBuilder();
00080 
00081   //! Cloning constructor useful to make clones from pointers:
00082   virtual PyrBuilder<T>* clone() const = 0;
00083 
00084   //! Create a pyramid from an input image, with given depth (=nb levels)
00085   /*! @param firstlevel if non-zero, then pyramid levels prior to
00086       firstlevel may be skipped and left empty, as long as the
00087       remaining pyramid levels contain the same values that they would
00088       normally contain -- this parameter is only an optimization hint,
00089       and subclasses are free to ignore it if they so choose
00090 
00091       @param depth number of levels the pyramid should contain (note
00092       that if firstlevel is non-zero, then some of those levels may be
00093       empty)
00094    */
00095   virtual ImageSet<T> build(const Image<T>& image,
00096                             const int firstlevel, const int depth,
00097                             PyramidCache<T>* cache = 0) = 0;
00098 
00099   //! reset the pyramid - whatever that means for a specific pyramid
00100   /*! a no op implementation is given in this base class - so if pyramids
00101     don't need this, they don't have to worry about it */
00102   virtual void reset();
00103 
00104 private:
00105 };
00106 
00107 
00108 // ######################################################################
00109 //! Builds pyramids based on Gaussian filters.
00110 template <class T>
00111 class GaussianPyrBuilder : public PyrBuilder<T>
00112 {
00113 public:
00114   //! Constructor.
00115   GaussianPyrBuilder(const int filter_size);
00116 
00117   // Default copy constructor and assignment operator ok.
00118 
00119   //! Cloning constructor:
00120   virtual GaussianPyrBuilder<T>* clone() const;
00121 
00122   //! Builds a Gaussian pyramid based on \a img.
00123   virtual ImageSet<T> build(const Image<T>& img,
00124                             const int firstlevel, const int depth,
00125                             PyramidCache<T>* cache = 0);
00126 
00127 private:
00128   int itsFiltSize;
00129 };
00130 
00131 // ######################################################################
00132 //! Builds pyramids based on Gaussian filters with boundary conditions for radially transformed images
00133 template <class T>
00134 class GaussianRadialPyrBuilder : public PyrBuilder<T>
00135 {
00136 public:
00137   //! Constructor.
00138   GaussianRadialPyrBuilder();
00139 
00140   // Default copy constructor and assignment operator ok.
00141 
00142   //! Cloning constructor:
00143   virtual GaussianRadialPyrBuilder<T>* clone() const;
00144 
00145   //! Builds a Gaussian pyramid based on \a img.
00146   virtual ImageSet<T> build(const Image<T>& img,
00147                             const int firstlevel, const int depth,
00148                             PyramidCache<T>* cache = 0);
00149 };
00150 
00151 // ######################################################################
00152 //! Builds pyramids based on arbitrary filters.
00153 template <class T>
00154 class ConvolvePyrBuilder : public PyrBuilder<T>
00155 {
00156 public:
00157   //! Constructor.
00158   ConvolvePyrBuilder(const Image<float>& filt,
00159                      ConvolutionBoundaryStrategy boundary);
00160 
00161   // Default copy constructor and assignment operator ok.
00162 
00163   //! Cloning constructor:
00164   virtual ConvolvePyrBuilder<T>* clone() const;
00165 
00166   //! Builds a pyramid based on \a img.
00167   virtual ImageSet<T> build(const Image<T>& img,
00168                             const int firstlevel, const int depth,
00169                             PyramidCache<T>* cache = 0);
00170 
00171 private:
00172   Image<float> itsFilt;
00173   ConvolutionBoundaryStrategy itsBoundary;
00174 };
00175 
00176 // ######################################################################
00177 //! Builds pyramids based on arbitrary color filters.
00178 template <class T>
00179 class RGBConvolvePyrBuilder : public PyrBuilder<T>
00180 {
00181 public:
00182   //! Constructor.
00183   RGBConvolvePyrBuilder(const Image<float>& rfilt,
00184                         const Image<float>& gfilt,
00185                         const Image<float>& bfilt,
00186                         ConvolutionBoundaryStrategy boundary);
00187 
00188   // Default copy constructor and assignment operator ok.
00189 
00190   //! Cloning constructor:
00191   virtual RGBConvolvePyrBuilder<T>* clone() const;
00192 
00193   //! Builds a pyramid based on a img.
00194   virtual ImageSet<T> build(const Image< PixRGB<T> >& img,
00195                             const int firstlevel, const int depth,
00196                             PyramidCache<T>* cache = 0);
00197 
00198   //! Don't use this one!
00199   virtual ImageSet<T> build(const Image<T>& img,
00200                             const int firstlevel, const int depth,
00201                             PyramidCache<T>* cache = 0);
00202 
00203   //! Builds a color pyramid based on a img.
00204   //! Only used to display results, filters behaviour...
00205   ImageSet< PixRGB<T> > build2(const Image< PixRGB<T> >& img,
00206                                const int firstlevel,
00207                                const int depth,
00208                                PyramidCache<T>* cache = 0);
00209 
00210 private:
00211   Image<float> itsRFilt, itsGFilt, itsBFilt;
00212   ConvolutionBoundaryStrategy itsBoundary;
00213 };
00214 
00215 // ######################################################################
00216 //! Builds pyramids based on Laplacian filters.
00217 template <class T>
00218 class LaplacianPyrBuilder : public PyrBuilder<T>
00219 {
00220 public:
00221   //! Constructor.
00222   LaplacianPyrBuilder(const int filter_size);
00223 
00224   // Default copy constructor and assignment operator ok.
00225 
00226   //! Cloning constructor:
00227   virtual LaplacianPyrBuilder<T>* clone() const;
00228 
00229   //! Builds a Laplacian pyramid based on \a img.
00230   virtual ImageSet<T> build(const Image<T>& img,
00231                             const int firstlevel, const int depth,
00232                             PyramidCache<T>* cache = 0);
00233 
00234 private:
00235   int itsFiltSize;
00236 };
00237 
00238 
00239 // ######################################################################
00240 //! Builds pyramid based on oriented Laplacian filters.
00241 /*! This is a fast approximation to Gabor convolution. */
00242 template <class T>
00243 class OrientedPyrBuilder : public PyrBuilder<T>
00244 {
00245 public:
00246   //! Construct with a given gabor filter orientation and intensity.
00247   OrientedPyrBuilder(const int filter_size, const float theta = 0.0F,
00248                      const float intens = 10.0F,
00249                      const bool usetab = false);
00250 
00251   // Default copy constructor and assignment operator ok.
00252 
00253   //! Cloning constructor:
00254   virtual OrientedPyrBuilder<T>* clone() const;
00255 
00256   //! Builds an oriented pyramid based on \a img.
00257   virtual ImageSet<T> build(const Image<T>& img,
00258                             const int firstlevel, const int depth,
00259                             PyramidCache<T>* cache = 0);
00260 
00261 private:
00262   int itsFiltSize;
00263   float itsAngle;
00264   float itsGaborIntens;
00265   bool itsUseTab;
00266 };
00267 
00268 
00269 // ######################################################################
00270 //! Builds pyramids of a type specified by a PyramidType.
00271 /*! This is a chameleon class; it can build any kind of pyramid (Gaussian,
00272     Laplacian, Gabor, QuickLocalAvg, QuickLocalMax) depending on the
00273     PyramidType passed to its constructor.
00274  */
00275 template <class T>
00276 class GenericPyrBuilder : public PyrBuilder<T>
00277 {
00278 public:
00279   //! Build with depth & type, but no input image yet.
00280   /*! \a gabor_theta and \a intens are used for Gabor pyramids. */
00281   GenericPyrBuilder(const PyramidType typ, const float gabor_theta = 0.0F,
00282                     const float intens = 10.0F);
00283 
00284   // Default copy constructor and assignment operator ok.
00285 
00286   //! Cloning constructor:
00287   virtual GenericPyrBuilder<T>* clone() const;
00288 
00289   //! Create a pyramid from an input image.
00290   /*! The type of pyramid that is built is determined by the PyramidType
00291       that was given to the constructor. */
00292   virtual ImageSet<T> build(const Image<T>& image,
00293                             const int firstlevel, const int depth,
00294                             PyramidCache<T>* cache = 0);
00295 
00296 private:
00297   PyramidType itsPtype;     // Gaussian, Laplacian, Gabor, etc.
00298   float itsGaborAngle;      // orientation tuning for Gabor pyr
00299   float itsGaborIntens;     // filter strength for Gabor pyr
00300 };
00301 
00302 
00303 // ######################################################################
00304 //! This class implements Reichardt motion detections
00305 /*! The class uses the filter results of pyramids of other types
00306   to implement Reichardt motion detection. The pyramids of the previous
00307   time step are stored and used with the pyramid of this time step and
00308   a version of the current pyramid, in which each level is shifted by the
00309   same amount dx and dy. The results are stored in the Reichardt pyramid and
00310   represent motion at different speeds and spatial resolutions. */
00311 template <class T>
00312 class ReichardtPyrBuilder : public PyrBuilder<T>
00313 {
00314 public:
00315   // ######################################################################
00316   // #### Constructors
00317   // ######################################################################
00318   //! build with depth, dx, dy and type, but no input image yet
00319   /*! @param dx the number of pixels to shift into the x-direction
00320     (can be fractional value)
00321     @param dy the number of pixels to shift into the y-direction
00322     @param typ the type of pyramid to use for the filtering
00323     @param gabor_theta orientation of a gabor filter (if typ is GaborX)
00324     @param intens used for gabor filter ... */
00325   ReichardtPyrBuilder(const float dx,
00326                       const float dy,
00327                       const PyramidType typ,
00328                       const float gabor_theta = 0.0F,
00329                       const float intens = 10.0F);
00330 
00331   // default copy constructor and assignment are okay
00332   // std::vector and std::deque handle the copying of the individual images
00333 
00334   //! cloning constructor
00335   virtual ReichardtPyrBuilder<T>* clone() const;
00336 
00337   //! Builds a Reichardt pyramid based on a image
00338   virtual ImageSet<T> build(const Image<T>& image,
00339                             const int firstlevel, const int depth,
00340                             PyramidCache<T>* cache = 0);
00341 
00342   //! reset the stored queues - overrides PyrBuilder<T>::reset()
00343   virtual void reset();
00344 
00345 private:
00346   float itsDX, itsDY;
00347   PyramidType itsPtype;     // Gaussian, Laplacian, Gabor, etc.
00348   float itsGaborAngle;      // orientation tuning for Gabor pyr
00349   float itsGaborIntens;     // filter strength for Gabor pyr
00350   std::deque< ImageSet<T> > shifted, unshifted;
00351 };
00352 
00353 // ######################################################################
00354 //! A PyrBuilder that does template matching
00355 class TemplateMatchPyrBuilder : public PyrBuilder<float>
00356 {
00357 public:
00358   // Constructor
00359   TemplateMatchPyrBuilder(const Image<float>& templ);
00360 
00361   //! Cloning constructor useful to make clones from pointers:
00362   virtual TemplateMatchPyrBuilder* clone() const;
00363 
00364   //! Create a pyramid from an input image.
00365   virtual ImageSet<float> build(const Image<float>& image,
00366                                 const int firstlevel, const int depth,
00367                                 PyramidCache<float>* cache = 0);
00368 
00369 private:
00370   // return an image where higher values indicate better matches:
00371   Image<float> templateMatch(const Image<float>& img);
00372 
00373   Image<float> itsFilt;
00374 };
00375 
00376 // ######################################################################
00377 //! A pyramid based on convolution with oriented Gabor filters
00378 template <class T>
00379 class GaborPyrBuilder : public PyrBuilder<T>
00380 {
00381 public:
00382   //! Constructor.
00383   /*! @param angle Angle (in degrees); parallel to the Gabor's "ridges".
00384       @param filter_period Period (in pixels) of underlying grating.
00385       @param elongation Ratio of major/minor axis lengths of Gaussian envelope.
00386       @param size determines the filter size (in pixels) - in the default case
00387       (-1), the size is computed from the filter_preiod and elongation
00388       @param buildFlags see Pyramid_Ops.H for possible values
00389   */
00390   GaborPyrBuilder(double angle,
00391                   double filter_period,
00392                   double elongation = 1.0,
00393                   int size = -1,
00394                   int buildFlags = 0);
00395 
00396   // Default copy constructor and assignment operator ok.
00397 
00398   //! Cloning constructor.
00399   virtual GaborPyrBuilder<T>* clone() const;
00400 
00401   //! Builds a Gabor pyramid based on an image.
00402   virtual ImageSet<T> build(const Image<T>& img,
00403                             const int firstlevel, const int depth,
00404                             PyramidCache<T>* cache = 0);
00405 
00406   //! Builds a Gabor pyramid from the levels in the given pyramid.
00407   ImageSet<T> input(const ImageSet<T>& pyr);
00408 
00409 private:
00410   double itsAngle;
00411   double itsPeriod;
00412   double itsElongation;
00413   int itsSize;
00414   int itsBuildFlags;
00415 };
00416 
00417 #endif // !PYRBUILDER_H_DEFINED
00418 
00419 // ######################################################################
00420 /* So things look consistent in everyone's emacs... */
00421 /* Local Variables: */
00422 /* indent-tabs-mode: nil */
00423 /* End: */
Generated on Sun May 8 08:40:57 2011 for iLab Neuromorphic Vision Toolkit by  doxygen 1.6.3