Doxygen doucmentation: ml module

modules/objdetect/include/opencv2/objdetect.hpp

@@ -46,15 +46,78 @@
 
 #include "opencv2/core.hpp"
 
+/**
+@defgroup objdetect Object Detection
+
+Haar Feature-based Cascade Classifier for Object Detection
+----------------------------------------------------------
+
+The object detector described below has been initially proposed by Paul Viola @cite Viola01 and
+improved by Rainer Lienhart @cite Lienhart02.
+
+First, a classifier (namely a *cascade of boosted classifiers working with haar-like features*) is
+trained with a few hundred sample views of a particular object (i.e., a face or a car), called
+positive examples, that are scaled to the same size (say, 20x20), and negative examples - arbitrary
+images of the same size.
+
+After a classifier is trained, it can be applied to a region of interest (of the same size as used
+during the training) in an input image. The classifier outputs a "1" if the region is likely to show
+the object (i.e., face/car), and "0" otherwise. To search for the object in the whole image one can
+move the search window across the image and check every location using the classifier. The
+classifier is designed so that it can be easily "resized" in order to be able to find the objects of
+interest at different sizes, which is more efficient than resizing the image itself. So, to find an
+object of an unknown size in the image the scan procedure should be done several times at different
+scales.
+
+The word "cascade" in the classifier name means that the resultant classifier consists of several
+simpler classifiers (*stages*) that are applied subsequently to a region of interest until at some
+stage the candidate is rejected or all the stages are passed. The word "boosted" means that the
+classifiers at every stage of the cascade are complex themselves and they are built out of basic
+classifiers using one of four different boosting techniques (weighted voting). Currently Discrete
+Adaboost, Real Adaboost, Gentle Adaboost and Logitboost are supported. The basic classifiers are
+decision-tree classifiers with at least 2 leaves. Haar-like features are the input to the basic
+classifiers, and are calculated as described below. The current algorithm uses the following
+Haar-like features:
+
+![image](pics/haarfeatures.png)
+
+The feature used in a particular classifier is specified by its shape (1a, 2b etc.), position within
+the region of interest and the scale (this scale is not the same as the scale used at the detection
+stage, though these two scales are multiplied). For example, in the case of the third line feature
+(2c) the response is calculated as the difference between the sum of image pixels under the
+rectangle covering the whole feature (including the two white stripes and the black stripe in the
+middle) and the sum of the image pixels under the black stripe multiplied by 3 in order to
+compensate for the differences in the size of areas. The sums of pixel values over a rectangular
+regions are calculated rapidly using integral images (see below and the integral description).
+
+To see the object detector at work, have a look at the facedetect demo:
+<https://github.com/Itseez/opencv/tree/master/samples/cpp/dbt_face_detection.cpp>
+
+The following reference is for the detection part only. There is a separate application called
+opencv\_traincascade that can train a cascade of boosted classifiers from a set of samples.
+
+@note In the new C++ interface it is also possible to use LBP (local binary pattern) features in
+addition to Haar-like features. .. [Viola01] Paul Viola and Michael J. Jones. Rapid Object Detection
+using a Boosted Cascade of Simple Features. IEEE CVPR, 2001. The paper is available online at
+<http://research.microsoft.com/en-us/um/people/viola/Pubs/Detect/violaJones_CVPR2001.pdf>
+
+@{
+    @defgroup objdetect_c C API
+@}
+ */
+
 typedef struct CvHaarClassifierCascade CvHaarClassifierCascade;
 
 namespace cv
 {
 
+//! @addtogroup objdetect
+//! @{
+
 ///////////////////////////// Object Detection ////////////////////////////
 
-// class for grouping object candidates, detected by Cascade Classifier, HOG etc.
+//! class for grouping object candidates, detected by Cascade Classifier, HOG etc.
-// instance of the class is to be passed to cv::partition (see cxoperations.hpp)
+//! instance of the class is to be passed to cv::partition (see cxoperations.hpp)
 class CV_EXPORTS SimilarRects
 {
 public:
@@ -70,13 +133,32 @@ public:
     double eps;
 };
 
+/** @brief Groups the object candidate rectangles.
+
+@param rectList Input/output vector of rectangles. Output vector includes retained and grouped
+rectangles. (The Python list is not modified in place.)
+@param groupThreshold Minimum possible number of rectangles minus 1. The threshold is used in a
+group of rectangles to retain it.
+@param eps Relative difference between sides of the rectangles to merge them into a group.
+
+The function is a wrapper for the generic function partition . It clusters all the input rectangles
+using the rectangle equivalence criteria that combines rectangles with similar sizes and similar
+locations. The similarity is defined by eps. When eps=0 , no clustering is done at all. If
+\f$\texttt{eps}\rightarrow +\inf\f$ , all the rectangles are put in one cluster. Then, the small
+clusters containing less than or equal to groupThreshold rectangles are rejected. In each other
+cluster, the average rectangle is computed and put into the output rectangle list.
+ */
 CV_EXPORTS   void groupRectangles(std::vector<Rect>& rectList, int groupThreshold, double eps = 0.2);
+/** @overload */
 CV_EXPORTS_W void groupRectangles(CV_IN_OUT std::vector<Rect>& rectList, CV_OUT std::vector<int>& weights,
                                   int groupThreshold, double eps = 0.2);
+/** @overload */
 CV_EXPORTS   void groupRectangles(std::vector<Rect>& rectList, int groupThreshold,
                                   double eps, std::vector<int>* weights, std::vector<double>* levelWeights );
+/** @overload */
 CV_EXPORTS   void groupRectangles(std::vector<Rect>& rectList, std::vector<int>& rejectLevels,
                                   std::vector<double>& levelWeights, int groupThreshold, double eps = 0.2);
+/** @overload */
 CV_EXPORTS   void groupRectangles_meanshift(std::vector<Rect>& rectList, std::vector<double>& foundWeights,
                                             std::vector<double>& foundScales,
                                             double detectThreshold = 0.0, Size winDetSize = Size(64, 128));
@@ -133,15 +215,54 @@ public:
     virtual Ptr<MaskGenerator> getMaskGenerator() = 0;
 };
 
