LoSensorModel.H

Go to the documentation of this file.

/**
   \file  Robots/LoBot/tti/LoSensorModel.H
   \brief A data structure encapsulating the sensor model for Bayesian
   TTI estimation.

   This file defines a class that encapsulates the sensor model required
   to make Bayesian time-to-impact estimation work. This sensor model is
   basically a table of probabilities that describe the causal data,
   i.e., P(lgmd|tti), or, the likelihoods of seeing different LGMD values
   given different TTI values.

   The columns of the table discretize the LGMD "space" and its rows
   discretize the TTI "space." The Bayes filter works by using the column
   vector of the sensor model corresponding to the latest LGMD value as
   the P(lgmd|tti) term in the update equation.

   The sensor model's probabilities are generated by applying the
   Gabbiani LGMD model on each discretized TTI value to get the
   corresponding LGMD spike rate. These [TTI, LGMD] pairs are then used
   to find the correct bin in the table and increment it. To ensure that
   we don't have zeros in any bin, the remaining bins in the column
   corresponding to the generated LGMD value are also incremented
   according to a Gaussian weighting formula.
*/

// //////////////////////////////////////////////////////////////////// //
// The iLab Neuromorphic Vision C++ Toolkit - Copyright (C) 2000-2005   //
// by the University of Southern California (USC) and the iLab at USC.  //
// See http://iLab.usc.edu for information about this project.          //
// //////////////////////////////////////////////////////////////////// //
// Major portions of the iLab Neuromorphic Vision Toolkit are protected //
// under the U.S. patent ``Computation of Intrinsic Perceptual Saliency //
// in Visual Environments, and Applications'' by Christof Koch and      //
// Laurent Itti, California Institute of Technology, 2001 (patent       //
// pending; application number 09/912,225 filed July 23, 2001; see      //
// http://pair.uspto.gov/cgi-bin/final/home.pl for current status).     //
// //////////////////////////////////////////////////////////////////// //
// This file is part of the iLab Neuromorphic Vision C++ Toolkit.       //
//                                                                      //
// The iLab Neuromorphic Vision C++ Toolkit is free software; you can   //
// redistribute it and/or modify it under the terms of the GNU General  //
// Public License as published by the Free Software Foundation; either  //
// version 2 of the License, or (at your option) any later version.     //
//                                                                      //
// The iLab Neuromorphic Vision C++ Toolkit is distributed in the hope  //
// that it will be useful, but WITHOUT ANY WARRANTY; without even the   //
// implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR      //
// PURPOSE.  See the GNU General Public License for more details.       //
//                                                                      //
// You should have received a copy of the GNU General Public License    //
// along with the iLab Neuromorphic Vision C++ Toolkit; if not, write   //
// to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,   //
// Boston, MA 02111-1307 USA.                                           //
// //////////////////////////////////////////////////////////////////// //
//
// Primary maintainer for this file: mviswana usc edu
// $HeadURL: svn://isvn.usc.edu/software/invt/trunk/saliency/src/Robots/LoBot/tti/LoSensorModel.H $
// $Id: LoSensorModel.H 13521 2010-06-06 14:23:03Z mviswana $
//

#ifndef LOBOT_SENSOR_MODEL_DOT_H
#define LOBOT_SENSOR_MODEL_DOT_H

//------------------------------ HEADERS --------------------------------

// lobot headers
#include "Robots/LoBot/thread/LoMutex.H"
#include "Robots/LoBot/misc/singleton.hh"
#include "Robots/LoBot/util/range.hh"
#include "Robots/LoBot/util/triple.hh"

// Standard C++ headers
#include <string>
#include <deque>
#include <vector>

//----------------------------- NAMESPACE -------------------------------

namespace lobot {

//------------------------- CLASS DEFINITION ----------------------------

/**
   \class lobot::SensorModel

   \brief Data structure encapsulating sensor model required for Bayesian
   time-to-impact state estimation.

   This class implements a two-dimensional array (i.e., a table)
   containing P(lgmd|tti) probability values. The columns of this table
   correspond to different LGMD ranges; its rows to different TTI states.
   The array is stored in a single-dimensional array in column-major
   order.
*/
class SensorModel {
   // Prevent copy and assignment
   SensorModel(const SensorModel&) ;
   SensorModel& operator=(const SensorModel&) ;

