trying to solve valarray pointer access problem, enhancing documentation

modules/contrib/doc/retina/index.rst

@@ -5,8 +5,7 @@ Retina : a Bio mimetic human retina model
 
 Retina
 ======
-
+.. ocv:class:: Retina : public Algorithm
-.. ocv:class:: Retina
 
 Class which provides the main controls to the Gipsa/Listic labs human  retina model. Spatio-temporal filtering modelling the two main retina information channels :
 
@@ -14,19 +13,30 @@ Class which provides the main controls to the Gipsa/Listic labs human  retina mo
 
 * periphearal vision for sensitive transient signals detection (motion and events) : the magnocellular pathway.
 
+From a general point of view, this filter corrects luminance thanks to local adaptation. It filters out spatio-temporal noise and enhances details.
 This model originates from Jeanny Herault work [Herault2010]_. It has been involved in Alexandre Benoit phd and current research [Benoit2010]_. It includes the work of other Jeanny's phd student such as [Chaix2007]_ and the log polar transformations of Barthelemy Durette described in Jeanny's book.
 
 **NOTE : See the Retina tutorial in the tutorial/contrib section for complementary explanations.**
 
+Example : a low quality color jpeg image with backlight problems as input of the retina model.
+
 .. image:: images/retinaInput.jpg
    :alt: a low quality color jpeg image with backlight problems.
    :align: center
 
-.. image:: images/retinaOutput.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, increase horizontalCellsGain near 1 to remove them.
-   :alt: the retina foveal model applied on the entire image with default parameters. Here contours are enforced, halo effects are voluntary visible with this configuration, increase horizontalCellsGain near 1 to remove them.
+
+.. image:: images/retinaOutput_default.jpg
+   :alt: 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.
    :align: center
 
-The retina can be settled up with various parameters, by default, as shown on the figure above, the retina cancels mean luminance and enforces all details of the visual scene. Halo effects can be modulated (exagerated to cancelled). In order to use your own parameters, you can use at least one time the *write(String fs)* method which will write a proper XML file with all default parameters. Then, tweak it on your own and reload them at any time using method *setup(String fs)*. These methods update a *Retina::RetinaParameters* member structure that is described hereafter. ::
+Below, a second the retina foveal model output applied on the entire image with 'naturalness' parameters. Here contours are enforced, luminance is corrected but halos are avoided with this configuration. As shown at the end of the page, parameters change from defaults are horizontalCellsGain=0.3 and photoreceptorsLocalAdaptationSensitivity=ganglioncellsSensitivity=0.89.
+
+.. image:: images/retinaOutput_realistic.jpg
+   :alt: 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.
+   :align: center
+
+The retina can be settled up with various parameters, by default, as shown on the figure above, the retina modulates mean luminance and enforces all details of the visual scene. Halo effects can be modulated (exagerated to cancelled as shown on the two examples). In order to use your own parameters, you can use at least one time the *write(String fs)* method which will write a proper XML file with all default parameters. Then, tweak it on your own and reload them at any time using method *setup(String fs)*. These methods update a *Retina::RetinaParameters* member structure that is described hereafter. XML parameters samples are shown at the end of the page. ::
 
   class Retina
   {
@@ -373,3 +383,60 @@ Retina::RetinaParameters
             struct OPLandIplParvoParameters OPLandIplParvo;
             struct IplMagnoParameters IplMagno;
     };
+
+Retina parameters files examples
+++++++++++++++++++++++++++++++++
+
+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.
+
+.. code-block:: cpp
+
+    <?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>
+
+Here is the 'realistic" setup used to obtain the second retina output shown on the top of this page.
+
+.. code-block:: cpp
+
+    <?xml version="1.0"?>
+    <opencv_storage>
+    <OPLandIPLparvo>
+      <colorMode>1</colorMode>
+      <normaliseOutput>1</normaliseOutput>
+      <photoreceptorsLocalAdaptationSensitivity>8.9e-01</photoreceptorsLocalAdaptationSensitivity>
+      <photoreceptorsTemporalConstant>0.0000000000000000e-01</photoreceptorsTemporalConstant>
+      <photoreceptorsSpatialConstant>5.3e-01</photoreceptorsSpatialConstant>
+      <horizontalCellsGain>0.3</horizontalCellsGain>
+      <hcellsTemporalConstant>0.</hcellsTemporalConstant>
+      <hcellsSpatialConstant>.</hcellsSpatialConstant>
+      <ganglionCellsSensitivity>8.9e-01</ganglionCellsSensitivity></OPLandIPLparvo>
+    <IPLmagno>
+      <normaliseOutput>1</normaliseOutput>
+      <parasolCells_beta>0.</parasolCells_beta>
+      <parasolCells_tau>0.</parasolCells_tau>
+      <parasolCells_k>7.</parasolCells_k>
+      <amacrinCellsTemporalCutFrequency>1.2000000476837158e+00</amacrinCellsTemporalCutFrequency>
+      <V0CompressionParameter>9.4999998807907104e-01</V0CompressionParameter>
+      <localAdaptintegration_tau>0.</localAdaptintegration_tau>
+      <localAdaptintegration_k>7.</localAdaptintegration_k></IPLmagno>
+    </opencv_storage>

modules/contrib/src/retina.cpp

@@ -564,8 +564,7 @@ void RetinaImpl::getParvoRAW(cv::Mat &parvoOutputBufferCopy){
 // original API level data accessors : get buffers addresses...
 const Mat RetinaImpl::getMagnoRAW() const {
     // create a cv::Mat header for the valarray
-    const float *retinaMagnoFilterOutputPTR=&(_retinaFilter->getMovingContours()[0]);
+    return Mat(_retinaFilter->getMovingContours().size(),1, CV_32F, (void*)get_data(_retinaFilter->getMovingContours()));
-    return Mat(_retinaFilter->getMovingContours().size(),1, CV_32F, (void*)retinaMagnoFilterOutputPTR);
 
 }
 
@@ -573,13 +572,11 @@ const Mat RetinaImpl::getParvoRAW() const {
     if (_retinaFilter->getColorMode()) // check if color mode is enabled
     {
         // create a cv::Mat table (for RGB planes as a single vector)
-        const float *retinaParvoFilterOutputPTR=&(_retinaFilter->getColorOutput()[0]);
+        return Mat(_retinaFilter->getColorOutput().size(), 1, CV_32F, (void*)get_data(_retinaFilter->getColorOutput()));
-        return Mat(_retinaFilter->getColorOutput().size(), 1, CV_32F, (void*)retinaParvoFilterOutputPTR);
     }
     // otherwise, output is gray level
     // create a cv::Mat header for the valarray
-    const float *retinaParvoFilterOutputPTR=&(_retinaFilter->getContours()[0]);
+    return Mat( _retinaFilter->getContours().size(), 1, CV_32F, (void*)get_data(_retinaFilter->getContours()));
-    return Mat( _retinaFilter->getContours().size(), 1, CV_32F, (void*)retinaParvoFilterOutputPTR);
 }
 
 // private method called by constructirs