Cascade Classifier

API reference for CascadeClassifier and HOGDescriptor classes for object detection

Cascade Classifier

API reference for cascade-based object detection and HOG descriptor computation.

CascadeClassifier

Cascade classifier class for object detection using Haar or LBP features.

Constructor

cv::CascadeClassifier::CascadeClassifier()
cv::CascadeClassifier::CascadeClassifier(const String& filename)

filename · String

Path to the classifier file (e.g., haarcascade_frontalface_default.xml)

Methods

load

Loads a classifier from a file.

bool load(const String& filename)

filename · String

Name of the file from which the classifier is loaded. The file may contain an old HAAR classifier trained by the haartraining application or a new cascade classifier trained by the traincascade application.

Returns: true if the classifier was loaded successfully

detectMultiScale

Detects objects of different sizes in the input image.

void detectMultiScale(
    InputArray image,
    std::vector<Rect>& objects,
    double scaleFactor = 1.1,
    int minNeighbors = 3,
    int flags = 0,
    Size minSize = Size(),
    Size maxSize = Size()
)

image · InputArray

Matrix of type CV_8U containing an image where objects are detected

objects · std::vector<Rect>&

Output vector of rectangles where each rectangle contains a detected object

scaleFactor · double · default: "1.1"

Parameter specifying how much the image size is reduced at each image scale

minNeighbors · int · default: "3"

Parameter specifying how many neighbors each candidate rectangle should have to retain it

flags · int · default: "0"

Parameter with the same meaning for an old cascade as in cvHaarDetectObjects. Not used for new cascades.

minSize · Size · default: "Size()"

Minimum possible object size. Objects smaller than this are ignored.

maxSize · Size · default: "Size()"

Maximum possible object size. Objects larger than this are ignored. If maxSize == minSize, model is evaluated on single scale.

The function does not correct lens distortion. If camera parameters are known, it’s recommended to undistort the input image first.

detectMultiScale (with detection counts)

void detectMultiScale(
    InputArray image,
    std::vector<Rect>& objects,
    std::vector<int>& numDetections,
    double scaleFactor = 1.1,
    int minNeighbors = 3,
    int flags = 0,
    Size minSize = Size(),
    Size maxSize = Size()
)

numDetections · std::vector<int>&

Vector of detection numbers for the corresponding objects. An object’s number of detections is the number of neighboring positively classified rectangles that were joined together.

detectMultiScale (with confidence levels)

void detectMultiScale(
    InputArray image,
    std::vector<Rect>& objects,
    std::vector<int>& rejectLevels,
    std::vector<double>& levelWeights,
    double scaleFactor = 1.1,
    int minNeighbors = 3,
    int flags = 0,
    Size minSize = Size(),
    Size maxSize = Size(),
    bool outputRejectLevels = false
)

rejectLevels · std::vector<int>&

Output vector of reject levels for each detection

levelWeights · std::vector<double>&

Output vector containing the certainty of classification at the final stage for each detection

outputRejectLevels · bool · default: "false"

Set to true to retrieve the final stage decision certainty of classification

empty

Checks whether the classifier has been loaded.

bool empty() const

Returns: true if the classifier is empty

Example Usage

C++

#include <opencv2/objdetect.hpp>
#include <opencv2/imgproc.hpp>

// Load the cascade classifier
cv::CascadeClassifier face_cascade;
face_cascade.load("haarcascade_frontalface_default.xml");

// Detect faces
cv::Mat gray;
cv::cvtColor(image, gray, cv::COLOR_BGR2GRAY);

std::vector<cv::Rect> faces;
face_cascade.detectMultiScale(gray, faces, 1.1, 3);

// Draw rectangles around detected faces
for (const auto& face : faces) {
    cv::rectangle(image, face, cv::Scalar(255, 0, 0), 2);
}

Python

import cv2

# Load the cascade classifier
face_cascade = cv2.CascadeClassifier('haarcascade_frontalface_default.xml')

# Convert to grayscale
gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)

# Detect faces
faces = face_cascade.detectMultiScale(gray, 1.1, 3)

# Draw rectangles around detected faces
for (x, y, w, h) in faces:
    cv2.rectangle(image, (x, y), (x+w, y+h), (255, 0, 0), 2)

---

HOGDescriptor

Implementation of HOG (Histogram of Oriented Gradients) descriptor and object detector.

Based on the algorithm introduced by Navneet Dalal and Bill Triggs.

Constructor

cv::HOGDescriptor::HOGDescriptor()

cv::HOGDescriptor::HOGDescriptor(
    Size winSize,
    Size blockSize,
    Size blockStride,
    Size cellSize,
    int nbins,
    int derivAperture = 1,
    double winSigma = -1,
    HOGDescriptor::HistogramNormType histogramNormType = HOGDescriptor::L2Hys,
    double L2HysThreshold = 0.2,
    bool gammaCorrection = false,
    int nlevels = HOGDescriptor::DEFAULT_NLEVELS,
    bool signedGradient = false
)

cv::HOGDescriptor::HOGDescriptor(const String& filename)

winSize · Size

Detection window size. Default is Size(64, 128). Must align to block size and block stride.

blockSize · Size

Block size in pixels. Default is Size(16, 16). Must align to cell size.

blockStride · Size

Block stride. Default is Size(8, 8). Must be a multiple of cell size.

cellSize · Size

Cell size. Default is Size(8, 8).

nbins · int

