1 \section{Object Detection}
5 \cvCPyFunc{MatchTemplate}
6 Compares a template against overlapped image regions.
9 void cvMatchTemplate( \par const CvArr* image,\par const CvArr* templ,\par CvArr* result,\par int method );
10 }\cvdefPy{MatchTemplate(image,templ,result,method)-> None}
13 \cvarg{image}{Image where the search is running; should be 8-bit or 32-bit floating-point}
14 \cvarg{templ}{Searched template; must be not greater than the source image and the same data type as the image}
15 \cvarg{result}{A map of comparison results; single-channel 32-bit floating-point.
16 If \texttt{image} is $W \times H$ and
17 \texttt{templ} is $w \times h$ then \texttt{result} must be $(W-w+1) \times (H-h+1)$}
18 \cvarg{method}{Specifies the way the template must be compared with the image regions (see below)}
21 The function is similar to
22 \cvCPyCross{CalcBackProjectPatch}. It slides through \texttt{image}, compares the
23 overlapped patches of size $w \times h$ against \texttt{templ}
24 using the specified method and stores the comparison results to
25 \texttt{result}. Here are the formulas for the different comparison
26 methods one may use ($I$ denotes \texttt{image}, $T$ \texttt{template},
27 $R$ \texttt{result}). The summation is done over template and/or the
28 image patch: $x' = 0...w-1, y' = 0...h-1$
30 % \texttt{x'=0..w-1, y'=0..h-1}):
33 \item[method=CV\_TM\_SQDIFF]
34 \[ R(x,y)=\sum_{x',y'} (T(x',y')-I(x+x',y+y'))^2 \]
36 \item[method=CV\_TM\_SQDIFF\_NORMED]
38 {\sum_{x',y'} (T(x',y')-I(x+x',y+y'))^2}
39 {\sqrt{\sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}
42 \item[method=CV\_TM\_CCORR]
43 \[ R(x,y)=\sum_{x',y'} (T(x',y') \cdot I(x+x',y+y')) \]
45 \item[method=CV\_TM\_CCORR\_NORMED]
47 {\sum_{x',y'} (T(x',y') \cdot I'(x+x',y+y'))}
48 {\sqrt{\sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}
51 \item[method=CV\_TM\_CCOEFF]
52 \[ R(x,y)=\sum_{x',y'} (T'(x',y') \cdot I(x+x',y+y')) \]
57 T'(x',y')=T(x',y') - 1/(w \cdot h) \cdot \sum_{x'',y''} T(x'',y'')\\
58 I'(x+x',y+y')=I(x+x',y+y') - 1/(w \cdot h) \cdot \sum_{x'',y''} I(x+x'',y+y'')
62 \item[method=CV\_TM\_CCOEFF\_NORMED]
64 { \sum_{x',y'} (T'(x',y') \cdot I'(x+x',y+y')) }
65 { \sqrt{\sum_{x',y'}T'(x',y')^2 \cdot \sum_{x',y'} I'(x+x',y+y')^2} }
69 After the function finishes the comparison, the best matches can be found as global minimums (\texttt{CV\_TM\_SQDIFF}) or maximums (\texttt{CV\_TM\_CCORR} and \texttt{CV\_TM\_CCOEFF}) using the \cvCPyCross{MinMaxLoc} function. In the case of a color image, template summation in the numerator and each sum in the denominator is done over all of the channels (and separate mean values are used for each channel).
71 \subsection{Haar Feature-based Cascade Classifier for Object Detection}
73 The object detector described below has been initially proposed by Paul Viola
75 and improved by Rainer Lienhart
76 \cvCPyCross{Lienhart02}
77 . First, a classifier (namely a \emph{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.
79 After a classifier is trained, it can be applied to a region of interest
80 (of the same size as used during the training) in an input image. The
81 classifier outputs a "1" if the region is likely to show the object
82 (i.e., face/car), and "0" otherwise. To search for the object in the
83 whole image one can move the search window across the image and check
84 every location using the classifier. The classifier is designed so that
85 it can be easily "resized" in order to be able to find the objects of
86 interest at different sizes, which is more efficient than resizing the
87 image itself. So, to find an object of an unknown size in the image the
88 scan procedure should be done several times at different scales.
90 The word "cascade" in the classifier name means that the resultant
91 classifier consists of several simpler classifiers (\emph{stages}) that
92 are applied subsequently to a region of interest until at some stage the
93 candidate is rejected or all the stages are passed. The word "boosted"
94 means that the classifiers at every stage of the cascade are complex
95 themselves and they are built out of basic classifiers using one of four
96 different \texttt{boosting} techniques (weighted voting). Currently
97 Discrete Adaboost, Real Adaboost, Gentle Adaboost and Logitboost are
98 supported. The basic classifiers are decision-tree classifiers with at
99 least 2 leaves. Haar-like features are the input to the basic classifers,
100 and are calculated as described below. The current algorithm uses the
101 following Haar-like features:
103 \includegraphics[width=0.5\textwidth]{pics/haarfeatures.png}
105 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 \cvCPyCross{Integral} description).
108 A simple demonstration of face detection, which draws a rectangle around each detected face:
112 hc = cv.Load("haarcascade_frontalface_default.xml")
113 img = cv.LoadImage("faces.jpg", 0)
114 faces = cv.HaarDetectObjects(img, hc, cv.CreateMemStorage())
115 for (x,y,w,h),n in faces:
116 cv.Rectangle(img, (x,y), (x+w,y+h), 255)
117 cv.SaveImage("faces_detected.jpg", img)
124 To see the object detector at work, have a look at the HaarFaceDetect demo.
126 The following reference is for the detection part only. There
127 is a separate application called \texttt{haartraining} that can
128 train a cascade of boosted classifiers from a set of samples. See
129 \texttt{opencv/apps/haartraining} for details.
131 \cvclass{CvHaarFeature, CvHaarClassifier, CvHaarStageClassifier, CvHaarClassifierCascade}
132 \label{CvHaarFeature}
133 \label{CvHaarClassifier}
134 \label{CvHaarStageClassifier}
135 \label{CvHaarClassifierCascade}
137 Boosted Haar classifier structures.
140 #define CV_HAAR_FEATURE_MAX 3
142 /* a haar feature consists of 2-3 rectangles with appropriate weights */
143 typedef struct CvHaarFeature
145 int tilted; /* 0 means up-right feature, 1 means 45--rotated feature */
147 /* 2-3 rectangles with weights of opposite signs and
148 with absolute values inversely proportional to the areas of the
149 rectangles. If rect[2].weight !=0, then
150 the feature consists of 3 rectangles, otherwise it consists of 2 */
155 } rect[CV_HAAR_FEATURE_MAX];
159 /* a single tree classifier (stump in the simplest case) that returns the
160 response for the feature at the particular image location (i.e. pixel
161 sum over subrectangles of the window) and gives out a value depending
163 typedef struct CvHaarClassifier
165 int count; /* number of nodes in the decision tree */
167 /* these are "parallel" arrays. Every index \texttt{i}
168 corresponds to a node of the decision tree (root has 0-th index).
170 left[i] - index of the left child (or negated index if the
171 left child is a leaf)
172 right[i] - index of the right child (or negated index if the
173 right child is a leaf)
174 threshold[i] - branch threshold. if feature responce is <= threshold,
175 left branch is chosen, otherwise right branch is chosen.
176 alpha[i] - output value correponding to the leaf. */
177 CvHaarFeature* haar_feature;
185 /* a boosted battery of classifiers(=stage classifier):
186 the stage classifier returns 1
187 if the sum of the classifiers responses
188 is greater than \texttt{threshold} and 0 otherwise */
189 typedef struct CvHaarStageClassifier
191 int count; /* number of classifiers in the battery */
192 float threshold; /* threshold for the boosted classifier */
193 CvHaarClassifier* classifier; /* array of classifiers */
195 /* these fields are used for organizing trees of stage classifiers,
196 rather than just stright cascades */
201 CvHaarStageClassifier;
203 typedef struct CvHidHaarClassifierCascade CvHidHaarClassifierCascade;
205 /* cascade or tree of stage classifiers */
206 typedef struct CvHaarClassifierCascade
208 int flags; /* signature */
209 int count; /* number of stages */
210 CvSize orig_window_size; /* original object size (the cascade is
213 /* these two parameters are set by cvSetImagesForHaarClassifierCascade */
214 CvSize real_window_size; /* current object size */
215 double scale; /* current scale */
216 CvHaarStageClassifier* stage_classifier; /* array of stage classifiers */
217 CvHidHaarClassifierCascade* hid_cascade; /* hidden optimized
218 representation of the
220 cvSetImagesForHaarClassifierCascade */
222 CvHaarClassifierCascade;
225 All the structures are used for representing a cascaded of boosted Haar classifiers. The cascade has the following hierarchical structure:
242 The whole hierarchy can be constructed manually or loaded from a file or an embedded base using the function \cvCPyCross{LoadHaarClassifierCascade}.
244 \cvCPyFunc{LoadHaarClassifierCascade}
245 Loads a trained cascade classifier from a file or the classifier database embedded in OpenCV.
248 CvHaarClassifierCascade* cvLoadHaarClassifierCascade( \par const char* directory,\par CvSize orig\_window\_size );
252 \cvarg{directory}{Name of the directory containing the description of a trained cascade classifier}
253 \cvarg{orig\_window\_size}{Original size of the objects the cascade has been trained on. Note that it is not stored in the cascade and therefore must be specified separately}
256 The function loads a trained cascade
257 of haar classifiers from a file or the classifier database embedded in
258 OpenCV. The base can be trained using the \texttt{haartraining} application
259 (see opencv/apps/haartraining for details).
261 \textbf{The function is obsolete}. Nowadays object detection classifiers are stored in XML or YAML files, rather than in directories. To load a cascade from a file, use the \cvCPyCross{Load} function.
265 \cvCPyFunc{HaarDetectObjects}
266 Detects objects in the image.
270 typedef struct CvAvgComp
272 CvRect rect; /* bounding rectangle for the object (average rectangle of a group) */
273 int neighbors; /* number of neighbor rectangles in the group */
280 CvSeq* cvHaarDetectObjects( \par const CvArr* image,\par CvHaarClassifierCascade* cascade,\par CvMemStorage* storage,\par double scale\_factor=1.1,\par int min\_neighbors=3,\par int flags=0,\par CvSize min\_size=cvSize(0,\par0) );
281 }\cvdefPy{HaarDetectObjects(image,cascade,storage,scale\_factor=1.1,min\_neighbors=3,flags=0,min\_size=(0,0))-> detected\_objects}
284 \cvarg{image}{Image to detect objects in}
285 \cvarg{cascade}{Haar classifier cascade in internal representation}
286 \cvarg{storage}{Memory storage to store the resultant sequence of the object candidate rectangles}
287 \cvarg{scale\_factor}{The factor by which the search window is scaled between the subsequent scans, 1.1 means increasing window by 10\% }
288 \cvarg{min\_neighbors}{Minimum number (minus 1) of neighbor rectangles that makes up an object. All the groups of a smaller number of rectangles than \texttt{min\_neighbors}-1 are rejected. If \texttt{min\_neighbors} is 0, the function does not any grouping at all and returns all the detected candidate rectangles, which may be useful if the user wants to apply a customized grouping procedure}
289 \cvarg{flags}{Mode of operation. Currently the only flag that may be specified is \texttt{CV\_HAAR\_DO\_CANNY\_PRUNING}. If it is set, the function uses Canny edge detector to reject some image regions that contain too few or too much edges and thus can not contain the searched object. The particular threshold values are tuned for face detection and in this case the pruning speeds up the processing}
290 \cvarg{min\_size}{Minimum window size. By default, it is set to the size of samples the classifier has been trained on ($\sim 20\times 20$ for face detection)}
293 The function finds rectangular regions in the given image that are likely to contain objects the cascade has been trained for and returns those regions as a sequence of rectangles. The function scans the image several times at different scales (see \cvCPyCross{SetImagesForHaarClassifierCascade}). Each time it considers overlapping regions in the image and applies the classifiers to the regions using \cvCPyCross{RunHaarClassifierCascade}. It may also apply some heuristics to reduce number of analyzed regions, such as Canny prunning. After it has proceeded and collected the candidate rectangles (regions that passed the classifier cascade), it groups them and returns a sequence of average rectangles for each large enough group. The default parameters (\texttt{scale\_factor} =1.1, \texttt{min\_neighbors} =3, \texttt{flags} =0) are tuned for accurate yet slow object detection. For a faster operation on real video images the settings are: \texttt{scale\_factor} =1.2, \texttt{min\_neighbors} =2, \texttt{flags} =\texttt{CV\_HAAR\_DO\_CANNY\_PRUNING}, \texttt{min\_size} =\textit{minimum possible face size} (for example, $\sim$ 1/4 to 1/16 of the image area in the case of video conferencing).
296 The function returns a list of tuples, \texttt{(rect, neighbors)}, where rect is a \cross{CvRect} specifying the object's extents
297 and neighbors is a number of neighbors.
301 >>> image = cv.LoadImageM("lena.jpg", cv.CV_LOAD_IMAGE_GRAYSCALE)
302 >>> cascade = cv.Load("../../data/haarcascades/haarcascade_frontalface_alt.xml")
303 >>> print cv.HaarDetectObjects(image, cascade, cv.CreateMemStorage(0), 1.2, 2, 0, (20, 20))
304 [((217, 203, 169, 169), 24)]
309 % ===== Example. Using cascade of Haar classifiers to find objects (e.g. faces). =====
314 CvHaarClassifierCascade* load_object_detector( const char* cascade_path )
316 return (CvHaarClassifierCascade*)cvLoad( cascade_path );
319 void detect_and_draw_objects( IplImage* image,
320 CvHaarClassifierCascade* cascade,
323 IplImage* small_image = image;
324 CvMemStorage* storage = cvCreateMemStorage(0);
328 /* if the flag is specified, down-scale the input image to get a
329 performance boost w/o loosing quality (perhaps) */
332 small_image = cvCreateImage( cvSize(image->width/2,image->height/2), IPL_DEPTH_8U, 3 );
333 cvPyrDown( image, small_image, CV_GAUSSIAN_5x5 );
337 /* use the fastest variant */
338 faces = cvHaarDetectObjects( small_image, cascade, storage, 1.2, 2, CV_HAAR_DO_CANNY_PRUNING );
340 /* draw all the rectangles */
341 for( i = 0; i < faces->total; i++ )
343 /* extract the rectanlges only */
344 CvRect face_rect = *(CvRect*)cvGetSeqElem( faces, i );
345 cvRectangle( image, cvPoint(face_rect.x*scale,face_rect.y*scale),
346 cvPoint((face_rect.x+face_rect.width)*scale,
347 (face_rect.y+face_rect.height)*scale),
348 CV_RGB(255,0,0), 3 );
351 if( small_image != image )
352 cvReleaseImage( &small_image );
353 cvReleaseMemStorage( &storage );
356 /* takes image filename and cascade path from the command line */
357 int main( int argc, char** argv )
360 if( argc==3 && (image = cvLoadImage( argv[1], 1 )) != 0 )
362 CvHaarClassifierCascade* cascade = load_object_detector(argv[2]);
363 detect_and_draw_objects( image, cascade, 1 );
364 cvNamedWindow( "test", 0 );
365 cvShowImage( "test", image );
367 cvReleaseHaarClassifierCascade( &cascade );
368 cvReleaseImage( &image );
376 \cvCPyFunc{SetImagesForHaarClassifierCascade}
377 Assigns images to the hidden cascade.
380 void cvSetImagesForHaarClassifierCascade( \par CvHaarClassifierCascade* cascade,\par const CvArr* sum,\par const CvArr* sqsum,\par const CvArr* tilted\_sum,\par double scale );
384 \cvarg{cascade}{Hidden Haar classifier cascade, created by \cvCPyCross{CreateHidHaarClassifierCascade}}
385 \cvarg{sum}{Integral (sum) single-channel image of 32-bit integer format. This image as well as the two subsequent images are used for fast feature evaluation and brightness/contrast normalization. They all can be retrieved from input 8-bit or floating point single-channel image using the function \cvCPyCross{Integral}}
386 \cvarg{sqsum}{Square sum single-channel image of 64-bit floating-point format}
387 \cvarg{tilted\_sum}{Tilted sum single-channel image of 32-bit integer format}
388 \cvarg{scale}{Window scale for the cascade. If \texttt{scale} =1, the original window size is used (objects of that size are searched) - the same size as specified in \cvCPyCross{LoadHaarClassifierCascade} (24x24 in the case of \texttt{default\_face\_cascade}), if \texttt{scale} =2, a two times larger window is used (48x48 in the case of default face cascade). While this will speed-up search about four times, faces smaller than 48x48 cannot be detected}
391 The function assigns images and/or window scale to the hidden classifier cascade. If image pointers are NULL, the previously set images are used further (i.e. NULLs mean "do not change images"). Scale parameter has no such a "protection" value, but the previous value can be retrieved by the \cvCPyCross{GetHaarClassifierCascadeScale} function and reused again. The function is used to prepare cascade for detecting object of the particular size in the particular image. The function is called internally by \cvCPyCross{HaarDetectObjects}, but it can be called by the user if they are using the lower-level function \cvCPyCross{RunHaarClassifierCascade}.
393 \cvCPyFunc{ReleaseHaarClassifierCascade}
394 Releases the haar classifier cascade.
397 void cvReleaseHaarClassifierCascade( \par CvHaarClassifierCascade** cascade );
401 \cvarg{cascade}{Double pointer to the released cascade. The pointer is cleared by the function}
404 The function deallocates the cascade that has been created manually or loaded using \cvCPyCross{LoadHaarClassifierCascade} or \cvCPyCross{Load}.
406 \cvCPyFunc{RunHaarClassifierCascade}
407 Runs a cascade of boosted classifiers at the given image location.
410 int cvRunHaarClassifierCascade( \par CvHaarClassifierCascade* cascade,\par CvPoint pt,\par int start\_stage=0 );
414 \cvarg{cascade}{Haar classifier cascade}
415 \cvarg{pt}{Top-left corner of the analyzed region. Size of the region is a original window size scaled by the currenly set scale. The current window size may be retrieved using the \cvCPyCross{GetHaarClassifierCascadeWindowSize} function}
416 \cvarg{start\_stage}{Initial zero-based index of the cascade stage to start from. The function assumes that all the previous stages are passed. This feature is used internally by \cvCPyCross{HaarDetectObjects} for better processor cache utilization}
419 The function runs the Haar classifier
420 cascade at a single image location. Before using this function the
421 integral images and the appropriate scale (window size) should be set
422 using \cvCPyCross{SetImagesForHaarClassifierCascade}. The function returns
423 a positive value if the analyzed rectangle passed all the classifier stages
424 (it is a candidate) and a zero or negative value otherwise.
432 \cvclass{FeatureEvaluator}
433 Base class for computing feature values in cascade classifiers.
436 class CV_EXPORTS FeatureEvaluator
439 enum { HAAR = 0, LBP = 1 }; // supported feature types
440 virtual ~FeatureEvaluator(); // destructor
441 virtual bool read(const FileNode& node);
442 virtual Ptr<FeatureEvaluator> clone() const;
443 virtual int getFeatureType() const;
445 virtual bool setImage(const Mat& img, Size origWinSize);
446 virtual bool setWindow(Point p);
448 virtual double calcOrd(int featureIdx) const;
449 virtual int calcCat(int featureIdx) const;
451 static Ptr<FeatureEvaluator> create(int type);
455 \cvCppFunc{FeatureEvaluator::read}
456 Reads parameters of the features from a FileStorage node.
459 bool FeatureEvaluator::read(const FileNode\& node);
463 \cvarg{node}{File node from which the feature parameters are read.}
466 \cvCppFunc{FeatureEvaluator::clone}
467 Returns a full copy of the feature evaluator.
470 Ptr<FeatureEvaluator> FeatureEvaluator::clone() const;
473 \cvCppFunc{FeatureEvaluator::getFeatureType}
474 Returns the feature type (HAAR or LBP for now).
477 int FeatureEvaluator::getFeatureType() const;
480 \cvCppFunc{FeatureEvaluator::setImage}
481 Sets the image in which to compute the features.
484 bool FeatureEvaluator::setImage(const Mat\& img, Size origWinSize);
488 \cvarg{img}{Matrix of type \texttt{CV\_8UC1} containing the image in which to compute the features.}
489 \cvarg{origWinSize}{Size of training images.}
492 \cvCppFunc{FeatureEvaluator::setWindow}
493 Sets window in the current image in which the features will be computed (called by \cvCppCross{CascadeClassifier::runAt}).
496 bool FeatureEvaluator::setWindow(Point p);
500 \cvarg{p}{The upper left point of window in which the features will be computed. Size of the window is equal to size of training images.}
503 \cvCppFunc{FeatureEvaluator::calcOrd}
504 Computes value of an ordered (numerical) feature.
507 double FeatureEvaluator::calcOrd(int featureIdx) const;
511 \cvarg{featureIdx}{Index of feature whose value will be computed.}
513 Returns computed value of ordered feature.
515 \cvCppFunc{FeatureEvaluator::calcCat}
516 Computes value of a categorical feature.
519 int FeatureEvaluator::calcCat(int featureIdx) const;
523 \cvarg{featureIdx}{Index of feature whose value will be computed.}
525 Returns computed label of categorical feature, i.e. value from [0,... (number of categories - 1)].
527 \cvCppFunc{FeatureEvaluator::create}
528 Constructs feature evaluator.
531 static Ptr<FeatureEvaluator> FeatureEvaluator::create(int type);
535 \cvarg{type}{Type of features evaluated by cascade (HAAR or LBP for now).}
538 \cvclass{CascadeClassifier}
539 The cascade classifier class for object detection.
542 class CascadeClassifier
545 // structure for storing tree node
546 struct CV_EXPORTS DTreeNode
548 int featureIdx; // feature index on which is a split
549 float threshold; // split threshold of ordered features only
550 int left; // left child index in the tree nodes array
551 int right; // right child index in the tree nodes array
554 // structure for storing desision tree
555 struct CV_EXPORTS DTree
557 int nodeCount; // nodes count
560 // structure for storing cascade stage (BOOST only for now)
561 struct CV_EXPORTS Stage
563 int first; // first tree index in tree array
564 int ntrees; // number of trees
565 float threshold; // treshold of stage sum
568 enum { BOOST = 0 }; // supported stage types
570 // mode of detection (see parameter flags in function HaarDetectObjects)
571 enum { DO_CANNY_PRUNING = CV_HAAR_DO_CANNY_PRUNING,
572 SCALE_IMAGE = CV_HAAR_SCALE_IMAGE,
573 FIND_BIGGEST_OBJECT = CV_HAAR_FIND_BIGGEST_OBJECT,
574 DO_ROUGH_SEARCH = CV_HAAR_DO_ROUGH_SEARCH };
576 CascadeClassifier(); // default constructor
577 CascadeClassifier(const string& filename);
578 ~CascadeClassifier(); // destructor
581 bool load(const string& filename);
582 bool read(const FileNode& node);
584 void detectMultiScale( const Mat& image, vector<Rect>& objects,
585 double scaleFactor=1.1, int minNeighbors=3,
586 int flags=0, Size minSize=Size());
588 bool setImage( Ptr<FeatureEvaluator>&, const Mat& );
589 int runAt( Ptr<FeatureEvaluator>&, Point );
591 bool is_stump_based; // true, if the trees are stumps
593 int stageType; // stage type (BOOST only for now)
594 int featureType; // feature type (HAAR or LBP for now)
595 int ncategories; // number of categories (for categorical features only)
596 Size origWinSize; // size of training images
598 vector<Stage> stages; // vector of stages (BOOST for now)
599 vector<DTree> classifiers; // vector of decision trees
600 vector<DTreeNode> nodes; // vector of tree nodes
601 vector<float> leaves; // vector of leaf values
602 vector<int> subsets; // subsets of split by categorical feature
604 Ptr<FeatureEvaluator> feval; // pointer to feature evaluator
605 Ptr<CvHaarClassifierCascade> oldCascade; // pointer to old cascade
609 \cvCppFunc{CascadeClassifier::CascadeClassifier}
610 Loads the classifier from file.
613 CascadeClassifier::CascadeClassifier(const string\& filename);
617 \cvarg{filename}{Name of file from which classifier will be load.}
620 \cvCppFunc{CascadeClassifier::empty}
621 Checks if the classifier has been loaded or not.
624 bool CascadeClassifier::empty() const;
627 \cvCppFunc{CascadeClassifier::load}
628 Loads the classifier from file. The previous content is destroyed.
631 bool CascadeClassifier::load(const string\& filename);
635 \cvarg{filename}{Name of file from which classifier will be load. File may contain as old haar classifier (trained by haartraining application) or new cascade classifier (trained traincascade application).}
638 \cvCppFunc{CascadeClassifier::read}
639 Reads the classifier from a FileStorage node. File may contain a new cascade classifier (trained traincascade application) only.
642 bool CascadeClassifier::read(const FileNode\& node);
645 \cvCppFunc{CascadeClassifier::detectMultiScale}
646 Detects objects of different sizes in the input image. The detected objects are returned as a list of rectangles.
649 void CascadeClassifier::detectMultiScale( const Mat\& image,
650 vector<Rect>\& objects,
651 double scaleFactor=1.1,
652 int minNeighbors=3, int flags=0,
653 Size minSize=Size());
657 \cvarg{image}{Matrix of type \texttt{CV\_8U} containing the image in which to detect objects.}
658 \cvarg{objects}{Vector of rectangles such that each rectangle contains the detected object.}
659 \cvarg{scaleFactor}{Specifies how much the image size is reduced at each image scale.}
660 \cvarg{minNeighbors}{Speficifes how many neighbors should each candiate rectangle have to retain it.}
661 \cvarg{flags}{This parameter is not used for new cascade and have the same meaning for old cascade as in function cvHaarDetectObjects.}
662 \cvarg{minSize}{The minimum possible object size. Objects smaller than that are ignored.}
665 \cvCppFunc{CascadeClassifier::setImage}
666 Sets the image for detection (called by detectMultiScale at each image level).
669 bool CascadeClassifier::setImage( Ptr<FeatureEvaluator>\& feval, const Mat\& image );
673 \cvarg{feval}{Pointer to feature evaluator which is used for computing features.}
674 \cvarg{image}{Matrix of type \texttt{CV\_8UC1} containing the image in which to compute the features.}
677 \cvCppFunc{CascadeClassifier::runAt}
678 Runs the detector at the specified point (the image that the detector is working with should be set by setImage).
681 int CascadeClassifier::runAt( Ptr<FeatureEvaluator>\& feval, Point pt );
685 \cvarg{feval}{Feature evaluator which is used for computing features.}
686 \cvarg{pt}{The upper left point of window in which the features will be computed. Size of the window is equal to size of training images.}
689 1 - if cascade classifier detects object in the given location.
690 -si - otherwise. si is an index of stage which first predicted that given window is a background image.
692 \cvCppFunc{groupRectangles}
693 Groups the object candidate rectangles
695 \cvdefCpp{void groupRectangles(vector<Rect>\& rectList,\par
696 int groupThreshold, double eps=0.2);}
698 \cvarg{rectList}{The input/output vector of rectangles. On output there will be retained and grouped rectangles}
699 \cvarg{groupThreshold}{The minimum possible number of rectangles, minus 1, in a group of rectangles to retain it.}
700 \cvarg{eps}{The relative difference between sides of the rectangles to merge them into a group}
703 The function is a wrapper for a generic function \cvCppCross{partition}. It clusters all the input rectangles using the rectangle equivalence criteria, that combines rectangles that have similar sizes and similar locations (the similarity is defined by \texttt{eps}). When \texttt{eps=0}, no clustering is done at all. If $\texttt{eps}\rightarrow +\inf$, all the rectangles will be put in one cluster. Then, the small clusters, containing less than or equal to \texttt{groupThreshold} rectangles, will be rejected. In each other cluster the average rectangle will be computed and put into the output rectangle list.
705 \cvCppFunc{matchTemplate}
706 Compares a template against overlapped image regions.
708 \cvdefCpp{void matchTemplate( const Mat\& image, const Mat\& templ,\par
709 Mat\& result, int method );}
711 \cvarg{image}{Image where the search is running; should be 8-bit or 32-bit floating-point}
712 \cvarg{templ}{Searched template; must be not greater than the source image and have the same data type}
713 \cvarg{result}{A map of comparison results; will be single-channel 32-bit floating-point.
714 If \texttt{image} is $W \times H$ and
715 \texttt{templ} is $w \times h$ then \texttt{result} will be $(W-w+1) \times (H-h+1)$}
716 \cvarg{method}{Specifies the comparison method (see below)}
719 The function slides through \texttt{image}, compares the
720 overlapped patches of size $w \times h$ against \texttt{templ}
721 using the specified method and stores the comparison results to
722 \texttt{result}. Here are the formulas for the available comparison
723 methods ($I$ denotes \texttt{image}, $T$ \texttt{template},
724 $R$ \texttt{result}). The summation is done over template and/or the
725 image patch: $x' = 0...w-1, y' = 0...h-1$
727 % \texttt{x'=0..w-1, y'=0..h-1}):
730 \item[method=CV\_TM\_SQDIFF]
731 \[ R(x,y)=\sum_{x',y'} (T(x',y')-I(x+x',y+y'))^2 \]
733 \item[method=CV\_TM\_SQDIFF\_NORMED]
735 {\sum_{x',y'} (T(x',y')-I(x+x',y+y'))^2}
736 {\sqrt{\sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}
739 \item[method=CV\_TM\_CCORR]
740 \[ R(x,y)=\sum_{x',y'} (T(x',y') \cdot I(x+x',y+y')) \]
742 \item[method=CV\_TM\_CCORR\_NORMED]
744 {\sum_{x',y'} (T(x',y') \cdot I'(x+x',y+y'))}
745 {\sqrt{\sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}
748 \item[method=CV\_TM\_CCOEFF]
749 \[ R(x,y)=\sum_{x',y'} (T'(x',y') \cdot I(x+x',y+y')) \]
754 T'(x',y')=T(x',y') - 1/(w \cdot h) \cdot \sum_{x'',y''} T(x'',y'')\\
755 I'(x+x',y+y')=I(x+x',y+y') - 1/(w \cdot h) \cdot \sum_{x'',y''} I(x+x'',y+y'')
759 \item[method=CV\_TM\_CCOEFF\_NORMED]
761 { \sum_{x',y'} (T'(x',y') \cdot I'(x+x',y+y')) }
762 { \sqrt{\sum_{x',y'}T'(x',y')^2 \cdot \sum_{x',y'} I'(x+x',y+y')^2} }
766 After the function finishes the comparison, the best matches can be found as global minimums (when \texttt{CV\_TM\_SQDIFF} was used) or maximums (when \texttt{CV\_TM\_CCORR} or \texttt{CV\_TM\_CCOEFF} was used) using the \cvCppCross{minMaxLoc} function. In the case of a color image, template summation in the numerator and each sum in the denominator is done over all of the channels (and separate mean values are used for each channel). That is, the function can take a color template and a color image; the result will still be a single-channel image, which is easier to analyze.