faceDetector

Detect faces using pretrained RetinaFace face detector

Since R2025a

Description

The faceDetector function object stores a pretrained RetinaFace face detector used to detect faces in images. The RetinaFace face detector is trained on the WIDER FACE data set. When creating the faceDetector object, you can load a RetinaFace face detector that uses either MobileNet-0.25 or ResNet-50 as the backbone network.

Note

This functionality requires Deep Learning Toolbox™ and the Computer Vision Toolbox™ Model for RetinaFace Face Detection. You can install the Computer Vision Toolbox Model for RetinaFace Face Detection from Add-On Explorer. For more information about installing add-ons, see Get and Manage Add-Ons.

Creation

Syntax

detector = faceDetector

detector = faceDetector(name)

detector = faceDetector(___,InputSize=inputSize)

Description

detector = faceDetector returns a RetinaFace face detector object that uses MobileNet-0.25 as the backbone network. The lightweight architecture of MobileNet-0.25 enables the face detector to maintain a good balance between detection accuracy and computational efficiency.

detector = faceDetector(name) returns a pretrained RetinaFace face detector object that uses MobileNet-0.25 or ResNet-50 as the backbone network. You can specify the name of the face detector by using the input argument name, which determines the choice of backbone network.

detector = faceDetector(___,InputSize=inputSize) specifies the image size to use for inference in addition to any combination of input arguments from previous syntaxes.

Input Arguments

name — Name of RetinaFace face detector

"small-network" | "large-network"

Name of the RetinaFace face detector, specified as one of these values.

• "small-network" — Specify this value to use MobileNet-0.25 as the backbone network.

  The small network, with its few layers, provides faster inference times due to its reduced parameters and computational complexity. Use the small network to detect faces in images with simple and uniform backgrounds, where facial features are distinguishable. Additionally, you can use the small network to detect faces in large batches of images, where detection speed and computational efficiency are crucial.

• "large-network" — Specify this value to use ResNet-50 as the backbone network.

  The large network, with its numerous layers, provides higher accuracy in detection results at the cost of reduced computational efficiency. Use the large network to achieve high accuracy in detecting faces within images that have complex or cluttered backgrounds, as well as in images containing numerous faces.

The name argument sets the ModelName property.

Data Types: char | string

inputSize — Inference image size

[640 640] (default) | two-element row vector of integers

Inference image size, specified as a two-element row vector of integers of the form [H W]. H and W correspond to the height and width of the input image, respectively.

If the resolution of the face class to be detected in the test image is too small, increase the inputSize value for better detection accuracy. However, increasing the inputSize value also increases the computational cost.

The inputSize argument sets the InputSize property.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Properties

ModelName — Name of RetinaFace face detector

'small-network' (default) | 'large-network'

Name of the RetinaFace face detector, represented as 'small-network' or 'large-network'. To set this property, use the name argument, when calling the faceDetector function.

This property is read-only after object creation.

ClassNames — Name of object class

Read-only: 'face'

This property is read-only.

Name of the object class to detect, represented as 'face'.

InputSize — Image size used for inference

[640 640] (default) | two-element row vector of integers

Image size used for inference, represented as a two-element row vector of integers of the form [H W]. H and W correspond to the height and width of the input image, respectively.

This property is read-only after object creation. By default, the InputSize property value is set to the network's input size [640 640], which is the size of the training images. To set this property, use the inputSize argument when calling the faceDetector function.

The detect function resizes the test image to the dimensions specified by the InputSize property before performing the detections.

Object Functions

detect

Detect faces in images using deep learning based face detector

Examples

Detect Faces in Image Using RetinaFace Detector

Read an input image into the MATLAB® workspace.

I = imread("visionteam1.jpg");

Create a face detector object using the faceDetector function. The default configuration of the object loads a small, pretrained RetinaFace deep learning detector for face detection. The small network uses MobileNet-0.25 as the backbone network.

detector = faceDetector

detector = 
  faceDetector with properties:

     ModelName: "small-network"
    ClassNames: face
     InputSize: [640 640]

Detect faces in the image using the detect function of the faceDetector object. The detect function returns bounding boxes, detection scores, and labels for the detected faces.

[bboxes,scores,labels] = detect(detector,I);

Overlay bounding boxes, labels, and scores on the image using the insertObjectAnnotation function.

detectedImg = insertObjectAnnotation(I,"rectangle",bboxes,scores);

Display the detection results.

table(bboxes,scores,labels)

ans=6×3 table
                   bboxes                   scores     labels
    ____________________________________    _______    ______

    571.25    70.582    38.566    61.612    0.99237     face 
    333.02    99.076    31.217    40.832    0.98568     face 
    217.33    122.22    21.548    31.311    0.96641     face 
    107.12    124.86    37.822    47.239    0.99897     face 
    510.94     128.6     29.52    38.307    0.97089     face 
    648.56    132.91    26.986    38.698    0.99424     face 

