update documentation for softcascade module

2013-01-29 19:18:22 +04:00
parent 7f80054dfd
commit a01f596474
6 changed files with 173 additions and 44 deletions
--- a/modules/softcascade/doc/softcascade_detector.rst
+++ b/modules/softcascade/doc/softcascade_detector.rst
@@ -25,29 +25,37 @@ The sample has been rejected if it fall rejection threshold. So stageless cascad
 .. [BMTG12] Rodrigo Benenson, Markus Mathias, Radu Timofte and Luc Van Gool. Pedestrian detection at 100 frames per second. IEEE CVPR, 2012.


-SCascade
----------------
-.. ocv:class:: SCascade
+SoftCascadeDetector
+-------------------
+.. ocv:class:: SoftCascadeDetector

 Implementation of soft (stageless) cascaded detector. ::

-    class CV_EXPORTS SCascade : public Algorithm
+    class CV_EXPORTS_W SoftCascadeDetector : public Algorithm
    {
    public:
-        SCascade(const float minScale = 0.4f, const float maxScale = 5.f, const int scales = 55, const int rejfactor = 1);
-        virtual ~SCascade();
+
+        enum { NO_REJECT = 1, DOLLAR = 2, /*PASCAL = 4,*/ DEFAULT = NO_REJECT};
+
+        CV_WRAP SoftCascadeDetector(double minScale = 0.4, double maxScale = 5., int scales = 55, int rejCriteria = 1);
+        CV_WRAP virtual ~SoftCascadeDetector();
        cv::AlgorithmInfo* info() const;
-        virtual bool load(const FileNode& fn);
+        CV_WRAP virtual bool load(const FileNode& fileNode);
+        CV_WRAP virtual void read(const FileNode& fileNode);
        virtual void detect(InputArray image, InputArray rois, std::vector<Detection>& objects) const;
-        virtual void detect(InputArray image, InputArray rois, OutputArray rects, OutputArray confs) const;
-    };
+        CV_WRAP virtual void detect(InputArray image, InputArray rois, CV_OUT OutputArray rects, CV_OUT OutputArray confs) const;
+
+    }


-SCascade::SCascade
--------------------------
+
+SoftCascadeDetector::SoftCascadeDetector
+----------------------------------------
 An empty cascade will be created.

-.. ocv:function:: bool SCascade::SCascade(const float minScale = 0.4f, const float maxScale = 5.f, const int scales = 55, const int rejfactor = 1)
+.. ocv:function:: SoftCascadeDetector::SoftCascadeDetector(float minScale = 0.4f, float maxScale = 5.f, int scales = 55, int rejCriteria = 1)
+
+.. ocv:pyfunction:: cv2.SoftCascadeDetector.SoftCascadeDetector(minScale[, maxScale[, scales[, rejCriteria]]]) -> cascade

    :param minScale: a minimum scale relative to the original size of the image on which cascade will be applied.

@@ -55,35 +63,39 @@ An empty cascade will be created.

    :param scales: a number of scales from minScale to maxScale.

-    :param rejfactor: used for non maximum suppression.
+    :param rejCriteria: algorithm used for non maximum suppression.



-SCascade::~SCascade
---------------------------
-Destructor for SCascade.
+SoftCascadeDetector::~SoftCascadeDetector
+-----------------------------------------
+Destructor for SoftCascadeDetector.

-.. ocv:function:: SCascade::~SCascade()
+.. ocv:function:: SoftCascadeDetector::~SoftCascadeDetector()



-SCascade::load
+SoftCascadeDetector::load
 --------------------------
 Load cascade from FileNode.

-.. ocv:function:: bool SCascade::load(const FileNode& fn)
+.. ocv:function:: bool SoftCascadeDetector::load(const FileNode& fileNode)

-    :param fn: File node from which the soft cascade are read.
+.. ocv:pyfunction:: cv2.SoftCascadeDetector.load(fileNode)
+
+    :param fileNode: File node from which the soft cascade are read.



-SCascade::detect
--------------------------
+SoftCascadeDetector::detect
+---------------------------
 Apply cascade to an input frame and return the vector of Detection objects.

