DNN-based face detection and recognition

Check the corresponding tutorial for more details.

Classes

Name	Description
class cv::FaceDetectorYN	DNN-based face detector.
class cv::FaceRecognizerSF	DNN-based face recognizer.

Class cv::FaceDetectorYN

DNN-based face detector.

#include <opencv2/objdetect/face.hpp>

Collaboration diagram for cv::FaceDetectorYN:

Detailed Description

class FaceDetectorYN

DNN-based face detector.

model download link: opencv/opencv_zoo

Constructor & Destructor Documentation

~FaceDetectorYN()

cv::FaceDetectorYN::~FaceDetectorYN()

Member Function Documentation

detect()

int cv::FaceDetectorYN::detect(
InputArray image,
OutputArray faces )

Python:

cv.FaceDetectorYN.detect(image[, faces]) -> retval, faces

Detects faces in the input image. Following is an example output.

Parameters

• image — an image to detect

• faces — detection results stored in a 2D cv::Mat of shape [num_faces, 15]

  • 0-1: x, y of bbox top left corner

  • 2-3: width, height of bbox

  • 4-5: x, y of right eye (blue point in the example image)

  • 6-7: x, y of left eye (red point in the example image)

  • 8-9: x, y of nose tip (green point in the example image)

  • 10-11: x, y of right corner of mouth (pink point in the example image)

  • 12-13: x, y of left corner of mouth (yellow point in the example image)

  • 14: face score

getInputSize()

Size cv::FaceDetectorYN::getInputSize()

Python:

cv.FaceDetectorYN.getInputSize() -> retval

getNMSThreshold()

float cv::FaceDetectorYN::getNMSThreshold()

Python:

cv.FaceDetectorYN.getNMSThreshold() -> retval

getScoreThreshold()

float cv::FaceDetectorYN::getScoreThreshold()

Python:

cv.FaceDetectorYN.getScoreThreshold() -> retval

getTopK()

int cv::FaceDetectorYN::getTopK()

Python:

cv.FaceDetectorYN.getTopK() -> retval

setInputSize()

void cv::FaceDetectorYN::setInputSize(const Size & input_size)

Python:

cv.FaceDetectorYN.setInputSize(input_size)

Set the size for the network input, which overwrites the input size of creating model. Call this method when the size of input image does not match the input size when creating model.

Parameters

• input_size — the size of the input image

setNMSThreshold()

void cv::FaceDetectorYN::setNMSThreshold(float nms_threshold)

Python:

cv.FaceDetectorYN.setNMSThreshold(nms_threshold)

Set the Non-maximum-suppression threshold to suppress bounding boxes that have IoU greater than the given value.

Parameters

• nms_threshold — threshold for NMS operation

setScoreThreshold()

void cv::FaceDetectorYN::setScoreThreshold(float score_threshold)

Python:

cv.FaceDetectorYN.setScoreThreshold(score_threshold)

Set the score threshold to filter out bounding boxes of score less than the given value.

Parameters

• score_threshold — threshold for filtering out bounding boxes

setTopK()

void cv::FaceDetectorYN::setTopK(int top_k)

Python:

cv.FaceDetectorYN.setTopK(top_k)

Set the number of bounding boxes preserved before NMS.

Parameters

• top_k — the number of bounding boxes to preserve from top rank based on score

create()

static Ptr< FaceDetectorYN > cv::FaceDetectorYN::create(
const String & framework,
const std::vector< uchar > & bufferModel,
const std::vector< uchar > & bufferConfig,
const Size & input_size,
float score_threshold = 0.9f,
float nms_threshold = 0.3f,
int top_k = 5000,
int backend_id = 0,
int target_id = 0 )

Python:

cv.FaceDetectorYN.create(model, config, input_size[, score_threshold[, nms_threshold[, top_k[, backend_id[, target_id]]]]]) -> retval

cv.FaceDetectorYN.create(framework, bufferModel, bufferConfig, input_size[, score_threshold[, nms_threshold[, top_k[, backend_id[, target_id]]]]]) -> retval

cv.FaceDetectorYN_create(model, config, input_size[, score_threshold[, nms_threshold[, top_k[, backend_id[, target_id]]]]]) -> retval

cv.FaceDetectorYN_create(framework, bufferModel, bufferConfig, input_size[, score_threshold[, nms_threshold[, top_k[, backend_id[, target_id]]]]]) -> retval

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

• framework — Name of origin framework

• bufferModel — A buffer with a content of binary file with weights

• bufferConfig — A buffer with a content of text file contains network configuration

• input_size — the size of the input image

• score_threshold — the threshold to filter out bounding boxes of score smaller than the given value

• nms_threshold — the threshold to suppress bounding boxes of IoU bigger than the given value

• top_k — keep top K bboxes before NMS

• backend_id — the id of backend

• target_id — the id of target device

create()

static Ptr< FaceDetectorYN > cv::FaceDetectorYN::create(
CV_WRAP_FILE_PATH const String & model,
CV_WRAP_FILE_PATH const String & config,
const Size & input_size,
float score_threshold = 0.9f,
float nms_threshold = 0.3f,
int top_k = 5000,
int backend_id = 0,
int target_id = 0 )

Python:

cv.FaceDetectorYN.create(model, config, input_size[, score_threshold[, nms_threshold[, top_k[, backend_id[, target_id]]]]]) -> retval