+/** @brief Cascade classifier class for object detection.
+ */
 class CV_EXPORTS_W CascadeClassifier
 {
 public:
     CV_WRAP CascadeClassifier();
+    /** @brief Loads a classifier from a file.
+
+    @param filename Name of the file from which the classifier is loaded.
+     */
     CV_WRAP CascadeClassifier(const String& filename);
     ~CascadeClassifier();
+    /** @brief Checks whether the classifier has been loaded.
+    */
     CV_WRAP bool empty() const;
+    /** @brief Loads a classifier from a file.
+
+    @param filename Name of the file from which the classifier is loaded. The file may contain an old
+    HAAR classifier trained by the haartraining application or a new cascade classifier trained by the
+    traincascade application.
+     */
     CV_WRAP bool load( const String& filename );
+    /** @brief Reads a classifier from a FileStorage node.
+
+    @note The file may contain a new cascade classifier (trained traincascade application) only.
+     */
     CV_WRAP bool read( const FileNode& node );
+
+    /** @brief Detects objects of different sizes in the input image. The detected objects are returned as a list
+    of rectangles.
+
+    @param image Matrix of the type CV\_8U containing an image where objects are detected.
+    @param objects Vector of rectangles where each rectangle contains the detected object, the
+    rectangles may be partially outside the original image.
+    @param scaleFactor Parameter specifying how much the image size is reduced at each image scale.
+    @param minNeighbors Parameter specifying how many neighbors each candidate rectangle should have
+    to retain it.
+    @param flags Parameter with the same meaning for an old cascade as in the function
+    cvHaarDetectObjects. It is not used for a new cascade.
+    @param minSize Minimum possible object size. Objects smaller than that are ignored.
+    @param maxSize Maximum possible object size. Objects larger than that are ignored.
+
+    The function is parallelized with the TBB library.
+
+    @note
+       -   (Python) A face detection example using cascade classifiers can be found at
+            opencv\_source\_code/samples/python2/facedetect.py
+    */
     CV_WRAP void detectMultiScale( InputArray image,
                           CV_OUT std::vector<Rect>& objects,
                           double scaleFactor = 1.1,
@@ -149,6 +270,21 @@ public:
                           Size minSize = Size(),
                           Size maxSize = Size() );
 
+    /** @overload
+    @param image Matrix of the type CV\_8U containing an image where objects are detected.
+    @param objects Vector of rectangles where each rectangle contains the detected object, the
+    rectangles may be partially outside the original image.
+    @param numDetections Vector of detection numbers for the corresponding objects. An object's number
+    of detections is the number of neighboring positively classified rectangles that were joined
+    together to form the object.
+    @param scaleFactor Parameter specifying how much the image size is reduced at each image scale.
+    @param minNeighbors Parameter specifying how many neighbors each candidate rectangle should have
+    to retain it.
+    @param flags Parameter with the same meaning for an old cascade as in the function
+    cvHaarDetectObjects. It is not used for a new cascade.
+    @param minSize Minimum possible object size. Objects smaller than that are ignored.
+    @param maxSize Maximum possible object size. Objects larger than that are ignored.
+    */
     CV_WRAP_AS(detectMultiScale2) void detectMultiScale( InputArray image,
                           CV_OUT std::vector<Rect>& objects,
                           CV_OUT std::vector<int>& numDetections,
@@ -157,6 +293,9 @@ public:
                           Size minSize=Size(),
                           Size maxSize=Size() );
 
+    /** @overload
+    if `outputRejectLevels` is `true` returns `rejectLevels` and `levelWeights`
+    */
     CV_WRAP_AS(detectMultiScale3) void detectMultiScale( InputArray image,
                                   CV_OUT std::vector<Rect>& objects,
                                   CV_OUT std::vector<int>& rejectLevels,
@@ -184,14 +323,14 @@ CV_EXPORTS Ptr<BaseCascadeClassifier::MaskGenerator> createFaceDetectionMaskGene
 
 //////////////// HOG (Histogram-of-Oriented-Gradients) Descriptor and Object Detector //////////////
 
-// struct for detection region of interest (ROI)
+//! struct for detection region of interest (ROI)
 struct DetectionROI
 {
-   // scale(size) of the bounding box
+   //! scale(size) of the bounding box
    double scale;
-   // set of requrested locations to be evaluated
+   //! set of requrested locations to be evaluated
    std::vector<cv::Point> locations;
-   // vector that will contain confidence values for each location
+   //! vector that will contain confidence values for each location
    std::vector<double> confidences;
 };
 
@@ -250,24 +389,24 @@ public:
                          Size winStride = Size(), Size padding = Size(),
                          const std::vector<Point>& locations = std::vector<Point>()) const;
 
-    //with found weights output
+    //! with found weights output
     CV_WRAP virtual void detect(const Mat& img, CV_OUT std::vector<Point>& foundLocations,
                         CV_OUT std::vector<double>& weights,
                         double hitThreshold = 0, Size winStride = Size(),
                         Size padding = Size(),
                         const std::vector<Point>& searchLocations = std::vector<Point>()) const;
-    //without found weights output
+    //! without found weights output
     virtual void detect(const Mat& img, CV_OUT std::vector<Point>& foundLocations,
                         double hitThreshold = 0, Size winStride = Size(),
                         Size padding = Size(),
                         const std::vector<Point>& searchLocations=std::vector<Point>()) const;
 
-    //with result weights output
+    //! with result weights output
     CV_WRAP virtual void detectMultiScale(InputArray img, CV_OUT std::vector<Rect>& foundLocations,
                                   CV_OUT std::vector<double>& foundWeights, double hitThreshold = 0,
                                   Size winStride = Size(), Size padding = Size(), double scale = 1.05,
                                   double finalThreshold = 2.0,bool useMeanshiftGrouping = false) const;
-    //without found weights output
+    //! without found weights output
     virtual void detectMultiScale(InputArray img, CV_OUT std::vector<Rect>& foundLocations,
                                   double hitThreshold = 0, Size winStride = Size(),
                                   Size padding = Size(), double scale = 1.05,
@@ -295,24 +434,26 @@ public:
     CV_PROP int nlevels;
 
 
-    // evaluate specified ROI and return confidence value for each location
+    //! evaluate specified ROI and return confidence value for each location
     virtual void detectROI(const cv::Mat& img, const std::vector<cv::Point> &locations,
                                    CV_OUT std::vector<cv::Point>& foundLocations, CV_OUT std::vector<double>& confidences,
                                    double hitThreshold = 0, cv::Size winStride = Size(),
                                    cv::Size padding = Size()) const;
 
-    // evaluate specified ROI and return confidence value for each location in multiple scales
+    //! evaluate specified ROI and return confidence value for each location in multiple scales
     virtual void detectMultiScaleROI(const cv::Mat& img,
                                                        CV_OUT std::vector<cv::Rect>& foundLocations,
                                                        std::vector<DetectionROI>& locations,
                                                        double hitThreshold = 0,
                                                        int groupThreshold = 0) const;
 
-    // read/parse Dalal's alt model file
+    //! read/parse Dalal's alt model file
     void readALTModel(String modelfile);
     void groupRectangles(std::vector<cv::Rect>& rectList, std::vector<double>& weights, int groupThreshold, double eps) const;
 };
 
+//! @} objdetect
+
 }
 
 #include "opencv2/objdetect/detection_based_tracker.hpp"