figure
imshow(detectedImg)

Detect Faces in Video Using RetinaFace Detector

Create a face detector object using the faceDetector function. Specify the detector name as "large-network". This configuration loads a pretrained RetinaFace face detector with ResNet-50 as the backbone network for face detection.

detector = faceDetector("large-network");

Create a VideoReader object to read video data from a video file.

reader = VideoReader('handshake_right.avi');

Configure a VideoPlayer object to display the video frames and the face detection results.

videoPlayer = vision.VideoPlayer(Position=[0 0 400 400]);

Read and iterate over each frame in the video using a while loop. Perform these steps to detect faces and display the detection results.

• Step 1: Read the current video frame with the readFrame function of the VideoReader object.

• Step 2: Detect faces in the video frame using the detect function of the faceDetector object. The detect function returns bounding boxes and detection scores for the detected faces.

• Step 3: Overlay bounding boxes and scores on the video frame using the insertObjectAnnotation function.

• Step 4: Display the annotated frame using the step function of the VideoPlayer object.

while hasFrame(reader)
    % Step 1 %
    videoFrame = readFrame(reader);
    % Step 2 %
    [bboxes,scores] = detect(detector,videoFrame);
    % Step 3 %
    videoFrame= insertObjectAnnotation(videoFrame,"rectangle",bboxes,scores);
    % Step 4 %
    step(videoPlayer,videoFrame)
end

Call the release function to free up the resources allocated to the VideoPlayer object.

release(videoPlayer)

Detect and Blur Faces in Video

Create a face detector object using the faceDetector function. By default, the function uses the RetinaFace detector with a small backbone network for face detection.

detector = faceDetector;

Create a VideoReader object to read video data from a video file.

reader = VideoReader('tilted_face.avi');

Configure a VideoPlayer object to display the video frames and the face detection results.

videoPlayer = vision.VideoPlayer(Position=[0 0 600 600]);

Read and iterate over each frame in the video using a while loop. Perform these steps to detect faces and display the detection results.

• Step 1: Read the current video frame with the readFrame function of the VideoReader object.

• Step 2: Detect faces in the video frame using the detect function of the faceDetector object. The detect function returns bounding boxes for the detected faces.

• Step 3: If the current frame has detected faces, use the helper function helperBlurFaces to blur the faces in the frame. The helper function applies Gaussian filtering to blur the areas of the frame defined by the bounding boxes. This effectively obscures the detected faces.

• Step 4: Display the processed frame using the step function of the VideoPlayer object.

while hasFrame(reader)
    % Step 1 %
    videoFrame = readFrame(reader);
    % Step 2 %
    bboxes = detect(detector,videoFrame,Threshold=0.2);
    % Step 3 %
    if ~isempty(bboxes)
        videoFrame = helperBlurFaces(videoFrame,bboxes);
    end   
    % Step 4 %
    step(videoPlayer,videoFrame)
end

Call the release function to free up the resources allocated to the VideoPlayer object.

release(videoPlayer)

The helperBlurFaces function applies Gaussian filtering to the regions defined by each bounding box, which correspond to detected faces.

function I = helperBlurFaces(I,bbox)
for j=1:size(bbox,1)
    xbox = round(bbox(j,:));   
    subImage = imcrop(I,xbox);
    blurred = imgaussfilt(subImage,12);
    I(xbox(2):xbox(2)+xbox(4),xbox(1):xbox(1)+xbox(3),1:end) = blurred;
end
end

References

[1] Deng, Jiankang, Jia Guo, Evangelos Ververas, Irene Kotsia, and Stefanos Zafeiriou. “RetinaFace: Single-Shot Multi-Level Face Localisation in the Wild.” In 2020 IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR), 5202–11. Seattle, WA, USA: IEEE, 2020. https://doi.org/10.1109/CVPR42600.2020.00525.

[2] Yang, Shuo, Ping Luo, Chen Change Loy, and Xiaoou Tang. “WIDER FACE: A Face Detection Benchmark.” In 2016 IEEE Conference on Computer Vision and Pattern Recognition (CVPR), 5525–33. Las Vegas, NV, USA: IEEE, 2016. https://doi.org/10.1109/CVPR.2016.596.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The faceDetector object supports the generation of generic code only, which does not depend on any third-party libraries.

• The roi argument of the detect object function must be a code generation constant (coder.const()) and a 1-by-4 vector.

• The AutoResize name-value argument of the detect object function must be a code generation constant (coder.const()).

• The detect object function supports only the Threshold, SelectStrongest, MinSize, MaxSize, MiniBatchSize, and AutoResize name-value arguments.

• The detect object function does not support code generation for the ds input argument, which specifies a datastore of test images.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same limitations apply to GPU code generation.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Version History

Introduced in R2025a