Merge pull request #223 from albenoit/master

Added python support, updated Retina class documentation

modules/bioinspired/CMakeLists.txt

 set(the_description "Biologically inspired algorithms")
 ocv_warnings_disable(CMAKE_CXX_FLAGS -Wundef)
-ocv_define_module(bioinspired opencv_core OPTIONAL opencv_highgui opencv_ocl WRAP java)
+ocv_define_module(bioinspired opencv_core OPTIONAL opencv_highgui opencv_ocl WRAP java python)

modules/bioinspired/README.md

 Biologically inspired vision models and derivated tools
 =======================================================
+
+1. A biological retina model for image spatio-temporal noise and luminance changes enhancement
+2. A transient areas (spatio-temporal events) segmentation tool to use at the output of the Retina
+3. High Dynamic Range (HDR >8bit images) tone mapping to (conversion to 8bit) use cas of the retina  

modules/bioinspired/doc/bioinspired.bib

@@ -9,6 +9,15 @@
   publisher={Elsevier}
 }
 
+@INPROCEEDINGS{Benoit2014,
+  author={Strat, S.T. and Benoit, A. and Lambert, P.}, 
+  booktitle={Signal Processing Conference (EUSIPCO), 2014 Proceedings of the 22nd European}, 
+  title={Retina enhanced bag of words descriptors for video classification}, 
+  year={2014}, 
+  month={Sept}, 
+  pages={1307-1311}
+}
+
 @inproceedings{Strat2013,
   title={Retina enhanced SIFT descriptors for video indexing},
   author={Strat, Sabin Tiberius and Benoit, Alexandre and Lambert, Patrick},

modules/bioinspired/include/opencv2/bioinspired/transientareassegmentationmodule.hpp

@@ -12,12 +12,12 @@
  **
  ** Maintainers : Listic lab (code author current affiliation & applications)
  **
- **  Creation - enhancement process 2007-2013
+ **  Creation - enhancement process 2007-2015
  **      Author: Alexandre Benoit (benoit.alexandre.vision@gmail.com), LISTIC lab, Annecy le vieux, France
  **
  ** 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).
  ** Refer to the following research paper for more information:
