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 .. note::
  66
  67    * An example applying the HOG descriptor for people detection can be found at opencv_source_code/samples/cpp/peopledetect.cpp
  68    * A GPU example applying the HOG descriptor for people detection can be found at opencv_source_code/samples/gpu/hog.cpp
  69
  70    * (Python) An example applying the HOG descriptor for people detection can be found at opencv_source_code/samples/python2/peopledetect.py
  71
  72 gpu::HOGDescriptor::HOGDescriptor
  73 -------------------------------------
  74 Creates the ``HOG`` descriptor and detector.
  75
  76 .. 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)
  77
  78    :param win_size: Detection window size. Align to block size and block stride.
  79
  80    :param block_size: Block size in pixels. Align to cell size. Only (16,16) is supported for now.
  81
  82    :param block_stride: Block stride. It must be a multiple of cell size.
  83
  84    :param cell_size: Cell size. Only (8, 8) is supported for now.
  85
  86    :param nbins: Number of bins. Only 9 bins per cell are supported for now.
  87
  88    :param win_sigma: Gaussian smoothing window parameter.
  89
  90    :param threshold_L2hys: L2-Hys normalization method shrinkage.
  91
  92    :param gamma_correction: Flag to specify whether the gamma correction preprocessing is required or not.
  93
  94    :param nlevels: Maximum number of detection window increases.
  95
  96
  97
  98 gpu::HOGDescriptor::getDescriptorSize
  99 -----------------------------------------
 100 Returns the number of coefficients required for the classification.
 101
 102 .. ocv:function:: size_t gpu::HOGDescriptor::getDescriptorSize() const
 103
 104
 105
 106 gpu::HOGDescriptor::getBlockHistogramSize
 107 ---------------------------------------------
 108 Returns the block histogram size.
 109
 110 .. ocv:function:: size_t gpu::HOGDescriptor::getBlockHistogramSize() const
 111
 112
 113
 114 gpu::HOGDescriptor::setSVMDetector
 115 --------------------------------------
 116 Sets coefficients for the linear SVM classifier.
 117
 118 .. ocv:function:: void gpu::HOGDescriptor::setSVMDetector(const vector<float>& detector)
 119
 120
 121
 122 gpu::HOGDescriptor::getDefaultPeopleDetector
 123 ------------------------------------------------
 124 Returns coefficients of the classifier trained for people detection (for default window size).
 125
 126 .. ocv:function:: static vector<float> gpu::HOGDescriptor::getDefaultPeopleDetector()
 127
 128
 129
 130 gpu::HOGDescriptor::getPeopleDetector48x96
 131 ----------------------------------------------
 132 Returns coefficients of the classifier trained for people detection (for 48x96 windows).
 133
 134 .. ocv:function:: static vector<float> gpu::HOGDescriptor::getPeopleDetector48x96()
 135
 136
 137
 138 gpu::HOGDescriptor::getPeopleDetector64x128
 139 -----------------------------------------------
 140 Returns coefficients of the classifier trained for people detection (for 64x128 windows).
 141
 142 .. ocv:function:: static vector<float> gpu::HOGDescriptor::getPeopleDetector64x128()
 143
 144
 145
 146 gpu::HOGDescriptor::detect
 147 ------------------------------
 148 Performs object detection without a multi-scale window.
 149
 150 .. ocv:function:: void gpu::HOGDescriptor::detect(const GpuMat& img, vector<Point>& found_locations, double hit_threshold=0, Size win_stride=Size(), Size padding=Size())
 151
 152    :param img: Source image.  ``CV_8UC1``  and  ``CV_8UC4`` types are supported for now.
 153
 154    :param found_locations: Left-top corner points of detected objects boundaries.
 155
 156    :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.
 157
 158    :param win_stride: Window stride. It must be a multiple of block stride.
 159
 160    :param padding: Mock parameter to keep the CPU interface compatibility. It must be (0,0).
 161
 162
 163
 164 gpu::HOGDescriptor::detectMultiScale
 165 ----------------------------------------
 166 Performs object detection with a multi-scale window.
 167
 168 .. 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)
 169
 170    :param img: Source image. See  :ocv:func:`gpu::HOGDescriptor::detect`  for type limitations.
 171
 172    :param found_locations: Detected objects boundaries.
 173
 174    :param hit_threshold: Threshold for the distance between features and SVM classifying plane. See  :ocv:func:`gpu::HOGDescriptor::detect`  for details.
 175
 176    :param win_stride: Window stride. It must be a multiple of block stride.
 177
 178    :param padding: Mock parameter to keep the CPU interface compatibility. It must be (0,0).
 179
 180    :param scale0: Coefficient of the detection window increase.
 181
 182    :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` .
 183
 184
 185
 186 gpu::HOGDescriptor::getDescriptors
 187 --------------------------------------
 188 Returns block descriptors computed for the whole image.
 189
 190 .. ocv:function:: void gpu::HOGDescriptor::getDescriptors(const GpuMat& img, Size win_stride, GpuMat& descriptors, int descr_format=DESCR_FORMAT_COL_BY_COL)
 191
 192    :param img: Source image. See  :ocv:func:`gpu::HOGDescriptor::detect`  for type limitations.
 193
 194    :param win_stride: Window stride. It must be a multiple of block stride.
 195
 196    :param descriptors: 2D array of descriptors.
 197
 198    :param descr_format: Descriptor storage format:
 199
 200         * **DESCR_FORMAT_ROW_BY_ROW** - Row-major order.
 201
 202         * **DESCR_FORMAT_COL_BY_COL** - Column-major order.
 203
 204 The function is mainly used to learn the classifier.
 205
 206
 207
 208 gpu::CascadeClassifier_GPU
 209 --------------------------
 210 .. ocv:class:: gpu::CascadeClassifier_GPU
 211
 212 Cascade classifier class used for object detection. Supports HAAR and LBP cascades. ::
 213
 214     class CV_EXPORTS CascadeClassifier_GPU
 215     {
 216     public:
 217             CascadeClassifier_GPU();
 218             CascadeClassifier_GPU(const string& filename);
 219             ~CascadeClassifier_GPU();
 220
 221             bool empty() const;
 222             bool load(const string& filename);
 223             void release();
 224
 225             /* Returns number of detected objects */
 226             int detectMultiScale( const GpuMat& image, GpuMat& objectsBuf, double scaleFactor=1.2, int minNeighbors=4, Size minSize=Size());
 227             int detectMultiScale( const GpuMat& image, GpuMat& objectsBuf, Size maxObjectSize, Size minSize = Size(), double scaleFactor = 1.1, int minNeighbors = 4);
 228
 229             /* Finds only the largest object. Special mode if training is required.*/
 230             bool findLargestObject;
 231
 232             /* Draws rectangles in input image */
 233             bool visualizeInPlace;
 234
 235             Size getClassifierSize() const;
 236     };
 237
 238 .. note::
 239
 240    * A cascade classifier example can be found at opencv_source_code/samples/gpu/cascadeclassifier.cpp
 241    * A Nvidea API specific cascade classifier example can be found at opencv_source_code/samples/gpu/cascadeclassifier_nvidia_api.cpp
 242
 243 gpu::CascadeClassifier_GPU::CascadeClassifier_GPU
 244 -----------------------------------------------------
 245 Loads the classifier from a file. Cascade type is detected automatically by constructor parameter.
 246
 247 .. ocv:function:: gpu::CascadeClassifier_GPU::CascadeClassifier_GPU(const string& filename)
 248
 249     :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.
 250
 251
 252
 253 gpu::CascadeClassifier_GPU::empty
 254 -------------------------------------
 255 Checks whether the classifier is loaded or not.
 256
 257 .. ocv:function:: bool gpu::CascadeClassifier_GPU::empty() const
 258
 259
 260
 261 gpu::CascadeClassifier_GPU::load
 262 ------------------------------------
 263 Loads the classifier from a file. The previous content is destroyed.
 264
 265 .. ocv:function:: bool gpu::CascadeClassifier_GPU::load(const string& filename)
 266
 267     :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.
 268
 269
 270 gpu::CascadeClassifier_GPU::release
 271 ---------------------------------------
 272 Destroys the loaded classifier.
 273
 274 .. ocv:function:: void gpu::CascadeClassifier_GPU::release()
 275
 276
 277
 278 gpu::CascadeClassifier_GPU::detectMultiScale
 279 ------------------------------------------------
 280 Detects objects of different sizes in the input image.
 281
 282 .. ocv:function:: int gpu::CascadeClassifier_GPU::detectMultiScale(const GpuMat& image, GpuMat& objectsBuf, double scaleFactor=1.2, int minNeighbors=4, Size minSize=Size())
 283
 284 .. ocv:function:: int gpu::CascadeClassifier_GPU::detectMultiScale(const GpuMat& image, GpuMat& objectsBuf, Size maxObjectSize, Size minSize = Size(), double scaleFactor = 1.1, int minNeighbors = 4)
 285
 286     :param image: Matrix of type  ``CV_8U``  containing an image where objects should be detected.
 287
 288     :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)``.
 289
 290     :param maxObjectSize: Maximum possible object size. Objects larger than that are ignored. Used for second signature and supported only for LBP cascades.
 291
 292     :param scaleFactor:  Parameter specifying how much the image size is reduced at each image scale.
 293
 294     :param minNeighbors: Parameter specifying how many neighbors each candidate rectangle should have to retain it.
 295
 296     :param minSize: Minimum possible object size. Objects smaller than that are ignored.
 297
 298 The detected objects are returned as a list of rectangles.
 299
 300 The function returns the number of detected objects, so you can retrieve them as in the following example: ::
 301
 302     gpu::CascadeClassifier_GPU cascade_gpu(...);
 303
 304     Mat image_cpu = imread(...)
 305     GpuMat image_gpu(image_cpu);
 306
 307     GpuMat objbuf;
 308     int detections_number = cascade_gpu.detectMultiScale( image_gpu,
 309               objbuf, 1.2, minNeighbors);
 310
 311     Mat obj_host;
 312     // download only detected number of rectangles
 313     objbuf.colRange(0, detections_number).download(obj_host);
 314
 315     Rect* faces = obj_host.ptr<Rect>();
 316     for(int i = 0; i < detections_num; ++i)
 317        cv::rectangle(image_cpu, faces[i], Scalar(255));
 318
 319     imshow("Faces", image_cpu);
 320
 321
 322 .. seealso:: :ocv:func:`CascadeClassifier::detectMultiScale`
 323
 324
 325
 326 .. [Dalal2005] Navneet Dalal and Bill Triggs. *Histogram of oriented gradients for human detection*. 2005.