-.. ocv:function:: void SCascade::detect(InputArray image, InputArray rois, std::vector<Detection>& objects) const
+.. ocv:function:: void SoftCascadeDetector::detect(InputArray image, InputArray rois, std::vector<Detection>& objects) const

-.. ocv:function:: void SCascade::detect(InputArray image, InputArray rois, OutputArray rects, OutputArray confs) const
+.. ocv:function:: void SoftCascadeDetector::detect(InputArray image, InputArray rois, OutputArray rects, OutputArray confs) const
+
+.. ocv:pyfunction:: cv2.SoftCascadeDetector.detect(image, rois) -> (rects, confs)

    :param image: a frame on which detector will be applied.

@@ -93,4 +105,41 @@ Apply cascade to an input frame and return the vector of Detection objects.

    :param rects: an output array of bounding rectangles for detected objects.

-    :param confs: an output array of confidence for detected objects. i-th bounding rectangle corresponds i-th confidence.
+    :param confs: an output array of confidence for detected objects. i-th bounding rectangle corresponds i-th confidence.
+
+
+ChannelFeatureBuilder
+---------------------
+.. ocv:class:: ChannelFeatureBuilder
+
+Public interface for of soft (stageless) cascaded detector. ::
+
+    class CV_EXPORTS_W ChannelFeatureBuilder : public Algorithm
+    {
+    public:
+        virtual ~ChannelFeatureBuilder();
+
+        CV_WRAP_AS(compute) virtual void operator()(InputArray src, CV_OUT OutputArray channels) const = 0;
+
+        CV_WRAP static cv::Ptr<ChannelFeatureBuilder> create();
+    };
+
+
+ChannelFeatureBuilder:~ChannelFeatureBuilder
+--------------------------------------------
+Destructor for ChannelFeatureBuilder.
+
+.. ocv:function:: ChannelFeatureBuilder::~ChannelFeatureBuilder()
+
+
+ChannelFeatureBuilder::operator()
+---------------------------------
+Create channel feature integrals for input image.
+
+.. ocv:function:: void ChannelFeatureBuilder::operator()(InputArray src, OutputArray channels) const
+
+.. ocv:pyfunction:: cv2.ChannelFeatureBuilder.compute(src, channels) -> None
+
+    :param src source frame
+
+    :param channels in OutputArray of computed channels
--- a/modules/softcascade/doc/softcascade_training.rst
+++ b/modules/softcascade/doc/softcascade_training.rst
@@ -1,2 +1,82 @@
 Soft Cascade Training
-=======================
+=======================
+
+.. highlight:: cpp
+
+Soft Cascade Detector Training
+--------------------------------------------
+
+
+SoftCascadeOctave
+-----------------
+.. ocv:class:: SoftCascadeOctave
+
+Public interface for soft cascade training algorithm
+
+    class CV_EXPORTS SoftCascadeOctave : public Algorithm
+    {
+    public:
+
+        enum {
+            // Direct backward pruning. (Cha Zhang and Paul Viola)
+            DBP = 1,
+            // Multiple instance pruning. (Cha Zhang and Paul Viola)
+            MIP = 2,
+            // Originally proposed by L. Bourdev and J. Brandt
+            HEURISTIC = 4 };
+
+        virtual ~SoftCascadeOctave();
+        static cv::Ptr<SoftCascadeOctave> create(cv::Rect boundingBox, int npositives, int nnegatives, int logScale, int shrinkage);
+
+        virtual bool train(const Dataset* dataset, const FeaturePool* pool, int weaks, int treeDepth) = 0;
+        virtual void setRejectThresholds(OutputArray thresholds) = 0;
+        virtual void write( cv::FileStorage &fs, const FeaturePool* pool, InputArray thresholds) const = 0;
+        virtual void write( CvFileStorage* fs, string name) const = 0;
+
+    };
+
+
+
+SoftCascadeOctave::~SoftCascadeOctave
+---------------------------------------
+Destructor for SoftCascadeOctave.
+
+.. ocv:function:: SoftCascadeOctave::~SoftCascadeOctave()
+
+
+SoftCascadeOctave::train
+------------------------
+
+.. ocv:function:: bool SoftCascadeOctave::train(const Dataset* dataset, const FeaturePool* pool, int weaks, int treeDepth)
+
+    :param dataset an object that allows communicate for training set.
+
+    :param pool an object that presents feature pool.
+
+    :param weaks a number of weak trees should be trained.
+
+    :param treeDepth a depth of resulting weak trees.
+
+
+
+SoftCascadeOctave::setRejectThresholds
+--------------------------------------
+
+.. ocv:function:: void SoftCascadeOctave::setRejectThresholds(OutputArray thresholds)
+
+    :param thresholds an output array of resulted rejection vector. Have same size as number of trained stages.
+
+
+SoftCascadeOctave::write
+------------------------
+
+.. ocv:function:: write SoftCascadeOctave::train(cv::FileStorage &fs, const FeaturePool* pool, InputArray thresholds) const
+.. ocv:function:: write SoftCascadeOctave::train( CvFileStorage* fs, string name) const
+
+    :param fs an output file storage to store trained detector.
+
+    :param pool an object that presents feature pool.
+
+    :param dataset a rejection vector that should be included in detector xml file.
+
+    :param name a name of root node for trained detector.
--- a/modules/softcascade/src/soft_cascade_octave.cpp
+++ b/modules/softcascade/src/soft_cascade_octave.cpp
@@ -11,7 +11,7 @@
 //                For Open Source Computer Vision Library
 //
 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