- ** Strat S. T. , Benoit A.Lambert P. , Caplier A., "Retina Enhanced SURF Descriptors for Spatio-Temporal Concept Detection", Multimedia Tools and Applications, 2012 (DOI: 10.1007/s11042-012-1280-0)
+ ** Strat, S.T.; Benoit, A.; Lambert, P., "Retina enhanced bag of words descriptors for video classification," Signal Processing Conference (EUSIPCO), 2014 Proceedings of the 22nd European , vol., no., pp.1307,1311, 1-5 Sept. 2014 (http://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=6952461&isnumber=6951911)
  ** 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
  ** 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:
  ** 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.
@@ -30,7 +30,7 @@
  ** Copyright (C) 2008-2011, Willow Garage Inc., all rights reserved.
  **
  **               For Human Visual System tools (bioinspired)
- ** Copyright (C) 2007-2011, LISTIC Lab, Annecy le Vieux and GIPSA Lab, Grenoble, France, all rights reserved.
+ ** Copyright (C) 2007-2015, LISTIC Lab, Annecy le Vieux and GIPSA Lab, Grenoble, France, all rights reserved.
  **
  ** Third party copyrights are property of their respective owners.
  **
@@ -74,10 +74,37 @@ namespace cv
 {
 namespace bioinspired
 {
-
 //! @addtogroup bioinspired
 //! @{
 
+/** @brief parameter structure that stores the transient events detector setup parameters
+*/
+struct SegmentationParameters{ // CV_EXPORTS_W_MAP to export to python native dictionnaries
+	// default structure instance construction with default values	
+	SegmentationParameters():
+	    thresholdON(100),
+	    thresholdOFF(100),
+	    localEnergy_temporalConstant(0.5),
+	    localEnergy_spatialConstant(5),
+	    neighborhoodEnergy_temporalConstant(1),
+	    neighborhoodEnergy_spatialConstant(15),
+	    contextEnergy_temporalConstant(1),
+	    contextEnergy_spatialConstant(75){};
+	// all properties list
+	float thresholdON;
+	float thresholdOFF;
+	//! the time constant of the first order low pass filter, use it to cut high temporal frequencies (noise or fast motion), unit is frames, typical value is 0.5 frame
+	float localEnergy_temporalConstant;
+	//! the spatial constant of the first order low pass filter, use it to cut high spatial frequencies (noise or thick contours), unit is pixels, typical value is 5 pixel
+	float localEnergy_spatialConstant;
+	//! local neighborhood energy filtering parameters : the aim is to get information about the energy neighborhood to perform a center surround energy analysis
+	float neighborhoodEnergy_temporalConstant;
+	float neighborhoodEnergy_spatialConstant;
+	//! context neighborhood energy filtering parameters : the aim is to get information about the energy on a wide neighborhood area to filtered out local effects
+	float contextEnergy_temporalConstant;
+	float contextEnergy_spatialConstant;
+};
+
 /** @brief class which provides a transient/moving areas segmentation module
 
 perform a locally adapted segmentation by using the retina magno input data Based on Alexandre
@@ -96,30 +123,6 @@ class CV_EXPORTS_W TransientAreasSegmentationModule: public Algorithm
 {
 public:
 
-    //! parameters structure
-    struct CV_EXPORTS_W SegmentationParameters{
-        SegmentationParameters():
-            thresholdON(100),
-            thresholdOFF(100),
-            localEnergy_temporalConstant(0.5),
-            localEnergy_spatialConstant(5),
-            neighborhoodEnergy_temporalConstant(1),
-            neighborhoodEnergy_spatialConstant(15),
-            contextEnergy_temporalConstant(1),
-            contextEnergy_spatialConstant(75){};// default setup
-        CV_PROP_RW float thresholdON;
-        CV_PROP_RW float thresholdOFF;
-        //! the time constant of the first order low pass filter, use it to cut high temporal frequencies (noise or fast motion), unit is frames, typical value is 0.5 frame
-        CV_PROP_RW float localEnergy_temporalConstant;
-        //! the spatial constant of the first order low pass filter, use it to cut high spatial frequencies (noise or thick contours), unit is pixels, typical value is 5 pixel
-        CV_PROP_RW float localEnergy_spatialConstant;
-        //! local neighborhood energy filtering parameters : the aim is to get information about the energy neighborhood to perform a center surround energy analysis
-        CV_PROP_RW float neighborhoodEnergy_temporalConstant;
-        CV_PROP_RW float neighborhoodEnergy_spatialConstant;
-        //! context neighborhood energy filtering parameters : the aim is to get information about the energy on a wide neighborhood area to filtered out local effects
-        CV_PROP_RW float contextEnergy_temporalConstant;
-        CV_PROP_RW float contextEnergy_spatialConstant;
-    };
 
     /** @brief return the sze of the manage input and output images
     */
@@ -141,7 +144,7 @@ public:
     @param fs : the open Filestorage which contains segmentation parameters
     @param applyDefaultSetupOnFailure : set to true if an error must be thrown on error
     */
-    CV_WRAP virtual void setup(cv::FileStorage &fs, const bool applyDefaultSetupOnFailure=true)=0;
+    virtual void setup(cv::FileStorage &fs, const bool applyDefaultSetupOnFailure=true)=0;
 
     /** @brief try to open an XML segmentation parameters file to adjust current segmentation instance setup
 
@@ -149,11 +152,11 @@ public:
     - warning, Exceptions are thrown if read XML file is not valid
     @param newParameters : a parameters structures updated with the new target configuration
      */
-    CV_WRAP virtual void setup(SegmentationParameters newParameters)=0;
+    virtual void setup(SegmentationParameters newParameters)=0;
 
     /** @brief return the current parameters setup
     */
-    CV_WRAP virtual SegmentationParameters getParameters()=0;
+    virtual SegmentationParameters getParameters()=0;
 
     /** @brief parameters setup display method
     @return a string which contains formatted parameters information
@@ -168,7 +171,7 @@ public:
     /** @brief write xml/yml formated parameters information
     @param fs : a cv::Filestorage object ready to be filled
     */
-    CV_WRAP virtual void write( cv::FileStorage& fs ) const=0;
+    virtual void write( cv::FileStorage& fs ) const=0;
 
     /** @brief main processing method, get result using methods getSegmentationPicture()
     @param inputToSegment : the image to process, it must match the instance buffer size !

modules/bioinspired/samples/basicRetina.cpp

+//============================================================================
+// Name        : retinademo.cpp
+// Author      : Alexandre Benoit, benoit.alexandre.vision@gmail.com
+// Version     : 0.1
+// Copyright   : LISTIC/GIPSA French Labs, May 2015
+// Description : Gipsa/LISTIC Labs quick retina demo in C++, Ansi-style
+//============================================================================
+
+// include bioinspired module and OpenCV core utilities
+#include "opencv2/bioinspired.hpp"
+#include "opencv2/imgcodecs.hpp"
+#include "opencv2/videoio.hpp"
+#include "opencv2/highgui.hpp"
+#include <iostream>
+#include <cstring>
+
+// main function
+int main(int argc, char* argv[]) {
+
+  // basic input arguments checking
+  if (argc>1)
+  {
+        std::cout<<"****************************************************"<<std::endl;
+	std::cout<<"* Retina demonstration : demonstrates the use of is a wrapper class of the Gipsa/Listic Labs retina model."<<std::endl;
+	std::cout<<"* This retina model allows spatio-temporal image processing (applied on a webcam sequences)."<<std::endl;
+	std::cout<<"* As a summary, these are the retina model properties:"<<std::endl;
+	std::cout<<"* => It applies a spectral whithening (mid-frequency details enhancement)"<<std::endl;
+	std::cout<<"* => high frequency spatio-temporal noise reduction"<<std::endl;
+	std::cout<<"* => low frequency luminance to be reduced (luminance range compression)"<<std::endl;
+	std::cout<<"* => local logarithmic luminance compression allows details to be enhanced in low light conditions\n"<<std::endl;
+	std::cout<<"* for more information, reer to the following papers :"<<std::endl;
+	std::cout<<"* 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"<<std::endl;
+	std::cout<<"* 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."<<std::endl;
+	std::cout<<"* => reports comments/remarks at benoit.alexandre.vision@gmail.com"<<std::endl;
+	std::cout<<"* => more informations and papers at : http://sites.google.com/site/benoitalexandrevision/"<<std::endl;
+	std::cout<<"****************************************************"<<std::endl;
+	std::cout<<" NOTE : this program generates the default retina parameters file 'RetinaDefaultParameters.xml'"<<std::endl;
+	std::cout<<" => you can use this to fine tune parameters and load them if you save to file 'RetinaSpecificParameters.xml'"<<std::endl;
+       
+        if (strcmp(argv[1],  "help")==0){
+	    std::cout<<"No help provided for now, please test the retina Demo for a more complete program"<<std::endl;
+        }
+  }
+
+  std::string inputMediaType=argv[1];
+  // declare the retina input buffer.
+  cv::Mat inputFrame;
+  // setup webcam reader and grab a first frame to get its size
+  cv::VideoCapture videoCapture(0); 
+  videoCapture>>inputFrame;
+
+  // allocate a retina instance with input size equal to the one of the loaded image
+  cv::Ptr<cv::bioinspired::Retina> myRetina = cv::bioinspired::createRetina(inputFrame.size());
+
+  /* retina parameters management methods use sample
+     -> save current (here default) retina parameters to a xml file (you may use it only one time to get the file and modify it)
+  */
+  myRetina->write("RetinaDefaultParameters.xml");
+
+  // -> load parameters if file exists
+  myRetina->setup("RetinaSpecificParameters.xml");
+
+  // reset all retina buffers (open your eyes)  
+  myRetina->clearBuffers();
+
+  // declare retina output buffers
+  cv::Mat retinaOutput_parvo;
+  cv::Mat retinaOutput_magno;
+
+  //main processing loop
+  bool stillProcess=true;
+  while(stillProcess){
+	
+	// if using video stream, then, grabbing a new frame, else, input remains the same
+	if (videoCapture.isOpened())
+		videoCapture>>inputFrame;
+        else
+		stillProcess=false;
+	// run retina filter
+	myRetina->run(inputFrame);
+	// Retrieve and display retina output
+	myRetina->getParvo(retinaOutput_parvo);
+	myRetina->getMagno(retinaOutput_magno);
+	cv::imshow("retina input", inputFrame);
+	cv::imshow("Retina Parvo", retinaOutput_parvo);
+	cv::imshow("Retina Magno", retinaOutput_magno);
+
+	cv::waitKey(5);
+  }
+
+}

modules/bioinspired/src/transientareassegmentationmodule.cpp

@@ -12,12 +12,12 @@
  **
  ** Maintainers : Listic lab (code author current affiliation & applications)
  **
- **  Creation - enhancement process 2007-2013
+ **  Creation - enhancement process 2007-2015
  **      Author: Alexandre Benoit (benoit.alexandre.vision@gmail.com), LISTIC lab, Annecy le vieux, France
  **
  ** 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).
  ** Refer to the following research paper for more information:
- ** Strat S. T. , Benoit A.Lambert P. , Caplier A., "Retina Enhanced SURF Descriptors for Spatio-Temporal Concept Detection", Multimedia Tools and Applications, 2012 (DOI: 10.1007/s11042-012-1280-0)
+ ** Strat, S.T.; Benoit, A.; Lambert, P., "Retina enhanced bag of words descriptors for video classification," Signal Processing Conference (EUSIPCO), 2014 Proceedings of the 22nd European , vol., no., pp.1307,1311, 1-5 Sept. 2014 (http://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=6952461&isnumber=6951911)
  ** 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
  ** 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:
  ** 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.
@@ -30,7 +30,7 @@
  ** Copyright (C) 2008-2011, Willow Garage Inc., all rights reserved.
  **
  **               For Human Visual System tools (bioinspired)
- ** Copyright (C) 2007-2011, LISTIC Lab, Annecy le Vieux and GIPSA Lab, Grenoble, France, all rights reserved.
+ ** Copyright (C) 2007-2015, LISTIC Lab, Annecy le Vieux and GIPSA Lab, Grenoble, France, all rights reserved.
  **
  ** Third party copyrights are property of their respective owners.
  **
@@ -132,12 +132,12 @@ public:
      * @param newParameters : a parameters structures updated with the new target configuration
      * @param applyDefaultSetupOnFailure : set to true if an error must be thrown on error
      */
-    void setup(TransientAreasSegmentationModule::SegmentationParameters newParameters);
+    void setup(SegmentationParameters newParameters);
 
     /**
      * @return the current parameters setup
      */
-    struct TransientAreasSegmentationModule::SegmentationParameters getParameters();
+    struct SegmentationParameters getParameters();
 
     /**
      * parameters setup display method
@@ -203,7 +203,7 @@ protected:
      */
     inline const std::valarray<float> &getMotionContextPicture() const {return _contextMotionEnergy;};
 
-    struct cv::bioinspired::TransientAreasSegmentationModule::SegmentationParameters _segmentationParameters;
+    struct cv::bioinspired::SegmentationParameters _segmentationParameters;
     // template buffers and related acess pointers
     std::valarray<float> _inputToSegment;
     std::valarray<float> _contextMotionEnergy;
@@ -221,7 +221,7 @@ protected:
     void _convertValarrayBuffer2cvMat(const std::valarray<bool> &grayMatrixToConvert, const unsigned int nbRows, const unsigned int nbColumns, OutputArray outBuffer);
     bool _convertCvMat2ValarrayBuffer(InputArray inputMat, std::valarray<float> &outputValarrayMatrix);
 	
-	const TransientAreasSegmentationModuleImpl & operator = (const TransientAreasSegmentationModuleImpl &);
+    const TransientAreasSegmentationModuleImpl & operator = (const TransientAreasSegmentationModuleImpl &);
 };
 
 class TransientAreasSegmentationModuleImpl_: public  TransientAreasSegmentationModule
@@ -232,9 +232,9 @@ public:
     inline virtual void write( cv::FileStorage& fs ) const{_segmTool.write(fs);};
     inline virtual void setup(String segmentationParameterFile, const bool applyDefaultSetupOnFailure){_segmTool.setup(segmentationParameterFile, applyDefaultSetupOnFailure);};
     inline virtual void setup(cv::FileStorage &fs, const bool applyDefaultSetupOnFailure){_segmTool.setup(fs, applyDefaultSetupOnFailure);};
-    inline virtual void setup(TransientAreasSegmentationModule::SegmentationParameters newParameters){_segmTool.setup(newParameters);};
+    inline virtual void setup(SegmentationParameters newParameters){_segmTool.setup(newParameters);};
     inline virtual const String printSetup(){return _segmTool.printSetup();};
-    inline virtual struct TransientAreasSegmentationModule::SegmentationParameters getParameters(){return _segmTool.getParameters();};
+    inline virtual struct SegmentationParameters getParameters(){return _segmTool.getParameters();};
     inline virtual void write( String fs ) const{_segmTool.write(fs);};
     inline virtual void run(InputArray inputToSegment, const int channelIndex){_segmTool.run(inputToSegment, channelIndex);};
     inline virtual void getSegmentationPicture(OutputArray transientAreas){return _segmTool.getSegmentationPicture(transientAreas);};
@@ -286,7 +286,7 @@ void TransientAreasSegmentationModuleImpl::clearAllBuffers()
     _segmentedAreas=0;
 }
 
