Merge pull request #374 from biometrics/cascade_documentation

Documentation for cascade branch transforms

Merge pull request #374 from biometrics/cascade_documentation
Documentation for cascade branch transforms
Scott Klum
2 parents 4594dd42 4d52c58f
Showing 8 changed files with 67 additions and 8 deletions
openbr/plugins/classification/boostedforest.cpp
openbr/plugins/classification/cascade.cpp
openbr/plugins/imgproc/rndaffine.cpp
openbr/plugins/imgproc/slidingwindow.cpp
openbr/plugins/representation/gradienthistogram.cpp
openbr/plugins/representation/haar.cpp
openbr/plugins/representation/mblbp.cpp
openbr/plugins/representation/random.cpp
@@ -83,6 +83,18 @@ static void storeRecursive(QDataStream &amp;stream, const Node *node, int maxCatCoun
     }
 }
  
+/*!
+ * \brief A classification wrapper on OpenCV's CvBoost class. It uses CvBoost for training a boosted forest and then performs classification using the trained nodes.
+ * \author Jordan Cheney \cite jcheney
+ * \author Scott Klum \cite sklum
+ * \br_property Representation* representation The Representation describing the features used by the boosted forest
+ * \br_property float minTAR The minimum true accept rate during training
+ * \br_property float maxFAR The maximum false accept rate during training
+ * \br_property float trimRate The trim rate during training
+ * \br_property int maxDepth The maximum depth for each trained tree
+ * \br_property int maxWeakCount The maximum number of trees in the forest
+ * \br_property Type type. The type of boosting to perform. Options are [Discrete, Real, Logit, Gentle]. Gentle is the default.
+ */
 class BoostedForestClassifier : public Classifier
 {
     Q_OBJECT
@@ -102,6 +102,19 @@ struct ImageHandler
     Size    winSize;
 };
  
