clarified parameters inputs and outputs at the interface level for better...

clarified parameters inputs and outputs at the interface level for better clarity and ease of use, also corrected a mistake at activateContoursProcessing interface method

modules/contrib/include/opencv2/contrib/retina.hpp

@@ -114,24 +114,54 @@ class CV_EXPORTS Retina {
 
 public:
 
+	// parameters structure for better clarity
+        struct RetinaParameters{ 
+	    struct OPLandIplParvoParameters{ // Outer Plexiform Layer (OPL) and Inner Plexiform Layer Parvocellular (IplParvo) parameters 
+               OPLandIplParvoParameters():colorMode(true),
+                                 normaliseOutput(true),
+                                 photoreceptorsLocalAdaptationSensitivity(0.7),
+                                 photoreceptorsTemporalConstant(0.5),
+                                 photoreceptorsSpatialConstant(0.53),
+                                 horizontalCellsGain(0),
+                                 hcellsTemporalConstant(1),
+                                 hcellsSpatialConstant(7),
+                                 ganglionCellsSensitivity(0.7){};// default setup
+               bool colorMode, normaliseOutput;
+               float photoreceptorsLocalAdaptationSensitivity, photoreceptorsTemporalConstant, photoreceptorsSpatialConstant, horizontalCellsGain, hcellsTemporalConstant, hcellsSpatialConstant, ganglionCellsSensitivity;
+           };
+           struct IplMagnoParameters{ // Inner Plexiform Layer Magnocellular channel (IplMagno)
+               IplMagnoParameters():
+                          normaliseOutput(true),
+                          parasolCells_beta(0),
+                          parasolCells_tau(0),
+                          parasolCells_k(7),
+                          amacrinCellsTemporalCutFrequency(1.2),
+                          V0CompressionParameter(0.95),
+                          localAdaptintegration_tau(0),
+                          localAdaptintegration_k(7){};// default setup
+               bool normaliseOutput;
+               float parasolCells_beta, parasolCells_tau, parasolCells_k, amacrinCellsTemporalCutFrequency, V0CompressionParameter, localAdaptintegration_tau, localAdaptintegration_k;
+           };
+            struct OPLandIplParvoParameters OPLandIplParvo;
+            struct IplMagnoParameters IplMagno;
+	};
+
 	/**
 	 * Main constructor with most commun use setup : create an instance of color ready retina model
 	 * @param inputSize : the input frame size
-	 * @param parametersSaveFile : the filename of the xml file that records the default retina parameters setup, if empty, then, no default parameter file will be written
 	 */
-	Retina(Size inputSize, const std::string parametersSaveFile="");
+	Retina(Size inputSize);
 
 	/**
 	 * Complete Retina filter constructor which allows all basic structural parameters definition
          * @param inputSize : the input frame size
-	 * @param parametersSaveFile : the filename of the xml file that records the default retina parameters setup, if empty, then, no default parameter file will be written
 	 * @param colorMode : the chosen processing mode : with or without color processing
 	 * @param colorSamplingMethod: specifies which kind of color sampling will be used
 	 * @param useRetinaLogSampling: activate retina log sampling, if true, the 2 following parameters can be used
 	 * @param reductionFactor: only usefull if param useRetinaLogSampling=true, specifies the reduction factor of the output frame (as the center (fovea) is high resolution and corners can be underscaled, then a reduction of the output is allowed without precision leak
 	 * @param samplingStrenght: only usefull if param useRetinaLogSampling=true, specifies the strenght of the log scale that is applied
 	 */
-	Retina(Size inputSize, const std::string parametersSaveFile, const bool colorMode, RETINA_COLORSAMPLINGMETHOD colorSamplingMethod=RETINA_COLOR_BAYER, const bool useRetinaLogSampling=false, const double reductionFactor=1.0, const double samplingStrenght=10.0);
+	Retina(Size inputSize, const bool colorMode, RETINA_COLORSAMPLINGMETHOD colorSamplingMethod=RETINA_COLOR_BAYER, const bool useRetinaLogSampling=false, const double reductionFactor=1.0, const double samplingStrenght=10.0);
 
 	virtual ~Retina();
 
@@ -144,12 +174,39 @@ public:
 	 */
 	void setup(std::string retinaParameterFile="", const bool applyDefaultSetupOnFailure=true);
 
+	/**
+	 * try to open an XML retina parameters file to adjust current retina instance setup
+	 * => if the xml file does not exist, then default setup is applied
+	 * => warning, Exceptions are thrown if read XML file is not valid
+	 * @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(RetinaParameters newParameters);
+
+        /**
+         * @return the current parameters setup
+         */
+        struct Retina::RetinaParameters getParameters();
+
 	/**
 	 * parameters setup display method
 	 * @return a string which contains formatted parameters information
 	 */
 	const std::string printSetup();
 
+	/**
+	 * write xml/yml formated parameters information
+	 * @rparam fs : the filename of the xml file that will be open and writen with formatted parameters information
+	 */
+	virtual void write( std::string fs ) const;
+
+
+	/**
+	 * write xml/yml formated parameters information
+	 * @param fs : a cv::Filestorage object ready to be filled
+         */
+	virtual void write( FileStorage& fs ) const;
+
 	/**
 	 * 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)
@@ -238,8 +295,7 @@ public:
 
 protected:
 	// Parameteres setup members
-	FileStorage _parametersSaveFile; //!< parameters file ... saved on instance delete
-	std::string _parametersSaveFileName; //!< parameters file name
+	RetinaParameters _retinaParameters; // structure of parameters
 	
         // Retina model related modules
 	std::valarray<float> _inputBuffer; //!< buffer used to convert input cv::Mat to internal retina buffers format (valarrays)
@@ -266,7 +322,7 @@ protected:
 	const bool _convertCvMat2ValarrayBuffer(const cv::Mat inputMatToConvert, std::valarray<float> &outputValarrayMatrix);
 
 	//! private method called by constructors, gathers their parameters and use them in a unified way
-	void _init(const std::string parametersSaveFileName, Size inputSize, const bool colorMode, RETINA_COLORSAMPLINGMETHOD colorSamplingMethod=RETINA_COLOR_BAYER, const bool useRetinaLogSampling=false, const double reductionFactor=1.0, const double samplingStrenght=10.0);
+	void _init(const Size inputSize, const bool colorMode, RETINA_COLORSAMPLINGMETHOD colorSamplingMethod=RETINA_COLOR_BAYER, const bool useRetinaLogSampling=false, const double reductionFactor=1.0, const double samplingStrenght=10.0);
 
 
 };