cv.FaceDetectorYN.create(framework, bufferModel, bufferConfig, input_size[, score_threshold[, nms_threshold[, top_k[, backend_id[, target_id]]]]]) -> retval

cv.FaceDetectorYN_create(model, config, input_size[, score_threshold[, nms_threshold[, top_k[, backend_id[, target_id]]]]]) -> retval

cv.FaceDetectorYN_create(framework, bufferModel, bufferConfig, input_size[, score_threshold[, nms_threshold[, top_k[, backend_id[, target_id]]]]]) -> retval

Creates an instance of face detector class with given parameters.

Parameters

• model — the path to the requested model

• config — the path to the config file for compatibility, which is not requested for ONNX models

• input_size — the size of the input image

• score_threshold — the threshold to filter out bounding boxes of score smaller than the given value

• nms_threshold — the threshold to suppress bounding boxes of IoU bigger than the given value

• top_k — keep top K bboxes before NMS

• backend_id — the id of backend

• target_id — the id of target device

Source file

The documentation for this class was generated from the following file:

• opencv2/objdetect/face.hpp

Class cv::FaceRecognizerSF

DNN-based face recognizer.

#include <opencv2/objdetect/face.hpp>

Collaboration diagram for cv::FaceRecognizerSF:

Public Types

Definition of distance used for calculating the distance between two face features.

enum DisType {
    FR_COSINE =0,
    FR_NORM_L2 =1
}

Detailed Description

class FaceRecognizerSF

DNN-based face recognizer.

model download link: opencv/opencv_zoo

Member Enumeration Documentation

enum DisType

Definition of distance used for calculating the distance between two face features.

FR_COSINE Python: cv.FaceRecognizerSF_FR_COSINE

FR_NORM_L2 Python: cv.FaceRecognizerSF_FR_NORM_L2

Constructor & Destructor Documentation

~FaceRecognizerSF()

cv::FaceRecognizerSF::~FaceRecognizerSF()

Member Function Documentation

alignCrop()

void cv::FaceRecognizerSF::alignCrop(
InputArray src_img,
InputArray face_box,
OutputArray aligned_img )

Python:

cv.FaceRecognizerSF.alignCrop(src_img, face_box[, aligned_img]) -> aligned_img

Aligns detected face with the source input image and crops it.

Parameters

• src_img — input image

• face_box — the detected face result from the input image

• aligned_img — output aligned image

feature()

void cv::FaceRecognizerSF::feature(
InputArray aligned_img,
OutputArray face_feature )

Python:

cv.FaceRecognizerSF.feature(aligned_img[, face_feature]) -> face_feature

Extracts face feature from aligned image.

Parameters

• aligned_img — input aligned image

• face_feature — output face feature

match()

double cv::FaceRecognizerSF::match(
InputArray face_feature1,
InputArray face_feature2,
int dis_type = FaceRecognizerSF::FR_COSINE )

Python:

cv.FaceRecognizerSF.match(face_feature1, face_feature2[, dis_type]) -> retval

Calculates the distance between two face features.

Parameters

• face_feature1 — the first input feature

• face_feature2 — the second input feature of the same size and the same type as face_feature1

• dis_type — defines how to calculate the distance between two face features with optional values “FR_COSINE” or “FR_NORM_L2”

create()

static Ptr< FaceRecognizerSF > cv::FaceRecognizerSF::create(
const String & framework,
const std::vector< uchar > & bufferModel,
const std::vector< uchar > & bufferConfig,
int backend_id = 0,
int target_id = 0 )

Python:

cv.FaceRecognizerSF.create(model, config[, backend_id[, target_id]]) -> retval

cv.FaceRecognizerSF.create(framework, bufferModel, bufferConfig[, backend_id[, target_id]]) -> retval

cv.FaceRecognizerSF_create(model, config[, backend_id[, target_id]]) -> retval

cv.FaceRecognizerSF_create(framework, bufferModel, bufferConfig[, backend_id[, target_id]]) -> retval

Creates an instance of this class from a buffer containing the model weights and configuration.

Parameters

• framework — Name of the framework (ONNX, etc.)

• bufferModel — A buffer containing the binary model weights.

• bufferConfig — A buffer containing the network configuration.

• backend_id — The id of the backend.

• target_id — The id of the target device.

Returns

A pointer to the created instance of FaceRecognizerSF.

create()

static Ptr< FaceRecognizerSF > cv::FaceRecognizerSF::create(
CV_WRAP_FILE_PATH const String & model,
CV_WRAP_FILE_PATH const String & config,
int backend_id = 0,
int target_id = 0 )

Python:

cv.FaceRecognizerSF.create(model, config[, backend_id[, target_id]]) -> retval

cv.FaceRecognizerSF.create(framework, bufferModel, bufferConfig[, backend_id[, target_id]]) -> retval

cv.FaceRecognizerSF_create(model, config[, backend_id[, target_id]]) -> retval

cv.FaceRecognizerSF_create(framework, bufferModel, bufferConfig[, backend_id[, target_id]]) -> retval

Creates an instance of this class with given parameters.

Parameters

• model — the path of the onnx model used for face recognition

• config — the path to the config file for compatibility, which is not requested for ONNX models

• backend_id — the id of backend

• target_id — the id of target device

Source file

The documentation for this class was generated from the following file:

• opencv2/objdetect/face.hpp