retina.hpp
Go to the documentation of this file.
1 /*#******************************************************************************
2  ** IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
3  **
4  ** By downloading, copying, installing or using the software you agree to this license.
5  ** If you do not agree to this license, do not download, install,
6  ** copy or use the software.
7  **
8  **
9  ** HVStools : interfaces allowing OpenCV users to integrate Human Vision System models. Presented models originate from Jeanny Herault's original research and have been reused and adapted by the author&collaborators for computed vision applications since his thesis with Alice Caplier at Gipsa-Lab.
10  ** Use: extract still images & image sequences features, from contours details to motion spatio-temporal features, etc. for high level visual scene analysis. Also contribute to image enhancement/compression such as tone mapping.
11  **
12  ** Maintainers : Listic lab (code author current affiliation & applications) and Gipsa Lab (original research origins & applications)
13  **
14  ** Creation - enhancement process 2007-2011
15  ** Author: Alexandre Benoit (benoit.alexandre.vision@gmail.com), LISTIC lab, Annecy le vieux, France
16  **
17  ** Theses algorithm have been developped by Alexandre BENOIT since his thesis with Alice Caplier at Gipsa-Lab (www.gipsa-lab.inpg.fr) and the research he pursues at LISTIC Lab (www.listic.univ-savoie.fr).
18  ** Refer to the following research paper for more information:
19  ** Benoit A., Caplier A., Durette B., Herault, J., "USING HUMAN VISUAL SYSTEM MODELING FOR BIO-INSPIRED LOW LEVEL IMAGE PROCESSING", Elsevier, Computer Vision and Image Understanding 114 (2010), pp. 758-773, DOI: http://dx.doi.org/10.1016/j.cviu.2010.01.011
20  ** This work have been carried out thanks to Jeanny Herault who's research and great discussions are the basis of all this work, please take a look at his book:
21  ** Vision: Images, Signals and Neural Networks: Models of Neural Processing in Visual Perception (Progress in Neural Processing),By: Jeanny Herault, ISBN: 9814273686. WAPI (Tower ID): 113266891.
22  **
23  ** The retina filter includes the research contributions of phd/research collegues from which code has been redrawn by the author :
24  ** _take a look at the retinacolor.hpp module to discover Brice Chaix de Lavarene color mosaicing/demosaicing and the reference paper:
25  ** ====> B. Chaix de Lavarene, D. Alleysson, B. Durette, J. Herault (2007). "Efficient demosaicing through recursive filtering", IEEE International Conference on Image Processing ICIP 2007
26  ** _take a look at imagelogpolprojection.hpp to discover retina spatial log sampling which originates from Barthelemy Durette phd with Jeanny Herault. A Retina / V1 cortex projection is also proposed and originates from Jeanny's discussions.
27  ** ====> more informations in the above cited Jeanny Heraults's book.
28  **
29  ** License Agreement
30  ** For Open Source Computer Vision Library
31  **
32  ** Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
33  ** Copyright (C) 2008-2011, Willow Garage Inc., all rights reserved.
34  **
35  ** For Human Visual System tools (hvstools)
36  ** Copyright (C) 2007-2011, LISTIC Lab, Annecy le Vieux and GIPSA Lab, Grenoble, France, all rights reserved.
37  **
38  ** Third party copyrights are property of their respective owners.
39  **
40  ** Redistribution and use in source and binary forms, with or without modification,
41  ** are permitted provided that the following conditions are met:
42  **
43  ** * Redistributions of source code must retain the above copyright notice,
44  ** this list of conditions and the following disclaimer.
45  **
46  ** * Redistributions in binary form must reproduce the above copyright notice,
47  ** this list of conditions and the following disclaimer in the documentation
48  ** and/or other materials provided with the distribution.
49  **
50  ** * The name of the copyright holders may not be used to endorse or promote products
51  ** derived from this software without specific prior written permission.
52  **
53  ** This software is provided by the copyright holders and contributors "as is" and
54  ** any express or implied warranties, including, but not limited to, the implied
55  ** warranties of merchantability and fitness for a particular purpose are disclaimed.
56  ** In no event shall the Intel Corporation or contributors be liable for any direct,
57  ** indirect, incidental, special, exemplary, or consequential damages
58  ** (including, but not limited to, procurement of substitute goods or services;
59  ** loss of use, data, or profits; or business interruption) however caused
60  ** and on any theory of liability, whether in contract, strict liability,
61  ** or tort (including negligence or otherwise) arising in any way out of
62  ** the use of this software, even if advised of the possibility of such damage.
63  *******************************************************************************/
64 
65 #ifndef __OPENCV_CONTRIB_RETINA_HPP__
66 #define __OPENCV_CONTRIB_RETINA_HPP__
67 
68 /*
69  * Retina.hpp
70  *
71  * Created on: Jul 19, 2011
72  * Author: Alexandre Benoit
73  */
74 
75 #include "opencv2/core/core.hpp" // for all OpenCV core functionalities access, including cv::Exception support
76 #include <valarray>
77 
78 namespace cv
79 {
80 
82 {
86 };
87 
88 class RetinaFilter;
89 
113 class CV_EXPORTS Retina {
114 
115 public:
116 
117  // parameters structure for better clarity, check explenations on the comments of methods : setupOPLandIPLParvoChannel and setupIPLMagnoChannel
119  struct OPLandIplParvoParameters{ // Outer Plexiform Layer (OPL) and Inner Plexiform Layer Parvocellular (IplParvo) parameters
121  normaliseOutput(true),
122  photoreceptorsLocalAdaptationSensitivity(0.7f),
123  photoreceptorsTemporalConstant(0.5f),
124  photoreceptorsSpatialConstant(0.53f),
125  horizontalCellsGain(0.0f),
126  hcellsTemporalConstant(1.f),
127  hcellsSpatialConstant(7.f),
128  ganglionCellsSensitivity(0.7f){};// default setup
129  bool colorMode, normaliseOutput;
130  float photoreceptorsLocalAdaptationSensitivity, photoreceptorsTemporalConstant, photoreceptorsSpatialConstant, horizontalCellsGain, hcellsTemporalConstant, hcellsSpatialConstant, ganglionCellsSensitivity;
131  };
132  struct IplMagnoParameters{ // Inner Plexiform Layer Magnocellular channel (IplMagno)
134  normaliseOutput(true),
135  parasolCells_beta(0.f),
136  parasolCells_tau(0.f),
137  parasolCells_k(7.f),
138  amacrinCellsTemporalCutFrequency(1.2f),
139  V0CompressionParameter(0.95f),
140  localAdaptintegration_tau(0.f),
141  localAdaptintegration_k(7.f){};// default setup
142  bool normaliseOutput;
143  float parasolCells_beta, parasolCells_tau, parasolCells_k, amacrinCellsTemporalCutFrequency, V0CompressionParameter, localAdaptintegration_tau, localAdaptintegration_k;
144  };
145  struct OPLandIplParvoParameters OPLandIplParvo;
146  struct IplMagnoParameters IplMagno;
147  };
148 
153  Retina(Size inputSize);
154 
164  Retina(Size inputSize, const bool colorMode, RETINA_COLORSAMPLINGMETHOD colorSamplingMethod=RETINA_COLOR_BAYER, const bool useRetinaLogSampling=false, const double reductionFactor=1.0, const double samplingStrenght=10.0);
165 
166  virtual ~Retina();
167 
171  Size inputSize();
172 
176  Size outputSize();
177 
185  void setup(std::string retinaParameterFile="", const bool applyDefaultSetupOnFailure=true);
186 
187 
195  void setup(cv::FileStorage &fs, const bool applyDefaultSetupOnFailure=true);
196 
204  void setup(RetinaParameters newParameters);
205 
209  Retina::RetinaParameters getParameters();
210 
215  const std::string printSetup();
216 
221  virtual void write( std::string fs ) const;
222 
223 
228  virtual void write( FileStorage& fs ) const;
229 
245  void setupOPLandIPLParvoChannel(const bool colorMode=true, const bool normaliseOutput = true, const float photoreceptorsLocalAdaptationSensitivity=0.7, const float photoreceptorsTemporalConstant=0.5, const float photoreceptorsSpatialConstant=0.53, const float horizontalCellsGain=0, const float HcellsTemporalConstant=1, const float HcellsSpatialConstant=7, const float ganglionCellsSensitivity=0.7);
246 
259  void setupIPLMagnoChannel(const bool normaliseOutput = true, const float parasolCells_beta=0, const float parasolCells_tau=0, const float parasolCells_k=7, const float amacrinCellsTemporalCutFrequency=1.2, const float V0CompressionParameter=0.95, const float localAdaptintegration_tau=0, const float localAdaptintegration_k=7);
260 
265  void run(const Mat &inputImage);
266 
271  void getParvo(Mat &retinaOutput_parvo);
272 
277  void getParvo(std::valarray<float> &retinaOutput_parvo);
278 
283  void getMagno(Mat &retinaOutput_magno);
284 
289  void getMagno(std::valarray<float> &retinaOutput_magno);
290 
291  // original API level data accessors : get buffers addresses...
292  const std::valarray<float> & getMagno() const;
293  const std::valarray<float> & getParvo() const;
294 
301  void setColorSaturation(const bool saturateColors=true, const float colorSaturationValue=4.0);
302 
306  void clearBuffers();
307 
312  void activateMovingContoursProcessing(const bool activate);
313 
318  void activateContoursProcessing(const bool activate);
319 
320 protected:
321  // Parameteres setup members
322  RetinaParameters _retinaParameters; // structure of parameters
323 
324  // Retina model related modules
325  std::valarray<float> _inputBuffer;
326 
327  // pointer to retina model
328  RetinaFilter* _retinaFilter;
329 
338  void _convertValarrayBuffer2cvMat(const std::valarray<float> &grayMatrixToConvert, const unsigned int nbRows, const unsigned int nbColumns, const bool colorMode, Mat &outBuffer);
339 
346  bool _convertCvMat2ValarrayBuffer(const cv::Mat inputMatToConvert, std::valarray<float> &outputValarrayMatrix);
347 
349  void _init(const Size inputSize, const bool colorMode, RETINA_COLORSAMPLINGMETHOD colorSamplingMethod=RETINA_COLOR_BAYER, const bool useRetinaLogSampling=false, const double reductionFactor=1.0, const double samplingStrenght=10.0);
350 
351 
352 };
353 
354 }
355 #endif /* __OPENCV_CONTRIB_RETINA_HPP__ */
color sampling is RGBRGBRGB..., line 2 BRGBRGBRG..., line 3, GBRGBRGBR...
Definition: retina.hpp:84
std::valarray< float > _inputBuffer
buffer used to convert input cv::Mat to internal retina buffers format (valarrays) ...
Definition: retina.hpp:325
RetinaParameters _retinaParameters
Definition: retina.hpp:322
each pixel position is either R, G or B in a random choice
Definition: retina.hpp:83
Definition: retina.hpp:113
CV_EXPORTS_W void write(FileStorage &fs, const string &name, int value)
RETINA_COLORSAMPLINGMETHOD
Definition: retina.hpp:81
The 2D size class.
Definition: core.hpp:81
RetinaFilter * _retinaFilter
the pointer to the retina module, allocated with instance construction
Definition: retina.hpp:328
XML/YAML File Storage Class.
Definition: core.hpp:4040
The Core Functionality.
The n-dimensional matrix class.
Definition: core.hpp:1688
float photoreceptorsTemporalConstant
Definition: retina.hpp:130
standard bayer sampling
Definition: retina.hpp:85
true
Definition: color.hpp:221
float V0CompressionParameter
Definition: retina.hpp:143
GLclampf f
IplMagnoParameters()
Definition: retina.hpp:133
Definition: retina.hpp:118