   /// The basic idea behind any sort of Bayesian state estimation is to
   /// determine P(x|z), i.e., the likelihood of being in state x given a
   /// measurement z. For this to work, we will need a sensor model,
   /// viz., a table containing P(z|x), i.e., the likelihood of seeing a
   /// measurement z given that the system is in state x.
   ///
   /// The columns of the sensor model's probability table denote the
   /// different ranges of values for sensor measurements. For
   /// Robolocust, the sensor measurements are LGMD spike rates. Thus,
   /// the columns of the sensor model table will be LGMD spike rate
   /// ranges. These ranges are read from the config file and mapped to
   /// column indices using a simple linear search through the range
   /// boundaries.
   ///
   /// For example, let's say the user configures Robolocust to use LGMD
   /// ranges 0, 250, 400, 600. The m_lgmd_ranges member variable will be
   /// a list of these numbers. There will be three LGMD ranges, viz.,
   /// [0, 250), [250, 400) and [400, 600]. LGMD values in the range [0,
   /// 250) will correspond to the first column in the sensor model
   /// probability table; LGMD values in [250, 400) will pick the second
   /// column; and LGMD values in [400, 600] will pick the probability
   /// table's third column.
   std::deque<float> m_lgmd_ranges ;

   /// As mentioned above, for the Bayesian time-to-impact estimation to
   /// work, we need a table containing P(lgmd|tti) values. This table is
   /// considered to be a collection of column vectors. Each column
   /// contains the so-called causal probabilities for some range of
   /// sensor (LGMD) values.
   ///
   /// The size of each column vector will be the same as the size of the
   /// posterior probability distribution, which depends on how the TTI
   /// space has been discretized. For instance, if the TTI range is [0,
   /// 3] and the discretization step size is 0.1 seconds, then the TTI
   /// belief consists of a distribution containing 30 probabilities.
   /// Therefore, the size of each column vector in the sensor model must
   /// also be 30 elements.
   ///
   /// This data structure is used to represent the sensor model, viz., a
   /// table of probabilities stored in a single-dimensional array in
   /// column-major order.
   //@{
   typedef std::vector<float> Table ;
   Table m_prob ;
   //@}

   /// The sensor model's probability table's column vectors have to be
   /// combined with the current TTI belief in each iteration of the
   /// Bayes filter. To ensure that the filter works reasonably well
   /// without entering pathological conditions, the sensor model's
   /// column vectors should avoid having zero probabilities (extremely
   /// low likelihoods can also cause trouble due to numerical
   /// instabilities).
   ///
   /// Thus, during initialization, when we apply the Gabbiani model to
   /// obtain [TTI, LGMD] pairs that point to bins in the probability
   /// table that should be incremented, we should also update the other
   /// bins in the columns pointed to by each of the generated LGMD
   /// values by some amount. The nearby bins' increment factors are
   /// obtained using a Gaussian weighting formula.
   ///
   /// This data member stores the standard deviation of the
   /// above-mentioned Gaussian weighting formula.
   float m_sigma ;

   /// The LGMD spikes with increasing frequency as objects approach and
   /// then, right before collision, it reaches a peak and experiences a
   /// rapid die-off. Therefore, we can divide the LGMD's spike rate
   /// curve into two distinct phases, viz., LOOMING and BLANKING.
   ///
   /// It is best to have different sensor model corresponding to each of
   /// the above-mentioned phases of the LGMD input signal. Since each
   /// phase's sensor model can be parametrized differently, clients must
   /// specify the name of the LGMD signal's phase when instantiating a
   /// sensor model object. This name is used to lookup the different
   /// parameters in the config file.
   std::string m_name ;

   /// This class is designed to allow multiple threads to access its
   /// instances simultaneously. Specifically, behaviours such as
   /// lgmd_extricate_tti, which use this class indirectly via
   /// lobot::TTIEstimator, will read probabilities from the sensor
   /// model, while others such as calibrate_let will update the sensor
   /// model. This allows customizations to the Bayes filter while the
   /// robot is online.
   ///
   /// We use a mutex to ensure that one behaviour doesn't read
   /// intermediate results while another is busy writing to the sensor
   /// model.
   Mutex m_mutex ;

public:
   /// As mentioned earlier, the LGMD input signal is partitioned into
   /// two phases, viz., LOOMING and BLANKING. Robolocust uses different
   /// causal likelihood profiles for these phases. Thus, when creating a
   /// sensor model object, the client must specify the phase
   /// corresponding to this instance so that it can retrieve the correct
   /// set of parameters from the config file.
   SensorModel(const std::string& lgmd_phase) ;

