Doxygen documentation for all modules

modules/adas/include/opencv2/adas.hpp

@@ -38,3 +38,7 @@ or tort (including negligence or otherwise) arising in any way out of
 the use of this software, even if advised of the possibility of such damage.
 
 */
+
+/** @defgroup adas Advanced Driver Assistance
+*/
+

modules/bgsegm/doc/bgsegm.bib

@@ -0,0 +1,17 @@
+@incollection{KB2001,
+  title={An improved adaptive background mixture model for real-time tracking with shadow detection},
+  author={KaewTraKulPong, Pakorn and Bowden, Richard},
+  booktitle={Video-Based Surveillance Systems},
+  pages={135--144},
+  year={2002},
+  publisher={Springer}
+}
+
+@inproceedings{Gold2012,
+  title={Visual tracking of human visitors under variable-lighting conditions for a responsive audio art installation},
+  author={Godbehere, Andrew B and Matsukawa, Akihiro and Goldberg, Ken},
+  booktitle={American Control Conference (ACC), 2012},
+  pages={4305--4312},
+  year={2012},
+  organization={IEEE}
+}

modules/bgsegm/include/opencv2/bgsegm.hpp

@@ -44,21 +44,21 @@ the use of this software, even if advised of the possibility of such damage.
 
 #ifdef __cplusplus
 
+/** @defgroup bgsegm Improved Background-Foreground Segmentation Methods
+*/
+
 namespace cv
 {
 namespace bgsegm
 {
 
-/*!
- Gaussian Mixture-based Backbround/Foreground Segmentation Algorithm
+//! @addtogroup bgsegm
+//! @{
 
- The class implements the following algorithm:
- "An improved adaptive background mixture model for real-time tracking with shadow detection"
- P. KadewTraKuPong and R. Bowden,
- Proc. 2nd European Workshp on Advanced Video-Based Surveillance Systems, 2001."
- http://personal.ee.surrey.ac.uk/Personal/R.Bowden/publications/avbs01/avbs01.pdf
+/** @brief Gaussian Mixture-based Background/Foreground Segmentation Algorithm.
 
-*/
+The class implements the algorithm described in @cite KB2001.
+ */
 class CV_EXPORTS_W BackgroundSubtractorMOG : public BackgroundSubtractor
 {
 public:
@@ -75,54 +75,118 @@ public:
     CV_WRAP virtual void setNoiseSigma(double noiseSigma) = 0;
 };
 
+/** @brief Creates mixture-of-gaussian background subtractor
+
+@param history Length of the history.
+@param nmixtures Number of Gaussian mixtures.
+@param backgroundRatio Background ratio.
+@param noiseSigma Noise strength (standard deviation of the brightness or each color channel). 0
+means some automatic value.
+ */
 CV_EXPORTS_W Ptr<BackgroundSubtractorMOG>
     createBackgroundSubtractorMOG(int history=200, int nmixtures=5,
                                   double backgroundRatio=0.7, double noiseSigma=0);
                                   
-/**
- * Background Subtractor module. Takes a series of images and returns a sequence of mask (8UC1)
- * images of the same size, where 255 indicates Foreground and 0 represents Background.
- * This class implements an algorithm described in "Visual Tracking of Human Visitors under
- * Variable-Lighting Conditions for a Responsive Audio Art Installation," A. Godbehere,
- * A. Matsukawa, K. Goldberg, American Control Conference, Montreal, June 2012.
+
+/** @brief Background Subtractor module based on the algorithm given in @cite Gold2012.
+
+ Takes a series of images and returns a sequence of mask (8UC1)
+ images of the same size, where 255 indicates Foreground and 0 represents Background.
+ This class implements an algorithm described in "Visual Tracking of Human Visitors under
+ Variable-Lighting Conditions for a Responsive Audio Art Installation," A. Godbehere,
+ A. Matsukawa, K. Goldberg, American Control Conference, Montreal, June 2012.
  */
 class CV_EXPORTS_W BackgroundSubtractorGMG : public BackgroundSubtractor
 {
 public:
+    /** @brief Returns total number of distinct colors to maintain in histogram.
+    */
     CV_WRAP virtual int getMaxFeatures() const = 0;
+    /** @brief Sets total number of distinct colors to maintain in histogram.
+    */
     CV_WRAP virtual void setMaxFeatures(int maxFeatures) = 0;
 
+    /** @brief Returns the learning rate of the algorithm.
+
+    It lies between 0.0 and 1.0. It determines how quickly features are "forgotten" from
+    histograms.
+     */
     CV_WRAP virtual double getDefaultLearningRate() const = 0;
+    /** @brief Sets the learning rate of the algorithm.
+    */
     CV_WRAP virtual void setDefaultLearningRate(double lr) = 0;
 
+    /** @brief Returns the number of frames used to initialize background model.
+    */
     CV_WRAP virtual int getNumFrames() const = 0;
+    /** @brief Sets the number of frames used to initialize background model.
+    */
     CV_WRAP virtual void setNumFrames(int nframes) = 0;
 
+    /** @brief Returns the parameter used for quantization of color-space.
+
+    It is the number of discrete levels in each channel to be used in histograms.
+     */
     CV_WRAP virtual int getQuantizationLevels() const = 0;
+    /** @brief Sets the parameter used for quantization of color-space
+    */
     CV_WRAP virtual void setQuantizationLevels(int nlevels) = 0;
 
+    /** @brief Returns the prior probability that each individual pixel is a background pixel.
+    */
     CV_WRAP virtual double getBackgroundPrior() const = 0;
+    /** @brief Sets the prior probability that each individual pixel is a background pixel.
+    */
     CV_WRAP virtual void setBackgroundPrior(double bgprior) = 0;
 
+    /** @brief Returns the kernel radius used for morphological operations
+    */
     CV_WRAP virtual int getSmoothingRadius() const = 0;
+    /** @brief Sets the kernel radius used for morphological operations
+    */
     CV_WRAP virtual void setSmoothingRadius(int radius) = 0;
 
+    /** @brief Returns the value of decision threshold.
+
+    Decision value is the value above which pixel is determined to be FG.
+     */
     CV_WRAP virtual double getDecisionThreshold() const = 0;
+    /** @brief Sets the value of decision threshold.
+    */
     CV_WRAP virtual void setDecisionThreshold(double thresh) = 0;
 
+    /** @brief Returns the status of background model update
+    */
     CV_WRAP virtual bool getUpdateBackgroundModel() const = 0;
+    /** @brief Sets the status of background model update
+    */
     CV_WRAP virtual void setUpdateBackgroundModel(bool update) = 0;
 
+    /** @brief Returns the minimum value taken on by pixels in image sequence. Usually 0.
+    */
     CV_WRAP virtual double getMinVal() const = 0;
+    /** @brief Sets the minimum value taken on by pixels in image sequence.
+    */
     CV_WRAP virtual void setMinVal(double val) = 0;
 
+    /** @brief Returns the maximum value taken on by pixels in image sequence. e.g. 1.0 or 255.
+    */
     CV_WRAP virtual double getMaxVal() const = 0;
+    /** @brief Sets the maximum value taken on by pixels in image sequence.
+    */
     CV_WRAP virtual void setMaxVal(double val) = 0;
 };
 
+/** @brief Creates a GMG Background Subtractor
+
+@param initializationFrames number of frames used to initialize the background models.
+@param decisionThreshold Threshold value, above which it is marked foreground, else background.
+ */
 CV_EXPORTS_W Ptr<BackgroundSubtractorGMG> createBackgroundSubtractorGMG(int initializationFrames=120,
                                                                         double decisionThreshold=0.8);                                  
 
+//! @}
+
 }
 }
 

modules/bioinspired/doc/bioinspired.bib