Number of bins used in the calculation of histogram of gradients. Default is 9.

filename · String

File name containing HOGDescriptor properties and coefficients for the linear SVM classifier

Methods

compute

Computes HOG descriptors of given image.

void compute(
    InputArray img,
    std::vector<float>& descriptors,
    Size winStride = Size(),
    Size padding = Size(),
    const std::vector<Point>& locations = std::vector<Point>()
) const

img · InputArray

Matrix of type CV_8U containing an image where HOG features will be calculated

descriptors · std::vector<float>&

Output matrix of type CV_32F containing computed descriptors

winStride · Size · default: "Size()"

Window stride. Must be a multiple of block stride.

padding · Size · default: "Size()"

Padding around the image

locations · std::vector<Point> · default: "empty"

Vector of specific locations to compute descriptors at

detect

Performs object detection without a multi-scale window.

void detect(
    InputArray img,
    std::vector<Point>& foundLocations,
    std::vector<double>& weights,
    double hitThreshold = 0,
    Size winStride = Size(),
    Size padding = Size(),
    const std::vector<Point>& searchLocations = std::vector<Point>()
) const

img · InputArray

Matrix of type CV_8U or CV_8UC3 containing an image where objects are detected

foundLocations · std::vector<Point>&

Vector of points where each point contains left-top corner of detected object boundaries

weights · std::vector<double>&

Vector that will contain confidence values for each detected object

hitThreshold · double · default: "0"

Threshold for the distance between features and SVM classifying plane

winStride · Size · default: "Size()"

Window stride. Must be a multiple of block stride.

padding · Size · default: "Size()"

Padding around the image

searchLocations · std::vector<Point> · default: "empty"

Vector of specific locations to search

detectMultiScale

Detects objects of different sizes in the input image.

void detectMultiScale(
    InputArray img,
    std::vector<Rect>& foundLocations,
    std::vector<double>& foundWeights,
    double hitThreshold = 0,
    Size winStride = Size(),
    Size padding = Size(),
    double scale = 1.05,
    double groupThreshold = 2.0,
    bool useMeanshiftGrouping = false
) const

img · InputArray

Matrix of type CV_8U or CV_8UC3 containing an image where objects are detected

foundLocations · std::vector<Rect>&

Vector of rectangles where each rectangle contains the detected object

foundWeights · std::vector<double>&

Vector that will contain confidence values for each detected object

scale · double · default: "1.05"

Coefficient of the detection window increase

groupThreshold · double · default: "2.0"

Coefficient to regulate the similarity threshold. When detected, some objects can be covered by many rectangles. 0 means not to perform grouping.

useMeanshiftGrouping · bool · default: "false"

Indicates whether to use meanshift grouping algorithm

setSVMDetector

Sets coefficients for the linear SVM classifier.

void setSVMDetector(InputArray svmdetector)

svmdetector · InputArray

Coefficients for the linear SVM classifier

getDefaultPeopleDetector

Returns coefficients of the classifier trained for people detection (for 64x128 windows).

static std::vector<float> getDefaultPeopleDetector()

Returns: Vector of SVM coefficients for people detection

getDaimlerPeopleDetector

Returns coefficients of the classifier trained for people detection (for 48x96 windows).

static std::vector<float> getDaimlerPeopleDetector()

Returns: Vector of SVM coefficients for Daimler people detection

Properties

• winSize (Size): Detection window size. Default Size(64, 128).
• blockSize (Size): Block size in pixels. Default Size(16, 16).
• blockStride (Size): Block stride. Default Size(8, 8).
• cellSize (Size): Cell size. Default Size(8, 8).
• nbins (int): Number of bins. Default 9.
• derivAperture (int): Derivative aperture.
• winSigma (double): Gaussian smoothing window parameter.
• histogramNormType (HistogramNormType): Histogram normalization type.
• L2HysThreshold (double): L2-Hys normalization method shrinkage.
• gammaCorrection (bool): Flag to specify gamma correction preprocessing.
• svmDetector (std::vector<float>): Coefficients for the linear SVM classifier.
• nlevels (int): Maximum number of detection window increases. Default 64.
• signedGradient (bool): Indicates whether signed gradient will be used.

Example Usage

C++

#include <opencv2/objdetect.hpp>
#include <opencv2/imgproc.hpp>

// Create HOG descriptor with default people detector
cv::HOGDescriptor hog;
hog.setSVMDetector(cv::HOGDescriptor::getDefaultPeopleDetector());

// Detect people in the image
std::vector<cv::Rect> found;
std::vector<double> weights;
hog.detectMultiScale(image, found, weights, 0, cv::Size(8, 8), 
                     cv::Size(32, 32), 1.05, 2, false);

// Draw rectangles around detected people
for (const auto& rect : found) {
    cv::rectangle(image, rect, cv::Scalar(0, 255, 0), 2);
}

Python

import cv2

# Create HOG descriptor with default people detector
hog = cv2.HOGDescriptor()
hog.setSVMDetector(cv2.HOGDescriptor_getDefaultPeopleDetector())

# Detect people in the image
found, weights = hog.detectMultiScale(image, winStride=(8, 8),
                                      padding=(32, 32), scale=1.05)

# Draw rectangles around detected people
for (x, y, w, h) in found:
    cv2.rectangle(image, (x, y), (x + w, y + h), (0, 255, 0), 2)

See Also

• Face Detection
• ArUco Detection
• QR Code Detection