   /// This method can be used to recompute the sensor model using some
   /// new value for the standard deviation of the Gaussian weighting
   /// formula used for the increment factors of each bin in the sensor
   /// model's probability table.
   ///
   /// NOTE: The standard deviation provided to this function is actually
   /// an increment factor for the current sigma value maintained
   /// internally by the sensor model object. Thus, the dsigma parameter
   /// to this function will be added to the m_sigma member variable.
   /// This design caters to a client behaviour that is specifically
   /// designed to update and visualize the available sensor models.
   void update(float dsigma) ;

private:

   /// This method increments the bin "pointed" to by the given [TTI,
   /// LGMD] pair. It also increments the other bins in the row "pointed"
   /// to by the TTI using a Gaussian weighting formula (which is what
   /// the third parameter is for) to ensure that no bin in that row has
   /// weird likelihood values that can screw up the Bayesian TTI
   /// estimation. Finally, it normalizes the row to ensure that each row
   /// vector is a valid probability distribution.
   void update_row(float tti, float lgmd, float sigma) ;

   /// This method uses the LGMD discretization to look up the column
   /// index in the probability table given an LGMD spike rate.
   int col_index(float lgmd) const ;

   /// Given a time-to-impact, this method returns the row index in the
   /// probability table using the TTI discretization parameters.
   int row_index(float tti) const {
      return static_cast<int>((tti - row_min())/row_step()) ;
   }

public:
   /// As mentioned earlier, the sensor model is a table containing
   /// causal probabilities. These methods return the sizes of this
   /// table's rows and columns and the its total size.
   //@{
   int column_size() const {return Params::belief_size()    ;}
   int row_size()    const {return m_lgmd_ranges.size() - 1 ;}
   //@}

   /// These methods return the minimum, maximum and step values
   /// associated with the discretization used on the rows (i.e., TTI
   /// values).
   //@{
   float row_min () const {return Params::tti_range().min() ;}
   float row_max () const {return Params::tti_range().max() ;}
   float row_step() const {return Params::tti_step()        ;}
   //@}

   /// Return the current value of the standard deviation used for the
   /// Gaussian weighting for neighbouring bins.
   float sigma() const {return m_sigma ;}

   /// Return the name of LGMD phase this sensor model corresponds to.
   std::string name() const {return m_name ;}

   /// This method returns an STL vector containing the column vector
   /// "pointed to" by the given LGMD value.
   std::vector<float> column_vector(float lgmd) const  ;

   /// This method returns an STL vector containing the entire table of
   /// probabilities.
   std::vector<float> table() const ;

   /// Clean-up.
   ~SensorModel() ;

private:
   /// This inner class encapsulates various parameters that can be used
   /// to tweak different aspects of the Bayesian time-to-impact
   /// estimation's sensor model.
   class Params : public singleton<Params> {
      /// To get the Bayesian time-to-impact state estimation to work, we
      /// need to discretize both TTI and LGMD values. This setting
      /// specifies the TTI discretization using three parameters, viz.,
      /// a TTI [min, max] range and a step value. For example, a triple
      /// containing [0 10 0.1] means that the time-to-impact estimates
      /// will be made in the range of zero to ten seconds in increments
      /// of a tenth of a second.
      triple<float, float, float> m_tti_discretization ;

      /// It can be cumbersome to constantly "convert" the above triple
      /// into a [min, max] range and step value. Therefore, these two
      /// member variables are used to "split" the TTI discretization
      /// into its range and step components.
      //@{
      range<float> m_tti_range ;
      float m_tti_step ;
      //@}

      /// This member variable is used to compute (once during
      /// initialization) and store the number of elements in the TTI
      /// probability distribution. It is simply the TTI range divided by
      /// the TTI step size.
      int m_belief_size ;

      /// Private constructor because this is a singleton.
      Params() ;

      // Boilerplate code to make generic singleton design pattern work
      friend class singleton<Params> ;

   public:
      /// Accessing the various parameters.
      //@{
      static range<float> tti_range() {return instance().m_tti_range   ;}
      static float tti_step()         {return instance().m_tti_step    ;}
      static int   belief_size()      {return instance().m_belief_size ;}
      //@}

      /// Clean-up.
      ~Params() ;
   } ;
} ;

//-----------------------------------------------------------------------

} // end of namespace encapsulating this file's definitions

#endif

/* So things look consistent in everyone's emacs... */
/* Local Variables: */
/* indent-tabs-mode: nil */
/* End: */