From 7392ce0a81b76cdad44dd29fc4814b3da2eb2170 Mon Sep 17 00:00:00 2001
From: Maksim Shabunin <maksim.shabunin@itseez.com>
Date: Thu, 5 Nov 2015 17:17:18 +0300
Subject: [PATCH] Added some documentation for MSER

---
 doc/opencv.bib                                | 16 ++++++++
 .../features2d/include/opencv2/features2d.hpp | 41 +++++++++++++++----
 2 files changed, 48 insertions(+), 9 deletions(-)

diff --git a/doc/opencv.bib b/doc/opencv.bib
index b2e5002224..839ff886a7 100644
--- a/doc/opencv.bib
+++ b/doc/opencv.bib
@@ -848,3 +848,19 @@
   year={2007},
   publisher={Springer}
 }
+@incollection{nister2008linear,
+  title={Linear time maximally stable extremal regions},
+  author={Nist{\'e}r, David and Stew{\'e}nius, Henrik},
+  booktitle={Computer Vision--ECCV 2008},
+  pages={183--196},
+  year={2008},
+  publisher={Springer}
+}
+@inproceedings{forssen2007maximally,
+  title={Maximally stable colour regions for recognition and matching},
+  author={Forss{\'e}n, Per-Erik},
+  booktitle={Computer Vision and Pattern Recognition, 2007. CVPR'07. IEEE Conference on},
+  pages={1--8},
+  year={2007},
+  organization={IEEE}
+}
diff --git a/modules/features2d/include/opencv2/features2d.hpp b/modules/features2d/include/opencv2/features2d.hpp
index cf95e7d343..2542d537f2 100644
--- a/modules/features2d/include/opencv2/features2d.hpp
+++ b/modules/features2d/include/opencv2/features2d.hpp
@@ -317,25 +317,48 @@ public:
     CV_WRAP virtual int getFastThreshold() const = 0;
 };
 
-/** @brief Maximally stable extremal region extractor. :
+/** @brief Maximally stable extremal region extractor
 
-The class encapsulates all the parameters of the MSER extraction algorithm (see
-<http://en.wikipedia.org/wiki/Maximally_stable_extremal_regions>). Also see
-<http://code.opencv.org/projects/opencv/wiki/MSER> for useful comments and parameters description.
+The class encapsulates all the parameters of the %MSER extraction algorithm (see [wiki
+article](http://en.wikipedia.org/wiki/Maximally_stable_extremal_regions)).
 
-@note
-   -   (Python) A complete example showing the use of the MSER detector can be found at
-        opencv_source_code/samples/python2/mser.py
- */
+- there are two different implementation of %MSER: one for grey image, one for color image
+
+- the grey image algorithm is taken from: @cite nister2008linear ;  the paper claims to be faster
+than union-find method; it actually get 1.5~2m/s on my centrino L7200 1.2GHz laptop.
+
+- the color image algorithm is taken from: @cite forssen2007maximally ; it should be much slower
+than grey image method ( 3~4 times ); the chi_table.h file is taken directly from paper's source
+code which is distributed under GPL.
+
+- (Python) A complete example showing the use of the %MSER detector can be found at samples/python2/mser.py
+*/
 class CV_EXPORTS_W MSER : public Feature2D
 {
 public:
-    //! the full constructor
+    /** @brief Full consturctor for %MSER detector
+
+    @param _delta it compares \f$(size_{i}-size_{i-delta})/size_{i-delta}\f$
+    @param _min_area prune the area which smaller than minArea
+    @param _max_area prune the area which bigger than maxArea
+    @param _max_variation prune the area have simliar size to its children
+    @param _min_diversity for color image, trace back to cut off mser with diversity less than min_diversity
+    @param _max_evolution  for color image, the evolution steps
+    @param _area_threshold for color image, the area threshold to cause re-initialize
+    @param _min_margin for color image, ignore too small margin
+    @param _edge_blur_size for color image, the aperture size for edge blur
+     */
     CV_WRAP static Ptr<MSER> create( int _delta=5, int _min_area=60, int _max_area=14400,
           double _max_variation=0.25, double _min_diversity=.2,
           int _max_evolution=200, double _area_threshold=1.01,
           double _min_margin=0.003, int _edge_blur_size=5 );
 
+    /** @brief Detect %MSER regions
+
+    @param image input image (8UC1, 8UC3 or 8UC4)
+    @param msers resulting list of point sets
+    @param bboxes resulting bounding boxes
+    */
     CV_WRAP virtual void detectRegions( InputArray image,
                                         CV_OUT std::vector<std::vector<Point> >& msers,
                                         std::vector<Rect>& bboxes ) = 0;