Yoti.FCM.FaceDetection 0.1.0-beta2

This is a prerelease version of Yoti.FCM.FaceDetection.
There is a newer version of this package available.
See the version list below for details.
dotnet add package Yoti.FCM.FaceDetection --version 0.1.0-beta2
NuGet\Install-Package Yoti.FCM.FaceDetection -Version 0.1.0-beta2
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Yoti.FCM.FaceDetection" Version="0.1.0-beta2" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Yoti.FCM.FaceDetection --version 0.1.0-beta2
#r "nuget: Yoti.FCM.FaceDetection, 0.1.0-beta2"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Yoti.FCM.FaceDetection as a Cake Addin
#addin nuget:?package=Yoti.FCM.FaceDetection&version=0.1.0-beta2&prerelease

// Install Yoti.FCM.FaceDetection as a Cake Tool
#tool nuget:?package=Yoti.FCM.FaceDetection&version=0.1.0-beta2&prerelease

Yoti FCM Face detection

Face detection for the face capture module. It takes an image and returns a validated image or a validation error describing the issue in the image.

Dependencies

The package uses C++ libraries so the machines that run the face detector will need to install the Microsoft Visual C++ Redistributable packages.

Usage

  1. Install the Yoti.FCM.FaceDetection nuget package.

  2. Create an face detector instance instance and call Detect that expects an System.Drawing.Image:

    var faceDetector = FaceDetectorFactory.NewInstance();
    
    var imagePath = "<image_path>";
    var image = Image.FromFile(imagePath);
    var result = await faceDetector.DetectAsync(image);
    

The face detector implements the interface IFaceDetector:

/// <summary>
/// Face detector entity.
/// </summary>
public interface IFaceDetector : IDisposable
{
    /// <summary>
    /// Detects a face in the image provided.
    /// </summary>
    /// <param name="image">Image with a face.</param>
    /// <param name="crop">
    /// If the crop option is used. This new crop image will contain a single-face optimized
    /// to be sent to Yoti AI service.
    /// <see href="https://developers.yoti.com/age-estimation/integration-guide"/>.
    /// </param>
    /// <param name="cancellationToken">The token to cancel the detection method.</param>
    /// <returns>The <see cref="FaceDetectorResult"/> as an asynchronous operation.</returns>
    Task<FaceDetectorResult> DetectAsync(Image image, bool crop = false, CancellationToken cancellationToken = default);
}

Response

The DetectAsync method returns a FaceDetectorResult that contains the image (ResultB64 property) to be sent to Yoti AI service with the .NET Yoti SDK or any other Yoti SDK if the image is propagated to a back-end first.

Error codes

The FaceDetectorResult also provides an Error property in case the face detection fails:

Error code Description
NoFace No not found.
MultiFace Multiple faces in the image provided.
GrayScale Grayscale images not supported.
BrightnessTooLow Image too dark.
BrightnessTooHigh Image too bright.
FaceTooSmall The bigger face in the image provided is too small.
FaceTooBig The bigger face in the image provided is too big.
NoAreaAroundFace Insufficient area around the bigger face in the image provided.
ImageMinPixels The image size (num pixels) is too small.
ImageMaxPixels The image size (num pixels) is too big.
ImageMinWidth The image width is under ImageMinWidth threshold.
ImageMaxWidth The image width is over ImageMaxWidth threshold.
ImageMinHeight The image height is under ImageMinHeight threshold.
ImageMaxHeight The image height is over ImageMaxHeight threshold.
ImagePayloadTooBig The image payload is over ImagePayloadTooBig maximum size.
ImagePayloadTooSmall The image payload is under ImagePayloadTooSmall minimum size.
FaceNotStable The face detection cannot find an stable face in the images provided (See NumberStableFrames and StabilityConfidenceThreshold options for more details).
Exceptions

The face detector can throw the following exceptions:

  • Yoti.FCM.FaceDetection.Exceptions.ConfigurationException: Invalid configuration.
  • System.Exception: Unexpected exceptions.

Options

The integrators can provide the custom options to the face detector. See DefaultConfig class for more details:

var options = new DefaultConfig();
var faceDetector = FaceDetectorFactory.NewInstance(options);

Note: Package integrators can provide their own custom configuration instance if they implement the interface IConfig.

Configuration fields:

Property name Type Default value Range Description
ProbabilityThreshold FaceConfidenceThreshold FaceConfidenceThreshold.Medium Face probability score threshold used to detect faces.
CroppingRelativeMargin float 0.5F 0.2 - 1.0 Relative margin applied to crop around the detected face.
GrayScaleThreshold float 23.0F 20.0 - 30.0 Image grayscale threshold.
MultiFaceAreaThreshold int 200 180 - 250 Minimum face area size to check for multiple faces.
FaceOverlapingThreshold float 0.3F 0.2 - 0.35 Threshold to check if there is another face in the result face area.
LowBrightnessThreshold float 50.0F 40 - 60 Lowest brightness level allowed.
HighBrightnessThreshold float 200.0F 180 - 210 Highest brightness level allowed.
MinMainFaceArea int 20000 10000 - 60000 Minimum main face size in pixels.
MinRelativeAreaAroundFace float 0.3F 0.25 - 0.4 Minimum distance from the image edges relative to the face. It is measured as a percentage of the face size.
MinFaceRelativeSize float 0.005F 0.0025 - 0.05 Minimum size for the main face relative to the frame.
MaxFaceRelativeSize float 0.25F 0.1 - 0.6 Maximum size for the main face relative to the frame.
OutputFormat ImageFormat ImageFormat.JPEG Format to encode the output Image (JPEG, PNG).
OutputQuality ImageQuality ImageQuality.High JPEG compression quality (High, Medium, Low).
NumberStableFrames int 1 1 - 12 NumberStableFrames is the consecutive valid frames of a face needed to consider it valid.
StabilityConfidenceThreshold float 0.9F 0.8 - 0.95 StabilityConfidenceThreshold is the required stability score for each frame with the previous.

Note: Set NumberStableFrames to 1 to check a single image and ignore StabilityConfidenceThreshold configuration. If NumberStableFrames value is different than 1, the Face detector will expect multiple consecutive different images of the same face with minimum differences.

Product Compatible and additional computed target framework versions.
.NET Framework net45 is compatible.  net451 was computed.  net452 was computed.  net46 was computed.  net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Yoti.FCM.FaceDetection:

Package Downloads
Yoti.FCM

WPF user control for face detection.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.1 695 4/17/2023
1.0.0 521 2/8/2023
0.1.0-beta2 290 12/2/2022
0.1.0-beta1 262 11/7/2022

- Provide new Min/MaxFaceRelativeSize configuration fields.
- MinMainFaceArea default value is 20000 now.
- Num stable frames default value is 1 now.
- New data type for ProbabilityThreshold property.
- The face detector will throw a new ConfigurationException entity for configuration errors.
- Improve package documentation.