modules/objdetect/include/opencv2/objdetect/detection_based_tracker.hpp

@@ -51,6 +51,10 @@
 
 namespace cv
 {
+
+//! @addtogroup objdetect
+//! @{
+
 class CV_EXPORTS DetectionBasedTracker
 {
     public:
@@ -211,6 +215,9 @@ class CV_EXPORTS DetectionBasedTracker
         cv::Rect calcTrackedObjectPositionToShow(int i, ObjectStatus& status) const;
         void detectInRegion(const cv::Mat& img, const cv::Rect& r, std::vector<cv::Rect>& detectedObjectsInRegions);
 };
+
+//! @} objdetect
+
 } //end of cv namespace
 #endif
 

modules/objdetect/include/opencv2/objdetect/objdetect_c.h

@@ -53,6 +53,10 @@
 extern "C" {
 #endif
 
+/** @addtogroup objdetect_c
+  @{
+  */
+
 /****************************************************************************************\
 *                         Haar-like Object Detection functions                           *
 \****************************************************************************************/
@@ -143,6 +147,7 @@ CVAPI(void) cvSetImagesForHaarClassifierCascade( CvHaarClassifierCascade* cascad
 CVAPI(int) cvRunHaarClassifierCascade( const CvHaarClassifierCascade* cascade,
                                        CvPoint pt, int start_stage CV_DEFAULT(0));
 
+/** @} objdetect_c */
 
 #ifdef __cplusplus
 }