@@ -0,0 +1,47 @@
+@article{Benoit2010,
+  title={Using human visual system modeling for bio-inspired low level image processing},
+  author={Benoit, Alexandre and Caplier, Alice and Durette, Barth{\'e}l{\'e}my and H{\'e}rault, Jeanny},
+  journal={Computer vision and Image understanding},
+  volume={114},
+  number={7},
+  pages={758--773},
+  year={2010},
+  publisher={Elsevier}
+}
+
+@inproceedings{Strat2013,
+  title={Retina enhanced SIFT descriptors for video indexing},
+  author={Strat, Sabin Tiberius and Benoit, Alexandre and Lambert, Patrick},
+  booktitle={Content-Based Multimedia Indexing (CBMI), 2013 11th International Workshop on},
+  pages={201--206},
+  year={2013},
+  organization={IEEE}
+}
+
+@book{Herault2010,
+  title={Vision: Images, Signals and Neural Networks-Models of Neural Processing in Visual Perception},
+  author={Jeanny, Herault},
+  year={2010},
+  publisher={World Scientific}
+}
+
+@inproceedings{Chaix2007,
+  title={Efficient demosaicing through recursive filtering},
+  author={De Lavar{\`e}ne, Brice Chaix and Alleysson, David and Durette, Barth{\'e}l{\'e}my and H{\'e}rault, Jeanny},
+  booktitle={Image Processing, 2007. ICIP 2007. IEEE International Conference on},
+  volume={2},
+  pages={II--189},
+  year={2007},
+  organization={IEEE}
+}
+
+@article{Meylan2007,
+  title={Model of retinal local adaptation for the tone mapping of color filter array images},
+  author={Meylan, Laurence and Alleysson, David and S{\"u}sstrunk, Sabine},
+  journal={JOSA A},
+  volume={24},
+  number={9},
+  pages={2807--2816},
+  year={2007},
+  publisher={Optical Society of America}
+}

modules/bioinspired/doc/bioinspired.rst

@@ -7,4 +7,4 @@ The module provides biological visual systems models (human visual system and ot
 .. toctree::
     :maxdepth: 2
 
-    Human retina documentation <retina/index>
+    Human retina documentation <retina>

modules/bioinspired/doc/retina.markdown

@@ -0,0 +1,223 @@
+Retina : a Bio mimetic human retina model {#bioinspired_retina}
+=========================================
+
+Retina
+------
+
+**Note** : do not forget that the retina model is included in the following namespace :
+*cv::bioinspired*.
+
+### Introduction
+
+Class which provides the main controls to 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
+such as @cite Chaix2007 and the log polar transformations of Barthelemy Durette described in Jeanny's
+book.
+
+**NOTES :**
+
+-   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.
+
+### Preliminary illustration
+
+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.](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 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)
+
+Below, a second retina foveal model output applied on the entire image with a parameters setup
+focused on naturalness perception. *"Hey, i now recognize my cat, looking at the mountains at the
+end of the day !"*. Here contours are enforced, luminance is corrected but halos are avoided with
+this configuration. The backlight effect is corrected and highlight details are still preserved.
+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 :
+
+-   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)
+
+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
+enforces all details of the visual scene. Luminance energy and 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 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.:
+
+    namespace cv{namespace bioinspired{
+
+    class Retina : public Algorithm
+    {
+    public:
+      // parameters setup instance
+      struct RetinaParameters; // this class is detailled later
+
+      // main method for input frame processing (all use method, can also perform High Dynamic Range tone mapping)
+      void run (InputArray inputImage);
+
+      // specific method aiming at correcting luminance only (faster High Dynamic Range tone mapping)
+      void applyFastToneMapping(InputArray inputImage, OutputArray outputToneMappedImage)
+
+      // output buffers retreival methods
+      // -> foveal color vision details channel with luminance and noise correction
+      void getParvo (OutputArray retinaOutput_parvo);
+      void getParvoRAW (OutputArray retinaOutput_parvo);// retreive original output buffers without any normalisation
+      const Mat getParvoRAW () const;// retreive original output buffers without any normalisation
+      // -> peripheral monochrome motion and events (transient information) channel
+      void getMagno (OutputArray retinaOutput_magno);
+      void getMagnoRAW (OutputArray retinaOutput_magno); // retreive original output buffers without any normalisation
+      const Mat getMagnoRAW () const;// retreive original output buffers without any normalisation
+
+      // reset retina buffers... equivalent to closing your eyes for some seconds
+      void clearBuffers ();
+
+      // retreive input and output buffers sizes
+      Size getInputSize ();
+      Size getOutputSize ();
+
+      // setup methods with specific parameters specification of global xml config file loading/write
+      void setup (String retinaParameterFile="", const bool applyDefaultSetupOnFailure=true);
+      void setup (FileStorage &fs, const bool applyDefaultSetupOnFailure=true);
+      void setup (RetinaParameters newParameters);
+      struct Retina::RetinaParameters getParameters ();
+      const String printSetup ();
+      virtual void write (String fs) const;
+      virtual void write (FileStorage &fs) const;
+      void setupOPLandIPLParvoChannel (const bool colorMode=true, const bool normaliseOutput=true, const float photoreceptorsLocalAdaptationSensitivity=0.7, const float photoreceptorsTemporalConstant=0.5, const float photoreceptorsSpatialConstant=0.53, const float horizontalCellsGain=0, const float HcellsTemporalConstant=1, const float HcellsSpatialConstant=7, const float ganglionCellsSensitivity=0.7);
+      void setupIPLMagnoChannel (const bool normaliseOutput=true, const float parasolCells_beta=0, const float parasolCells_tau=0, const float parasolCells_k=7, const float amacrinCellsTemporalCutFrequency=1.2, const float V0CompressionParameter=0.95, const float localAdaptintegration_tau=0, const float localAdaptintegration_k=7);
+      void setColorSaturation (const bool saturateColors=true, const float colorSaturationValue=4.0);
+      void activateMovingContoursProcessing (const bool activate);
+      void activateContoursProcessing (const bool activate);
+    };
+
+      // Allocators
+      cv::Ptr<Retina> createRetina (Size inputSize);
+      cv::Ptr<Retina> createRetina (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);
+      }} // cv and bioinspired namespaces end
+
+### Description
+
+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:
+
+-   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
+
+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.
+
+Literature
+----------
+
+For more information, refer to the following papers :
+
+-   Model description :
+
+[Benoit2010] 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>
+
+-   Model use in a Bag of Words approach :
+
+[Strat2013] Strat S., Benoit A., Lambert P., "Retina enhanced SIFT descriptors for video indexing", CBMI2013, Veszprém, Hungary, 2013.
+
+-   Please have a look at the reference work of Jeanny Herault that you can read in his book :
+
+[Herault2010] 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.
+
+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:
+
+[Chaix2007] 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.
+
+-   Meylan&al work on HDR tone mapping that is implemented as a specific method within the model :
+
+[Meylan2007] L. Meylan , D. Alleysson, S. Susstrunk, "A Model of Retinal Local Adaptation for the Tone Mapping of Color Filter Array Images", Journal of Optical Society of America, A, Vol. 24, N 9, September, 1st, 2007, pp. 2807-2816
+
+Demos and experiments !
+-----------------------
+
+**NOTE : Complementary to the following examples, have a look at the Retina tutorial in the
+tutorial/contrib section for complementary explanations.**
+
+Take a look at the provided C++ examples provided with OpenCV :
+
+-  **samples/cpp/retinademo.cpp** shows how to use the retina module for details enhancement (Parvo channel output) and transient maps observation (Magno channel output). You can play with images, video sequences and webcam video.
+   Typical uses are (provided your OpenCV installation is situated in folder
+        *OpenCVReleaseFolder*)
+
+        -   image processing : **OpenCVReleaseFolder/bin/retinademo -image myPicture.jpg**
+        -   video processing : **OpenCVReleaseFolder/bin/retinademo -video myMovie.avi**
+        -   webcam processing: **OpenCVReleaseFolder/bin/retinademo -video**
+
+    **Note :** This demo generates the file *RetinaDefaultParameters.xml* which contains the
+    default parameters of the retina. Then, rename this as *RetinaSpecificParameters.xml*, adjust
+    the parameters the way you want and reload the program to check the effect.
+
+-   **samples/cpp/OpenEXRimages\_HDR\_Retina\_toneMapping.cpp** shows how to use the retina to
+    perform High Dynamic Range (HDR) luminance compression
+
+    Then, take a HDR image using bracketing with your camera and generate an OpenEXR image and
+    then process it using the demo.
+
+    Typical use, supposing that you have the OpenEXR image such as *memorial.exr* (present in the
+    samples/cpp/ folder)
+
+-   **OpenCVReleaseFolder/bin/OpenEXRimages\_HDR\_Retina\_toneMapping memorial.exr [optional:
+    'fast']**
+
+    Note that some sliders are made available to allow you to play with luminance compression.
+
+    If not using the 'fast' option, then, tone mapping is performed using the full retina model
+    @cite Benoit2010. It includes spectral whitening that allows luminance energy to be reduced.
+    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.hpp

@@ -47,4 +47,14 @@
 #include "opencv2/bioinspired/retina.hpp"
 #include "opencv2/bioinspired/retinafasttonemapping.hpp"
 #include "opencv2/bioinspired/transientareassegmentationmodule.hpp"
+
+/** @defgroup bioinspired Biologically inspired vision models and derivated tools
+
+The module provides biological visual systems models (human visual system and others). It also
+provides derivated objects that take advantage of those bio-inspired models.
+
+@ref bioinspired_retina
+
+*/
+
 #endif

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

@@ -65,12 +65,11 @@
 #ifndef __OPENCV_BIOINSPIRED_RETINA_HPP__
 #define __OPENCV_BIOINSPIRED_RETINA_HPP__
 
-/*
- * Retina.hpp
- *
- *  Created on: Jul 19, 2011
- *      Author: Alexandre Benoit
- */
+/**
+@file
+@date Jul 19, 2011
+@author Alexandre Benoit
+*/
 
 #include "opencv2/core.hpp" // for all OpenCV core functionalities access, including cv::Exception support
 
@@ -78,42 +77,104 @@
 namespace cv{
 namespace bioinspired{
 
+//! @addtogroup bioinspired
+//! @{
+
 enum {
     RETINA_COLOR_RANDOM, //!< each pixel position is either R, G or B in a random choice
     RETINA_COLOR_DIAGONAL,//!< color sampling is RGBRGBRGB..., line 2 BRGBRGBRG..., line 3, GBRGBRGBR...
     RETINA_COLOR_BAYER//!< standard bayer sampling
 };
 
-/**
- * a wrapper 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.
+/** @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:
 
-    // parameters structure for better clarity, check explenations on the comments of methods : setupOPLandIPLParvoChannel and setupIPLMagnoChannel
+    /** @brief parameters structure
+
+    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.
+
+    @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.3e-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
+
+    Here is the 'realistic" setup used to obtain the second retina output shown on the top of this page.
+
+    @code{xml}
+    <?xml version="1.0"?>
+    <opencv_storage>
+    <OPLandIPLparvo>
+      <colorMode>1</colorMode>
+      <normaliseOutput>1</normaliseOutput>
+      <photoreceptorsLocalAdaptationSensitivity>8.9e-01</photoreceptorsLocalAdaptationSensitivity>
+      <photoreceptorsTemporalConstant>9.0e-01</photoreceptorsTemporalConstant>
+      <photoreceptorsSpatialConstant>5.3e-01</photoreceptorsSpatialConstant>
+      <horizontalCellsGain>0.3</horizontalCellsGain>
+      <hcellsTemporalConstant>0.5</hcellsTemporalConstant>
+      <hcellsSpatialConstant>7.</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>2.0e+00</amacrinCellsTemporalCutFrequency>
+      <V0CompressionParameter>9.5e-01</V0CompressionParameter>
+      <localAdaptintegration_tau>0.</localAdaptintegration_tau>
+      <localAdaptintegration_k>7.</localAdaptintegration_k></IPLmagno>
+    </opencv_storage>
+    @endcode
+      */
     struct CV_EXPORTS_W RetinaParameters{
-        struct CV_EXPORTS_W OPLandIplParvoParameters{ // Outer Plexiform Layer (OPL) and Inner Plexiform Layer Parvocellular (IplParvo) parameters
+        //! Outer Plexiform Layer (OPL) and Inner Plexiform Layer Parvocellular (IplParvo) parameters
+        struct CV_EXPORTS_W OPLandIplParvoParameters{
                OPLandIplParvoParameters():colorMode(true),
                                  normaliseOutput(true),
                                  photoreceptorsLocalAdaptationSensitivity(0.75f),
@@ -126,7 +187,8 @@ public:
                CV_PROP_RW bool colorMode, normaliseOutput;
                CV_PROP_RW float photoreceptorsLocalAdaptationSensitivity, photoreceptorsTemporalConstant, photoreceptorsSpatialConstant, horizontalCellsGain, hcellsTemporalConstant, hcellsSpatialConstant, ganglionCellsSensitivity;
         };
-        struct CV_EXPORTS_W IplMagnoParameters{ // Inner Plexiform Layer Magnocellular channel (IplMagno)
+        //! Inner Plexiform Layer Magnocellular channel (IplMagno)
+        struct CV_EXPORTS_W IplMagnoParameters{
             IplMagnoParameters():
                           normaliseOutput(true),
                           parasolCells_beta(0.f),
@@ -143,170 +205,267 @@ public:
         CV_PROP_RW IplMagnoParameters IplMagno;
     };
 
-    /**
-    * retreive retina input buffer size
-    */
+    /** @brief Retreive retina input buffer size
+    @return the retina input buffer size
+     */
     CV_WRAP virtual Size getInputSize()=0;
 
-    /**
-    * retreive retina output buffer size
-    */
+    /** @brief Retreive retina output buffer size that can be different from the input if a spatial log
+    transformation is applied
+    @return the retina output buffer size
+     */
     CV_WRAP virtual Size getOutputSize()=0;
 
-    /**
-     * 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 retinaParameterFile : the parameters filename
-         * @param applyDefaultSetupOnFailure : set to true if an error must be thrown on error
+    /** @brief 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 retinaParameterFile the parameters filename
+    @param applyDefaultSetupOnFailure set to true if an error must be thrown on error
+    You can retreive the current parameers structure using method Retina::getParameters and update
+    it before running method Retina::setup
      */
     CV_WRAP virtual void setup(String retinaParameterFile="", const bool applyDefaultSetupOnFailure=true)=0;
 
-    /**
-     * 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 fs : the open Filestorage which contains retina parameters
-     * @param applyDefaultSetupOnFailure : set to true if an error must be thrown on error
-     */
+    /** @overload
+    @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;
 
-    /**
-     * 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
-     */
+    /** @overload
+    @param newParameters a parameters structures updated with the new target configuration.
+    */
     CV_WRAP virtual void setup(RetinaParameters newParameters)=0;
 
     /**
-    * @return the current parameters setup
+   @return the current parameters setup
     */
     CV_WRAP virtual RetinaParameters getParameters()=0;
 
-    /**
-     * parameters setup display method
-     * @return a string which contains formatted parameters information
+    /** @brief Outputs a string showing the used parameters setup
+    @return a string which contains formated parameters information
      */
     CV_WRAP virtual const String printSetup()=0;
 
-    /**
-     * write xml/yml formated parameters information
-     * @param fs : the filename of the xml file that will be open and writen with formatted parameters information
+    /** @brief Write xml/yml formated parameters information
+    @param fs the filename of the xml file that will be open and writen with formatted parameters
+    information
      */
     CV_WRAP virtual void write( String fs ) const=0;
 
-    /**
-     * write xml/yml formated parameters information
-     * @param fs : a cv::Filestorage object ready to be filled
-         */
+    /** @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
+    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
+     */
+
+    /** @brief 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 a part of the
+    Inner Plexiform layer of the retina, it allows high contours sensitivity in foveal vision. See
+    reference papers for more informations.
+    @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 0.6 and 1 for best results, a high value increases more the low
+    value sensitivity... and the output saturates faster, recommended value: 0.7
      */
     CV_WRAP virtual void setupOPLandIPLParvoChannel(const bool colorMode=true, const bool normaliseOutput = true, const float photoreceptorsLocalAdaptationSensitivity=0.7, const float photoreceptorsTemporalConstant=0.5, const float photoreceptorsSpatialConstant=0.53, const float horizontalCellsGain=0, const float HcellsTemporalConstant=1, const float HcellsSpatialConstant=7, const float ganglionCellsSensitivity=0.7)=0;
 
-    /**
-     * set parameters values for the Inner Plexiform Layer (IPL) magnocellular channel
-     * this channel processes signals outpint from OPL processing stage in peripheral vision, it allows motion information enhancement. It is decorrelated from the details channel. See reference paper for more details.
-     * @param normaliseOutput : specifies if (true) output is rescaled between 0 and 255 of not (false)
-     * @param parasolCells_beta: the low pass filter gain used for local contrast adaptation at the IPL level of the retina (for ganglion cells local adaptation), typical value is 0
-     * @param parasolCells_tau: the low pass filter time constant used for local contrast adaptation at the IPL level of the retina (for ganglion cells local adaptation), unit is frame, typical value is 0 (immediate response)
-     * @param parasolCells_k: the low pass filter spatial constant used for local contrast adaptation at the IPL level of the retina (for ganglion cells local adaptation), unit is pixels, typical value is 5
-     * @param amacrinCellsTemporalCutFrequency: the time constant of the first order high pass fiter of the magnocellular way (motion information channel), unit is frames, tipicall value is 5
-     * @param V0CompressionParameter: 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: 200
-     * @param localAdaptintegration_tau: specifies the temporal constant of the low pas filter involved in the computation of the local "motion mean" for the local adaptation computation
-     * @param localAdaptintegration_k: specifies the spatial constant of the low pas filter involved in the computation of the local "motion mean" for the local adaptation computation
+    /** @brief Set parameters values for the Inner Plexiform Layer (IPL) magnocellular channel
+
+    this channel processes signals output from OPL processing stage in peripheral vision, it allows
+    motion information enhancement. It is decorrelated from the details channel. See reference
+    papers for more details.
+
+    @param normaliseOutput specifies if (true) output is rescaled between 0 and 255 of not (false)
+    @param parasolCells_beta the low pass filter gain used for local contrast adaptation at the
+    IPL level of the retina (for ganglion cells local adaptation), typical value is 0
+    @param parasolCells_tau the low pass filter time constant used for local contrast adaptation
+    at the IPL level of the retina (for ganglion cells local adaptation), unit is frame, typical
+    value is 0 (immediate response)
+    @param parasolCells_k the low pass filter spatial constant used for local contrast adaptation
+    at the IPL level of the retina (for ganglion cells local adaptation), unit is pixels, typical
+    value is 5
+    @param amacrinCellsTemporalCutFrequency the time constant of the first order high pass fiter of
+    the magnocellular way (motion information channel), unit is frames, typical value is 1.2
+    @param V0CompressionParameter the compression strengh of the ganglion cells local adaptation
+    output, set a value between 0.6 and 1 for best results, a high value increases more the low
+    value sensitivity... and the output saturates faster, recommended value: 0.95
+    @param localAdaptintegration_tau specifies the temporal constant of the low pas filter
+    involved in the computation of the local "motion mean" for the local adaptation computation
+    @param localAdaptintegration_k specifies the spatial constant of the low pas filter involved
+    in the computation of the local "motion mean" for the local adaptation computation
      */
     CV_WRAP virtual void setupIPLMagnoChannel(const bool normaliseOutput = true, const float parasolCells_beta=0, const float parasolCells_tau=0, const float parasolCells_k=7, const float amacrinCellsTemporalCutFrequency=1.2, const float V0CompressionParameter=0.95, const float localAdaptintegration_tau=0, const float localAdaptintegration_k=7)=0;
 
-    /**
-     * method which allows retina to be applied on an input image, after run, encapsulated retina module is ready to deliver its outputs using dedicated acccessors, see getParvo and getMagno methods
-     * @param inputImage : the input cv::Mat image to be processed, can be gray level or BGR coded in any format (from 8bit to 16bits)
+    /** @brief Method which allows retina to be applied on an input image,
+
+    after run, encapsulated retina module is ready to deliver its outputs using dedicated
+    acccessors, see getParvo and getMagno methods
+    @param inputImage the input Mat image to be processed, can be gray level or BGR coded in any
+    format (from 8bit to 16bits)
      */
     CV_WRAP virtual void run(InputArray inputImage)=0;
 
-    /**
-     * method that applies a luminance correction (initially High Dynamic Range (HDR) tone mapping) using only the 2 local adaptation stages of the retina parvo channel : photoreceptors level and ganlion cells level. Spatio temporal filtering is applied but limited to temporal smoothing and eventually high frequencies attenuation. This is a lighter method than the one available using the regular run method. It is then faster but it does not include complete temporal filtering nor retina spectral whitening. Then, it can have a more limited effect on images with a very high dynamic range. This is an adptation of the original still image HDR tone mapping algorithm of David Alleyson, Sabine Susstruck and Laurence Meylan's work, please cite:
-    * -> Meylan L., Alleysson D., and Susstrunk S., A Model of Retinal Local Adaptation for the Tone Mapping of Color Filter Array Images, Journal of Optical Society of America, A, Vol. 24, N 9, September, 1st, 2007, pp. 2807-2816
-     @param inputImage the input image to process RGB or gray levels
-     @param outputToneMappedImage the output tone mapped image
+    /** @brief Method which processes an image in the aim to correct its luminance correct
+    backlight problems, enhance details in shadows.
+
+    This method is designed to perform High Dynamic Range image tone mapping (compress \>8bit/pixel
+    images to 8bit/pixel). This is a simplified version of the Retina Parvocellular model
+    (simplified version of the run/getParvo methods call) since it does not include the
+    spatio-temporal filter modelling the Outer Plexiform Layer of the retina that performs spectral
+    whitening and many other stuff. However, it works great for tone mapping and in a faster way.
+
+    Check the demos and experiments section to see examples and the way to perform tone mapping
+    using the original retina model and the method.
+
+    @param inputImage the input image to process (should be coded in float format : CV_32F,
+    CV_32FC1, CV_32F_C3, CV_32F_C4, the 4th channel won't be considered).
+    @param outputToneMappedImage the output 8bit/channel tone mapped image (CV_8U or CV_8UC3 format).
      */
     CV_WRAP virtual void applyFastToneMapping(InputArray inputImage, OutputArray outputToneMappedImage)=0;
 
-    /**
-     * accessor of the details channel of the retina (models foveal vision)
-     * @param retinaOutput_parvo : the output buffer (reallocated if necessary), this output is rescaled for standard 8bits image processing use in OpenCV
+    /** @brief Accessor of the details channel of the retina (models foveal vision).
+
+    Warning, getParvoRAW methods return buffers that are not rescaled within range [0;255] while
+    the non RAW method allows a normalized matrix to be retrieved.
+
+    @param retinaOutput_parvo the output buffer (reallocated if necessary), format can be :
+    -   a Mat, this output is rescaled for standard 8bits image processing use in OpenCV
+    -   RAW methods actually return a 1D matrix (encoding is R1, R2, ... Rn, G1, G2, ..., Gn, B1,
+    B2, ...Bn), this output is the original retina filter model output, without any
+    quantification or rescaling.
+    @see getParvoRAW
      */
     CV_WRAP virtual void getParvo(OutputArray retinaOutput_parvo)=0;
 
-    /**
-     * accessor of the details channel of the retina (models foveal vision)
-     * @param retinaOutput_parvo : a cv::Mat header filled with the internal parvo buffer of the retina module. This output is the original retina filter model output, without any quantification or rescaling
+    /** @brief Accessor of the details channel of the retina (models foveal vision).
+    @see getParvo
      */
     CV_WRAP virtual void getParvoRAW(OutputArray retinaOutput_parvo)=0;
 
-    /**
-     * accessor of the motion channel of the retina (models peripheral vision)
-     * @param retinaOutput_magno : the output buffer (reallocated if necessary), this output is rescaled for standard 8bits image processing use in OpenCV
+    /** @brief Accessor of the motion channel of the retina (models peripheral vision).
+
+    Warning, getMagnoRAW methods return buffers that are not rescaled within range [0;255] while
+    the non RAW method allows a normalized matrix to be retrieved.
+    @param retinaOutput_magno the output buffer (reallocated if necessary), format can be :
+    -   a Mat, this output is rescaled for standard 8bits image processing use in OpenCV
+    -   RAW methods actually return a 1D matrix (encoding is M1, M2,... Mn), this output is the
+    original retina filter model output, without any quantification or rescaling.
+    @see getMagnoRAW
      */
     CV_WRAP virtual void getMagno(OutputArray retinaOutput_magno)=0;
 
-    /**
-     * accessor of the motion channel of the retina (models peripheral vision)
-     * @param retinaOutput_magno : a cv::Mat header filled with the internal retina magno buffer of the retina module. This output is the original retina filter model output, without any quantification or rescaling
+    /** @brief Accessor of the motion channel of the retina (models peripheral vision).
+    @see getMagno
      */
     CV_WRAP virtual void getMagnoRAW(OutputArray retinaOutput_magno)=0;
 
-    // original API level data accessors : get buffers addresses from a Mat header, similar to getParvoRAW and getMagnoRAW...
+    /** @overload */
     CV_WRAP virtual const Mat getMagnoRAW() const=0;
+    /** @overload */
     CV_WRAP virtual const Mat getParvoRAW() const=0;
 
-    /**
-     * activate color saturation as the final step of the color demultiplexing process
-     * -> this saturation is a sigmoide function applied to each channel of the demultiplexed image.
-     * @param saturateColors: boolean that activates color saturation (if true) or desactivate (if false)
-     * @param colorSaturationValue: the saturation factor
+    /** @brief Activate color saturation as the final step of the color demultiplexing process -\> this
+    saturation is a sigmoide function applied to each channel of the demultiplexed image.
+    @param saturateColors boolean that activates color saturation (if true) or desactivate (if false)
+    @param colorSaturationValue the saturation factor : a simple factor applied on the chrominance
+    buffers
      */
     CV_WRAP virtual void setColorSaturation(const bool saturateColors=true, const float colorSaturationValue=4.0)=0;
 
-    /**
-     * clear all retina buffers (equivalent to opening the eyes after a long period of eye close ;o)
+    /** @brief Clears all retina buffers
+
+    (equivalent to opening the eyes after a long period of eye close ;o) whatchout the temporal
+    transition occuring just after this method call.
      */
     CV_WRAP virtual void clearBuffers()=0;
 
-    /**
-    * Activate/desactivate the Magnocellular pathway processing (motion information extraction), by default, it is activated
-    * @param activate: true if Magnocellular output should be activated, false if not
-    */
+    /** @brief Activate/desactivate the Magnocellular pathway processing (motion information extraction), by
+    default, it is activated
+    @param activate true if Magnocellular output should be activated, false if not... if activated,
+    the Magnocellular output can be retrieved using the **getMagno** methods
+     */
     CV_WRAP virtual void activateMovingContoursProcessing(const bool activate)=0;
 
-    /**
-    * Activate/desactivate the Parvocellular pathway processing (contours information extraction), by default, it is activated
-    * @param activate: true if Parvocellular (contours information extraction) output should be activated, false if not
-    */
+    /** @brief Activate/desactivate the Parvocellular pathway processing (contours information extraction), by
+    default, it is activated
+    @param activate true if Parvocellular (contours information extraction) output should be
+    activated, false if not... if activated, the Parvocellular output can be retrieved using the
+    Retina::getParvo methods
+     */
     CV_WRAP virtual void activateContoursProcessing(const bool activate)=0;
 };
+
+//! @relates bioinspired::Retina
+//! @{
+
+/** @overload */
 CV_EXPORTS_W Ptr<Retina> createRetina(Size inputSize);
+/** @brief Constructors from standardized interfaces : retreive a smart pointer to a Retina instance
+
+@param inputSize the input frame size
+@param colorMode the chosen processing mode : with or without color processing
+@param colorSamplingMethod specifies which kind of color sampling will be used :
+-   cv::bioinspired::RETINA_COLOR_RANDOM: each pixel position is either R, G or B in a random choice
+-   cv::bioinspired::RETINA_COLOR_DIAGONAL: color sampling is RGBRGBRGB..., line 2 BRGBRGBRG..., line 3, GBRGBRGBR...
+-   cv::bioinspired::RETINA_COLOR_BAYER: standard bayer sampling
+@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
+ */
 CV_EXPORTS_W Ptr<Retina> createRetina(Size inputSize, const bool colorMode, int colorSamplingMethod=RETINA_COLOR_BAYER, const bool useRetinaLogSampling=false, const double reductionFactor=1.0, const double samplingStrenght=10.0);
 
 #ifdef HAVE_OPENCV_OCL
 Ptr<Retina> createRetina_OCL(Size inputSize);
 Ptr<Retina> createRetina_OCL(Size inputSize, const bool colorMode, int colorSamplingMethod=RETINA_COLOR_BAYER, const bool useRetinaLogSampling=false, const double reductionFactor=1.0, const double samplingStrenght=10.0);
 #endif
+
+//! @}
+
+//! @}
+
 }
 }
 #endif /* __OPENCV_BIOINSPIRED_RETINA_HPP__ */

modules/bioinspired/include/opencv2/bioinspired/retinafasttonemapping.hpp

@@ -67,11 +67,10 @@
 #ifndef __OPENCV_BIOINSPIRED_RETINAFASTTONEMAPPING_HPP__
 #define __OPENCV_BIOINSPIRED_RETINAFASTTONEMAPPING_HPP__
 
-/*
- * retinafasttonemapping.hpp
- *
- *  Created on: May 26, 2013
- *      Author: Alexandre Benoit
+/**
+@file
+@date May 26, 2013
+@author Alexandre Benoit
  */
 
 #include "opencv2/core.hpp" // for all OpenCV core functionalities access, including cv::Exception support
@@ -79,43 +78,61 @@
 namespace cv{
 namespace bioinspired{
 
-/**
- * a wrapper class which allows the tone mapping algorithm of Meylan&al(2007) to be used with OpenCV.
- * This algorithm is already implemented in thre Retina class (retina::applyFastToneMapping) but used it does not require all the retina model to be allocated. This allows a light memory use for low memory devices (smartphones, etc.
- * As a summary, these are the model properties:
- * => 2 stages of local luminance adaptation with a different local neighborhood for each.
- * => first stage models the retina photorecetors local luminance adaptation
- * => second stage models th ganglion cells local information adaptation
- * => compared to the initial publication, this class uses spatio-temporal low pass filters instead of spatial only filters.
- * ====> this can help noise robustness and temporal stability for video sequence use cases.
- * for more information, read to the following papers :
- *  Meylan L., Alleysson D., and Susstrunk S., A Model of Retinal Local Adaptation for the Tone Mapping of Color Filter Array Images, Journal of Optical Society of America, A, Vol. 24, N 9, September, 1st, 2007, pp. 2807-2816Benoit 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
- * regarding spatio-temporal filter and the bigger retina model :
- * 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.
- */
+//! @addtogroup bioinspired
+//! @{
+
+/** @brief  a wrapper class which allows the tone mapping algorithm of Meylan&al(2007) to be used with OpenCV.
+
+This algorithm is already implemented in thre Retina class (retina::applyFastToneMapping) but used it does not require all the retina model to be allocated. This allows a light memory use for low memory devices (smartphones, etc.
+As a summary, these are the model properties:
+- 2 stages of local luminance adaptation with a different local neighborhood for each.
+- first stage models the retina photorecetors local luminance adaptation
+- second stage models th ganglion cells local information adaptation
+- compared to the initial publication, this class uses spatio-temporal low pass filters instead of spatial only filters.
+  this can help noise robustness and temporal stability for video sequence use cases.
+
+for more information, read to the following papers :
+Meylan L., Alleysson D., and Susstrunk S., A Model of Retinal Local Adaptation for the Tone Mapping of Color Filter Array Images, Journal of Optical Society of America, A, Vol. 24, N 9, September, 1st, 2007, pp. 2807-2816Benoit 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
+regarding spatio-temporal filter and the bigger retina model :
+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.
+*/
 class CV_EXPORTS_W RetinaFastToneMapping : public Algorithm
 {
 public:
 
-    /**
-     * method that applies a luminance correction (initially High Dynamic Range (HDR) tone mapping) using only the 2 local adaptation stages of the retina parvocellular channel : photoreceptors level and ganlion cells level. Spatio temporal filtering is applied but limited to temporal smoothing and eventually high frequencies attenuation. This is a lighter method than the one available using the regular retina::run method. It is then faster but it does not include complete temporal filtering nor retina spectral whitening. Then, it can have a more limited effect on images with a very high dynamic range. This is an adptation of the original still image HDR tone mapping algorithm of David Alleyson, Sabine Susstruck and Laurence Meylan's work, please cite:
-    * -> Meylan L., Alleysson D., and Susstrunk S., A Model of Retinal Local Adaptation for the Tone Mapping of Color Filter Array Images, Journal of Optical Society of America, A, Vol. 24, N 9, September, 1st, 2007, pp. 2807-2816
-     @param inputImage the input image to process RGB or gray levels
-     @param outputToneMappedImage the output tone mapped image
-     */
+    /** @brief applies a luminance correction (initially High Dynamic Range (HDR) tone mapping)
+
+    using only the 2 local adaptation stages of the retina parvocellular channel : photoreceptors
+    level and ganlion cells level. Spatio temporal filtering is applied but limited to temporal
+    smoothing and eventually high frequencies attenuation. This is a lighter method than the one
+    available using the regular retina::run method. It is then faster but it does not include
+    complete temporal filtering nor retina spectral whitening. Then, it can have a more limited
+    effect on images with a very high dynamic range. This is an adptation of the original still
+    image HDR tone mapping algorithm of David Alleyson, Sabine Susstruck and Laurence Meylan's
+    work, please cite: -> Meylan L., Alleysson D., and Susstrunk S., A Model of Retinal Local
+    Adaptation for the Tone Mapping of Color Filter Array Images, Journal of Optical Society of
+    America, A, Vol. 24, N 9, September, 1st, 2007, pp. 2807-2816
+
+    @param inputImage the input image to process RGB or gray levels
+    @param outputToneMappedImage the output tone mapped image
+    */
     CV_WRAP virtual void applyFastToneMapping(InputArray inputImage, OutputArray outputToneMappedImage)=0;
 
-    /**
-     * setup method that updates tone mapping behaviors by adjusing the local luminance computation area
-     * @param photoreceptorsNeighborhoodRadius the first stage local adaptation area
-     * @param ganglioncellsNeighborhoodRadius the second stage local adaptation area
-     * @param meanLuminanceModulatorK the factor applied to modulate the meanLuminance information (default is 1, see reference paper)
+    /** @brief updates tone mapping behaviors by adjusing the local luminance computation area
+
+    @param photoreceptorsNeighborhoodRadius the first stage local adaptation area
+    @param ganglioncellsNeighborhoodRadius the second stage local adaptation area
+    @param meanLuminanceModulatorK the factor applied to modulate the meanLuminance information
+    (default is 1, see reference paper)
      */
     CV_WRAP virtual void setup(const float photoreceptorsNeighborhoodRadius=3.f, const float ganglioncellsNeighborhoodRadius=1.f, const float meanLuminanceModulatorK=1.f)=0;
 };
 
+//! @relates bioinspired::RetinaFastToneMapping
 CV_EXPORTS_W Ptr<RetinaFastToneMapping> createRetinaFastToneMapping(Size inputSize);
 
+//! @}
+
 }
 }
 #endif /* __OPENCV_BIOINSPIRED_RETINAFASTTONEMAPPING_HPP__ */

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

@@ -63,18 +63,10 @@
 #define SEGMENTATIONMODULE_HPP_
 
 /**
- * @class TransientAreasSegmentationModule
- * @brief class which provides a transient/moving areas segmentation module
- * -> perform a locally adapted segmentation by using the retina magno input data
- * @author Alexandre BENOIT, benoit.alexandre.vision@gmail.com
- * Release date 2007-2013
- * Based on Alexandre BENOIT thesis: "Le système visuel humain au secours de la vision par ordinateur"
- * -> 3 spatio temporal filters are used:
- * a first one which filters the noise and local variations of the input motion energy
- * a second (more powerfull low pass spatial filter) which gives the neighborhood motion energy
- * -> the segmentation consists in the comparison of these both outputs, if the local motion energy is higher to the neighborhood otion energy, then the area is considered as moving and is segmented
- * => a stronger third low pass filter helps decision by providing a smooth information about the "motion context" in a wider area
- */
+@file
+@date 2007-2013
+@author Alexandre BENOIT, benoit.alexandre.vision@gmail.com
+*/
 
 #include "opencv2/core.hpp" // for all OpenCV core functionalities access, including cv::Exception support
 
@@ -83,108 +75,125 @@ namespace cv
 namespace bioinspired
 {
 
+//! @addtogroup bioinspired
+//! @{
+
+/** @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
+BENOIT thesis: "Le système visuel humain au secours de la vision par ordinateur"
+
+3 spatio temporal filters are used:
+- a first one which filters the noise and local variations of the input motion energy
+- a second (more powerfull low pass spatial filter) which gives the neighborhood motion energy the
+segmentation consists in the comparison of these both outputs, if the local motion energy is higher
+to the neighborhood otion energy, then the area is considered as moving and is segmented
+- a stronger third low pass filter helps decision by providing a smooth information about the
+"motion context" in a wider area
+ */
+
 class CV_EXPORTS_W TransientAreasSegmentationModule: public Algorithm
 {
 public:
 
-    // parameters structure
+    //! parameters structure
     struct CV_EXPORTS_W SegmentationParameters{
         SegmentationParameters():
             thresholdON(100),
             thresholdOFF(100),
-            // local energy filtering parameters : the aim is to smooth local textures and residual noise
-            localEnergy_temporalConstant(0.5), // 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
-            localEnergy_spatialConstant(5), // 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
-            // local neighborhood energy filtering parameters : the aim is to get information about the energy neighborhood to perform a center surround energy analysis
+            localEnergy_temporalConstant(0.5),
+            localEnergy_spatialConstant(5),
             neighborhoodEnergy_temporalConstant(1),
             neighborhoodEnergy_spatialConstant(15),
-            // context neighborhood energy filtering parameters : the aim is to get information about the energy on a wide neighborhood area to filtered out local effects
             contextEnergy_temporalConstant(1),
             contextEnergy_spatialConstant(75){};// default setup
-        CV_PROP_RW float thresholdON, thresholdOFF;
-        CV_PROP_RW float localEnergy_temporalConstant, localEnergy_spatialConstant;
-        CV_PROP_RW float neighborhoodEnergy_temporalConstant, neighborhoodEnergy_spatialConstant;
-        CV_PROP_RW float contextEnergy_temporalConstant, contextEnergy_spatialConstant;
+        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;
     };
 
-    /**
-     * @return the sze of the manage input and output images
-     */
+    /** @brief return the sze of the manage input and output images
+    */
     CV_WRAP virtual Size getSize()=0;
 
-    /**
-     * try to open an XML segmentation parameters file to adjust current segmentation 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 segmentationParameterFile : the parameters filename
-     * @param applyDefaultSetupOnFailure : set to true if an error must be thrown on error
+    /** @brief try to open an XML segmentation parameters file to adjust current segmentation 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 segmentationParameterFile : the parameters filename
+    @param applyDefaultSetupOnFailure : set to true if an error must be thrown on error
      */
     CV_WRAP virtual void setup(String segmentationParameterFile="", const bool applyDefaultSetupOnFailure=true)=0;
 
-    /**
-     * try to open an XML segmentation parameters file to adjust current segmentation 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 fs : the open Filestorage which contains segmentation parameters
-     * @param applyDefaultSetupOnFailure : set to true if an error must be thrown on error
-     */
+    /** @brief try to open an XML segmentation parameters file to adjust current segmentation 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 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;
 
-    /**
-     * try to open an XML segmentation parameters file to adjust current segmentation 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
+    /** @brief try to open an XML segmentation parameters file to adjust current segmentation 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
      */
     CV_WRAP virtual void setup(SegmentationParameters newParameters)=0;
 
-    /**
-     * @return the current parameters setup
-     */
+    /** @brief return the current parameters setup
+    */
     CV_WRAP virtual SegmentationParameters getParameters()=0;
 
-    /**
-     * parameters setup display method
-     * @return a string which contains formatted parameters information
-     */
+    /** @brief parameters setup display method
+    @return a string which contains formatted parameters information
+    */
     CV_WRAP virtual const String printSetup()=0;
 
-    /**
-     * write xml/yml formated parameters information
-     * @param fs : the filename of the xml file that will be open and writen with formatted parameters information
-     */
+    /** @brief write xml/yml formated parameters information
+    @param fs : the filename of the xml file that will be open and writen with formatted parameters information
+    */
     CV_WRAP virtual void write( String fs ) const=0;
 
-    /**
-     * write xml/yml formated parameters information
-     * @param fs : a cv::Filestorage object ready to be filled
-         */
+    /** @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;
 
-    /**
-     * main processing method, get result using methods getSegmentationPicture()
-     * @param inputToSegment : the image to process, it must match the instance buffer size !
-     * @param channelIndex : the channel to process in case of multichannel images
-     */
+    /** @brief main processing method, get result using methods getSegmentationPicture()
+    @param inputToSegment : the image to process, it must match the instance buffer size !
+    @param channelIndex : the channel to process in case of multichannel images
+    */
     CV_WRAP virtual void run(InputArray inputToSegment, const int channelIndex=0)=0;
 
-    /**
-     * access function
-     * @return the last segmentation result: a boolean picture which is resampled between 0 and 255 for a display purpose
-     */
+    /** @brief access function
+    @return the last segmentation result: a boolean picture which is resampled between 0 and 255 for a display purpose
+   */
     CV_WRAP virtual void getSegmentationPicture(OutputArray transientAreas)=0;
 
-    /**
-     * cleans all the buffers of the instance
-     */
+    /** @brief cleans all the buffers of the instance
+    */
     CV_WRAP virtual void clearAllBuffers()=0;
 };
 
-    /** allocator
-     * @param inputSize : size of the images input to segment (output will be the same size)
-     */
+/** @brief allocator
+@param inputSize : size of the images input to segment (output will be the same size)
+@relates bioinspired::TransientAreasSegmentationModule
+ */
 CV_EXPORTS_W Ptr<TransientAreasSegmentationModule> createTransientAreasSegmentationModule(Size inputSize);
 
+//! @}
+
 }} // namespaces end : cv and bioinspired
 
 

modules/ccalib/include/opencv2/ccalib.hpp

@@ -49,8 +49,14 @@
 
 #include <vector>
 
+/** @defgroup ccalib Custom Calibration Pattern for 3D reconstruction
+*/
+
 namespace cv{ namespace ccalib{
 
+//! @addtogroup ccalib
+//! @{
+
 class CV_EXPORTS CustomPattern : public Algorithm
 {
 public:
@@ -66,11 +72,11 @@ public:
 	bool isInitialized();
 
 	void getPatternPoints(OutputArray original_points);
-	/*
+    /**<
 		Returns a vector<Point> of the original points.
 	*/
 	double getPixelSize();
-	/*
+    /**<
 		Get the pixel size of the pattern
 	*/
 
@@ -86,7 +92,7 @@ public:
 				Size imageSize, InputOutputArray cameraMatrix, InputOutputArray distCoeffs,
 				OutputArrayOfArrays rvecs, OutputArrayOfArrays tvecs, int flags = 0,
 				TermCriteria criteria = TermCriteria(TermCriteria::COUNT + TermCriteria::EPS, 30, DBL_EPSILON));
-	/*
+    /**<
 		Calls the calirateCamera function with the same inputs.
 	*/
 
@@ -94,7 +100,7 @@ public:
                 OutputArray rvec, OutputArray tvec, bool useExtrinsicGuess = false, int flags = SOLVEPNP_ITERATIVE);
 	bool findRt(InputArray image, InputArray cameraMatrix, InputArray distCoeffs,
                 OutputArray rvec, OutputArray tvec, bool useExtrinsicGuess = false, int flags = SOLVEPNP_ITERATIVE);
-	/*
+    /**<
 		Uses solvePnP to find the rotation and translation of the pattern
 		with respect to the camera frame.
 	*/
@@ -105,13 +111,13 @@ public:
 	bool findRtRANSAC(InputArray image, InputArray cameraMatrix, InputArray distCoeffs,
 				OutputArray rvec, OutputArray tvec, bool useExtrinsicGuess = false, int iterationsCount = 100,
 				float reprojectionError = 8.0, int minInliersCount = 100, OutputArray inliers = noArray(), int flags = SOLVEPNP_ITERATIVE);
-        /*
+        /**<
 		Uses solvePnPRansac()
 	*/
 
 	void drawOrientation(InputOutputArray image, InputArray tvec, InputArray rvec, InputArray cameraMatrix,
 						 InputArray distCoeffs, double axis_length = 3, int axis_width = 2);
-	/*
+    /**<
 		pattern_corners -> projected over the image position of the edges of the pattern.
 	*/
 
@@ -144,6 +150,8 @@ private:
 	void refineKeypointsPos(const Mat& img, std::vector<KeyPoint>& kp);
 };
 
+//! @}
+
 }} // namespace ccalib, cv
 
 #endif

modules/cvv/doc/cvv.rst

@@ -7,5 +7,5 @@ The module provides an interactive GUI to debug and incrementally design compute
 .. toctree::
     :maxdepth: 2
 
-    CVV API Documentation <cvv_api/index>
-    CVV GUI Documentation <cvv_gui/index>
+    CVV API Documentation <cvv_api>
+    CVV GUI Documentation <cvv_gui>

modules/cvv/include/opencv2/cvv/call_meta_data.hpp

@@ -7,6 +7,10 @@
 
 namespace cvv
 {
+
+//! @addtogroup cvv
+//! @{
+
 namespace impl
 {
 
@@ -49,6 +53,9 @@ struct CallMetaData
 	const bool isKnown;
 };
 }
+
+//! @}
+
 } // namespaces
 
 #ifdef __GNUC__

modules/cvv/include/opencv2/cvv/cvv.hpp

@@ -1,6 +1,22 @@
+/**
+@defgroup cvv GUI for Interactive Visual Debugging of Computer Vision Programs
+
+Namespace for all functions is **cvv**, i.e. *cvv::showImage()*.
+
+Compilation:
+
+-   For development, i.e. for cvv GUI to show up, compile your code using cvv with
+    *g++ -DCVVISUAL_DEBUGMODE*.
+-   For release, i.e. cvv calls doing nothing, compile your code without above flag.
+
+See cvv tutorial for a commented example application using cvv.
+
+*/
+
 #include <opencv2/cvv/call_meta_data.hpp>
 #include <opencv2/cvv/debug_mode.hpp>
 #include <opencv2/cvv/dmatch.hpp>
 #include <opencv2/cvv/filter.hpp>
 #include <opencv2/cvv/final_show.hpp>
 #include <opencv2/cvv/show_image.hpp>
+

modules/cvv/include/opencv2/cvv/debug_mode.hpp

@@ -10,6 +10,9 @@
 namespace cvv
 {
 
+//! @addtogroup cvv
+//! @{
+
 namespace impl
 {
 
@@ -24,22 +27,25 @@ static inline bool &getDebugFlag()
 
 } // namespace impl
 
-/**
- * @brief Returns whether debug-mode is active for this TU and thread.
- */
+/** @brief Returns whether debug-mode is active for this TU and thread.
+*/
 static inline bool debugMode()
 {
 	return impl::getDebugFlag();
 }
 
-/**
- * @brief Set the debug-mode for this TU and thread.
+/** @brief Enable or disable cvv for current translation unit and thread
+
+(disabled this way has higher - but still low - overhead compared to using the compile flags).
+@param active
  */
 static inline void setDebugFlag(bool active)
 {
 	impl::getDebugFlag() = active;
 }
 
+//! @}
+
 } // namespace cvv
 
 #endif

modules/cvv/include/opencv2/cvv/dmatch.hpp

@@ -9,9 +9,16 @@
 #include "call_meta_data.hpp"
 #include "debug_mode.hpp"
 
+#ifdef CV_DOXYGEN
+#define CVVISUAL_DEBUGMODE
+#endif
+
 namespace cvv
 {
 
+//! @addtogroup cvv
+//! @{
+
 namespace impl
 {
 void debugDMatch(cv::InputArray img1, std::vector<cv::KeyPoint> keypoints1,
@@ -22,6 +29,22 @@ void debugDMatch(cv::InputArray img1, std::vector<cv::KeyPoint> keypoints1,
 } // namespace impl
 
 #ifdef CVVISUAL_DEBUGMODE
+/** @brief Add a filled in DMatch \<dmatch\> to debug GUI.
+
+The matches can are visualized for interactive inspection in different GUI views (one similar to an
+interactive :draw_matches:drawMatches\<\>).
+
+@param img1 First image used in DMatch \<dmatch\>.
+@param keypoints1 Keypoints of first image.
+@param img2 Second image used in DMatch.
+@param keypoints2 Keypoints of second image.
+@param matches
+@param data See showImage
+@param description See showImage
+@param view See showImage
+@param useTrainDescriptor Use DMatch \<dmatch\>'s train descriptor index instead of query
+descriptor index.
+ */
 static inline void
 debugDMatch(cv::InputArray img1, std::vector<cv::KeyPoint> keypoints1,
             cv::InputArray img2, std::vector<cv::KeyPoint> keypoints2,
@@ -36,6 +59,7 @@ debugDMatch(cv::InputArray img1, std::vector<cv::KeyPoint> keypoints1,
 		                  data, description, view, useTrainDescriptor);
 	}
 }
+/** @overload */
 static inline void
 debugDMatch(cv::InputArray img1, std::vector<cv::KeyPoint> keypoints1,
             cv::InputArray img2, std::vector<cv::KeyPoint> keypoints2,
@@ -52,9 +76,6 @@ debugDMatch(cv::InputArray img1, std::vector<cv::KeyPoint> keypoints1,
 	}
 }
 #else
-/**
- * @brief Debug a set of matches between two images.
- */
 static inline void debugDMatch(cv::InputArray, std::vector<cv::KeyPoint>,
                                cv::InputArray, std::vector<cv::KeyPoint>,
                                std::vector<cv::DMatch>,
@@ -63,9 +84,6 @@ static inline void debugDMatch(cv::InputArray, std::vector<cv::KeyPoint>,
                                bool = true)
 {
 }
-/**
- * Dito.
- */
 static inline void debugDMatch(cv::InputArray, std::vector<cv::KeyPoint>,
                                cv::InputArray, std::vector<cv::KeyPoint>,
                                std::vector<cv::DMatch>,
@@ -75,6 +93,8 @@ static inline void debugDMatch(cv::InputArray, std::vector<cv::KeyPoint>,
 }
 #endif
 
+//! @}
+
 } // namespace cvv
 
 #endif

modules/cvv/include/opencv2/cvv/filter.hpp

@@ -8,9 +8,16 @@
 #include "call_meta_data.hpp"
 #include "debug_mode.hpp"
 
+#ifdef CV_DOXYGEN
+#define CVVISUAL_DEBUGMODE
+#endif
+
 namespace cvv
 {
 
+//! @addtogroup cvv
+//! @{
+
 namespace impl
 {
 // implementation outside API
@@ -20,6 +27,11 @@ void debugFilter(cv::InputArray original, cv::InputArray result,
 } // namespace impl
 
 #ifdef CVVISUAL_DEBUGMODE
+/**
+ * @brief Use the debug-framework to compare two images (from which the second
+ * is intended to be the result of
+ * a filter applied to the first).
+ */
 static inline void
 debugFilter(cv::InputArray original, cv::InputArray result,
             impl::CallMetaData metaData = impl::CallMetaData(),
@@ -31,6 +43,7 @@ debugFilter(cv::InputArray original, cv::InputArray result,
 		                  view);
 	}
 }
+/** @overload */
 static inline void debugFilter(cv::InputArray original, cv::InputArray result,
                                impl::CallMetaData metaData,
                                const ::std::string &description,
@@ -43,20 +56,12 @@ static inline void debugFilter(cv::InputArray original, cv::InputArray result,
 	}
 }
 #else
-/**
- * @brief Use the debug-framework to compare two images (from which the second
- * is intended to be the result of
- * a filter applied to the first).
- */
 static inline void debugFilter(cv::InputArray, cv::InputArray,
                                impl::CallMetaData = impl::CallMetaData(),
                                const char * = nullptr, const char * = nullptr)
 {
 }
 
-/**
- * Dito.
- */
 static inline void debugFilter(cv::InputArray, cv::InputArray,
                                impl::CallMetaData, const ::std::string &,
                                const ::std::string &)
@@ -64,6 +69,8 @@ static inline void debugFilter(cv::InputArray, cv::InputArray,
 }
 #endif
 
+//! @}
+
 } // namespace cvv
 
 #endif

modules/cvv/include/opencv2/cvv/final_show.hpp

@@ -6,22 +6,18 @@
 namespace cvv
 {
 
+//! @addtogroup cvv
+//! @{
+
 namespace impl
 {
 void finalShow();
 }
 
-/**
- * @brief Passes the control to the debug-window for a last time.
- *
- * This function must be called once if there was any prior debug-call. After that all debug-data
- * are freed.
- *
- * If there was no prior call it may be called once in which case it returns
- * without opening a window.
- *
- * In either case no further debug-calls must be made (undefined behaviour!!).
- *
+/** @brief Passes the control to the debug-window for a last time.
+
+This function **must** be called *once* *after* all cvv calls if any. As an alternative create an
+instance of FinalShowCaller, which calls finalShow() in its destructor (RAII-style).
  */
 inline void finalShow()
 {
@@ -48,6 +44,8 @@ public:
 	}
 };
 
+//! @}
+
 }
 
 #endif

modules/cvv/include/opencv2/cvv/show_image.hpp

@@ -8,9 +8,16 @@
 #include "call_meta_data.hpp"
 #include "debug_mode.hpp"
 
+#ifdef CV_DOXYGEN
+#define CVVISUAL_DEBUGMODE
+#endif
+
 namespace cvv
 {
 
+//! @addtogroup cvv
+//! @{
+
 namespace impl
 {
 // implementation outside API
@@ -19,6 +26,15 @@ void showImage(cv::InputArray img, const CallMetaData &data,
 } // namespace impl
 
 #ifdef CVVISUAL_DEBUGMODE
+/** @brief Add a single image to debug GUI (similar to imshow \<\>).
+
+@param img Image to show in debug GUI.
+@param metaData Properly initialized CallMetaData struct, i.e. information about file, line and
+function name for GUI. Use CVVISUAL_LOCATION macro.
+@param description Human readable description to provide context to image.
+@param view Preselect view that will be used to visualize this image in GUI. Other views can still
+be selected in GUI later on.
+ */
 static inline void showImage(cv::InputArray img,
                              impl::CallMetaData metaData = impl::CallMetaData(),
                              const char *description = nullptr,
@@ -29,6 +45,7 @@ static inline void showImage(cv::InputArray img,
 		impl::showImage(img, metaData, description, view);
 	}
 }
+/** @overload */
 static inline void showImage(cv::InputArray img, impl::CallMetaData metaData,
                              const ::std::string &description,
                              const ::std::string &view = "")
@@ -40,23 +57,19 @@ static inline void showImage(cv::InputArray img, impl::CallMetaData metaData,
 	}
 }
 #else
-/**
- * Use the debug-framework to show a single image.
- */
 static inline void showImage(cv::InputArray,
                              impl::CallMetaData = impl::CallMetaData(),
                              const char * = nullptr, const char * = nullptr)
 {
 }
-/**
- * Dito.
- */
 static inline void showImage(cv::InputArray, impl::CallMetaData,
                              const ::std::string &, const ::std::string &)
 {
 }
 #endif
 
+//! @}
+
 } // namespace cvv
 
 #endif

modules/datasets/doc/datasets.rst

@@ -15,105 +15,105 @@ It is planned to have:
 .. toctree::
     :hidden:
 
-    datasets/ar_hmdb
-    datasets/ar_sports
-    datasets/fr_adience
-    datasets/fr_lfw
-    datasets/gr_chalearn
-    datasets/gr_skig
-    datasets/hpe_humaneva
-    datasets/hpe_parse
-    datasets/ir_affine
-    datasets/ir_robot
-    datasets/is_bsds
-    datasets/is_weizmann
-    datasets/msm_epfl
-    datasets/msm_middlebury
-    datasets/or_imagenet
-    datasets/or_mnist
-    datasets/or_sun
-    datasets/pd_caltech
-    datasets/slam_kitti
-    datasets/slam_tumindoor
-    datasets/tr_chars
-    datasets/tr_svt
+    ar_hmdb
+    ar_sports
+    fr_adience
+    fr_lfw
+    gr_chalearn
+    gr_skig
+    hpe_humaneva
+    hpe_parse
+    ir_affine
+    ir_robot
+    is_bsds
+    is_weizmann
+    msm_epfl
+    msm_middlebury
+    or_imagenet
+    or_mnist
+    or_sun
+    pd_caltech
+    slam_kitti
+    slam_tumindoor
+    tr_chars
+    tr_svt
 
 Action Recognition
 ------------------
 
-    :doc:`datasets/ar_hmdb` [#f1]_
+    :doc:`ar_hmdb` [#f1]_
 
-    :doc:`datasets/ar_sports`
+    :doc:`ar_sports`
 
 Face Recognition
 ----------------
 
-    :doc:`datasets/fr_adience`
+    :doc:`fr_adience`
 
-    :doc:`datasets/fr_lfw` [#f1]_
+    :doc:`fr_lfw` [#f1]_
 
 Gesture Recognition
 -------------------
 
-    :doc:`datasets/gr_chalearn`
+    :doc:`gr_chalearn`
 
-    :doc:`datasets/gr_skig`
+    :doc:`gr_skig`
 
 Human Pose Estimation
 ---------------------
 
-    :doc:`datasets/hpe_humaneva`
+    :doc:`hpe_humaneva`
 
-    :doc:`datasets/hpe_parse`
+    :doc:`hpe_parse`
 
 Image Registration
 ------------------
 
-    :doc:`datasets/ir_affine`
+    :doc:`ir_affine`
 
-    :doc:`datasets/ir_robot`
+    :doc:`ir_robot`
 
 Image Segmentation
 ------------------
 
-    :doc:`datasets/is_bsds`
+    :doc:`is_bsds`
 
-    :doc:`datasets/is_weizmann`
+    :doc:`is_weizmann`
 
 Multiview Stereo Matching
 -------------------------
 
-    :doc:`datasets/msm_epfl`
+    :doc:`msm_epfl`
 
-    :doc:`datasets/msm_middlebury`
+    :doc:`msm_middlebury`
 
 Object Recognition
 ------------------
 
-    :doc:`datasets/or_imagenet`
+    :doc:`or_imagenet`
 
-    :doc:`datasets/or_mnist` [#f2]_
+    :doc:`or_mnist` [#f2]_
 
-    :doc:`datasets/or_sun`
+    :doc:`or_sun`
 
 Pedestrian Detection
 --------------------
 
-    :doc:`datasets/pd_caltech` [#f2]_
+    :doc:`pd_caltech` [#f2]_
 
 SLAM
 ----
 
-    :doc:`datasets/slam_kitti`
+    :doc:`slam_kitti`
 
-    :doc:`datasets/slam_tumindoor`
+    :doc:`slam_tumindoor`
 
 Text Recognition
 ----------------
 
-    :doc:`datasets/tr_chars`
+    :doc:`tr_chars`
 
-    :doc:`datasets/tr_svt` [#f1]_
+    :doc:`tr_svt` [#f1]_
 
 *Footnotes*
 

modules/datasets/include/opencv2/datasets/ar_hmdb.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_ar
+//! @{
+
 struct AR_hmdbObj : public Object
 {
     int id;
@@ -69,6 +72,8 @@ public:
     static Ptr<AR_hmdb> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/ar_sports.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_ar
+//! @{
+
 struct AR_sportsObj : public Object
 {
     std::string videoUrl;
@@ -68,6 +71,8 @@ public:
     static Ptr<AR_sports> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/dataset.hpp

@@ -47,11 +47,448 @@
 
 #include <opencv2/core.hpp>
 
+/** @defgroup datasets Framework for working with different datasets
+
+The datasets module includes classes for working with different datasets: load data, evaluate
+different algorithms on them, contains benchmarks, etc.
+
+It is planned to have:
+
+-   basic: loading code for all datasets to help start work with them.
+-   next stage: quick benchmarks for all datasets to show how to solve them using OpenCV and
+implement evaluation code.
+-   finally: implement on OpenCV state-of-the-art algorithms, which solve these tasks.
+
+@{
+@defgroup datasets_ar Action Recognition
+
+### HMDB: A Large Human Motion Database
+
+Implements loading dataset:
+
+"HMDB: A Large Human Motion Database": <http://serre-lab.clps.brown.edu/resource/hmdb-a-large-human-motion-database/>
+
+Usage:
+-# From link above download dataset files: `hmdb51_org.rar` & `test_train_splits.rar`.
+-# Unpack them. Unpack all archives from directory: `hmdb51_org/` and remove them.
+-# To load data run:
+~~~
+./opencv/build/bin/example_datasets_ar_hmdb -p=/home/user/path_to_unpacked_folders/
+~~~
+
+#### Benchmark
+
+For this dataset was implemented benchmark with accuracy: 0.107407 (using precomputed HOG/HOF
+"STIP" features from site, averaging for 3 splits)
+
+To run this benchmark execute:
+~~~
+./opencv/build/bin/example_datasets_ar_hmdb_benchmark -p=/home/user/path_to_unpacked_folders/
+~~~
+
+@note
+Precomputed features should be unpacked in the same folder: `/home/user/path_to_unpacked_folders/hmdb51_org_stips/`.
+Also unpack all archives from directory: `hmdb51_org_stips/` and remove them.
+
+### Sports-1M %Dataset
+
+Implements loading dataset:
+
+"Sports-1M Dataset": <http://cs.stanford.edu/people/karpathy/deepvideo/>
+
+Usage:
+-# From link above download dataset files (`git clone https://code.google.com/p/sports-1m-dataset/`).
+-# To load data run:
+~~~
+./opencv/build/bin/example_datasets_ar_sports -p=/home/user/path_to_downloaded_folders/
+~~~
+
+@defgroup datasets_fr Face Recognition
+
+### Adience
+
+Implements loading dataset:
+
+"Adience": <http://www.openu.ac.il/home/hassner/Adience/data.html>
+
+Usage:
+-# From link above download any dataset file: `faces.tar.gz\aligned.tar.gz` and files with splits:
+`fold_0_data.txt-fold_4_data.txt`, `fold_frontal_0_data.txt-fold_frontal_4_data.txt`. (For
+face recognition task another splits should be created)
+-# Unpack dataset file to some folder and place split files into the same folder.
+-# To load data run:
+~~~
+./opencv/build/bin/example_datasets_fr_adience -p=/home/user/path_to_created_folder/
+~~~
+
+### Labeled Faces in the Wild
+
+Implements loading dataset:
+
+"Labeled Faces in the Wild": <http://vis-www.cs.umass.edu/lfw/>
+
+Usage:
+-# From link above download any dataset file:
+`lfw.tgz\lfwa.tar.gz\lfw-deepfunneled.tgz\lfw-funneled.tgz` and files with pairs: 10 test
+splits: `pairs.txt` and developer train split: `pairsDevTrain.txt`.
+-# Unpack dataset file and place `pairs.txt` and `pairsDevTrain.txt` in created folder.
+-# To load data run:
+~~~
+./opencv/build/bin/example_datasets_fr_lfw -p=/home/user/path_to_unpacked_folder/lfw2/
+~~~
+
+#### Benchmark
+
+For this dataset was implemented benchmark with accuracy: 0.623833 +- 0.005223 (train split:
+`pairsDevTrain.txt`, dataset: lfwa)
+
+To run this benchmark execute:
+~~~
+./opencv/build/bin/example_datasets_fr_lfw_benchmark -p=/home/user/path_to_unpacked_folder/lfw2/
+~~~
+
+@defgroup datasets_gr Gesture Recognition
+
+### ChaLearn Looking at People
+
+Implements loading dataset:
+
+"ChaLearn Looking at People": <http://gesture.chalearn.org/>
+
+Usage
+-# Follow instruction from site above, download files for dataset "Track 3: Gesture Recognition":
+`Train1.zip`-`Train5.zip`, `Validation1.zip`-`Validation3.zip` (Register on site: www.codalab.org and
+accept the terms and conditions of competition:
+<https://www.codalab.org/competitions/991#learn_the_details> There are three mirrors for
+downloading dataset files. When I downloaded data only mirror: "Universitat Oberta de Catalunya"
+works).
+-# Unpack train archives `Train1.zip`-`Train5.zip` to folder `Train/`, validation archives
+`Validation1.zip`-`Validation3.zip` to folder `Validation/`
+-# Unpack all archives in `Train/` & `Validation/` in the folders with the same names, for example:
+`Sample0001.zip` to `Sample0001/`
+-# To load data run:
+~~~
+./opencv/build/bin/example_datasets_gr_chalearn -p=/home/user/path_to_unpacked_folders/
+~~~
+
+### Sheffield Kinect Gesture Dataset
+
+Implements loading dataset:
+
+"Sheffield Kinect Gesture Dataset": <http://lshao.staff.shef.ac.uk/data/SheffieldKinectGesture.htm>
+
+Usage:
+-# From link above download dataset files: `subject1_dep.7z`-`subject6_dep.7z`, `subject1_rgb.7z`-`subject6_rgb.7z`.
+-# Unpack them.
+-# To load data run:
+~~~
+./opencv/build/bin/example_datasets_gr_skig -p=/home/user/path_to_unpacked_folders/
+~~~
+
+@defgroup datasets_hpe Human Pose Estimation
+
+### HumanEva Dataset
+
+Implements loading dataset:
+
+"HumanEva Dataset": <http://humaneva.is.tue.mpg.de>
+
+Usage:
+-# From link above download dataset files for `HumanEva-I` (tar) & `HumanEva-II`.
+-# Unpack them to `HumanEva_1` & `HumanEva_2` accordingly.
+-# To load data run:
+~~~
+./opencv/build/bin/example_datasets_hpe_humaneva -p=/home/user/path_to_unpacked_folders/
+~~~
+
+### PARSE Dataset
+
+Implements loading dataset:
+
+"PARSE Dataset": <http://www.ics.uci.edu/~dramanan/papers/parse/>
+
+Usage:
+-# From link above download dataset file: `people.zip`.
+-# Unpack it.
+-# To load data run:
+~~~
+./opencv/build/bin/example_datasets_hpe_parse -p=/home/user/path_to_unpacked_folder/people_all/
+~~~
+
+@defgroup datasets_ir Image Registration
+
+### Affine Covariant Regions Datasets
+
+Implements loading dataset:
+
+"Affine Covariant Regions Datasets": <http://www.robots.ox.ac.uk/~vgg/data/data-aff.html>
+
+Usage:
+-# From link above download dataset files:
+`bark\bikes\boat\graf\leuven\trees\ubc\wall.tar.gz`.
+-# Unpack them.
+-# To load data, for example, for "bark", run:
+```
+./opencv/build/bin/example_datasets_ir_affine -p=/home/user/path_to_unpacked_folder/bark/
+```
+
+### Robot Data Set
+
+Implements loading dataset:
+
+"Robot Data Set, Point Feature Data Set – 2010": <http://roboimagedata.compute.dtu.dk/?page_id=24>
+
+Usage:
+-# From link above download dataset files: `SET001_6.tar.gz`-`SET055_60.tar.gz`
+-# Unpack them to one folder.
+-# To load data run:
+~~~
+./opencv/build/bin/example_datasets_ir_robot -p=/home/user/path_to_unpacked_folder/
+~~~
+
+@defgroup datasets_is Image Segmentation
+
+### The Berkeley Segmentation Dataset and Benchmark
+
+Implements loading dataset:
+
+"The Berkeley Segmentation Dataset and Benchmark": <https://www.eecs.berkeley.edu/Research/Projects/CS/vision/bsds/>
+
+Usage:
+-# From link above download dataset files: `BSDS300-human.tgz` & `BSDS300-images.tgz`.
+-# Unpack them.
+-# To load data run:
+~~~
+./opencv/build/bin/example_datasets_is_bsds -p=/home/user/path_to_unpacked_folder/BSDS300/
+~~~
+
+### Weizmann Segmentation Evaluation Database
+
+Implements loading dataset:
+
+"Weizmann Segmentation Evaluation Database": <http://www.wisdom.weizmann.ac.il/~vision/Seg_Evaluation_DB/>
+
+Usage:
+-# From link above download dataset files: `Weizmann_Seg_DB_1obj.ZIP` & `Weizmann_Seg_DB_2obj.ZIP`.
+-# Unpack them.
+-# To load data, for example, for `1 object` dataset, run:
+~~~
+./opencv/build/bin/example_datasets_is_weizmann -p=/home/user/path_to_unpacked_folder/1obj/
+~~~
+
+@defgroup datasets_msm Multiview Stereo Matching
+
+### EPFL Multi-View Stereo
+
+Implements loading dataset:
+
+"EPFL Multi-View Stereo": <http://cvlabwww.epfl.ch/~strecha/multiview/denseMVS.html>
+
+Usage:
+-# From link above download dataset files:
+`castle_dense\castle_dense_large\castle_entry\fountain\herzjesu_dense\herzjesu_dense_large_bounding\cameras\images\p.tar.gz`.
+-# Unpack them in separate folder for each object. For example, for "fountain", in folder `fountain/` :
+`fountain_dense_bounding.tar.gz -> bounding/`,
+`fountain_dense_cameras.tar.gz -> camera/`,
+`fountain_dense_images.tar.gz -> png/`,
+`fountain_dense_p.tar.gz -> P/`
+-# To load data, for example, for "fountain", run:
+~~~
+./opencv/build/bin/example_datasets_msm_epfl -p=/home/user/path_to_unpacked_folder/fountain/
+~~~
+
+### Stereo – Middlebury Computer Vision
+
+Implements loading dataset:
+
+"Stereo – Middlebury Computer Vision": <http://vision.middlebury.edu/mview/>
+
+Usage:
+-# From link above download dataset files:
+`dino\dinoRing\dinoSparseRing\temple\templeRing\templeSparseRing.zip`
+-# Unpack them.
+-# To load data, for example "temple" dataset, run:
+~~~
+./opencv/build/bin/example_datasets_msm_middlebury -p=/home/user/path_to_unpacked_folder/temple/
+~~~
+
+@defgroup datasets_or Object Recognition
+
+### ImageNet
+
+Implements loading dataset:  "ImageNet": <http://www.image-net.org/>
+
+Usage:
+-# From link above download dataset files:
+`ILSVRC2010_images_train.tar\ILSVRC2010_images_test.tar\ILSVRC2010_images_val.tar` & devkit:
+`ILSVRC2010_devkit-1.0.tar.gz` (Implemented loading of 2010 dataset as only this dataset has ground
+truth for test data, but structure for ILSVRC2014 is similar)
+-# Unpack them to: `some_folder/train/`, `some_folder/test/`, `some_folder/val` &
+`some_folder/ILSVRC2010_validation_ground_truth.txt`,
+`some_folder/ILSVRC2010_test_ground_truth.txt`.
+-# Create file with labels: `some_folder/labels.txt`, for example, using python script below (each
+file's row format: `synset,labelID,description`. For example: "n07751451,18,plum").
+-# Unpack all tar files in train.
+-# To load data run:
+~~~
+./opencv/build/bin/example_datasets_or_imagenet -p=/home/user/some_folder/
+~~~
+
+Python script to parse `meta.mat`:
+~~~{py}
+    import scipy.io
+    meta_mat = scipy.io.loadmat("devkit-1.0/data/meta.mat")
+
+    labels_dic = dict((m[0][1][0], m[0][0][0][0]-1) for m in meta_mat['synsets']
+    label_names_dic = dict((m[0][1][0], m[0][2][0]) for m in meta_mat['synsets']
+
+    for label in labels_dic.keys():
+        print "{0},{1},{2}".format(label, labels_dic[label], label_names_dic[label])
+~~~
+
+### MNIST
+
+Implements loading dataset:
+
+"MNIST": <http://yann.lecun.com/exdb/mnist/>
+
+Usage:
+-# From link above download dataset files:
+`t10k-images-idx3-ubyte.gz`, `t10k-labels-idx1-ubyte.gz`, `train-images-idx3-ubyte.gz`, `train-labels-idx1-ubyte.gz`.
+-# Unpack them.
+-# To load data run:
+~~~
+./opencv/build/bin/example_datasets_or_mnist -p=/home/user/path_to_unpacked_files/
+~~~
+
+### SUN Database
+
+Implements loading dataset:
+
+"SUN Database, Scene Recognition Benchmark. SUN397": <http://vision.cs.princeton.edu/projects/2010/SUN/>
+
+Usage:
+-# From link above download dataset file: `SUN397.tar` & file with splits: `Partitions.zip`
+-# Unpack `SUN397.tar` into folder: `SUN397/` & `Partitions.zip` into folder: `SUN397/Partitions/`
+-# To load data run:
+~~~
+./opencv/build/bin/example_datasets_or_sun -p=/home/user/path_to_unpacked_files/SUN397/
+~~~
+
+@defgroup datasets_pd Pedestrian Detection
+
+### Caltech Pedestrian Detection Benchmark
+
+Implements loading dataset:
+
+"Caltech Pedestrian Detection Benchmark": <http://www.vision.caltech.edu/Image_Datasets/CaltechPedestrians/>
+
+@note First version of Caltech Pedestrian dataset loading. Code to unpack all frames from seq files
+commented as their number is huge! So currently load only meta information without data. Also
+ground truth isn't processed, as need to convert it from mat files first.
+
+Usage:
+-# From link above download dataset files: `set00.tar`-`set10.tar`.
+-# Unpack them to separate folder.
+-# To load data run:
+~~~
+./opencv/build/bin/example_datasets_pd_caltech -p=/home/user/path_to_unpacked_folders/
+~~~
+
+@defgroup datasets_slam SLAM
+
+### KITTI Vision Benchmark
+
+Implements loading dataset:
+
+"KITTI Vision Benchmark": <http://www.cvlibs.net/datasets/kitti/eval_odometry.php>
+
+Usage:
+-# From link above download "Odometry" dataset files:
+`data_odometry_gray\data_odometry_color\data_odometry_velodyne\data_odometry_poses\data_odometry_calib.zip`.
+-# Unpack `data_odometry_poses.zip`, it creates folder `dataset/poses/`. After that unpack
+`data_odometry_gray.zip`, `data_odometry_color.zip`, `data_odometry_velodyne.zip`. Folder
+`dataset/sequences/` will be created with folders `00/..21/`. Each of these folders will contain:
+`image_0/`, `image_1/`, `image_2/`, `image_3/`, `velodyne/` and files `calib.txt` & `times.txt`.
+These two last files will be replaced after unpacking `data_odometry_calib.zip` at the end.
+-# To load data run:
+~~~
+./opencv/build/bin/example_datasets_slam_kitti -p=/home/user/path_to_unpacked_folder/dataset/
+~~~
+
+### TUMindoor Dataset
+
+Implements loading dataset:
+
+"TUMindoor Dataset": <http://www.navvis.lmt.ei.tum.de/dataset/>
+
+Usage:
+-# From link above download dataset files: `dslr\info\ladybug\pointcloud.tar.bz2` for each dataset:
+`11-11-28 (1st floor)\11-12-13 (1st floor N1)\11-12-17a (4th floor)\11-12-17b (3rd floor)\11-12-17c (Ground I)\11-12-18a (Ground II)\11-12-18b (2nd floor)`
+-# Unpack them in separate folder for each dataset.
+`dslr.tar.bz2 -> dslr/`,
+`info.tar.bz2 -> info/`,
+`ladybug.tar.bz2 -> ladybug/`,
+`pointcloud.tar.bz2 -> pointcloud/`.
+-# To load each dataset run:
+~~~
+./opencv/build/bin/example_datasets_slam_tumindoor -p=/home/user/path_to_unpacked_folders/
+~~~
+
+@defgroup datasets_tr Text Recognition
+
+### The Chars74K Dataset
+
+Implements loading dataset:
+
+"The Chars74K Dataset": <http://www.ee.surrey.ac.uk/CVSSP/demos/chars74k/>
+
+Usage:
+-# From link above download dataset files:
+`EnglishFnt\EnglishHnd\EnglishImg\KannadaHnd\KannadaImg.tgz`, `ListsTXT.tgz`.
+-# Unpack them.
+-# Move `.m` files from folder `ListsTXT/` to appropriate folder. For example,
+`English/list_English_Img.m` for `EnglishImg.tgz`.
+-# To load data, for example "EnglishImg", run:
+~~~
+./opencv/build/bin/example_datasets_tr_chars -p=/home/user/path_to_unpacked_folder/English/
+~~~
+
+### The Street View Text Dataset
+
+Implements loading dataset:
+
+"The Street View Text Dataset": <http://vision.ucsd.edu/~kai/svt/>
+
+Usage:
+-# From link above download dataset file: `svt.zip`.
+-# Unpack it.
+-# To load data run:
+~~~
+./opencv/build/bin/example_datasets_tr_svt -p=/home/user/path_to_unpacked_folder/svt/svt1/
+~~~
+
+#### Benchmark
+
+For this dataset was implemented benchmark with accuracy (mean f1): 0.217
+
+To run benchmark execute:
+~~~
+./opencv/build/bin/example_datasets_tr_svt_benchmark -p=/home/user/path_to_unpacked_folders/svt/svt1/
+~~~
+
+@}
+
+*/
+
 namespace cv
 {
 namespace datasets
 {
 
+//! @addtogroup datasets
+//! @{
+
 struct Object
 {
 };
@@ -79,6 +516,8 @@ private:
     std::vector< Ptr<Object> > empty;
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/fr_adience.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_fr
+//! @{
+
 enum genderType
 {
     male = 0,
@@ -87,6 +90,8 @@ public:
     std::vector<std::string> paths;
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/fr_lfw.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_fr
+//! @{
+
 struct FR_lfwObj : public Object
 {
     std::string image1, image2;
@@ -68,6 +71,8 @@ public:
     static Ptr<FR_lfw> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/gr_chalearn.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_gr
+//! @{
+
 struct groundTruth
 {
     int gestureID, initialFrame, lastFrame;
@@ -85,6 +88,8 @@ public:
     static Ptr<GR_chalearn> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/gr_skig.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_gr
+//! @{
+
 enum actionType
 {
     circle = 1,
@@ -107,6 +110,8 @@ public:
     static Ptr<GR_skig> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/hpe_humaneva.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_hpe
+//! @{
+
 struct HPE_humanevaObj : public Object
 {
     char person; // 1..4
@@ -79,6 +82,8 @@ public:
     static Ptr<HPE_humaneva> create(int num=humaneva_1);
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/hpe_parse.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_hpe
+//! @{
+
 struct HPE_parseObj : public Object
 {
     std::string name;
@@ -67,6 +70,8 @@ public:
     static Ptr<HPE_parse> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/ir_affine.hpp

@@ -55,6 +55,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_ir
+//! @{
+
 struct IR_affineObj : public Object
 {
     std::string imageName;
@@ -69,6 +72,8 @@ public:
     static Ptr<IR_affine> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/ir_robot.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_ir
+//! @{
+
 // calibration matrix from calibrationFile.mat
 // 2.8290e+03   0.0000e+00   8.0279e+02
 // 0.0000e+00   2.8285e+03   6.1618e+02
@@ -78,6 +81,8 @@ public:
     static Ptr<IR_robot> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/is_bsds.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_is
+//! @{
+
 struct IS_bsdsObj : public Object
 {
     std::string name;
@@ -67,6 +70,8 @@ public:
     static Ptr<IS_bsds> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/is_weizmann.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_is
+//! @{
+
 struct IS_weizmannObj : public Object
 {
     std::string imageName;
@@ -70,6 +73,8 @@ public:
     static Ptr<IS_weizmann> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/msm_epfl.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_msm
+//! @{
+
 struct cameraParam
 {
     Matx33d mat1;
@@ -79,6 +82,8 @@ public:
     static Ptr<MSM_epfl> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/msm_middlebury.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_msm
+//! @{
+
 struct MSM_middleburyObj : public Object
 {
     std::string imageName;
@@ -70,6 +73,8 @@ public:
     static Ptr<MSM_middlebury> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/or_imagenet.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_or
+//! @{
+
 struct OR_imagenetObj : public Object
 {
     int id;
@@ -68,6 +71,8 @@ public:
     static Ptr<OR_imagenet> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/or_mnist.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_or
+//! @{
+
 struct OR_mnistObj : public Object
 {
     char label; // 0..9
@@ -68,6 +71,8 @@ public:
     static Ptr<OR_mnist> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/or_sun.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_or
+//! @{
+
 struct OR_sunObj : public Object
 {
     int label;
@@ -70,6 +73,8 @@ public:
     std::vector<std::string> paths;
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/pd_caltech.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_pd
+//! @{
+
 struct PD_caltechObj : public Object
 {
     //double groundTrue[][];
@@ -78,6 +81,8 @@ public:
     static Ptr<PD_caltech> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/slam_kitti.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_slam
+//! @{
+
 struct pose
 {
     double elem[12];
@@ -76,6 +79,8 @@ public:
     static Ptr<SLAM_kitti> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/slam_tumindoor.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_slam
+//! @{
+
 enum imageType
 {
     LEFT = 0,
@@ -76,6 +79,8 @@ public:
     static Ptr<SLAM_tumindoor> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/tr_chars.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_tr
+//! @{
+
 struct TR_charsObj : public Object
 {
     std::string imgName;
@@ -68,6 +71,8 @@ public:
     static Ptr<TR_chars> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/tr_svt.hpp

@@ -54,6 +54,9 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets_tr
+//! @{
+
 struct tag
 {
     std::string value;
@@ -75,6 +78,8 @@ public:
     static Ptr<TR_svt> create();
 };
 
+//! @}
+
 }
 }
 

modules/datasets/include/opencv2/datasets/util.hpp

@@ -57,12 +57,17 @@ namespace cv
 namespace datasets
 {
 
+//! @addtogroup datasets
+//! @{
+
 void CV_EXPORTS split(const std::string &s, std::vector<std::string> &elems, char delim);
 
 void CV_EXPORTS createDirectory(const std::string &path);
 
 void CV_EXPORTS getDirList(const std::string &dirName, std::vector<std::string> &fileNames);
 
+//! @}
+
 }
 }
 

modules/face/doc/changelog.markdown

@@ -0,0 +1,75 @@
+Face module changelog {#face_changelog}
+=====================
+
+Release 0.05
+------------
+
+This library is now included in the official OpenCV distribution (from 2.4 on). The
+cv::FaceRecognizer is now an Algorithm, which better fits into the overall OpenCV API.
+
+To reduce the confusion on user side and minimize my work, libfacerec and OpenCV have been
+synchronized and are now based on the same interfaces and implementation.
+
+The library now has an extensive documentation:
+
+-   The API is explained in detail and with a lot of code examples.
+-   The face recognition guide I had written for Python and GNU Octave/MATLAB has been adapted to
+    the new OpenCV C++ cv::FaceRecognizer.
+-   A tutorial for gender classification with Fisherfaces.
+-   A tutorial for face recognition in videos (e.g. webcam).
+
+### Release highlights
+
+-   There are no single highlights to pick from, this release is a highlight itself.
+
+Release 0.04
+------------
+
+This version is fully Windows-compatible and works with OpenCV 2.3.1. Several bugfixes, but none
+influenced the recognition rate.
+
+### Release highlights
+
+-   A whole lot of exceptions with meaningful error messages.
+-   A tutorial for Windows users:
+    [<http://bytefish.de/blog/opencv_visual_studio_and_libfacerec>](http://bytefish.de/blog/opencv_visual_studio_and_libfacerec)
+
+Release 0.03
+------------
+
+Reworked the library to provide separate implementations in cpp files, because it's the preferred
+way of contributing OpenCV libraries. This means the library is not header-only anymore. Slight API
+changes were done, please see the documentation for details.
+
+### Release highlights
+
+-   New Unit Tests (for LBP Histograms) make the library more robust.
+-   Added more documentation.
+
+Release 0.02
+------------
+
+Reworked the library to provide separate implementations in cpp files, because it's the preferred
+way of contributing OpenCV libraries. This means the library is not header-only anymore. Slight API
+changes were done, please see the documentation for details.
+
+### Release highlights
+
+-   New Unit Tests (for LBP Histograms) make the library more robust.
+-   Added a documentation and changelog in reStructuredText.
+
+Release 0.01
+------------
+
+Initial release as header-only library.
+
+### Release highlights
+
+-   Colormaps for OpenCV to enhance the visualization.
+-   Face Recognition algorithms implemented:
+    -   Eigenfaces @cite TP91
+    -   Fisherfaces @cite BHK97
+    -   Local Binary Patterns Histograms @cite AHP04
+-   Added persistence facilities to store the models with a common API.
+-   Unit Tests (using [gtest](http://code.google.com/p/googletest/)).
+-   Providing a CMakeLists.txt to enable easy cross-platform building.

modules/face/doc/face.bib

@@ -0,0 +1,160 @@
+@incollection{AHP04,
+  title={Face recognition with local binary patterns},
+  author={Ahonen, Timo and Hadid, Abdenour and Pietik{\"a}inen, Matti},
+  booktitle={Computer vision-eccv 2004},
+  pages={469--481},
+  year={2004},
+  publisher={Springer}
+}
+
+@article{BHK97,
+  title={Eigenfaces vs. fisherfaces: Recognition using class specific linear projection},
+  author={Belhumeur, Peter N. and Hespanha, Jo{\~a}o P and Kriegman, David},
+  journal={Pattern Analysis and Machine Intelligence, IEEE Transactions on},
+  volume={19},
+  number={7},
+  pages={711--720},
+  year={1997},
+  publisher={IEEE}
+}
+
+@inproceedings{Bru92,
+  title={Face recognition through geometrical features},
+  author={Brunelli, Roberto and Poggio, Tomaso},
+  booktitle={Computer Vision—ECCV'92},
+  pages={792--800},
+  year={1992},
+  organization={Springer}
+}
+
+@book{Duda01,
+  title={Pattern classification},
+  author={Duda, Richard O and Hart, Peter E and Stork, David G},
+  year={2012},
+  publisher={John Wiley \& Sons}
+}
+
+@article{Fisher36,
+  title={The use of multiple measurements in taxonomic problems},
+  author={Fisher, Ronald A},
+  journal={Annals of eugenics},
+  volume={7},
+  number={2},
+  pages={179--188},
+  year={1936},
+  publisher={Wiley Online Library}
+}
+
+@article{GBK01,
+  title={From few to many: Illumination cone models for face recognition under variable lighting and pose},
+  author={Georghiades, Athinodoros S. and Belhumeur, Peter N. and Kriegman, David},
+  journal={Pattern Analysis and Machine Intelligence, IEEE Transactions on},
+  volume={23},
+  number={6},
+  pages={643--660},
+  year={2001},
+  publisher={IEEE}
+}
+
+@article{Kanade73,
+  title={Picture processing system by computer complex and recognition of human faces},
+  author={Kanade, Takeo},
+  year={1974}
+}
+
+@article{KM01,
+  title={Pca versus lda},
+  author={Mart{\'\i}nez, Aleix M and Kak, Avinash C},
+  journal={Pattern Analysis and Machine Intelligence, IEEE Transactions on},
+  volume={23},
+  number={2},
+  pages={228--233},
+  year={2001},
+  publisher={IEEE}
+}
+
+@article{Lee05,
+  title={Acquiring linear subspaces for face recognition under variable lighting},
+  author={Lee, Kuang-Chih and Ho, Jeffrey and Kriegman, David},
+  journal={Pattern Analysis and Machine Intelligence, IEEE Transactions on},
+  volume={27},
+  number={5},
+  pages={684--698},
+  year={2005},
+  publisher={IEEE}
+}
+
+@incollection{Messer06,
+  title={Performance characterisation of face recognition algorithms and their sensitivity to severe illumination changes},
+  author={Messer, Kieron and Kittler, Josef and Short, James and Heusch, Guillaume and Cardinaux, Fabien and Marcel, Sebastien and Rodriguez, Yann and Shan, Shiguang and Su, Yu and Gao, Wen and others},
+  booktitle={Advances in Biometrics},
+  pages={1--11},
+  year={2005},
+  publisher={Springer}
+}
+
+@article{RJ91,
+  title={Small sample size effects in statistical pattern recognition: Recommendations for practitioners},
+  author={Raudys, Sarunas J and Jain, Anil K.},
+  journal={IEEE Transactions on pattern analysis and machine intelligence},
+  volume={13},
+  number={3},
+  pages={252--264},
+  year={1991},
+  publisher={IEEE Computer Society}
+}
+
+@article{Tan10,
+  title={Enhanced local texture feature sets for face recognition under difficult lighting conditions},
+  author={Tan, Xiaoyang and Triggs, Bill},
+  journal={Image Processing, IEEE Transactions on},
+  volume={19},
+  number={6},
+  pages={1635--1650},
+  year={2010},
+  publisher={IEEE}
+}
+
+@article{TP91,
+  title={Eigenfaces for recognition},
+  author={Turk, Matthew and Pentland, Alex},
+  journal={Journal of cognitive neuroscience},
+  volume={3},
+  number={1},
+  pages={71--86},
+  year={1991},
+  publisher={MIT Press}
+}
+
+@article{Tu06,
+  title={Newborns' face recognition: Role of inner and outer facial features},
+  author={Turati, Chiara and Macchi Cassia, Viola and Simion, Francesca and Leo, Irene},
+  journal={Child development},
+  volume={77},
+  number={2},
+  pages={297--311},
+  year={2006},
+  publisher={Wiley Online Library}
+}
+
+@article{Wiskott97,
+  title={Face recognition by elastic bunch graph matching},
+  author={Wiskott, Laurenz and Fellous, J-M and Kuiger, N and Von Der Malsburg, Christoph},
+  journal={Pattern Analysis and Machine Intelligence, IEEE Transactions on},
+  volume={19},
+  number={7},
+  pages={775--779},
+  year={1997},
+  publisher={IEEE}
+}
+
+@article{Zhao03,
+  title={Face recognition: A literature survey},
+  author={Zhao, Wenyi and Chellappa, Rama and Phillips, P Jonathon and Rosenfeld, Azriel},
+  journal={Acm Computing Surveys (CSUR)},
+  volume={35},
+  number={4},
+  pages={399--458},
+  year={2003},
+  publisher={ACM}
+}

modules/face/doc/face.rst

@@ -7,4 +7,4 @@ The module contains some recently added functionality that has not been stabiliz
 .. toctree::
     :maxdepth: 2
 
-    FaceRecognizer Documentation <facerec/index>
+    FaceRecognizer Documentation <index>