FaceDetector

Description

This plugin is a face detector which is able to detect faces in an image (see papillon::PFrame).
The algorithm accepts every pixel formats available in Papillon (see papillon::PImage::EPixelFormat).
Smallest faces that can be detected are about 20x20 pixels.
This face detector has also an option to enable feature points localisation (try to find 16 key points on the face), which is required for Face Recognition.

Important Note: for Face Recognition applications you should favor FaceDetector2 instead.
FaceDetector2 cannot detect faces smaller than 40x40 pixels, but is faster and can detect up to 68 feature points which is a key advantages for Face Recognition.

For Face Recognition applications:
For best results, you should favor faces with at least 80x80 pixels (about 50 pixels between the eyes).

Note about Feature Points:
This face detector computes a confidence score in [0..1] for each feature points; on the following picture, features points with a good enough score appear in green, points with lower scores are in red.

This plugin creates a PDetector object.

• Plugin: PPluginDetectorFace
• Product name: FaceDetector
• Version: 1.0

How to create a face detector from this plugin?

PDetector detector;
PResult ret = PDetector::Create("FaceDetector", PProperties(), detector);
if (ret.Failed()) ...

Parameters

To configure this detector you have 3 options:

1. Use PProperties container argument in the PDetector::Create() factory
2. Use PDetector specific methods, e.g. PDetector::EnableLocaliser() or PDetector::SetMinDetectionSize(), see PDetector documentation to learn more.
3. Use PDetector generic PDetector::Set() and PDetector::Get() using PDetector::C_PARAM_XXX strings.

Parameter	Description
MinDetectionSize	Minimum detection size in pixels (minimum and default is 20x20). Faces that are smaller than this size won't be detected. Note that it takes more time to detect small faces.
MaxDetectionSize	Maximum detection size in pixels (default is 2000x2000). Faces that are greater than this size won't be detected.
MaxDetections	Maximum number of detected faces in an image (keep only the N largest faces).
RegionOfInterest (ROI)	Detection area in the image (in pixels): the analysed image is cropped to this specified rectangle before applying the face detector.
Localiser	Enable/disable feature points localisation: you can use PDetector::EnableLocaliser(). Disabled by default. These points are required for Face Recognition.

Example

/*
 * Copyright (C) 2015-2018 Digital Barriers plc. All rights reserved.
 * Contact: http://www.digitalbarriers.com/
 *
 * This file is part of the Papillon SDK.
 *
 * You can't use, modify or distribute any part of this file without
 * the explicit written agreements of Digital Barriers.
 */

#include <PapillonCore.h>
USING_NAMESPACE_PAPILLON

const PString SAMPLE_DIR   = PPath::Join(PUtils::GetEnv("PAPILLON_INSTALL_DIR"),
                                       "Data",
                                       "Samples");  // path to find sample data: $PAPILLON_INSTALL_DIR/Data/Samples
const float   SCALE_FACTOR = 1.0f;
const int     LINE_WIDTH   = 2;

static void RunDemo() {
    // ************************************************************************
    // 1. Open Video Stream
    // ************************************************************************
    PInputVideoStream ivs;
    PInputVideoStream::Open(PPath::Join(SAMPLE_DIR, "busy_office.avi"), ivs).OrDie();

    // ************************************************************************
    // 2. Create Face Detector
    // ************************************************************************
    PDetector detector;
    if(0) {
        // This creates an instance of FaceDetector5.  FaceDetector5 has been optimised for the
        // NVidia GPUs.  If you set the gpuId=0, then the detector will try and use the first NVidia GPU it finds.
        PDetector::Create("FaceDetector5", PProperties::CreateFromKeyValueString("gpuId=0;"), detector).OrDie();
        // FaceDetector5 will always provide a five-point location of face features.  For most situations this is fine.
        detector.Set(PDetector::C_PARAM_BOOL_LOCALISER, true);

        // However, you can also use another localiser which provides a 68 landmarks.
        if(0) {
            PDetector   localiser;
            PProperties localiserProperties =
                PProperties::CreateFromKeyValueString("maxNumDetectors=0;enableLocaliser=true");
            PDetector::Create("FaceDetector2", localiserProperties, localiser).OrDie();
            detector.Set(PDetector::C_PARAM_DETECTOR_LOCALISER, localiser).OrDie();
        }
    } else {
        // This creates an instance of FaceDetector6.  FaceDetector6 has been optimised for Intel CPUs and GPUs.
        // It also works well on faces wearing mask images - and should be used in this scenario.
        // If you have an Intel GPU you can specify to use it by setting gpuId=-2
        // If you enable the localiser, it will output 68 landmarks.
        PDetector::Create("FaceDetector6", PProperties::CreateFromKeyValueString("gpuId=-2;enableLocaliser=True;"), detector).OrDie();
    }

    // ************************************************************************
    // 3. Apply Face Detector to the video stream
    // ************************************************************************
    PFrame         frame;
    PDetectionList detectionList;
    while (ivs.GetFrame(frame).Ok() && !PUtils::IsEscPressed()) {
        detector.Detect(frame, detectionList);
        PUtils::DisplayDetectionList(frame, detectionList, "Papillon SDK - Person Detector example",
                                               SCALE_FACTOR, PColour3i::Red(), false, true, LINE_WIDTH);
        //display first detection in separate window
        if (detectionList.Size() > 0) {
            PDetection detection = detectionList.Get(0);
            const float scale = 4;
            PImage crop;
            PPoint2Di origin;
            PUtils::CropDetection(detection, crop, origin, 0.3).OrDie();
            crop.Resize(scale, PImage::E_INTERPOLATION_LINEAR);
            PFeatureMap featureMap = detection.GetFeatureMapShared();
            //translate feature map (careful it will modify feature map in detection!)
            featureMap.Translate(-origin.ToPPoint2Df());
            featureMap.Scale(scale);

            PUtils::DrawFeatureMap(crop, featureMap);
            crop.Display("Detection with feature map");
        }
    }
}

int main() {
    PapillonSDK::Initialise(PapillonSDK::E_CONSOLE_LOGGER_DEBUG_LEVEL).OrDie();
    RunDemo();
    PapillonSDK::Finalise();
    return 0;
}