-// Copyright (C) 2008-2012, Willow Garage Inc., all rights reserved.
+// Copyright (C) 2008-2013, Willow Garage Inc., all rights reserved.
 // Third party copyrights are property of their respective owners.
 //
 // Redistribution and use in source and binary forms, with or without modification,
@@ -22,7 +22,7 @@
 //
 //   * Redistribution's in binary form must reproduce the above copyright notice,
 //     this list of conditions and the following disclaimer in the documentation
-//     and/or other materials provided with the distribution.
+//     and / or other materials provided with the distribution.
 //
 //   * The name of the copyright holders may not be used to endorse or promote products
 //     derived from this software without specific prior written permission.
@@ -216,7 +216,7 @@ void BoostedSoftCascadeOctave::setRejectThresholds(cv::OutputArray _thresholds)
 {
    dprintf("set thresholds according to DBP strategy\n");

-    // labels desided by classifier
+    // labels decided by classifier
    cv::Mat desisions(responses.cols, responses.rows, responses.type());
    float* dptr = desisions.ptr<float>(0);

@@ -423,7 +423,7 @@ void BoostedSoftCascadeOctave::write( cv::FileStorage &fso, const FeaturePool* p
        << "scale" << logScale
        << "weaks" << weak->total
        << "trees" << "[";
-        // should be replased with the H.L. one
+        // should be replaced with the H.L. one
        CvSeqReader reader;
        cvStartReadSeq( weak, &reader);

@@ -463,7 +463,7 @@ bool BoostedSoftCascadeOctave::train(const Dataset* dataset, const FeaturePool*
    processPositives(dataset, pool);
    generateNegatives(dataset, pool);

-    // 2. only sumple case (all features used)
+    // 2. only simple case (all features used)
    int nfeatures = pool->size();
    cv::Mat varIdx(1, nfeatures, CV_32SC1);
    int* ptr = varIdx.ptr<int>(0);
@@ -471,7 +471,7 @@ bool BoostedSoftCascadeOctave::train(const Dataset* dataset, const FeaturePool*
    for (int x = 0; x < nfeatures; ++x)
        ptr[x] = x;

-    // 3. only sumple case (all samples used)
+    // 3. only simple case (all samples used)
    int nsamples = npositives + nnegatives;
    cv::Mat sampleIdx(1, nsamples, CV_32SC1);
    ptr = sampleIdx.ptr<int>(0);
@@ -479,7 +479,7 @@ bool BoostedSoftCascadeOctave::train(const Dataset* dataset, const FeaturePool*
    for (int x = 0; x < nsamples; ++x)
        ptr[x] = x;

-    // 4. ICF has an orderable responce.
+    // 4. ICF has an ordered response.
    cv::Mat varType(1, nfeatures + 1, CV_8UC1);
    uchar* uptr = varType.ptr<uchar>(0);
    for (int x = 0; x < nfeatures; ++x)