Yoti.FCM.FaceDetection 0.1.0-beta1

Yoti FCM Face detection

Face detection for the face capture module.

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.Detect(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 the AI service.
        /// https://developers.yoti.com/age-estimation/integration-guide
    /// </param>
    /// <returns>The face detection result.</returns>
    Task<FaceDetectorResult> Detect(Image image, bool crop = false);
}
```

### Result

The face detector will return an instance of the following class:

```cs
/// <summary>
/// Face detection result.
/// </summary>
public class FaceDetectorResult
{
    /// <summary>
    /// The face detection output image. It will be a crop if the face detection use the crop mode.
    /// </summary>
    public Image Image { get; private set; }

    /// <summary>
    /// The bounding box for the main face in the image.
    /// </summary>
    public Rectangle? MainBBox { get; private set; }

    /// <summary>
    /// The bounding boxes for the other faces in the input image.
    /// </summary>
    public IEnumerable<Rectangle> OtherBBoxes { get; private set; }

    /// <summary>
    /// The validation error in case the input image is not valid.
    /// </summary>
    public ErrorCode? Error { get; private set; }
}
```

### Options

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

```cs
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         | `float`                                | `0.95F`             | `0.85` - `0.97` | Face probability score threshold used to check if a face is real. |
| CroppingRelativeMargin       | `float`                                | `0.5F`              | `0.2` - `1.0`   | Relative margin to be applied when the face detector crops the resulting image. |
| GrayScaleThreshold           | `float`                                | `23.0F`             | `20.0` - `30.0` | Image grayscale threshold. |
| MultiFaceAreaThreshold       | `int`                                  | `200`               | `180` - `250`   | Minimum area size from which a face will be checked when the frame has multiple faces. |
| FaceOverlapingThreshold      | `float`                                | `0.3F`              | `0.2` - `0.35`  | Threshold where the multi-face validator will returns an error if there is another face in the result face area. |
| LowBrightnessThreshold       | `float`                                | `50.0F`             | `40` - `60`     | Lower brightness value that is considered to be valid. |
| HighBrightnessThreshold      | `float`                                | `200.0F`            | `180` - `210`   | Higher brightness value that is considered to be valid. |
| MinMainFaceArea              | `int`                                  | `25000`             |`20000` - `60000`| Min main face size in pixels. |
| MinRelativeAreaAroundFace    | `float`                                | `0.3F`             | `0.25` - `0.4`  | Min distance from the edges relative to the face. |
| OutputFormat                 | `ImageFormat`                          | `ImageFormat.JPEG`  |                 | Format to encode the output Image (JPEG, PNG). |
| OutputQuality                | `ImageQuality`                         | `ImageQuality.High` |                 | JPEG compression quality (High, Medium, Low). |
| NumberStableFrames           | `int`                                  | `4`                 | `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. |