modules/gpu/doc/object_detection.rst

   1 Object Detection
   2 ================
   3
   4 .. highlight:: cpp
   5
   6
   7
   8 gpu::HOGDescriptor
   9 ------------------
  10 .. ocv:struct:: gpu::HOGDescriptor
  11
  12 The class implements Histogram of Oriented Gradients ([Dalal2005]_) object detector. ::
  13
  14     struct CV_EXPORTS HOGDescriptor
  15     {
  16         enum { DEFAULT_WIN_SIGMA = -1 };
  17         enum { DEFAULT_NLEVELS = 64 };
  18         enum { DESCR_FORMAT_ROW_BY_ROW, DESCR_FORMAT_COL_BY_COL };
  19
  20         HOGDescriptor(Size win_size=Size(64, 128), Size block_size=Size(16, 16),
  21                       Size block_stride=Size(8, 8), Size cell_size=Size(8, 8),
  22                       int nbins=9, double win_sigma=DEFAULT_WIN_SIGMA,
  23                       double threshold_L2hys=0.2, bool gamma_correction=true,
  24                       int nlevels=DEFAULT_NLEVELS);
  25
  26         size_t getDescriptorSize() const;
  27         size_t getBlockHistogramSize() const;
  28
  29         void setSVMDetector(const vector<float>& detector);
  30
  31         static vector<float> getDefaultPeopleDetector();
  32         static vector<float> getPeopleDetector48x96();
  33         static vector<float> getPeopleDetector64x128();
  34
  35         void detect(const GpuMat& img, vector<Point>& found_locations,
  36                     double hit_threshold=0, Size win_stride=Size(),
  37                     Size padding=Size());
  38
  39         void detectMultiScale(const GpuMat& img, vector<Rect>& found_locations,
  40                               double hit_threshold=0, Size win_stride=Size(),
  41                               Size padding=Size(), double scale0=1.05,
  42                               int group_threshold=2);
  43
  44         void getDescriptors(const GpuMat& img, Size win_stride,
  45                             GpuMat& descriptors,
  46                             int descr_format=DESCR_FORMAT_COL_BY_COL);
  47
  48         Size win_size;
  49         Size block_size;
  50         Size block_stride;
  51         Size cell_size;
  52         int nbins;
  53         double win_sigma;
  54         double threshold_L2hys;
  55         bool gamma_correction;
  56         int nlevels;
  57
  58     private:
  59         // Hidden
  60     }
  61
  62
  63 Interfaces of all methods are kept similar to the ``CPU HOG`` descriptor and detector analogues as much as possible.
  64
  65
  66
  67 gpu::HOGDescriptor::HOGDescriptor
  68 -------------------------------------
  69 Creates the ``HOG`` descriptor and detector.
  70
  71 .. ocv:function:: gpu::HOGDescriptor::HOGDescriptor(Size win_size=Size(64, 128), Size block_size=Size(16, 16), Size block_stride=Size(8, 8), Size cell_size=Size(8, 8), int nbins=9, double win_sigma=DEFAULT_WIN_SIGMA, double threshold_L2hys=0.2, bool gamma_correction=true, int nlevels=DEFAULT_NLEVELS)
  72
  73    :param win_size: Detection window size. Align to block size and block stride.
  74
  75    :param block_size: Block size in pixels. Align to cell size. Only (16,16) is supported for now.
  76
  77    :param block_stride: Block stride. It must be a multiple of cell size.
  78
  79    :param cell_size: Cell size. Only (8, 8) is supported for now.
  80
  81    :param nbins: Number of bins. Only 9 bins per cell are supported for now.
  82
  83    :param win_sigma: Gaussian smoothing window parameter.
  84
  85    :param threshold_L2hys: L2-Hys normalization method shrinkage.
  86
  87    :param gamma_correction: Flag to specify whether the gamma correction preprocessing is required or not.
  88
  89    :param nlevels: Maximum number of detection window increases.
  90
  91
  92
  93 gpu::HOGDescriptor::getDescriptorSize
  94 -----------------------------------------
  95 Returns the number of coefficients required for the classification.
  96
  97 .. ocv:function:: size_t gpu::HOGDescriptor::getDescriptorSize() const
  98
  99
 100
 101 gpu::HOGDescriptor::getBlockHistogramSize
 102 ---------------------------------------------
 103 Returns the block histogram size.
 104
 105 .. ocv:function:: size_t gpu::HOGDescriptor::getBlockHistogramSize() const
 106
 107
 108
 109 gpu::HOGDescriptor::setSVMDetector
 110 --------------------------------------
 111 Sets coefficients for the linear SVM classifier.
 112
 113 .. ocv:function:: void gpu::HOGDescriptor::setSVMDetector(const vector<float>& detector)
 114
 115
 116
 117 gpu::HOGDescriptor::getDefaultPeopleDetector
 118 ------------------------------------------------
 119 Returns coefficients of the classifier trained for people detection (for default window size).
 120
 121 .. ocv:function:: static vector<float> gpu::HOGDescriptor::getDefaultPeopleDetector()
 122
 123
 124
 125 gpu::HOGDescriptor::getPeopleDetector48x96
 126 ----------------------------------------------
 127 Returns coefficients of the classifier trained for people detection (for 48x96 windows).
 128
 129 .. ocv:function:: static vector<float> gpu::HOGDescriptor::getPeopleDetector48x96()
 130
 131
 132
 133 gpu::HOGDescriptor::getPeopleDetector64x128
 134 -----------------------------------------------
 135 Returns coefficients of the classifier trained for people detection (for 64x128 windows).
 136
 137 .. ocv:function:: static vector<float> gpu::HOGDescriptor::getPeopleDetector64x128()
 138
 139
 140
 141 gpu::HOGDescriptor::detect
 142 ------------------------------
 143 Performs object detection without a multi-scale window.
 144
 145 .. ocv:function:: void gpu::HOGDescriptor::detect(const GpuMat& img, vector<Point>& found_locations, double hit_threshold=0, Size win_stride=Size(), Size padding=Size())
 146
 147    :param img: Source image.  ``CV_8UC1``  and  ``CV_8UC4`` types are supported for now.
 148
 149    :param found_locations: Left-top corner points of detected objects boundaries.
 150
 151    :param hit_threshold: Threshold for the distance between features and SVM classifying plane. Usually it is 0 and should be specfied in the detector coefficients (as the last free coefficient). But if the free coefficient is omitted (which is allowed), you can specify it manually here.
 152
 153    :param win_stride: Window stride. It must be a multiple of block stride.
 154
 155    :param padding: Mock parameter to keep the CPU interface compatibility. It must be (0,0).
 156
 157
 158
 159 gpu::HOGDescriptor::detectMultiScale
 160 ----------------------------------------
 161 Performs object detection with a multi-scale window.
 162
 163 .. ocv:function:: void gpu::HOGDescriptor::detectMultiScale(const GpuMat& img, vector<Rect>& found_locations, double hit_threshold=0, Size win_stride=Size(), Size padding=Size(), double scale0=1.05, int group_threshold=2)
 164
 165    :param img: Source image. See  :ocv:func:`gpu::HOGDescriptor::detect`  for type limitations.
 166
 167    :param found_locations: Detected objects boundaries.
 168
 169    :param hit_threshold: Threshold for the distance between features and SVM classifying plane. See  :ocv:func:`gpu::HOGDescriptor::detect`  for details.
 170
 171    :param win_stride: Window stride. It must be a multiple of block stride.
 172
 173    :param padding: Mock parameter to keep the CPU interface compatibility. It must be (0,0).
 174
 175    :param scale0: Coefficient of the detection window increase.
 176
 177    :param group_threshold: Coefficient to regulate the similarity threshold. When detected, some objects can be covered by many rectangles. 0 means not to perform grouping. See  :ocv:func:`groupRectangles` .
 178
 179
 180
 181 gpu::HOGDescriptor::getDescriptors
 182 --------------------------------------
 183 Returns block descriptors computed for the whole image.
 184
 185 .. ocv:function:: void gpu::HOGDescriptor::getDescriptors(const GpuMat& img, Size win_stride, GpuMat& descriptors, int descr_format=DESCR_FORMAT_COL_BY_COL)
 186
 187    :param img: Source image. See  :ocv:func:`gpu::HOGDescriptor::detect`  for type limitations.
 188
 189    :param win_stride: Window stride. It must be a multiple of block stride.
 190
 191    :param descriptors: 2D array of descriptors.
 192
 193    :param descr_format: Descriptor storage format:
 194
 195         * **DESCR_FORMAT_ROW_BY_ROW** - Row-major order.
 196
 197         * **DESCR_FORMAT_COL_BY_COL** - Column-major order.
 198
 199 The function is mainly used to learn the classifier.
 200
 201
 202
 203 gpu::CascadeClassifier_GPU
 204 --------------------------
 205 .. ocv:class:: gpu::CascadeClassifier_GPU
 206
 207 Cascade classifier class used for object detection. Supports HAAR and LBP cascades. ::
 208
 209     class CV_EXPORTS CascadeClassifier_GPU
 210     {
 211     public:
 212             CascadeClassifier_GPU();
 213             CascadeClassifier_GPU(const string& filename);
 214             ~CascadeClassifier_GPU();
 215
 216             bool empty() const;
 217             bool load(const string& filename);
 218             void release();
 219
 220             /* Returns number of detected objects */
 221             int detectMultiScale( const GpuMat& image, GpuMat& objectsBuf, double scaleFactor=1.2, int minNeighbors=4, Size minSize=Size());
 222             int detectMultiScale( const GpuMat& image, GpuMat& objectsBuf, Size maxObjectSize, Size minSize = Size(), double scaleFactor = 1.1, int minNeighbors = 4);
 223
 224             /* Finds only the largest object. Special mode if training is required.*/
 225             bool findLargestObject;
 226
 227             /* Draws rectangles in input image */
 228             bool visualizeInPlace;
 229
 230             Size getClassifierSize() const;
 231     };
 232
 233
 234
 235 gpu::CascadeClassifier_GPU::CascadeClassifier_GPU
 236 -----------------------------------------------------
 237 Loads the classifier from a file. Cascade type is detected automatically by constructor parameter.
 238
 239 .. ocv:function:: gpu::CascadeClassifier_GPU::CascadeClassifier_GPU(const string& filename)
 240
 241     :param filename: Name of the file from which the classifier is loaded. Only the old ``haar`` classifier (trained by the ``haar`` training application) and NVIDIA's ``nvbin`` are supported for HAAR and only new type of OpenCV XML cascade supported for LBP.
 242
 243
 244
 245 gpu::CascadeClassifier_GPU::empty
 246 -------------------------------------
 247 Checks whether the classifier is loaded or not.
 248
 249 .. ocv:function:: bool gpu::CascadeClassifier_GPU::empty() const
 250
 251
 252
 253 gpu::CascadeClassifier_GPU::load
 254 ------------------------------------
 255 Loads the classifier from a file. The previous content is destroyed.
 256
 257 .. ocv:function:: bool gpu::CascadeClassifier_GPU::load(const string& filename)
 258
 259     :param filename: Name of the file from which the classifier is loaded. Only the old ``haar`` classifier (trained by the ``haar`` training application) and NVIDIA's ``nvbin`` are supported for HAAR and only new type of OpenCV XML cascade supported for LBP.
 260
 261
 262 gpu::CascadeClassifier_GPU::release
 263 ---------------------------------------
 264 Destroys the loaded classifier.
 265
 266 .. ocv:function:: void gpu::CascadeClassifier_GPU::release()
 267
 268
 269
 270 gpu::CascadeClassifier_GPU::detectMultiScale
 271 ------------------------------------------------
 272 Detects objects of different sizes in the input image.
 273
 274 .. ocv:function:: int gpu::CascadeClassifier_GPU::detectMultiScale(const GpuMat& image, GpuMat& objectsBuf, double scaleFactor=1.2, int minNeighbors=4, Size minSize=Size())
 275
 276 .. ocv:function:: int gpu::CascadeClassifier_GPU::detectMultiScale(const GpuMat& image, GpuMat& objectsBuf, Size maxObjectSize, Size minSize = Size(), double scaleFactor = 1.1, int minNeighbors = 4)
 277
 278     :param image: Matrix of type  ``CV_8U``  containing an image where objects should be detected.
 279
 280     :param objectsBuf: Buffer to store detected objects (rectangles). If it is empty, it is allocated with the default size. If not empty, the function searches not more than N objects, where ``N = sizeof(objectsBufer's data)/sizeof(cv::Rect)``.
 281
 282     :param maxObjectSize: Maximum possible object size. Objects larger than that are ignored. Used for second signature and supported only for LBP cascades.
 283
 284     :param scaleFactor:  Parameter specifying how much the image size is reduced at each image scale.
 285
 286     :param minNeighbors: Parameter specifying how many neighbors each candidate rectangle should have to retain it.
 287
 288     :param minSize: Minimum possible object size. Objects smaller than that are ignored.
 289
 290 The detected objects are returned as a list of rectangles.
 291
 292 The function returns the number of detected objects, so you can retrieve them as in the following example: ::
 293
 294     gpu::CascadeClassifier_GPU cascade_gpu(...);
 295
 296     Mat image_cpu = imread(...)
 297     GpuMat image_gpu(image_cpu);
 298
 299     GpuMat objbuf;
 300     int detections_number = cascade_gpu.detectMultiScale( image_gpu,
 301               objbuf, 1.2, minNeighbors);
 302
 303     Mat obj_host;
 304     // download only detected number of rectangles
 305     objbuf.colRange(0, detections_number).download(obj_host);
 306
 307     Rect* faces = obj_host.ptr<Rect>();
 308     for(int i = 0; i < detections_num; ++i)
 309        cv::rectangle(image_cpu, faces[i], Scalar(255));
 310
 311     imshow("Faces", image_cpu);
 312
 313
 314 .. seealso:: :ocv:func:`CascadeClassifier::detectMultiScale`
 315
 316
 317
 318 .. [Dalal2005] Navneet Dalal and Bill Triggs. *Histogram of oriented gradients for human detection*. 2005.