opencv3.3 CascadeClassifier类 源码注释说明

/** @example facedetect.cpp
*/
/** @brief Cascade classifier class for object detection.
 */
class CV_EXPORTS_W CascadeClassifier
{
public:
    CV_WRAP CascadeClassifier();//无参数构造函数，new自动调用该函数分配初始内存
    /** @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);//带参数构造函数，参数为xml的绝对名称
    ~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 );// 加载分类器，参数为XML的绝对名称，函数内部调用read读取新格式的分类器，读取成功后直接返回，读取失败后调用cvLoad读取旧格式的分类器，读取成功返回true，否则返回false
    /** @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 );// load内部调用read解析XML中的内容，也可以自己创建节点然后调用Read即可，但是该函数只能读取新格式的分类器，不能读取旧格式的分类器

    /** @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. If `maxSize == minSize` model is evaluated on single scale.

    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/python/facedetect.py
    */
    // 多尺度检测函数
    /*
    函数介绍：

    参数1：image--待检测图片，一般为灰度图像加快检测速度；

    参数2：objects--被检测物体的矩形框向量组；
    参数3：scaleFactor--表示在前后两次相继的扫描中，搜索窗口的比例系数。默认为1.1即每次搜索窗口依次扩大10%;
    参数4：minNeighbors--表示构成检测目标的相邻矩形的最小个数(默认为3个)。
            如果组成检测目标的小矩形的个数和小于 min_neighbors - 1 都会被排除。
            如果min_neighbors 为 0, 则函数不做任何操作就返回所有的被检候选矩形框，
            这种设定值一般用在用户自定义对检测结果的组合程序上；
            minNeighbors控制着误检测，默认值为3表明至少有3次重叠检测，我们才认为人脸确实存。
    参数5：flags--只对旧格式的分类器有效；
          （但目前的haar分类器都是旧版的，CV_HAAR_DO_CANNY_PRUNING,这个值告诉分类器跳过平滑（无边缘区域），利用Canny边缘检测器来排除一些边缘很少或者很多的图像区域；
           CV_HAAR_SCALE_IMAGE，这个值告诉分类器不要缩放分类器。而是缩放图像（处理好内存和缓存的使用问题，这可以提高性能。）就是按比例正常检测；
           CV_HAAR_FIND_BIGGEST_OBJECTS，告诉分类器只返回最大的目标（这样返回的物体个数只可能是0或1）只检测最大的物；
           CV_HAAR_DO_ROUGH_SEARCH，他只可与CV_HAAR_FIND_BIGGEST_OBJECTS一起使用，这个标志告诉分类器在任何窗口，只要第一个候选者被发现则结束寻找（当然需要足够的相邻的区域来说明真正找到了。）,只做初略检测.
    参数6、7：minSize和maxSize用来限制得到的目标区域的范围。
    */    
    CV_WRAP void detectMultiScale( InputArray image,//图像，必须是8位，
                          CV_OUT std::vector<Rect>& objects,//输出矩形，注意vector不是线程安全的
                          double scaleFactor = 1.1,//缩放比例，必须大于1
                          int minNeighbors = 3, //合并窗口时最小neighbor，每个候选矩阵至少包含的附近元素个数
                          int flags = 0,//检测标记，只对旧格式的分类器有效，
                          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. If `maxSize == minSize` model is evaluated on single scale.
    */
    
    /** 
    detectMultiScale重载函数
    参数：
    image：包含检测对象的图像的CV_8U类型矩阵
    objects: 矩形的向量，其中每个矩形包含被检测的对象，矩形可以部分位于原始图像之外
    numDetections: 对应对象的检测编号向量。一个物体被探测到的次数是相邻的被积极分类的矩形的数量，这些矩形被连接在一起形成物体
    scaleFactor: 指定在每个图像缩放时的缩放比例
    minNeighbors：指定每个候选矩形需要保留多少个相邻矩形
    flags：含义与函数cvHaarDetectObjects中的旧级联相同。它不用于新的级联
    minSize：对象最小大小，小于该值的对象被忽略。
    maxSize：最大可能的对象大小，大于这个值的对象被忽略 
    */
    CV_WRAP_AS(detectMultiScale2) void detectMultiScale( InputArray image, //图像，必须是8位，
                          CV_OUT std::vector<Rect>& objects,//输出矩形，注意vector不是线程安全的
                          CV_OUT std::vector<int>& numDetections,//
                          double scaleFactor=1.1,//缩放比例，必须大于1
                          int minNeighbors=3, //合并窗口时最小neighbor，每个候选矩阵至少包含的附近元素个数
                          int flags=0,//检测标记，只对旧格式的分类器有效，与cvHaarDetectObjects的参数flags相同，默认为0，可能的取值为CV_HAAR_DO_CANNY_PRUNING(CANNY边缘检测)、CV_HAAR_SCALE_IMAGE(缩放图像)、CV_HAAR_FIND_BIGGEST_OBJECT(寻找最大的目标)、CV_HAAR_DO_ROUGH_SEARCH(做粗略搜索)；如果寻找最大的目标就不能缩放图像，也不能CANNY边缘检测
                          Size minSize=Size(),//最小检测目标
                          Size maxSize=Size() );//最大检测目标

    /** @overload
    This function allows you to retrieve the final stage decision certainty of classification.
    For this, one needs to set `outputRejectLevels` on true and provide the `rejectLevels` and `levelWeights` parameter.
    For each resulting detection, `levelWeights` will then contain the certainty of classification at the final stage.
    This value can then be used to separate strong from weaker classifications.

    A code sample on how to use it efficiently can be found below:
    @code
    Mat img;
    vector<double> weights;
    vector<int> levels;
    vector<Rect> detections;
    CascadeClassifier model("/path/to/your/model.xml");
    model.detectMultiScale(img, detections, levels, weights, 1.1, 3, 0, Size(), Size(), true);
    cerr << "Detection " << detections[0] << " with weight " << weights[0] << endl;
    @endcode
    */

    /*
    detectMultiScale重载函数，此函数允许您检索分类的最终阶段决策确定性
    为此，需要将' outputRejectLevels '设置为true，才能输出' rejectLevels '和' levelWeights '参数。
    对于每一个结果检测，‘levelWeights’将在最后阶段包含分类的确定性。这个值可以用来区分强分类和弱分类。 
    另，使用旧分类器的时候必须设置flags为CV_HAAR_SCALE_IMAGE，可以通过haarcascade_frontalface_alt.xml检测人脸尝试。   
    */
    CV_WRAP_AS(detectMultiScale3) void detectMultiScale( InputArray image,
                                  CV_OUT std::vector<Rect>& objects,
                                  CV_OUT std::vector<int>& rejectLevels,
                                  CV_OUT std::vector<double>& levelWeights,
                                  double scaleFactor = 1.1,
                                  int minNeighbors = 3, int flags = 0,
                                  Size minSize = Size(),
                                  Size maxSize = Size(),
                                  bool outputRejectLevels = false );

    CV_WRAP bool isOldFormatCascade() const; //是否是旧格式的分类器
    CV_WRAP Size getOriginalWindowSize() const;// 初始检测窗口大小，也就是训练的窗口
    CV_WRAP int getFeatureType() const;// 获取特征类型
    void* getOldCascade();//获取旧格式的分类器

    CV_WRAP static bool convert(const String& oldcascade, const String& newcascade);//旧格式分类器转为新格式分类器

    void setMaskGenerator(const Ptr<BaseCascadeClassifier::MaskGenerator>& maskGenerator);
    Ptr<BaseCascadeClassifier::MaskGenerator> getMaskGenerator();

    Ptr<BaseCascadeClassifier> cc;
};