-struct TransientAreasSegmentationModule::SegmentationParameters TransientAreasSegmentationModuleImpl::getParameters()
+struct SegmentationParameters TransientAreasSegmentationModuleImpl::getParameters()
 {
 	return _segmentationParameters;
 };
@@ -305,7 +305,7 @@ void TransientAreasSegmentationModuleImpl::setup(String segmentationParameterFil
         if (applyDefaultSetupOnFailure)
         {
            printf("Retina::setup: resetting retina with default parameters\n");
-            cv::bioinspired::TransientAreasSegmentationModule::SegmentationParameters defaults;
+            cv::bioinspired::SegmentationParameters defaults;
             setup(defaults);
         }
         else
@@ -344,7 +344,7 @@ void TransientAreasSegmentationModuleImpl::setup(cv::FileStorage &fs, const bool
         std::cout<<"Retina::setup: resetting retina with default parameters"<<std::endl;
         if (applyDefaultSetupOnFailure)
         {
-            struct cv::bioinspired::TransientAreasSegmentationModule::SegmentationParameters defaults;
+            struct cv::bioinspired::SegmentationParameters defaults;
             setup(defaults);
         }
         std::cout<<"SegmentationModule::setup: wrong/unappropriate xml parameter file : error report :`n=>"<<e.what()<<std::endl;
@@ -356,11 +356,11 @@ void TransientAreasSegmentationModuleImpl::setup(cv::FileStorage &fs, const bool
 }
 
 // setup parameters for the 2 filters that allow the segmentation
-void TransientAreasSegmentationModuleImpl::setup(cv::bioinspired::TransientAreasSegmentationModule::SegmentationParameters newParameters)
+void TransientAreasSegmentationModuleImpl::setup(cv::bioinspired::SegmentationParameters newParameters)
 {
 
     // copy structure contents
-    memcpy(&_segmentationParameters, &newParameters, sizeof(cv::bioinspired::TransientAreasSegmentationModule::SegmentationParameters));
+    memcpy(&_segmentationParameters, &newParameters, sizeof(cv::bioinspired::SegmentationParameters));
     // apply setup
     // init local motion energy extraction low pass filter
     BasicRetinaFilter::setLPfilterParameters(0, newParameters.localEnergy_temporalConstant, newParameters.localEnergy_spatialConstant);