added python support and completed 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/doc/retina.markdown

 Bioinspired Module Retina Introduction {#bioinspired_retina}
 ======================================
 
-Retina
-------
+Retina class overview
+---------------------
 
-@note do not forget that the retina model is included in the following namespace : cv::bioinspired
+@note do not forget that the retina model is included in the following namespace : cv::bioinspired with C++ and in cv2.bioinspired with Python
 
 ### Introduction
 
-Class which provides the main controls to the Gipsa/Listic labs human retina model. This is a non
+This class provides the main controls of the Gipsa/Listic labs human retina model. This is a non
 separable spatio-temporal filter modelling the two main retina information channels :
 
 -   foveal vision for detailled color vision : the parvocellular pathway.
--   peripheral vision for sensitive transient signals detection (motion and events) : the
-    magnocellular pathway.
-
-From a general point of view, this filter whitens the image spectrum and corrects luminance thanks
-to local adaptation. An other important property is its hability to filter out spatio-temporal noise
-while enhancing details. This model originates from Jeanny Herault work @cite Herault2010 . It has been
-involved in Alexandre Benoit phd and his current research @cite Benoit2010, @cite Strat2013 (he
-currently maintains this module within OpenCV). It includes the work of other Jeanny's phd student
+-   peripheral vision for sensitive transient signals detection (motion and events) : the magnocellular pathway.
+
+This model originates from Jeanny Herault work @cite Herault2010 . It has been
+involved in Alexandre Benoit phd and his current research @cite Benoit2010, @cite Benoit2014 . He
+currently maintains this module within OpenCV. It includes the work of other Jeanny's phd student
 such as @cite Chaix2007 and the log polar transformations of Barthelemy Durette described in Jeanny's
 book.
 
+More into details here is an overview of the retina properties that are implemented here :
+- regarding luminance and details enhancement :
+  -   local logarithmic luminance compression (at the entry point by photoreceptors and at the output by ganglion cells).
+  -   spectral whitening at the Outer Plexiform Layer level (photoreceptors and horizontal cells spatio-temporal filtering).
+
+The former behavior compresses luminance range and allows very bright and very dark areas to be visible on the same picture with lots of details. The latter reduces low frequency luminance energy (mean luminance) and enhances mid-frequencies (details). Applied all together, retina well prepares visual signals prior high level analysis. Those properties are really interesting with videos where light changes are dramatically reduced with an interesting temporal consistency.
+
+- regarding noise filtering :
+  - high frequency spatial and temporal noise is filtred out. Both outputs Parvo and Magno pathways benefit from this. Noise reduction benefits from the non separable spatio-temporal filtering.
+  - at the Parvo output, static textures are enhanced and noise is filtred (on videos, temporal noise is nicely removed). However, as human behaviors, moving textures are smoothed. Then, moving object details can be enhanced only if the retina tracks it and keeps it static from its point of view.
+  - at Magno output, it allows a cleaner detection of events (motion, changes) with reduced noise errors even in difficult lighting conditions. As a compromise, the Magno output is low spatial frequency signal and allows events blobs to be reliably extracted (check the TransientAreasSegmentationModule module for that).
+
+### Use
+
+This model can be used as a preprocessing stage in the aim of :
+
+-   performing texture analysis with enhanced signal to noise ratio and enhanced details robust
+    against input images luminance ranges (check out the parvocellular retina channel output, by
+    using the provided **getParvo** methods)
+-   performing motion analysis also taking advantage of the previously cited properties (check out the
+    magnocellular retina channel output, by using the provided **getMagno** methods)
+-   general image/video sequence description using either one or both channels. An example of the
+    use of Retina in a Bag of Words approach is given in @cite Benoit2014 .
+
 @note
 -   For ease of use in computer vision applications, the two retina channels are applied
-    homogeneously on all the input images. This does not follow the real retina topology but this
-    can still be done using the log sampling capabilities proposed within the class.
--   Extend the retina description and code use in the tutorial/contrib section for complementary
-    explanations.
+    on all the input images. This does not follow the real retina topology but is practical from an image processing point of view. If retina mapping (foveal and parafoveal vision) is required, use the log sampling capabilities proposed within the class.
+-   Please do not hesitate to contribute by extending the retina description, code, use cases for complementary explanations and demonstrations.
+
+### Use case illustrations
 
-### Preliminary illustration
+#### Image preprocessing
 
 As a preliminary presentation, let's start with a visual example. We propose to apply the filter on
-a low quality color jpeg image with backlight problems. Here is the considered input... *"Well, my
-eyes were able to see more that this strange black shadow..."*
+a low quality color jpeg image with backlight problems. Here is the considered input... *"Well,i could see more with my eyes than what i captured with my camera..."*
 
 ![a low quality color jpeg image with backlight problems.](images/retinaInput.jpg)
 
-Below, the retina foveal model applied on the entire image with default parameters. Here contours
-are enforced, halo effects are voluntary visible with this configuration. See parameters discussion
+Below, the retina foveal model applied on the entire image with default parameters. Details are enforced whatever the local luminance. Here contours
+are strongly enforced but noise level is kept low. Halo effects are voluntary visible with this configuration. See parameters discussion
 below and increase horizontalCellsGain near 1 to remove them.
 
 ![the retina foveal model applied on the entire image with default parameters. Here contours are enforced, luminance is corrected and halo effects are voluntary visible with this configuration, increase horizontalCellsGain near 1 to remove them.](images/retinaOutput_default.jpg)
@@ -51,12 +71,12 @@ this configuration. The backlight effect is corrected and highlight details are
 Then, even on a low quality jpeg image, if some luminance information remains, the retina is able to
 reconstruct a proper visual signal. Such configuration is also usefull for High Dynamic Range
 (*HDR*) images compression to 8bit images as discussed in @cite Benoit2010 and in the demonstration
-codes discussed below. As shown at the end of the page, parameters change from defaults are :
+codes discussed below. As shown at the end of the page, parameter changes from defaults are :
 
 -   horizontalCellsGain=0.3
 -   photoreceptorsLocalAdaptationSensitivity=ganglioncellsSensitivity=0.89.
 
-![the retina foveal model applied on the entire image with 'naturalness' parameters. Here contours are enforced but are avoided with this configuration, horizontalCellsGain is 0.3 and photoreceptorsLocalAdaptationSensitivity=ganglioncellsSensitivity=0.89.](images/retinaOutput_realistic.jpg)
+![the retina foveal model applied on the entire image with 'naturalness' parameters. Here contours are enforced but halo effects are avoided with this configuration, horizontalCellsGain is 0.3 and photoreceptorsLocalAdaptationSensitivity=ganglioncellsSensitivity=0.89.](images/retinaOutput_realistic.jpg)
 
 As observed in this preliminary demo, the retina can be settled up with various parameters, by
 default, as shown on the figure above, the retina strongly reduces mean luminance energy and
@@ -67,8 +87,76 @@ default parameters. Then, tweak it on your own and reload them at any time using
 *setup(String fs)*. These methods update a *Retina::RetinaParameters* member structure that is
 described hereafter. XML parameters file samples are shown at the end of the page.
 
-Here is an overview of the abstract Retina interface, allocate one instance with the *createRetina*
-functions.:
+#### Tone mapping processing capability
+
+This retina model naturally handles luminance range compression. Local adaptation stages and spectral whitening contribute
+to luminance range compression. In addition, high frequency noise that often corrupts tone mapped images is removed at early stages of the
+process thus leading to naturally perception and noise free tone mapping.
+
+Compared to the demos shown above, setup differences are the following: (see bioinspired/samples/OpenEXRimages_HDR_Retina_toneMapping.cpp for more details)
+* load HDR images (OpenEXR format is supported by OpenCV) and cut histogram borders at ~5% and 95% to eliminate salt&pepper like pixel corruption.
+* apply retina with default parameters and the following changes (generic parameters used for the presented illustrations of the section) : 
+  *   retina Hcells gain =0.4 (the main change compared to default configuration : it strongly reduces halo effects)
+  *   localAdaptation_photoreceptors=0.99 (a little higher than default value to enforce local adaptation)
+  *   localAdaptation_Gcells=0.95 (also slightly higher than default for local adaptation enforcement)
+
+Have a look at the end of this page to see how to specify these parameters in a configuration file.
+
+The following two illusrations show the effect of such configuration on 2 image samples.
+
+![HDR image tone mapping example with generic parameters. Original image comes from http://openexr.com/ samples (openexr-images-1.7.0/ScanLines/CandleGlass.exr)](images/HDRtoneMapping_candleSample.jpg)
+
+![HDR image tone mapping example with the same generic parameters. Original image comes from http://www.pauldebevec.com/Research/HDR/memorial.exr)](images/HDRtoneMapping_memorialSample.jpg)
+
+#### Motion and event detection
+
+Spatio-temporal events can be detected easily using magno output of the retina. Its energy linearly increases with motion speed.
+An event blob detector is proposed with the TransientAreasSegmentationModule class also provided in the bioinspired module. The basic idea is to detect local energy drops with regard of the neighborhood and apply a threshold. Such process has been used in a bag of words description of videos on the TRECVid challenge @cite Benoit2014 and allows video frames description only on transient areas.
+
+We present here some illustrations of the retina outputs on some examples taken from http://changedetection.net/ with RGB and thermal videos.
+
+@note here, we use the default retina setup that generates halos around strong edges. Note that temporal constants allow a temporal effect to be visible on moting objects (usefull for still image illustrations of a video). Halos can be removed by increasing retina Hcells gain and temporal effects can be reduced by decreasing temporal constant values.
+Also take into account that the two retina outputs are rescaled in range [0:255] such that magno output can show a lot of "noise" when nothing moves when you draw it. However, its energy remains low if you retreive it using *getMagnoRAW* getter instead.
+
+
+![Retina processing on RGB image sequence : example from http://changedetection.net/ (baseline/PETS2006). Parvo enforces static signals but smooths moving persons since they do not remain static from its point of view. Magno channel highligths moving persons, observe the energy mapping on the one on top, partly behind a dark glass.](images/VideoDemo_RGB_PETS2006.jpg)
+
+![Retina processing on gray levels image sequence : example from http://changedetection.net/ (thermal/park). On such grayscale images, parvo channel enforces contrasts while magno stronly reacts on moving pedestrians](images/VideoDemo_thermal_park.jpg)
+
+### Literature
+
+For more information, refer to the following papers :
+
+-   Model description : @cite Benoit2010
+
+-   Model use in a Bag of Words approach : @cite Benoit2014
+
+-   Please have a look at the reference work of Jeanny Herault that you can read in his book : @cite Herault2010
+
+This retina filter code includes the research contributions of phd/research collegues from which
+code has been redrawn by the author :
+
+-   take a look at the *retinacolor.hpp* module to discover Brice Chaix de Lavarene phD color
+    mosaicing/demosaicing and his reference paper: @cite Chaix2007
+
+-   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. More informations in the above cited
+    Jeanny Heraults's book.
+
+-   Meylan&al work on HDR tone mapping that is implemented as a specific method within the model : @cite Meylan2007
+
+
+Retina programming interfaces
+-----------------------------
+
+The proposed class allows the [Gipsa](http://www.gipsa-lab.inpg.fr) (preliminary work) /
+[Listic](http://www.listic.univ-savoie.fr) labs retina model to be used.
+It can be applied on still images, images sequences and video sequences.
+
+Here is an overview of the Retina interface, allocate one instance with the *createRetina*
+functions (C++, Java, Python) :
+
 @code{.cpp}
     namespace cv{namespace bioinspired{
 
@@ -122,57 +210,259 @@ functions.:
       }} // cv and bioinspired namespaces end
 @endcode
 
-### Description
+### Setting up Retina
+
+When using the *Retina::write* and *Retina::load* methods, you create or load a XML file that stores Retina configuration.
+
+The default configuration is presented below.
+
+@code{.xml}
+<?xml version="1.0"?>
+<opencv_storage>
+<OPLandIPLparvo>
+    <colorMode>1</colorMode>
+    <normaliseOutput>1</normaliseOutput>
+    <photoreceptorsLocalAdaptationSensitivity>7.5e-01</photoreceptorsLocalAdaptationSensitivity>
+    <photoreceptorsTemporalConstant>9.0e-01</photoreceptorsTemporalConstant>
+    <photoreceptorsSpatialConstant>5.7e-01</photoreceptorsSpatialConstant>
+    <horizontalCellsGain>0.01</horizontalCellsGain>
+    <hcellsTemporalConstant>0.5</hcellsTemporalConstant>
+    <hcellsSpatialConstant>7.</hcellsSpatialConstant>
+    <ganglionCellsSensitivity>7.5e-01</ganglionCellsSensitivity></OPLandIPLparvo>
+<IPLmagno>
+    <normaliseOutput>1</normaliseOutput>
+    <parasolCells_beta>0.</parasolCells_beta>
+    <parasolCells_tau>0.</parasolCells_tau>
+    <parasolCells_k>7.</parasolCells_k>
+    <amacrinCellsTemporalCutFrequency>2.0e+00</amacrinCellsTemporalCutFrequency>
+    <V0CompressionParameter>9.5e-01</V0CompressionParameter>
+    <localAdaptintegration_tau>0.</localAdaptintegration_tau>
+    <localAdaptintegration_k>7.</localAdaptintegration_k></IPLmagno>
+</opencv_storage>
+@endcode
 
-Class which allows the [Gipsa](http://www.gipsa-lab.inpg.fr) (preliminary work) /
-[Listic](http://www.listic.univ-savoie.fr) (code maintainer and user) labs retina model to be used.
-This class allows human retina spatio-temporal image processing to be applied on still images,
-images sequences and video sequences. Briefly, here are the main human retina model properties:
+Here are some words about all those parameters, tweak them as you wish to amplify or moderate retina effects (contours enforcement, halos effects, motion sensitivity, motion blurring, etc.)
+
+#### Basic parameters
+
+The most simple parameters are the following :
+
+-   **colorMode** : let the retina process color information (if 1) or gray scale images (if 0). In
+    this last case, only the first channel of the input will be processed.
+-   **normaliseOutput** : each channel has this parameter, if value is 1, then the considered
+    channel output is rescaled between 0 and 255. Take care in this case at the Magnocellular output
+    level (motion/transient channel detection). Residual noise will also be rescaled !
+
+**Note :** using color requires color channels multiplexing/demultipexing which requires more
+processing. You can expect much faster processing using gray levels : it would require around 30
+product per pixel for all the retina processes and it has recently been parallelized for multicore
+architectures.
+
+#### Photo-receptors parameters
+
+The following parameters act on the entry point of the retina - photo-receptors - and impact all the
+following processes. These sensors are low pass spatio-temporal filters that smooth temporal and
+spatial data and also adjust there sensitivity to local luminance thus improving details extraction
+and high frequency noise canceling.
+
+-   **photoreceptorsLocalAdaptationSensitivity** between 0 and 1. Values close to 1 allow high
+    luminance log compression effect at the photo-receptors level. Values closer to 0 give a more
+    linear sensitivity. Increased alone, it can burn the *Parvo (details channel)* output image. If
+    adjusted in collaboration with **ganglionCellsSensitivity** images can be very contrasted
+    whatever the local luminance there is... at the price of a naturalness decrease.
+-   **photoreceptorsTemporalConstant** this setups the temporal constant of the low pass filter
+    effect at the entry of the retina. High value lead to strong temporal smoothing effect : moving
+    objects are blurred and can disappear while static object are favored. But when starting the
+    retina processing, stable state is reached lately.
+-   **photoreceptorsSpatialConstant** specifies the spatial constant related to photo-receptors low
+    pass filter effect. This parameters specify the minimum allowed spatial signal period allowed in
+    the following. Typically, this filter should cut high frequency noise. Then a 0 value doesn't
+    cut anything noise while higher values start to cut high spatial frequencies and more and more
+    lower frequencies... Then, do not go to high if you wanna see some details of the input images !
+    A good compromise for color images is 0.53 since this won't affect too much the color spectrum.
+    Higher values would lead to gray and blurred output images.
+
+#### Horizontal cells parameters
+
+This parameter set tunes the neural network connected to the photo-receptors, the horizontal cells.
+It modulates photo-receptors sensitivity and completes the processing for final spectral whitening
+(part of the spatial band pass effect thus favoring visual details enhancement).
+
+-   **horizontalCellsGain** here is a critical parameter ! If you are not interested by the mean
+    luminance and focus on details enhancement, then, set to zero. But if you want to keep some
+    environment luminance data, let some low spatial frequencies pass into the system and set a
+    higher value (\<1).
+-   **hcellsTemporalConstant** similar to photo-receptors, this acts on the temporal constant of a
+    low pass temporal filter that smooths input data. Here, a high value generates a high retina
+    after effect while a lower value makes the retina more reactive. This value should be lower than
+    **photoreceptorsTemporalConstant** to limit strong retina after effects.
+-   **hcellsSpatialConstant** is the spatial constant of the low pass filter of these cells filter.
+    It specifies the lowest spatial frequency allowed in the following. Visually, a high value leads
+    to very low spatial frequencies processing and leads to salient halo effects. Lower values
+    reduce this effect but the limit is : do not go lower than the value of
+    **photoreceptorsSpatialConstant**. Those 2 parameters actually specify the spatial band-pass of
+    the retina.
+
+**NOTE** after the processing managed by the previous parameters, input data is cleaned from noise
+and luminance in already partly enhanced. The following parameters act on the last processing stages
+of the two outing retina signals.
+
+#### Parvo (details channel) dedicated parameter
+
+-   **ganglionCellsSensitivity** specifies the strength of the final local adaptation occurring at
+    the output of this details dedicated channel. Parameter values remain between 0 and 1. Low value
+    tend to give a linear response while higher values enforces the remaining low contrasted areas.
+
+**Note :** this parameter can correct eventual burned images by favoring low energetic details of
+the visual scene, even in bright areas.
+
+#### IPL Magno (motion/transient channel) parameters
+
+Once image information is cleaned, this channel acts as a high pass temporal filter that only
+selects signals related to transient signals (events, motion, etc.). A low pass spatial filter
+smooths extracted transient data and a final logarithmic compression enhances low transient events
+thus enhancing event sensitivity.
+
+-   **parasolCells_beta** generally set to zero, can be considered as an amplifier gain at the
+    entry point of this processing stage. Generally set to 0.
+-   **parasolCells_tau** the temporal smoothing effect that can be added
+-   **parasolCells_k** the spatial constant of the spatial filtering effect, set it at a high value
+    to favor low spatial frequency signals that are lower subject to residual noise.
+-   **amacrinCellsTemporalCutFrequency** specifies the temporal constant of the high pass filter.
+    High values let slow transient events to be selected.
+-   **V0CompressionParameter** specifies the strength of the log compression. Similar behaviors to
+    previous description but here it enforces sensitivity of transient events.
+-   **localAdaptintegration_tau** generally set to 0, no real use here actually
+-   **localAdaptintegration_k** specifies the size of the area on which local adaptation is
+    performed. Low values lead to short range local adaptation (higher sensitivity to noise), high
+    values secure log compression.
+
+
+### Demos and experiments !
+
+
+#### First time experiments
+
+Here are some code snippets to shortly show how to use Retina with default parameters (with halo effects). Next section redirects to more complete demos provided with the main retina class.
+
+Here is presented how to process a webcam stream with the following steps : 
+- load a frist input image to get its size
+- allocate a retina instance with appropriate input size
+- loop over grabbed frames :
+  - grab a new frame
+  - run on a frame
+  - call the two output getters
+  - display retina outputs
+
+C++ version (see bioinspired/samples/basicRetina.cpp) : 
 
--   spectral whithening (mid-frequency details enhancement)
--   high frequency spatio-temporal noise reduction (temporal noise and high frequency spatial noise
-    are minimized)
--   low frequency luminance reduction (luminance range compression) : high luminance regions do not
-    hide details in darker regions anymore
--   local logarithmic luminance compression allows details to be enhanced even in low light
-    conditions
+@code{.cpp}
+// 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>
+
+// main function
+int main(int argc, char* argv[]) {
+    // 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
+    while(true){
+        // if using video stream, then, grabbing a new frame, else, input remains the same
+        if (videoCapture.isOpened())
+            videoCapture>>inputFrame;
+        else
+            break;
+        imshow('input frame', inputImage)
+        // run retina on the input image
+        myRetina->run(inputFrame);
+        // grab retina outputs
+        myRetina->getParvo(retinaOutput_parvo);
+        myRetina->getMagno(retinaOutput_magno);
+        // draw retina outputs
+        cv::imshow("retina input", inputFrame);
+        cv::imshow("Retina Parvo", retinaOutput_parvo);
+        cv::imshow("Retina Magno", retinaOutput_magno);
+        cv::waitKey(5);
+        }
+}
+@endcode
+Compile this C++ code with the following command :
+@code{.sh}
+// compile
+g++ basicRetina.cpp -o basicRetina -lopencv_core -lopencv_highgui -lopencv_bioinspired -lopencv_videoio -lopencv_imgcodecs
+@endcode
 
-Use : this model can be used basically for spatio-temporal video effects but also in the aim of :
 
--   performing texture analysis with enhanced signal to noise ratio and enhanced details robust
-    against input images luminance ranges (check out the parvocellular retina channel output, by
-    using the provided **getParvo** methods)
--   performing motion analysis also taking benefit of the previously cited properties (check out the
-    magnocellular retina channel output, by using the provided **getMagno** methods)
--   general image/video sequence description using either one or both channels. An example of the
-    use of Retina in a Bag of Words approach is given in @cite Strat2013 .
+Python version
 
-Literature
-----------
+@code{.py}
+#import OpenCV module
+import cv2 
 
-For more information, refer to the following papers :
+#setup webcam reader
+videoHandler = cv2.VideoCapture(0)
+succeed, inputImage=videoHandler.read()
 
--   Model description : @cite Benoit2010
+#allocate a retina instance with input size equal to the one of the loaded image
+retina = cv2.bioinspired.createRetina((inputImage.shape[1], inputImage.shape[0]))
 
--   Model use in a Bag of Words approach : @cite Strat2013
+#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)
+retina.write('retinaParams.xml')
+#-> load retina parameters from a xml file : here we load the default parameters that we just wrote to file
+retina.setup('retinaParams.xml')
 
--   Please have a look at the reference work of Jeanny Herault that you can read in his book : @cite Herault2010
+#main processing loop
+stillProcess=True
+while stillProcess is True:
 
-This retina filter code includes the research contributions of phd/research collegues from which
-code has been redrawn by the author :
+	#grab a new frame and display it
+	stillProcess, inputImage=videoHandler.read()
+	cv2.imshow('input frame', inputImage)
 
--   take a look at the *retinacolor.hpp* module to discover Brice Chaix de Lavarene phD color
-    mosaicing/demosaicing and his reference paper: @cite Chaix2007
+	#run retina on the input image
+	retina.run(inputImage)
 
--   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. More informations in the above cited
-    Jeanny Heraults's book.
+	#grab retina outputs
+	retinaOut_parvo=retina.getParvo()
+	retinaOut_magno=retina.getMagno()
 
--   Meylan&al work on HDR tone mapping that is implemented as a specific method within the model : @cite Meylan2007
+	#draw retina outputs
+	cv2.imshow('retina parvo out', retinaOut_parvo)
+	cv2.imshow('retina magno out', retinaOut_magno)
+
+	#wait a little to let the time for figures to be drawn
+	cv2.waitKey(2)
+@endcode
 
-Demos and experiments !
------------------------
+
+
+#### More complete demos
 
 @note Complementary to the following examples, have a look at the Retina tutorial in the
 tutorial/contrib section for complementary explanations.**
@@ -208,3 +498,5 @@ Take a look at the provided C++ examples provided with OpenCV :
     When using the 'fast' option, then, a simpler method is used, it is an adaptation of the
     algorithm presented in @cite Meylan2007 . This method gives also good results and is faster to
     process but it sometimes requires some more parameters adjustement.
+
+

modules/bioinspired/include/opencv2/bioinspired/retina.hpp

@@ -11,7 +11,7 @@
  **
  ** Maintainers : Listic lab (code author current affiliation & applications) and Gipsa Lab (original research origins & 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).
@@ -33,7 +33,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.
  **
@@ -86,36 +86,10 @@ enum {
     RETINA_COLOR_BAYER//!< standard bayer sampling
 };
 
-/** @brief class which allows the Gipsa/Listic Labs model to be used with OpenCV.
-
-This retina model allows spatio-temporal image processing (applied on still images, video sequences).
-As a summary, these are the retina model properties:
-- It applies a spectral whithening (mid-frequency details enhancement)
-- high frequency spatio-temporal noise reduction
-- low frequency luminance to be reduced (luminance range compression)
-- local logarithmic luminance compression allows details to be enhanced in low light conditions
-
-USE : this model can be used basically for spatio-temporal video effects but also for :
-     _using the getParvo method output matrix : texture analysiswith enhanced signal to noise ratio and enhanced details robust against input images luminance ranges
-     _using the getMagno method output matrix : motion analysis also with the previously cited properties
-
-for more information, reer to the following papers :
-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
-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.
 
-The retina filter includes the research contributions of phd/research collegues from which code has been redrawn by the author :
-take a look at the retinacolor.hpp module to discover Brice Chaix de Lavarene color mosaicing/demosaicing and the reference paper:
-B. Chaix de Lavarene, D. Alleysson, B. Durette, J. Herault (2007). "Efficient demosaicing through recursive filtering", IEEE International Conference on Image Processing ICIP 2007
-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.
-more informations in the above cited Jeanny Heraults's book.
- */
-class CV_EXPORTS_W Retina : public Algorithm {
+/** @brief retina model parameters structure
 
-public:
-
-    /** @brief parameters structure
-
-    for better clarity, check explenations on the comments of methods : setupOPLandIPLParvoChannel and setupIPLMagnoChannel
+    For better clarity, check explenations on the comments of methods : setupOPLandIPLParvoChannel and setupIPLMagnoChannel
 
     Here is the default configuration file of the retina module. It gives results such as the first
     retina output shown on the top of this page.
@@ -172,9 +146,9 @@ public:
     </opencv_storage>
     @endcode
       */
-    struct CV_EXPORTS_W RetinaParameters{
+    struct RetinaParameters{ 
         //! Outer Plexiform Layer (OPL) and Inner Plexiform Layer Parvocellular (IplParvo) parameters
-        struct CV_EXPORTS_W OPLandIplParvoParameters{
+        struct OPLandIplParvoParameters{
                OPLandIplParvoParameters():colorMode(true),
                                  normaliseOutput(true),
                                  photoreceptorsLocalAdaptationSensitivity(0.75f),
@@ -184,11 +158,11 @@ public:
                                  hcellsTemporalConstant(0.5f),
                                  hcellsSpatialConstant(7.f),
                                  ganglionCellsSensitivity(0.75f) { } // default setup
-               CV_PROP_RW bool colorMode, normaliseOutput;
-               CV_PROP_RW float photoreceptorsLocalAdaptationSensitivity, photoreceptorsTemporalConstant, photoreceptorsSpatialConstant, horizontalCellsGain, hcellsTemporalConstant, hcellsSpatialConstant, ganglionCellsSensitivity;
+               bool colorMode, normaliseOutput;
+               float photoreceptorsLocalAdaptationSensitivity, photoreceptorsTemporalConstant, photoreceptorsSpatialConstant, horizontalCellsGain, hcellsTemporalConstant, hcellsSpatialConstant, ganglionCellsSensitivity;
         };
         //! Inner Plexiform Layer Magnocellular channel (IplMagno)
-        struct CV_EXPORTS_W IplMagnoParameters{
+        struct IplMagnoParameters{
             IplMagnoParameters():
                           normaliseOutput(true),
                           parasolCells_beta(0.f),
@@ -198,13 +172,43 @@ public:
                           V0CompressionParameter(0.95f),
                           localAdaptintegration_tau(0.f),
                           localAdaptintegration_k(7.f) { } // default setup
-            CV_PROP_RW bool normaliseOutput;
-            CV_PROP_RW float parasolCells_beta, parasolCells_tau, parasolCells_k, amacrinCellsTemporalCutFrequency, V0CompressionParameter, localAdaptintegration_tau, localAdaptintegration_k;
+            bool normaliseOutput;
+            float parasolCells_beta, parasolCells_tau, parasolCells_k, amacrinCellsTemporalCutFrequency, V0CompressionParameter, localAdaptintegration_tau, localAdaptintegration_k;
         };
-        CV_PROP_RW OPLandIplParvoParameters OPLandIplParvo;
-        CV_PROP_RW IplMagnoParameters IplMagno;
+        OPLandIplParvoParameters OPLandIplParvo;
+        IplMagnoParameters IplMagno;
     };
 
+
+
+/** @brief class which allows the Gipsa/Listic Labs model to be used with OpenCV.
+
+This retina model allows spatio-temporal image processing (applied on still images, video sequences).
+As a summary, these are the retina model properties:
+- It applies a spectral whithening (mid-frequency details enhancement)
+- high frequency spatio-temporal noise reduction
+- low frequency luminance to be reduced (luminance range compression)
+- local logarithmic luminance compression allows details to be enhanced in low light conditions
+
+USE : this model can be used basically for spatio-temporal video effects but also for :
+     _using the getParvo method output matrix : texture analysiswith enhanced signal to noise ratio and enhanced details robust against input images luminance ranges
+     _using the getMagno method output matrix : motion analysis also with the previously cited properties
+
+for more information, reer to the following papers :
+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
+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.
+
+The retina filter includes the research contributions of phd/research collegues from which code has been redrawn by the author :
+take a look at the retinacolor.hpp module to discover Brice Chaix de Lavarene color mosaicing/demosaicing and the reference paper:
+B. Chaix de Lavarene, D. Alleysson, B. Durette, J. Herault (2007). "Efficient demosaicing through recursive filtering", IEEE International Conference on Image Processing ICIP 2007
+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.
+more informations in the above cited Jeanny Heraults's book.
+ */
+class CV_EXPORTS_W Retina : public Algorithm {
+
+public:
+
+    
     /** @brief Retreive retina input buffer size
     @return the retina input buffer size
      */
@@ -231,17 +235,17 @@ public:
     @param fs the open Filestorage which contains retina 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;
 
     /** @overload
     @param newParameters a parameters structures updated with the new target configuration.
     */
-    CV_WRAP virtual void setup(RetinaParameters newParameters)=0;
+    virtual void setup(RetinaParameters newParameters)=0;
 
     /**
-   @return the current parameters setup
+    @return the current parameters setup
     */
-    CV_WRAP virtual RetinaParameters getParameters()=0;
+    virtual RetinaParameters getParameters()=0;
 
     /** @brief Outputs a string showing the used parameters setup
     @return a string which contains formated parameters information
@@ -255,23 +259,7 @@ public:
     CV_WRAP virtual void write( String fs ) const=0;
 
     /** @overload */
-    CV_WRAP virtual void write( FileStorage& fs ) const=0;
-
-    /**
-    setup the OPL and IPL parvo channels (see biologocal model)
-    OPL is referred as Outer Plexiform Layer of the retina, it allows the spatio-temporal filtering which withens the spectrum and reduces spatio-temporal noise while attenuating global luminance (low frequency energy)
-    IPL parvo is the OPL next processing stage, it refers to Inner Plexiform layer of the retina, it allows high contours sensitivity in foveal vision.
-    for more informations, please have a look at the paper 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
-    @param colorMode : specifies if (true) color is processed of not (false) to then processing gray level image
-    @param normaliseOutput : specifies if (true) output is rescaled between 0 and 255 of not (false)
-    @param photoreceptorsLocalAdaptationSensitivity: the photoreceptors sensitivity renage is 0-1 (more log compression effect when value increases)
-    @param photoreceptorsTemporalConstant: the time constant of the first order low pass filter of the photoreceptors, use it to cut high temporal frequencies (noise or fast motion), unit is frames, typical value is 1 frame
-    @param photoreceptorsSpatialConstant: the spatial constant of the first order low pass filter of the photoreceptors, use it to cut high spatial frequencies (noise or thick contours), unit is pixels, typical value is 1 pixel
-    @param horizontalCellsGain: gain of the horizontal cells network, if 0, then the mean value of the output is zero, if the parameter is near 1, then, the luminance is not filtered and is still reachable at the output, typicall value is 0
-    @param HcellsTemporalConstant: the time constant of the first order low pass filter of the horizontal cells, use it to cut low temporal frequencies (local luminance variations), unit is frames, typical value is 1 frame, as the photoreceptors
-    @param HcellsSpatialConstant: the spatial constant of the first order low pass filter of the horizontal cells, use it to cut low spatial frequencies (local luminance), unit is pixels, typical value is 5 pixel, this value is also used for local contrast computing when computing the local contrast adaptation at the ganglion cells level (Inner Plexiform Layer parvocellular channel model)
-    @param ganglionCellsSensitivity: the compression strengh of the ganglion cells local adaptation output, set a value between 160 and 250 for best results, a high value increases more the low value sensitivity... and the output saturates faster, recommended value: 230
-     */
+    virtual void write( FileStorage& fs ) const=0;
 
     /** @brief Setup the OPL and IPL parvo channels (see biologocal model)
 
@@ -280,6 +268,7 @@ public:
     (low frequency energy) IPL parvo is the OPL next processing stage, it refers to a part of the
     Inner Plexiform layer of the retina, it allows high contours sensitivity in foveal vision. See
     reference papers for more informations.
+    for more informations, please have a look at the paper 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
     @param colorMode specifies if (true) color is processed of not (false) to then processing gray
     level image
     @param normaliseOutput specifies if (true) output is rescaled between 0 and 255 of not (false)

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

+// 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>
+
+// main function
+int main(int argc, char* argv[]) {
+  // 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/retina.cpp

@@ -11,7 +11,7 @@
  **
  ** Maintainers : Listic lab (code author current affiliation & applications) and Gipsa Lab (original research origins & applications)
  **
- **  Creation - enhancement process 2007-2011
+ **  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).
@@ -30,7 +30,7 @@
  **               For Open Source Computer Vision Library
  **
  ** Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
- ** Copyright (C) 2008-2011, Willow Garage Inc., all rights reserved.
+ ** Copyright (C) 2008-2015, 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.
@@ -136,12 +136,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(Retina::RetinaParameters newParameters);
+    void setup(RetinaParameters newParameters);
 
     /**
     * @return the current parameters setup
     */
-    struct Retina::RetinaParameters getParameters();
+    struct RetinaParameters getParameters();
 
     /**
      * parameters setup display method
@@ -336,7 +336,7 @@ void RetinaImpl::setColorSaturation(const bool saturateColors, const float color
     _retinaFilter->setColorSaturation(saturateColors, colorSaturationValue);
 }
 
-struct Retina::RetinaParameters RetinaImpl::getParameters(){return _retinaParameters;}
+struct RetinaParameters RetinaImpl::getParameters(){return _retinaParameters;}
 
 void RetinaImpl::setup(String retinaParameterFile, const bool applyDefaultSetupOnFailure)
 {
@@ -416,10 +416,10 @@ void RetinaImpl::setup(cv::FileStorage &fs, const bool applyDefaultSetupOnFailur
     printf("%s\n", printSetup().c_str());
 }
 
-void RetinaImpl::setup(Retina::RetinaParameters newConfiguration)
+void RetinaImpl::setup(RetinaParameters newConfiguration)
 {
     // simply copy structures
-    memcpy(&_retinaParameters, &newConfiguration, sizeof(Retina::RetinaParameters));
+    memcpy(&_retinaParameters, &newConfiguration, sizeof(RetinaParameters));
     // apply setup
     setupOPLandIPLParvoChannel(_retinaParameters.OPLandIplParvo.colorMode, _retinaParameters.OPLandIplParvo.normaliseOutput, _retinaParameters.OPLandIplParvo.photoreceptorsLocalAdaptationSensitivity, _retinaParameters.OPLandIplParvo.photoreceptorsTemporalConstant, _retinaParameters.OPLandIplParvo.photoreceptorsSpatialConstant, _retinaParameters.OPLandIplParvo.horizontalCellsGain, _retinaParameters.OPLandIplParvo.hcellsTemporalConstant, _retinaParameters.OPLandIplParvo.hcellsSpatialConstant, _retinaParameters.OPLandIplParvo.ganglionCellsSensitivity);
     setupIPLMagnoChannel(_retinaParameters.IplMagno.normaliseOutput, _retinaParameters.IplMagno.parasolCells_beta, _retinaParameters.IplMagno.parasolCells_tau, _retinaParameters.IplMagno.parasolCells_k, _retinaParameters.IplMagno.amacrinCellsTemporalCutFrequency,_retinaParameters.IplMagno.V0CompressionParameter, _retinaParameters.IplMagno.localAdaptintegration_tau, _retinaParameters.IplMagno.localAdaptintegration_k);

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);

modules/bioinspired/tutorials/retina_model.markdown

@@ -141,7 +141,7 @@ read)* and opencv_bioinspired *(Retina description)* libraries to compile.
 
 @code{.sh}
 // compile
-gcc retina_tutorial.cpp -o Retina_tuto -lopencv_core -lopencv_highgui -lopencv_bioinspired
+gcc retina_tutorial.cpp -o Retina_tuto -lopencv_core -lopencv_highgui -lopencv_bioinspired -lopencv_videoio -lopencv_imgcodecs
 
 // Run commands : add 'log' as a last parameter to apply a spatial log sampling (simulates retina sampling)
 // run on webcam