ArrayCreator.H

Go to the documentation of this file.
00001 /** @file Psycho/ArrayCreator.H create search arrays */
00002 
00003 // //////////////////////////////////////////////////////////////////// //
00004 // The iLab Neuromorphic Vision C++ Toolkit - Copyright (C) 2000-2005   //
00005 // by the 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: David J Berg <dberg@usc.edu>
00034 // $HeadURL: svn://isvn.usc.edu/software/invt/trunk/saliency/src/Psycho/ArrayCreator.H $
00035 
00036 
00037 #ifndef PSYCHO_ARRAYCREATOR_H_DEFINED
00038 #define PSYCHO_ARRAYCREATOR_H_DEFINED
00039 
00040 #include "Image/Image.H"
00041 #include "Image/Pixels.H"
00042 #include "Image/vec2.h"
00043 #include "rutz/rand.h"
00044 
00045 #include <string>
00046 #include <vector>
00047 
00048 struct ModelOptionCateg;
00049 struct ModelOptionDef;
00050 
00051 // ######################################################################
00052 //! Command line options that could be used with the ArrayCreator object
00053 // ######################################################################
00054 //@{
00055 
00056 //! ArrayCreator options
00057 extern const ModelOptionCateg MOC_PSYCHOARRAYCREATOR;
00058 
00059 extern const ModelOptionDef OPT_ACFileName;
00060 extern const ModelOptionDef OPT_ACItemRadius;
00061 extern const ModelOptionDef OPT_ACJitterLevel;
00062 extern const ModelOptionDef OPT_ACBackgroundColor;
00063 extern const ModelOptionDef OPT_ACPpdX;
00064 extern const ModelOptionDef OPT_ACPpdY;
00065 extern const ModelOptionDef OPT_ACPermuteTargs;
00066 //@}
00067 
00068 // ######################################################################
00069 // Some enumerated types for convenience. One for the item type -
00070 // circle, bars, etc... and one for the colorspace - RGB, HSV,
00071 // DKL
00072 // ######################################################################
00073 enum ItemType {BARV, BARH, CIRCLE, SQUARE, BLOB}; //different item types
00074 
00075 //! Dims overload: format is "<ItemType>"
00076 std::string convertToString(const ItemType& itemtype);
00077 
00078 //! Dims overload: format is "<ItemType>"
00079 void convertFromString(const std::string& str,  ItemType& itemtype);
00080 
00081 enum ColorSpace {RGB, HSV, DKL}; //different color spaces
00082 
00083 //! Dims overload: format is "<ColorSpace>"
00084 std::string convertToString(const ColorSpace& colorspace);
00085 
00086 //! Dims overload: format is "<ColorSpace>"
00087 void convertFromString(const std::string& str,  ColorSpace& colorspace);
00088 
00089 // ######################################################################
00090 // ArrayItem: A template class to hold information about an array
00091 // item, which contains information about shape, position (pixels),
00092 // size(pixels), color, and orientation(degrees). The template
00093 // parameter is the type of pixel.
00094 // ######################################################################
00095 class ArrayItem
00096 {
00097 public:
00098   //constructor for template type T, which must be a pixel type
00099   template <typename PIXEL_TYPE>
00100   ArrayItem(const uint xpos, const uint ypos, const uint radius,
00101             const PIXEL_TYPE& color, const float& orientation);
00102 
00103   //virtual destructor for propper inheritance
00104   virtual ~ArrayItem();
00105 
00106   //draw the item on an image
00107   virtual void drawItem(Image<PixRGB<byte> >& dst) const = 0;
00108 
00109   //get the name of the shape
00110   virtual std::string getShapeName() const = 0;
00111 
00112   //!display internal information as a string
00113   std::string toString() const;
00114 protected:
00115   //accessor functions
00116   const geom::vec2<uint>& getPos() const {return itsPos;};
00117   const uint getRad() const {return itsRad;};
00118   const PixRGB<byte>& getCol() const {return itsCol;};
00119   const float& getOrient() const {return itsOrient;};
00120 
00121 private:
00122   geom::vec2<uint> itsPos;//position
00123   uint itsRad; //radius in pixels of longest axis of item
00124   PixRGB<byte> itsCol;//color of shape
00125   float itsOrient; //orientation in degrees of longest axis
00126 };
00127 
00128 // ######################################################################
00129 // Classes for different array item shapes. This includes oriented
00130 // bar, filled circle, square, gaussian blob.
00131 // ######################################################################
00132 class BarItem : public ArrayItem
00133 {
00134 public:
00135   template <class PIXEL_TYPE>
00136   BarItem(const uint xpos, const uint ypos, const uint radius,
00137           const PIXEL_TYPE& color, const float& orientation);
00138   ~BarItem();
00139   std::string getShapeName() const;
00140   void drawItem(Image<PixRGB<byte> >& dst) const;
00141 };
00142 
00143 // ######################################################################
00144 class CircleItem : public ArrayItem
00145 {
00146 public:
00147   template <class PIXEL_TYPE>
00148   CircleItem(const uint xpos, const uint ypos, const uint radius,
00149              const PIXEL_TYPE& color, const float& orientation);
00150   ~CircleItem();
00151   std::string getShapeName() const;
00152   void drawItem(Image<PixRGB<byte> >& dst) const;
00153 };
00154 
00155 // ######################################################################
00156 class SquareItem : public ArrayItem
00157 {
00158 public:
00159   template <class PIXEL_TYPE>
00160   SquareItem(const uint xpos, const uint ypos, const uint radius,
00161              const PIXEL_TYPE& color, const float& orientation);
00162   ~SquareItem();
00163   std::string getShapeName() const;
00164   void drawItem(Image<PixRGB<byte> >& dst) const;
00165 };
00166 
00167 // ######################################################################
00168 class BlobItem : public ArrayItem
00169 {
00170 public:
00171   template <class PIXEL_TYPE>
00172   BlobItem(const uint xpos, const uint ypos, const uint radius,
00173            const PIXEL_TYPE& color, const float& orientation);
00174   ~BlobItem();
00175   std::string getShapeName() const;
00176   void drawItem(Image<PixRGB<byte> >& dst) const;
00177 };
00178 
00179 // ######################################################################
00180 // ArrayCreator: A class for creating search arrays where targets may
00181 // appear in the receptive fields of multiple cells being recorded
00182 // simultaneosly. All possible combinations of target in receptive
00183 // field of 1, 2 ... N of the cells, and any additional conditions
00184 // where the target is outside the RF (possibly with other targets in
00185 // the cells RF). For each of these conditions we will perform
00186 // counterbalanced presentations where the target and distractor are
00187 // different colors (including intensity), density and shape. The
00188 // distractor positions are randomized every trial. This parameters
00189 // are stored in a text file, see parseFile below for the
00190 // format. Radius and noise are in degrees of visual angle.
00191 // ######################################################################
00192 class ArrayCreator
00193 {
00194 public:
00195   //!constructor
00196   ArrayCreator(const std::string& filename, //config file name
00197                const float& radius,  // radius of stimuli in degrees
00198                const float& noise,  //maximum noise in degrees
00199                const Dims& dims, //dimensions of image in pixels
00200                const float& ppdx, //pixels per degree fo visual angle x
00201                const float& ppdy,//pixels per degree fo visual angle y 
00202                const PixRGB<byte>& background, //background color
00203                const float& fixation_size,
00204                const bool permTargs = true);
00205 
00206   //!destructor
00207   ~ArrayCreator();
00208 
00209   //!get the total number of stims
00210   uint size() const;
00211 
00212   //! draw the specified array in the permutation sequence
00213   Image<PixRGB<byte> > draw(const uint permnum) const;
00214 
00215   //! draw the specified array in the permutation sequence
00216   void draw(Image<PixRGB<byte> >& dst, const uint permnum) const;
00217 
00218   //! Write out our whole array as a string. First we will have a ':'
00219   //seperated list describing the condition, with the following
00220   //format: <#RF targets>:<#Other targets>:<target color>:<distractor
00221   //color>:<target shape>:<distractor shape>:<distractor set size>
00222   //
00223   //The next section will be seperated by a '::', and will contain
00224   //information about each item in the array. Items will be seperated
00225   //by '::'. The format goes like this: <item type (RF, OT,
00226   //D)>:<position x>:<position y>:<radius>:<rgb color>:<orientation>
00227   std::string toString(const uint permnum) const;
00228 
00229 private:
00230   //!Parse a file to get receptive field positions, distractor
00231   //!densities, color, and shape conditions. The format goes like
00232   //!this:
00233 
00234   //1: The first lines should all be receptive fields locations where
00235   //targts are to be presented (or other locations you want targets to
00236   //be presented). A RF size of zero indicates that the position will
00237   //have a target, but that it is not actually a cell's RF. Although
00238   //this is not needed to create the conditions, it is useful to have
00239   //in the descriptive string. These will be counter balanced with all
00240   //possible subset combinations of RF's with/without target (see
00241   //computeSequence below). One line for each space seperated by ','
00242   //Ex "x,y,size"
00243 
00244   //2: Colors (could also be a contrast change of course) to be used
00245   //for targets and distractors in either RGB, HSV, or DKL
00246   //space. First put the type 'T' for target, and 'D' for
00247   //distractor. ':' and then the colorspace followed by a ':' and a
00248   //comma seperated list of color space components. Multiple color
00249   //conditions should be sperated by spaces. Target colors will
00250   //be counter balanced between the target on/of position. So that
00251   //every RF position will get to be a target of a given color, while
00252   //all other RF positions will be targets of a different color
00253   //Ex: "T:RGB:r,g,b T:RGB:r,g,b D:DKL:d,k,l"
00254 
00255   //3: Distractor set size in space seperated list. Ex 0 1 3 5 10
00256 
00257   //4: Shape conditions using the enum data type labels above. Pairs
00258   //can be defined by a '-' seperated list. Each pair will be counter
00259   //balanced so each one is a target and one a distractor. If pairs
00260   //are not used, the target and distractor will be rendered the same
00261   //shape in that condition. Seperate shape conditions are sperated by
00262   //spaces Ex "CIRCLE-SQUARE BLOB"
00263   void parseFile(const std::string& file);
00264 
00265   //!simple helper function to read lines without comments
00266   std::string readLine(std::ifstream& fs);
00267 
00268   //!Compute an internal list of all possible permutations of all
00269   //!conditions, counterbalanced.
00270   //
00271   //First, compute all the 'itsRF.size() choose ii' permutations
00272   //(without repeats, ie 1-2 = 2-1), for all ii = 0:itsRF.size(). We
00273   //are going to select all the combinations of ii members of the set
00274   //with size itsRF.size() and store them in one large vector. This
00275   //will give us all the possible combintations of RF on/off locations
00276   //for all RF's (and any other locations we added in the RF section
00277   //of the text file)
00278   //
00279   //Next, for all of these conditions compute all the possible target
00280   //color and target-distractor color combinations from the color
00281   //conditions list. If two targets are defined, then Next, add in all
00282   //the possible distractor density conditions. Finally, for the Shape
00283   //condition, target and distractor are only created with paired '-'
00284   //shapes from the config file. Otherwise, target and distractor will
00285   //be of the same shape.
00286   //
00287   void computeSequence();
00288 
00289   //!A recursive funcion to compute all the N choose K subsets
00290   //!(without repeats, ie consider 1,2 and 2,1 the same subset of
00291   //!N choose 2) For K = 1...N
00292   void subset(std::vector<std::vector<int> >& sub, const uint N);
00293 
00294   //Generate a list of points for possible distractors. Grid locations
00295   //closest to the targets are not considered. The grid is designed at
00296   //maximum density given the current radius.
00297   std::vector<geom::vec2<uint> > getGrid(const std::vector<int>& onpos);
00298 
00299   //create an array item from an ItemType
00300   ArrayItem* createItem(const ItemType item, const geom::vec2<uint>& pos,
00301                         const PixRGB<byte>& color);
00302 
00303   struct RF
00304   {
00305     geom::vec2<uint> pos; //position
00306     float size; //size in degrees
00307   };
00308 
00309   //to store infor about our different conditions from file.
00310   std::vector<RF> itsRF;
00311   std::vector<PixRGB<byte> > itsColT, itsColD;
00312   std::vector<uint> itsDist;
00313   std::vector<std::vector<ItemType> > itsShape;
00314 
00315   //store our list of created stims and informative strings
00316   std::vector<std::vector<ArrayItem*> > itsStims;
00317   std::vector<std::string> itsDescr;
00318 
00319   //for default values
00320   Dims itsDims;
00321   float itsRad, itsNoise, itsPpdx, itsPpdy, itsPpd;
00322   PixRGB<byte> itsBackgroundColor;
00323   float itsFixSize;
00324   rutz::urand rnum;
00325   bool itsPermTargs;
00326 };
00327 
00328 // ######################################################################
00329 /* So things look consistent in everyone's emacs... */
00330 /* Local Variables: */
00331 /* mode: c++ */
00332 /* indent-tabs-mode: nil */
00333 /* End: */
00334 
00335 #endif // PSYCHO_ARRAYCREATOR_H_DEFINED
Generated on Sun May 8 08:41:12 2011 for iLab Neuromorphic Vision Toolkit by  doxygen 1.6.3