objdetect.hpp

00001 /*M///////////////////////////////////////////////////////////////////////////////////////
00002 //
00003 //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
00004 //
00005 //  By downloading, copying, installing or using the software you agree to this license.
00006 //  If you do not agree to this license, do not download, install,
00007 //  copy or use the software.
00008 //
00009 //
00010 //                          License Agreement
00011 //                For Open Source Computer Vision Library
00012 //
00013 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
00014 // Copyright (C) 2009, Willow Garage Inc., all rights reserved.
00015 // Copyright (C) 2013, OpenCV Foundation, all rights reserved.
00016 // Third party copyrights are property of their respective owners.
00017 //
00018 // Redistribution and use in source and binary forms, with or without modification,
00019 // are permitted provided that the following conditions are met:
00020 //
00021 //   * Redistribution's of source code must retain the above copyright notice,
00022 //     this list of conditions and the following disclaimer.
00023 //
00024 //   * Redistribution's in binary form must reproduce the above copyright notice,
00025 //     this list of conditions and the following disclaimer in the documentation
00026 //     and/or other materials provided with the distribution.
00027 //
00028 //   * The name of the copyright holders may not be used to endorse or promote products
00029 //     derived from this software without specific prior written permission.
00030 //
00031 // This software is provided by the copyright holders and contributors "as is" and
00032 // any express or implied warranties, including, but not limited to, the implied
00033 // warranties of merchantability and fitness for a particular purpose are disclaimed.
00034 // In no event shall the Intel Corporation or contributors be liable for any direct,
00035 // indirect, incidental, special, exemplary, or consequential damages
00036 // (including, but not limited to, procurement of substitute goods or services;
00037 // loss of use, data, or profits; or business interruption) however caused
00038 // and on any theory of liability, whether in contract, strict liability,
00039 // or tort (including negligence or otherwise) arising in any way out of
00040 // the use of this software, even if advised of the possibility of such damage.
00041 //
00042 //M*/
00043 
00044 #ifndef __OPENCV_OBJDETECT_HPP__
00045 #define __OPENCV_OBJDETECT_HPP__
00046 
00047 #include "opencv2/core.hpp"
00048 
00049 /**
00050 @defgroup objdetect Object Detection
00051 
00052 Haar Feature-based Cascade Classifier for Object Detection
00053 ----------------------------------------------------------
00054 
00055 The object detector described below has been initially proposed by Paul Viola @cite Viola01 and
00056 improved by Rainer Lienhart @cite Lienhart02 .
00057 
00058 First, a classifier (namely a *cascade of boosted classifiers working with haar-like features*) is
00059 trained with a few hundred sample views of a particular object (i.e., a face or a car), called
00060 positive examples, that are scaled to the same size (say, 20x20), and negative examples - arbitrary
00061 images of the same size.
00062 
00063 After a classifier is trained, it can be applied to a region of interest (of the same size as used
00064 during the training) in an input image. The classifier outputs a "1" if the region is likely to show
00065 the object (i.e., face/car), and "0" otherwise. To search for the object in the whole image one can
00066 move the search window across the image and check every location using the classifier. The
00067 classifier is designed so that it can be easily "resized" in order to be able to find the objects of
00068 interest at different sizes, which is more efficient than resizing the image itself. So, to find an
00069 object of an unknown size in the image the scan procedure should be done several times at different
00070 scales.
00071 
00072 The word "cascade" in the classifier name means that the resultant classifier consists of several
00073 simpler classifiers (*stages*) that are applied subsequently to a region of interest until at some
00074 stage the candidate is rejected or all the stages are passed. The word "boosted" means that the
00075 classifiers at every stage of the cascade are complex themselves and they are built out of basic
00076 classifiers using one of four different boosting techniques (weighted voting). Currently Discrete
00077 Adaboost, Real Adaboost, Gentle Adaboost and Logitboost are supported. The basic classifiers are
00078 decision-tree classifiers with at least 2 leaves. Haar-like features are the input to the basic
00079 classifiers, and are calculated as described below. The current algorithm uses the following
00080 Haar-like features:
00081 
00082 ![image](pics/haarfeatures.png)
00083 
00084 The feature used in a particular classifier is specified by its shape (1a, 2b etc.), position within
00085 the region of interest and the scale (this scale is not the same as the scale used at the detection
00086 stage, though these two scales are multiplied). For example, in the case of the third line feature
00087 (2c) the response is calculated as the difference between the sum of image pixels under the
00088 rectangle covering the whole feature (including the two white stripes and the black stripe in the
00089 middle) and the sum of the image pixels under the black stripe multiplied by 3 in order to
00090 compensate for the differences in the size of areas. The sums of pixel values over a rectangular
00091 regions are calculated rapidly using integral images (see below and the integral description).
00092 
00093 To see the object detector at work, have a look at the facedetect demo:
00094 <https://github.com/Itseez/opencv/tree/master/samples/cpp/dbt_face_detection.cpp>
00095 
00096 The following reference is for the detection part only. There is a separate application called
00097 opencv_traincascade that can train a cascade of boosted classifiers from a set of samples.
00098 
00099 @note In the new C++ interface it is also possible to use LBP (local binary pattern) features in
00100 addition to Haar-like features. .. [Viola01] Paul Viola and Michael J. Jones. Rapid Object Detection
00101 using a Boosted Cascade of Simple Features. IEEE CVPR, 2001. The paper is available online at
00102 <http://research.microsoft.com/en-us/um/people/viola/Pubs/Detect/violaJones_CVPR2001.pdf>
00103 
00104 @{
00105     @defgroup objdetect_c C API
00106 @}
00107  */
00108 
00109 typedef struct CvHaarClassifierCascade CvHaarClassifierCascade;
00110 
00111 namespace cv
00112 {
00113 
00114 //! @addtogroup objdetect
00115 //! @{
00116 
00117 ///////////////////////////// Object Detection ////////////////////////////
00118 
00119 //! class for grouping object candidates, detected by Cascade Classifier, HOG etc.
00120 //! instance of the class is to be passed to cv::partition (see cxoperations.hpp)
00121 class CV_EXPORTS SimilarRects
00122 {
00123 public:
00124     SimilarRects(double _eps) : eps(_eps) {}
00125     inline bool operator()(const Rect& r1, const Rect& r2) const
00126     {
00127         double delta = eps*(std::min(r1.width, r2.width) + std::min(r1.height, r2.height))*0.5;
00128         return std::abs(r1.x - r2.x) <= delta &&
00129             std::abs(r1.y - r2.y) <= delta &&
00130             std::abs(r1.x + r1.width - r2.x - r2.width) <= delta &&
00131             std::abs(r1.y + r1.height - r2.y - r2.height) <= delta;
00132     }
00133     double eps;
00134 };
00135 
00136 /** @brief Groups the object candidate rectangles.
00137 
00138 @param rectList Input/output vector of rectangles. Output vector includes retained and grouped
00139 rectangles. (The Python list is not modified in place.)
00140 @param groupThreshold Minimum possible number of rectangles minus 1. The threshold is used in a
00141 group of rectangles to retain it.
00142 @param eps Relative difference between sides of the rectangles to merge them into a group.
00143 
00144 The function is a wrapper for the generic function partition . It clusters all the input rectangles
00145 using the rectangle equivalence criteria that combines rectangles with similar sizes and similar
00146 locations. The similarity is defined by eps. When eps=0 , no clustering is done at all. If
00147 \f$\texttt{eps}\rightarrow +\inf\f$ , all the rectangles are put in one cluster. Then, the small
00148 clusters containing less than or equal to groupThreshold rectangles are rejected. In each other
00149 cluster, the average rectangle is computed and put into the output rectangle list.
00150  */
00151 CV_EXPORTS   void groupRectangles(std::vector<Rect>& rectList, int groupThreshold, double eps = 0.2);
00152 /** @overload */
00153 CV_EXPORTS_W void groupRectangles(CV_IN_OUT std::vector<Rect>& rectList, CV_OUT std::vector<int>& weights,
00154                                   int groupThreshold, double eps = 0.2);
00155 /** @overload */
00156 CV_EXPORTS   void groupRectangles(std::vector<Rect>& rectList, int groupThreshold,
00157                                   double eps, std::vector<int>* weights, std::vector<double>* levelWeights );
00158 /** @overload */
00159 CV_EXPORTS   void groupRectangles(std::vector<Rect>& rectList, std::vector<int>& rejectLevels,
00160                                   std::vector<double>& levelWeights, int groupThreshold, double eps = 0.2);
00161 /** @overload */
00162 CV_EXPORTS   void groupRectangles_meanshift (std::vector<Rect>& rectList, std::vector<double>& foundWeights,
00163                                             std::vector<double>& foundScales,
00164                                             double detectThreshold = 0.0, Size winDetSize = Size(64, 128));
00165 
00166 template<> CV_EXPORTS void DefaultDeleter<CvHaarClassifierCascade>::operator ()(CvHaarClassifierCascade* obj) const;
00167 
00168 enum { CASCADE_DO_CANNY_PRUNING    = 1,
00169        CASCADE_SCALE_IMAGE         = 2,
00170        CASCADE_FIND_BIGGEST_OBJECT = 4,
00171        CASCADE_DO_ROUGH_SEARCH     = 8
00172      };
00173 
00174 class CV_EXPORTS_W BaseCascadeClassifier : public Algorithm
00175 {
00176 public:
00177     virtual ~BaseCascadeClassifier();
00178     virtual bool empty() const = 0;
00179     virtual bool load( const String& filename ) = 0;
00180     virtual void detectMultiScale( InputArray image,
00181                            CV_OUT std::vector<Rect>& objects,
00182                            double scaleFactor,
00183                            int minNeighbors, int flags,
00184                            Size minSize, Size maxSize ) = 0;
00185 
00186     virtual void detectMultiScale( InputArray image,
00187                            CV_OUT std::vector<Rect>& objects,
00188                            CV_OUT std::vector<int>& numDetections,
00189                            double scaleFactor,
00190                            int minNeighbors, int flags,
00191                            Size minSize, Size maxSize ) = 0;
00192 
00193     virtual void detectMultiScale( InputArray image,
00194                                    CV_OUT std::vector<Rect>& objects,
00195                                    CV_OUT std::vector<int>& rejectLevels,
00196                                    CV_OUT std::vector<double>& levelWeights,
00197                                    double scaleFactor,
00198                                    int minNeighbors, int flags,
00199                                    Size minSize, Size maxSize,
00200                                    bool outputRejectLevels ) = 0;
00201 
00202     virtual bool isOldFormatCascade() const = 0;
00203     virtual Size getOriginalWindowSize() const = 0;
00204     virtual int getFeatureType() const = 0;
00205     virtual void* getOldCascade() = 0;
00206 
00207     class CV_EXPORTS MaskGenerator
00208     {
00209     public:
00210         virtual ~MaskGenerator() {}
00211         virtual Mat generateMask(const Mat& src)=0;
00212         virtual void initializeMask(const Mat& /*src*/) { }
00213     };
00214     virtual void setMaskGenerator(const Ptr<MaskGenerator>& maskGenerator) = 0;
00215     virtual Ptr<MaskGenerator> getMaskGenerator() = 0;
00216 };
00217 
00218 /** @brief Cascade classifier class for object detection.
00219  */
00220 class CV_EXPORTS_W CascadeClassifier
00221 {
00222 public:
00223     CV_WRAP CascadeClassifier();
00224     /** @brief Loads a classifier from a file.
00225 
00226     @param filename Name of the file from which the classifier is loaded.
00227      */
00228     CV_WRAP CascadeClassifier(const String& filename);
00229     ~CascadeClassifier();
00230     /** @brief Checks whether the classifier has been loaded.
00231     */
00232     CV_WRAP bool empty() const;
00233     /** @brief Loads a classifier from a file.
00234 
00235     @param filename Name of the file from which the classifier is loaded. The file may contain an old
00236     HAAR classifier trained by the haartraining application or a new cascade classifier trained by the
00237     traincascade application.
00238      */
00239     CV_WRAP bool load( const String& filename );
00240     /** @brief Reads a classifier from a FileStorage node.
00241 
00242     @note The file may contain a new cascade classifier (trained traincascade application) only.
00243      */
00244     CV_WRAP bool read( const FileNode& node );
00245 
00246     /** @brief Detects objects of different sizes in the input image. The detected objects are returned as a list
00247     of rectangles.
00248 
00249     @param image Matrix of the type CV_8U containing an image where objects are detected.
00250     @param objects Vector of rectangles where each rectangle contains the detected object, the
00251     rectangles may be partially outside the original image.
00252     @param scaleFactor Parameter specifying how much the image size is reduced at each image scale.
00253     @param minNeighbors Parameter specifying how many neighbors each candidate rectangle should have
00254     to retain it.
00255     @param flags Parameter with the same meaning for an old cascade as in the function
00256     cvHaarDetectObjects. It is not used for a new cascade.
00257     @param minSize Minimum possible object size. Objects smaller than that are ignored.
00258     @param maxSize Maximum possible object size. Objects larger than that are ignored.
00259 
00260     The function is parallelized with the TBB library.
00261 
00262     @note
00263        -   (Python) A face detection example using cascade classifiers can be found at
00264             opencv_source_code/samples/python/facedetect.py
00265     */
00266     CV_WRAP void detectMultiScale( InputArray image,
00267                           CV_OUT std::vector<Rect>& objects,
00268                           double scaleFactor = 1.1,
00269                           int minNeighbors = 3, int flags = 0,
00270                           Size minSize = Size(),
00271                           Size maxSize = Size() );
00272 
00273     /** @overload
00274     @param image Matrix of the type CV_8U containing an image where objects are detected.
00275     @param objects Vector of rectangles where each rectangle contains the detected object, the
00276     rectangles may be partially outside the original image.
00277     @param numDetections Vector of detection numbers for the corresponding objects. An object's number
00278     of detections is the number of neighboring positively classified rectangles that were joined
00279     together to form the object.
00280     @param scaleFactor Parameter specifying how much the image size is reduced at each image scale.
00281     @param minNeighbors Parameter specifying how many neighbors each candidate rectangle should have
00282     to retain it.
00283     @param flags Parameter with the same meaning for an old cascade as in the function
00284     cvHaarDetectObjects. It is not used for a new cascade.
00285     @param minSize Minimum possible object size. Objects smaller than that are ignored.
00286     @param maxSize Maximum possible object size. Objects larger than that are ignored.
00287     */
00288     CV_WRAP_AS(detectMultiScale2) void detectMultiScale( InputArray image,
00289                           CV_OUT std::vector<Rect>& objects,
00290                           CV_OUT std::vector<int>& numDetections,
00291                           double scaleFactor=1.1,
00292                           int minNeighbors=3, int flags=0,
00293                           Size minSize=Size(),
00294                           Size maxSize=Size() );
00295 
00296     /** @overload
00297     if `outputRejectLevels` is `true` returns `rejectLevels` and `levelWeights`
00298     */
00299     CV_WRAP_AS(detectMultiScale3) void detectMultiScale( InputArray image,
00300                                   CV_OUT std::vector<Rect>& objects,
00301                                   CV_OUT std::vector<int>& rejectLevels,
00302                                   CV_OUT std::vector<double>& levelWeights,
00303                                   double scaleFactor = 1.1,
00304                                   int minNeighbors = 3, int flags = 0,
00305                                   Size minSize = Size(),
00306                                   Size maxSize = Size(),
00307                                   bool outputRejectLevels = false );
00308 
00309     CV_WRAP bool isOldFormatCascade() const;
00310     CV_WRAP Size getOriginalWindowSize() const;
00311     CV_WRAP int getFeatureType() const;
00312     void* getOldCascade();
00313 
00314     CV_WRAP static bool convert(const String& oldcascade, const String& newcascade);
00315 
00316     void setMaskGenerator(const Ptr<BaseCascadeClassifier::MaskGenerator>& maskGenerator);
00317     Ptr<BaseCascadeClassifier::MaskGenerator> getMaskGenerator();
00318 
00319     Ptr<BaseCascadeClassifier>  cc;
00320 };
00321 
00322 CV_EXPORTS Ptr<BaseCascadeClassifier::MaskGenerator> createFaceDetectionMaskGenerator();
00323 
00324 //////////////// HOG (Histogram-of-Oriented-Gradients) Descriptor and Object Detector //////////////
00325 
00326 //! struct for detection region of interest (ROI)
00327 struct DetectionROI
00328 {
00329    //! scale(size) of the bounding box
00330    double scale;
00331    //! set of requrested locations to be evaluated
00332    std::vector<cv::Point> locations;
00333    //! vector that will contain confidence values for each location
00334    std::vector<double> confidences;
00335 };
00336 
00337 struct CV_EXPORTS_W HOGDescriptor
00338 {
00339 public:
00340     enum { L2Hys = 0
00341          };
00342     enum { DEFAULT_NLEVELS = 64
00343          };
00344 
00345     CV_WRAP HOGDescriptor() : winSize(64,128), blockSize(16,16), blockStride(8,8),
00346         cellSize(8,8), nbins(9), derivAperture(1), winSigma(-1),
00347         histogramNormType(HOGDescriptor::L2Hys), L2HysThreshold(0.2), gammaCorrection(true),
00348         free_coef(-1.f), nlevels(HOGDescriptor::DEFAULT_NLEVELS), signedGradient(false)
00349     {}
00350 
00351     CV_WRAP HOGDescriptor(Size _winSize, Size _blockSize, Size _blockStride,
00352                   Size _cellSize, int _nbins, int _derivAperture=1, double _winSigma=-1,
00353                   int _histogramNormType=HOGDescriptor::L2Hys,
00354                   double _L2HysThreshold=0.2, bool _gammaCorrection=false,
00355                   int _nlevels=HOGDescriptor::DEFAULT_NLEVELS, bool _signedGradient=false)
00356     : winSize(_winSize), blockSize(_blockSize), blockStride(_blockStride), cellSize(_cellSize),
00357     nbins(_nbins), derivAperture(_derivAperture), winSigma(_winSigma),
00358     histogramNormType(_histogramNormType), L2HysThreshold(_L2HysThreshold),
00359     gammaCorrection(_gammaCorrection), free_coef(-1.f), nlevels(_nlevels), signedGradient(_signedGradient)
00360     {}
00361 
00362     CV_WRAP HOGDescriptor(const String& filename)
00363     {
00364         load(filename);
00365     }
00366 
00367     HOGDescriptor(const HOGDescriptor& d)
00368     {
00369         d.copyTo(*this);
00370     }
00371 
00372     virtual ~HOGDescriptor() {}
00373 
00374     CV_WRAP size_t getDescriptorSize() const;
00375     CV_WRAP bool checkDetectorSize() const;
00376     CV_WRAP double getWinSigma() const;
00377 
00378     CV_WRAP virtual void setSVMDetector(InputArray _svmdetector);
00379 
00380     virtual bool read(FileNode& fn);
00381     virtual void write(FileStorage& fs, const String& objname) const;
00382 
00383     CV_WRAP virtual bool load(const String& filename, const String& objname = String());
00384     CV_WRAP virtual void save(const String& filename, const String& objname = String()) const;
00385     virtual void copyTo(HOGDescriptor& c) const;
00386 
00387     CV_WRAP virtual void compute(InputArray img,
00388                          CV_OUT std::vector<float>& descriptors,
00389                          Size winStride = Size(), Size padding = Size(),
00390                          const std::vector<Point>& locations = std::vector<Point>()) const;
00391 
00392     //! with found weights output
00393     CV_WRAP virtual void detect(const Mat& img, CV_OUT std::vector<Point>& foundLocations,
00394                         CV_OUT std::vector<double>& weights,
00395                         double hitThreshold = 0, Size winStride = Size(),
00396                         Size padding = Size(),
00397                         const std::vector<Point>& searchLocations = std::vector<Point>()) const;
00398     //! without found weights output
00399     virtual void detect(const Mat& img, CV_OUT std::vector<Point>& foundLocations,
00400                         double hitThreshold = 0, Size winStride = Size(),
00401                         Size padding = Size(),
00402                         const std::vector<Point>& searchLocations=std::vector<Point>()) const;
00403 
00404     //! with result weights output
00405     CV_WRAP virtual void detectMultiScale(InputArray img, CV_OUT std::vector<Rect>& foundLocations,
00406                                   CV_OUT std::vector<double>& foundWeights, double hitThreshold = 0,
00407                                   Size winStride = Size(), Size padding = Size(), double scale = 1.05,
00408                                   double finalThreshold = 2.0,bool useMeanshiftGrouping = false) const;
00409     //! without found weights output
00410     virtual void detectMultiScale(InputArray img, CV_OUT std::vector<Rect>& foundLocations,
00411                                   double hitThreshold = 0, Size winStride = Size(),
00412                                   Size padding = Size(), double scale = 1.05,
00413                                   double finalThreshold = 2.0, bool useMeanshiftGrouping = false) const;
00414 
00415     CV_WRAP virtual void computeGradient(const Mat& img, CV_OUT Mat& grad, CV_OUT Mat& angleOfs,
00416                                  Size paddingTL = Size(), Size paddingBR = Size()) const;
00417 
00418     CV_WRAP static std::vector<float> getDefaultPeopleDetector();
00419     CV_WRAP static std::vector<float> getDaimlerPeopleDetector();
00420 
00421     CV_PROP Size winSize;
00422     CV_PROP Size blockSize;
00423     CV_PROP Size blockStride;
00424     CV_PROP Size cellSize;
00425     CV_PROP int nbins;
00426     CV_PROP int derivAperture;
00427     CV_PROP double winSigma;
00428     CV_PROP int histogramNormType;
00429     CV_PROP double L2HysThreshold;
00430     CV_PROP bool gammaCorrection;
00431     CV_PROP std::vector<float> svmDetector;
00432     UMat oclSvmDetector;
00433     float free_coef;
00434     CV_PROP int nlevels;
00435     CV_PROP bool signedGradient;
00436 
00437 
00438     //! evaluate specified ROI and return confidence value for each location
00439     virtual void detectROI(const cv::Mat& img, const std::vector<cv::Point> &locations,
00440                                    CV_OUT std::vector<cv::Point>& foundLocations, CV_OUT std::vector<double>& confidences,
00441                                    double hitThreshold = 0, cv::Size winStride = Size(),
00442                                    cv::Size padding = Size()) const;
00443 
00444     //! evaluate specified ROI and return confidence value for each location in multiple scales
00445     virtual void detectMultiScaleROI(const cv::Mat& img,
00446                                                        CV_OUT std::vector<cv::Rect>& foundLocations,
00447                                                        std::vector<DetectionROI>& locations,
00448                                                        double hitThreshold = 0,
00449                                                        int groupThreshold = 0) const;
00450 
00451     //! read/parse Dalal's alt model file
00452     void readALTModel(String modelfile);
00453     void groupRectangles(std::vector<cv::Rect>& rectList, std::vector<double>& weights, int groupThreshold, double eps) const;
00454 };
00455 
00456 //! @} objdetect
00457 
00458 }
00459 
00460 #include "opencv2/objdetect/detection_based_tracker.hpp"
00461 
00462 #ifndef DISABLE_OPENCV_24_COMPATIBILITY
00463 #include "opencv2/objdetect/objdetect_c.h"
00464 #endif
00465 
00466 #endif
00467