LocustModel.H

Go to the documentation of this file.
00001 /**
00002    \file  Robots/LoBot/lgmd/LocustModel.H
00003    \brief Abstract base class for different locust models.
00004 
00005    This file defines a class that supplies a common interface for all the
00006    different locust/LGMD models supported by Lobot/Robolocust.
00007 */
00008 
00009 // //////////////////////////////////////////////////////////////////// //
00010 // The iLab Neuromorphic Vision C++ Toolkit - Copyright (C) 2000-2005   //
00011 // by the University of Southern California (USC) and the iLab at USC.  //
00012 // See http://iLab.usc.edu for information about this project.          //
00013 // //////////////////////////////////////////////////////////////////// //
00014 // Major portions of the iLab Neuromorphic Vision Toolkit are protected //
00015 // under the U.S. patent ``Computation of Intrinsic Perceptual Saliency //
00016 // in Visual Environments, and Applications'' by Christof Koch and      //
00017 // Laurent Itti, California Institute of Technology, 2001 (patent       //
00018 // pending; application number 09/912,225 filed July 23, 2001; see      //
00019 // http://pair.uspto.gov/cgi-bin/final/home.pl for current status).     //
00020 // //////////////////////////////////////////////////////////////////// //
00021 // This file is part of the iLab Neuromorphic Vision C++ Toolkit.       //
00022 //                                                                      //
00023 // The iLab Neuromorphic Vision C++ Toolkit is free software; you can   //
00024 // redistribute it and/or modify it under the terms of the GNU General  //
00025 // Public License as published by the Free Software Foundation; either  //
00026 // version 2 of the License, or (at your option) any later version.     //
00027 //                                                                      //
00028 // The iLab Neuromorphic Vision C++ Toolkit is distributed in the hope  //
00029 // that it will be useful, but WITHOUT ANY WARRANTY; without even the   //
00030 // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR      //
00031 // PURPOSE.  See the GNU General Public License for more details.       //
00032 //                                                                      //
00033 // You should have received a copy of the GNU General Public License    //
00034 // along with the iLab Neuromorphic Vision C++ Toolkit; if not, write   //
00035 // to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,   //
00036 // Boston, MA 02111-1307 USA.                                           //
00037 // //////////////////////////////////////////////////////////////////// //
00038 //
00039 // Primary maintainer for this file: mviswana usc edu
00040 // $HeadURL: svn://isvn.usc.edu/software/invt/trunk/saliency/src/Robots/LoBot/lgmd/LocustModel.H $
00041 // $Id: LocustModel.H 13183 2010-04-08 07:17:49Z mviswana $
00042 //
00043 
00044 #ifndef LOBOT_LOCUST_MODEL_BASE_DOT_H
00045 #define LOBOT_LOCUST_MODEL_BASE_DOT_H
00046 
00047 //------------------------------ HEADERS --------------------------------
00048 
00049 // lobot headers
00050 #include "Robots/LoBot/ui/LoDrawable.H"
00051 #include "Robots/LoBot/io/LoInputSource.H"
00052 
00053 #include "Robots/LoBot/misc/LoTypes.H"
00054 #include "Robots/LoBot/util/LoMath.H"
00055 #include "Robots/LoBot/util/range.hh"
00056 
00057 // INVT image support
00058 #include "Image/Rectangle.H"
00059 
00060 // Standard C++ headers
00061 #include <deque>
00062 
00063 //----------------------------- NAMESPACE -------------------------------
00064 
00065 namespace lobot {
00066 
00067 //------------------------- CLASS DEFINITION ----------------------------
00068 
00069 /**
00070    \class lobot::LocustModel
00071    \brief Abstract base class for locust models of different types.
00072 
00073    This class acts as an abstract base for all the different locust/LGMD
00074    models supported by Lobot/Robolocust. Since it is an abstract class,
00075    it cannot be instantiated. However, its descendants are meant to be
00076    instantiated using the generic factory<LocustModel> defined in
00077    factory.hh.
00078 */
00079 class LocustModel : public Drawable {
00080    // Prevent copy and assignment
00081    LocustModel(const LocustModel&) ;
00082    LocustModel& operator=(const LocustModel&) ;
00083 
00084    /// Every locust model will read its assigned subportion of the input
00085    /// image from its source and then spit out a number that somehow
00086    /// measures the output of the locust LGMD (e.g., a firing rate or
00087    /// membrane potential or something similar).
00088    float m_lgmd ;
00089 
00090    /// The LGMD measure computed by each different locust model must lie
00091    /// within some range. This range can be fixed or adaptive. Derived
00092    /// classes are free to implement the range computation in any way
00093    /// they see fit. This class ensures that all LGMD values get clamped
00094    /// to this range.
00095    range<float> m_range ;
00096 
00097 protected:
00098    /// This method allows derived classes to implement something other
00099    /// than a fixed range for the LGMD values they compute. Usually, they
00100    /// will call this method as part of their update cycle.
00101    void adjust_range(const range<float>& r) {m_range = r ;}
00102 
00103    /// Each instance of a locust model must have some input image source.
00104    /// Usually, this will be the compositor that reads the current frames
00105    /// from all the video streams and then stitches them together to
00106    /// create a crude sort of panaromic image.
00107    const InputSource* m_source ;
00108 
00109    /// Each locust will be setup to look in a particular direction. Zero
00110    /// degrees corresponds to looking straight ahead. Positive angles are
00111    /// for the left and negative angles for locusts looking to the right.
00112    /// The direction angles are specified in degrees.
00113    float m_direction ;
00114 
00115    /// When working with vision as the primary sensing modality, each
00116    /// locust model will usually read only a subportion of the input
00117    /// image so as to allow simulation of multiple locusts with limited
00118    /// FOVs.
00119    Rectangle m_rect ;
00120 
00121    /// In case the locust model is set up to read its input from a laser
00122    /// range finder rather than a video frame source, we use a range of
00123    /// angles for the distance measurements instead of a rectangular
00124    /// subregion of an input image.
00125    range<int> m_lrf_range ;
00126 
00127    /// If the input source is a laser range finder, then each locust can
00128    /// (if required) keep track of the distance to approaching obstacles
00129    /// in its field of view. This can be useful, for instance, to gauge
00130    /// how well a particual model works w.r.t. ground truth.
00131    float m_distance ;
00132 
00133    /// In addition to computing an LGMD spike rate, some locust models
00134    /// might also work with a time-to-impact value.
00135    float m_tti ;
00136 
00137 public:
00138    /// Methods to return the cached result of the LGMD computations.
00139    //@{
00140    float get_lgmd() const {return m_lgmd    ;}
00141    float value()    const {return get_lgmd();} // for compatibility with EMD
00142    //@}
00143 
00144    /// This method returns the minimum and maximum possible values of the
00145    /// LGMD measure this model can compute. This range is useful for
00146    /// normalization and other scaling operations.
00147    range<float> get_range() const {return m_range ;}
00148 
00149    /// Retrieve the direction along which this locust is setup to look.
00150    float direction() const {return m_direction ;}
00151 
00152    /// This method returns the subportion of the input image that the
00153    /// this particular locust is "monitoring."
00154    const Rectangle& get_rect() const {return m_rect ;}
00155 
00156    /// This method returns the LRF angular range that specifies a
00157    /// locust's FOV when an LRF (rather than a camera) is the input
00158    /// source.
00159    range<int> get_lrf_range() const {return m_lrf_range ;}
00160 
00161    /// This method returns the current distance in this locust's FOV as
00162    /// reported by the laser range finder.
00163    float distance() const {return m_distance ;}
00164 
00165    /// This method returns the current time-to-impact computed by the
00166    /// LGMD model.
00167    float tti() const {return m_tti ;}
00168 
00169    /// On instantiation, each locust model will need to be provided these
00170    /// parameters.
00171    struct InitParams {
00172       range<float>       spike_range ; //< min and max spike rates
00173       float              direction ;   //< angle in which locust is looking
00174       const InputSource* source ;      //< from where model is getting i/p data
00175       Rectangle          rect ;        //<  source rectangle for image sources
00176       range<int>         lrf_range ;   //< angular range for LRF input sources
00177       std::string        name ;        //< name of this model's drawable
00178       Drawable::Geometry geometry ;    //< location and size of drawing area
00179 
00180       InitParams() ;
00181    } ;
00182 
00183 protected:
00184    /// A protected constructor because locust models are usually
00185    /// instantiated via a factory and config file setting. During
00186    /// initialization, derived class instances should pass in suitable
00187    /// values for the various initialization parameters using an
00188    /// InitParams structure.
00189    LocustModel(const InitParams&) ;
00190 
00191 public:
00192    /// This method triggers the LGMD computations that are to be
00193    /// performed by the locust model and caches the result internally.
00194    virtual void update() = 0 ;
00195 
00196 protected:
00197    /// Once a derived class has computed a suitable value for the LGMD
00198    /// measure, it should call this method to store that value for later
00199    /// retrieval by other parts of the Lobot/Robolocust framework.
00200    void update_lgmd(float lgmd) {
00201       m_lgmd = clamp(lgmd, m_range) ;
00202       add_spike(m_lgmd) ;
00203    }
00204 
00205 private:
00206    /// It is useful to be able to visualize the LGMD spiking activity.
00207    /// These functions and data structures are used for that purpose.
00208    //@{
00209    std::deque<float> m_spikes ;
00210 
00211    void add_spike(float) ;
00212    void render_me() ;
00213    //@}
00214 
00215 public:
00216    /// Clean-up.
00217    virtual ~LocustModel() ;
00218 } ;
00219 
00220 //-----------------------------------------------------------------------
00221 
00222 } // end of namespace encapsulating this file's definitions
00223 
00224 #endif
00225 
00226 /* So things look consistent in everyone's emacs... */
00227 /* Local Variables: */
00228 /* indent-tabs-mode: nil */
00229 /* End: */
Generated on Sun May 8 08:41:30 2011 for iLab Neuromorphic Vision Toolkit by  doxygen 1.6.3