+/*!
+ * \brief A meta Classifier that creates a cascade of another Classifier. The cascade is a series of stages, each with its own instance of a given classifier. A sample can only reach the next stage if it is classified as positive by the previous stage.
+ * \author Jordan Cheney \cite jcheney
+ * \author Scott Klum \cite sklum
+ * \br_property int numStages The number of stages in the cascade
+ * \br_property int numPos The number of positives to feed each stage during training
+ * \br_property int numNegs The number of negatives to feed each stage during training. A negative sample must have been classified by the previous stages in the cascade as positive to be fed to the next stage during training.
+ * \br_property float maxFAR A termination parameter. Calculated as (number of passed negatives) / (total number of checked negatives) for a given stage during training. If that number is below the given maxFAR cascade training is terminated early. This can help prevent overfitting.
+ * \br_paper Paul Viola, Michael Jones
+ *           Rapid Object Detection using a Boosted Cascade of Simple Features
+ *           CVPR, 2001
+ * \br_link Rapid Object Detection using a Boosted Cascade of Simple Features https://www.cs.cmu.edu/~efros/courses/LBMV07/Papers/viola-cvpr-01.pdf
+ */
 class CascadeClassifier : public Classifier
 {
     Q_OBJECT
@@ -8,6 +8,13 @@ using namespace cv;
 namespace br
 {
  
+/*!
+ * \brief Perform a number of random transformations to the points in metadata as "Affine_0" and "Affine_1"
+ * \author Jordan Cheney \cite jcheney
+ * \br_property int numAffines The number of independent random transformations to perform. The result of each transform is stored as its own template in the output TemplateList
+ * \br_property float scaleFactor Controls the magnitude of the random changes to the affine points
+ * \br_property int maxAngle the maximum angle between the original line between the two affine points and the new line between the points.
+ */
 class RndAffineTransform : public UntrainableMetaTransform
 {
     Q_OBJECT
@@ -17,8 +24,6 @@ class RndAffineTransform : public UntrainableMetaTransform
     Q_PROPERTY(float scaleFactor READ get_scaleFactor WRITE set_scaleFactor RESET reset_scaleFactor STORED false)
     Q_PROPERTY(int maxAngle READ get_maxAngle WRITE set_maxAngle RESET reset_maxAngle STORED false)
     BR_PROPERTY(int, numAffines, 0)
-    BR_PROPERTY(int, winWidth, 24)
-    BR_PROPERTY(int, winHeight, 24)
     BR_PROPERTY(float, scaleFactor, 1.2)
     BR_PROPERTY(int, maxAngle, 15)
  
@@ -27,10 +27,17 @@ namespace br
  
 /*!
  * \ingroup transforms
- * \brief Sliding Window Framework
- * \author Jordan Cheney
+ * \brief Sliding Window Framework for object detection. Performs an exhaustive search of an image by sliding a window of a given size around the image and then resizing the image and repeating until terminating conditions are met.
+ * \author Jordan Cheney \cite jcheney
+ * \author Scott Klum \cite sklum
+ * \br_property Classifier* classifier The classifier that determines if a given window is a positive or negative sample. The size of the window is determined using the classifiers *windowSize* method.
+ * \br_property int minSize The smallest sized object to detect in pixels
+ * \br_property int maxSize The largest sized object to detect in pixels. A negative value will set maxSize == image size
+ * \br_property float scaleFactor The factor to scale the image by during each resize.
+ * \br_property int minNeighbors Parameter for non-maximum supression
+ * \br_property float confidenceThreshold A threshold for positive detections. Positive detections returned by the classifier that have confidences below this threshold are considered negative detections.
+ * \br_property float eps Parameter for non-maximum supression
  */
-
 class SlidingWindowTransform : public MetaTransform
 {
     Q_OBJECT
@@ -10,7 +10,7 @@ namespace br
 {
  
 /*!
- * \ingroup galleries
+ * \ingroup representations
  * \brief Computes first order gradient histogram features using an integral image
  * \author Scott Klum \cite sklum
  */
@@ -18,6 +18,16 @@ namespace br
     /* (x + w, y + h) */                                                  \
     (p3) = (rect).x + (rect).width + (step) * ((rect).y + (rect).height);
  
+/*!
+ * \brief An implementation of Haar Features for Viola-Jones cascade object detection
+ * \author Jordan Cheney \cite jcheney
+ * \br_property int winWidth The width of the input image. The total feature space is based on this and the winHeight
+ * \br_property int winHeight The height of the input image. The total feature space is based on this and the winWidth.
+ * \br_paper Paul Viola, Michael Jones
+ *           Rapid Object Detection using a Boosted Cascade of Simple Features
+ *           CVPR, 2001
+ * \br_link Rapid Object Detection using a Boosted Cascade of Simple Features https://www.cs.cmu.edu/~efros/courses/LBMV07/Papers/viola-cvpr-01.pdf
+ */
 class HaarRepresentation : public Representation
 {
     Q_OBJECT
@@ -18,6 +18,16 @@ namespace br
     /* (x + w, y + h) */                                                  \
     (p3) = (rect).x + (rect).width + (step) * ((rect).y + (rect).height);
  
+/*!
+ * \brief An implementation of MBLBP as an OpenBR Representation
+ * \author Jordan Cheney \cite jcheney
+ * \br_property int winWidth The width of the input image. The total feature space is based on this and the winHeight
+ * \br_property int winHeight The height of the input image. The total feature space is based on this and the winWidth.
+ * \br_paper Shengcai Liao, Xiangxin Zhu, Zhen Lei, Lun Zhang, Stan Z. Li
+ *           Learning Multi-scale Block Local Binary Patterns for Face Recognition
+ *           ICB, 2007
+ * \br_link Learning Multi-scale Block Local Binary Patterns for Face Recognition http://www.cbsr.ia.ac.cn/users/lzhang/papers/ICB07/ICB07_Liao.pdf
+ */
 class MBLBPRepresentation : public Representation
 {
     Q_OBJECT
@@ -11,9 +11,11 @@ namespace br
 {
  
 /*!
- * \ingroup galleries
- * \brief Computes first order gradient histogram features using an integral image
+ * \ingroup representations
+ * \brief A meta Representation that creates a smaller, random feature space from the full feature space of a given representation.
  * \author Scott Klum \cite sklum
+ * \br_property Representation* representation The representation from which to create the random feature space
+ * \br_property int count The size of the random feature space
  */
 class RandomRepresentation : public Representation
 {