### Face Detection and Recognition Quick Start

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/index.md

This snippet demonstrates the basic setup for face detection and recognition using FaceAiSharp. It shows how to initialize the detector and embedder, process an image to detect faces, align them using landmarks, generate embeddings, and compare similarity.

```csharp
// Setup
var detector = FaceAiSharpBundleFactory.CreateFaceDetectorWithLandmarks();
var embedder = FaceAiSharpBundleFactory.CreateFaceEmbeddingsGenerator();

// Detect and recognize
var image = Image.Load<Rgb24>("photo.jpg");
var faces = detector.DetectFaces(image);

foreach (var face in faces)
{
    // Align and generate embedding
    var faceCopy = image.Clone();
    embedder.AlignFaceUsingLandmarks(faceCopy, face.Landmarks!); 
    var embedding = embedder.GenerateEmbedding(faceCopy);
    faceCopy.Dispose();
    
    // Compare embeddings
    var similarity = embedding.Dot(otherEmbedding);
    Console.WriteLine($"Similarity: {similarity}");
}

detector.Dispose();
embedder.Dispose();
```

--------------------------------

### Build Docker Image for Examples

Source: https://github.com/georg-jung/faceaisharp/blob/master/examples/README.md

Builds the Docker image for the current example folder using the project's base Dockerfile.

```shell
docker build . -f ./../Dockerfile
```

--------------------------------

### Complete FaceAiSharp Bundle Example

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/FaceAiSharpBundleFactory.md

A comprehensive example demonstrating the workflow of loading an image, detecting faces, aligning them using landmarks, generating embeddings, and comparing similarity. This example requires the FaceAiSharp and FaceAiSharp.Bundle packages, along with ONNX Runtime.

```csharp
using FaceAiSharp;
using FaceAiSharp.Extensions;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;

// Create factory instances
var detector = FaceAiSharpBundleFactory.CreateFaceDetectorWithLandmarks();
var embedder = FaceAiSharpBundleFactory.CreateFaceEmbeddingsGenerator();

// Load and detect faces
var image = Image.Load<Rgb24>("group_photo.jpg");
var faces = detector.DetectFaces(image);

// Process first two faces
var firstFace = faces.First();
var secondFace = faces.Skip(1).First();

// Align and generate embeddings
var img1 = image.Clone();
var img2 = image.Clone();

embedder.AlignFaceUsingLandmarks(img1, firstFace.Landmarks!);
embedder.AlignFaceUsingLandmarks(img2, secondFace.Landmarks!);

var emb1 = embedder.GenerateEmbedding(img1);
var emb2 = embedder.GenerateEmbedding(img2);

// Compare embeddings
var similarity = emb1.Dot(emb2);
Console.WriteLine($"Similarity: {similarity}");
if (similarity >= 0.42)
    Console.WriteLine("Same person");

// Cleanup
img1.Dispose();
img2.Dispose();
detector.Dispose();
embedder.Dispose();
```

--------------------------------

### Install FaceAiSharp packages

Source: https://github.com/georg-jung/faceaisharp/blob/master/README.md

Commands to install either the full bundle or the core library for custom model configurations.

```pwsh
dotnet add package FaceAiSharp.Bundle
```

```pwsh
dotnet add package FaceAiSharp
```

--------------------------------

### Extension Method Usage Example

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/Applications.md

Demonstrates the fluent syntax of extension methods provided by FaceAiSharp. This example shows how to call the CountFaces extension method.

```csharp
var detector = FaceAiSharpBundleFactory.CreateFaceDetectorWithLandmarks();
int count = detector.CountFaces(image);  // Extension method call
```

--------------------------------

### Complete FaceAiSharp Application Example

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/Applications.md

A comprehensive example showcasing multiple FaceAiSharp functionalities including counting faces and eye states, blurring faces for privacy, and cropping profile pictures. Images are modified in-place to reduce memory overhead.

```csharp
using FaceAiSharp;
using FaceAiSharp.Extensions;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;

var detector = FaceAiSharpBundleFactory.CreateFaceDetectorWithLandmarks();
var eyeDetector = FaceAiSharpBundleFactory.CreateEyeStateDetector();
var image = Image.Load<Rgb24>("event_photo.jpg");

// Count faces and eye states
var (faces, openEyes, closedEyes) = detector.CountEyeStates(eyeDetector, image);
Console.WriteLine($"Photo contains {faces} people with {openEyes} open and {closedEyes} closed eyes");

// Create a privacy-protected version
var privacyImage = image.Clone();
var blurredCount = detector.BlurFaces(privacyImage);
privacyImage.Save("privacy_protected.jpg");

// Extract profile picture of person with largest face
var profileImage = image.Clone();
detector.CropProfilePicture(profileImage, maxEdgeSize: 512, scaleFactor: 1.2f);
profileImage.Save("profile.jpg");

image.Dispose();
privacyImage.Dispose();
profileImage.Dispose();
```

--------------------------------

### Install FaceAiSharp dependencies

Source: https://github.com/georg-jung/faceaisharp/blob/master/README.md

Required NuGet packages for running the FaceAiSharp library and its bundled models.

```shell
dotnet add package Microsoft.ML.OnnxRuntime
dotnet add package FaceAiSharp.Bundle
```

--------------------------------

### Perform face detection and recognition

Source: https://github.com/georg-jung/faceaisharp/blob/master/README.md

Example demonstrating how to detect faces, align them using landmarks, and compare embeddings to determine if two faces belong to the same person.

```csharp
using FaceAiSharp;
using FaceAiSharp.Extensions;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;

using var hc = new HttpClient();
var groupPhoto = await hc.GetByteArrayAsync(
    "https://raw.githubusercontent.com/georg-jung/FaceAiSharp/master/examples/obama_family.jpg");
var img = Image.Load<Rgb24>(groupPhoto);

var det = FaceAiSharpBundleFactory.CreateFaceDetectorWithLandmarks();
var rec = FaceAiSharpBundleFactory.CreateFaceEmbeddingsGenerator();

var faces = det.DetectFaces(img);

foreach (var face in faces)
{
    Console.WriteLine($"Found a face with conficence {face.Confidence}: {face.Box}");
}

var first = faces.First();
var second = faces.Skip(1).First();

// AlignFaceUsingLandmarks is an in-place operation so we need to create a clone of img first
var secondImg = img.Clone();
rec.AlignFaceUsingLandmarks(img, first.Landmarks!);
rec.AlignFaceUsingLandmarks(secondImg, second.Landmarks!);

img.Save("aligned.jpg");
Console.WriteLine($"Saved an aligned version of one of the faces found at \"./aligned.jpg\".");

var embedding1 = rec.GenerateEmbedding(img);
var embedding2 = rec.GenerateEmbedding(secondImg);

var dot = embedding1.Dot(embedding2);

Console.WriteLine($"Dot product: {dot}");
if (dot >= 0.42)
{
    Console.WriteLine("Assessment: Both pictures show the same person.");
}
else if (dot > 0.28 && dot < 0.42)
{
    Console.WriteLine("Assessment: Hard to tell if the pictures show the same person.");
}
else if (dot <= 0.28)
{
    Console.WriteLine("Assessment: These are two different people.");
}
```

--------------------------------

### Example Usage of EyeBoxes

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/types.md

Demonstrates how to use the EyeBoxes struct to crop images of the left and right eyes. Requires pre-calculated eye centers and an image.

```csharp
var eyeBoxes = ImageCalculations.GetEyeBoxesFromCenterPoints(
    leftEyeCenter,
    rightEyeCenter,
    distanceDivisor: 3.0f
);

var leftEyeImage = image.CropAligned(eyeBoxes.Left, angle);
var rightEyeImage = image.CropAligned(eyeBoxes.Right, angle);
```

--------------------------------

### Conda Environment Package List

Source: https://github.com/georg-jung/faceaisharp/blob/master/src/dockerfiles/insightface-scrfd/README.md

List of dependencies and versions installed in the openmmlab environment.

```text
mmdet                     2.7.0                     dev_0    <develop>
    model-index               0.1.11                   pypi_0    pypi
    mpc                       1.1.0                h10f8cd9_1
    mpfr                      4.0.2                hb69a4c5_1
    mpmath                    1.2.1            py38h06a4308_0
    msgpack                   1.0.4                    pypi_0    pypi
    ncurses                   6.4                  h6a678d5_0
    ninja                     1.10.2               h06a4308_5
    ninja-base                1.10.2               hd09550d_5
    nose                      1.3.7                    pypi_0    pypi
    numpy                     1.23.5           py38h14f4228_0
    numpy-base                1.23.5           py38h31eccc5_0
    onnx                      1.13.0           py38h12ddb61_0
    onnxruntime               1.12.1           py38h8de7196_0
    onnxsim                   0.4.13                   pypi_0    pypi
    opencv-python             4.7.0.68                 pypi_0    pypi
    openmim                   0.3.5                    pypi_0    pypi
    openssl                   1.1.1s               h7f8727e_0
    ordered-set               4.1.0                    pypi_0    pypi
    packaging                 23.0                     pypi_0    pypi
    pandas                    1.5.3                    pypi_0    pypi
    paramiko                  2.12.0                   pypi_0    pypi
    partd                     1.3.0                    pypi_0    pypi
    pillow                    9.3.0            py38hace64e9_1
    pip                       22.3.1           py38h06a4308_0
    protobuf                  3.20.3           py38h6a678d5_0
    psutil                    5.9.4                    pypi_0    pypi
    pycocotools               2.0.6            py38h26c90d9_1    conda-forge
    pycparser                 2.21                     pypi_0    pypi
    pygments                  2.14.0                   pypi_0    pypi
    pynacl                    1.5.0                    pypi_0    pypi
    pyparsing                 3.0.9              pyhd8ed1ab_0    conda-forge
    python                    3.8.16               h7a1cb2a_2
    python-dateutil           2.8.2              pyhd8ed1ab_0    conda-forge
    python-flatbuffers        2.0                pyhd3eb1b0_0
    python_abi                3.8                      2_cp38    conda-forge
    pytorch                   1.6.0               py3.8_cpu_0  [cpuonly]  pytorch
    pytorch-mutex             1.0                         cpu    pytorch
    pytz                      2022.7.1                 pypi_0    pypi
    pyyaml                    6.0                      pypi_0    pypi
    re2                       2022.04.01           h295c915_0
    readline                  8.2                  h5eee18b_0
    requests                  2.28.2                   pypi_0    pypi
    rich                      13.3.1                   pypi_0    pypi
    scipy                     1.9.3            py38h14f4228_0
    setuptools                65.6.3           py38h06a4308_0
    six                       1.16.0             pyhd3eb1b0_1
    sortedcontainers          2.4.0                    pypi_0    pypi
    sqlite                    3.40.1               h5082296_0
    sympy                     1.11.1           py38h06a4308_0
    tabulate                  0.9.0                    pypi_0    pypi
    tblib                     1.7.0                    pypi_0    pypi
    terminaltables            3.1.10                   pypi_0    pypi
    tk                        8.6.12               h1ccaba5_0
    toolz                     0.12.0                   pypi_0    pypi
    torchvision               0.7.0                  py38_cpu  [cpuonly]  pytorch
    tornado                   6.2              py38h0a891b7_1    conda-forge
    tqdm                      4.64.1                   pypi_0    pypi
    typing-extensions         4.4.0            py38h06a4308_0
    typing_extensions         4.4.0            py38h06a4308_0
    urllib3                   1.26.14                  pypi_0    pypi
    wheel                     0.37.1             pyhd3eb1b0_0
    xz                        5.2.10               h5eee18b_1
    yapf                      0.32.0                   pypi_0    pypi
    zict                      2.2.0                    pypi_0    pypi
    zipp                      3.12.0                   pypi_0    pypi
    zlib                      1.2.13               h5eee18b_0
    zstd                      1.5.2                ha4553b6_0
```

--------------------------------

### Example Usage of Eye State Detector

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/FaceAiSharpBundleFactory.md

Demonstrates how to use the face detector and eye state detector to count faces and determine the number of open and closed eyes in an image. Ensure you have loaded an image and created the necessary detector instances.

```csharp
var detector = FaceAiSharpBundleFactory.CreateFaceDetectorWithLandmarks();
var eyeDetector = FaceAiSharpBundleFactory.CreateEyeStateDetector();
var image = Image.Load<Rgb24>("photo.jpg");

var (faceCount, openEyes, closedEyes) = detector.CountEyeStates(eyeDetector, image);
Console.WriteLine($"Faces: {faceCount}, Open eyes: {openEyes}, Closed eyes: {closedEyes}");
```

--------------------------------

### Verify Conda Environment Packages

Source: https://github.com/georg-jung/faceaisharp/blob/master/src/dockerfiles/insightface-scrfd/README.md

Use this command to list installed packages within the container environment to ensure dependencies are correctly configured.

```bash
# packages in environment at /opt/conda/envs/openmmlab:
#
# Name                    Version                   Build  Channel
_libgcc_mutex             0.1                 conda_forge    conda-forge
_openmp_mutex             4.5                  2_kmp_llvm    conda-forge
addict                    2.4.0                    pypi_0    pypi
autotorch                 0.0.1                    pypi_0    pypi
bcrypt                    4.0.1                    pypi_0    pypi
blas                      1.0                         mkl
c-ares                    1.18.1               h7f8727e_0
ca-certificates           2023.01.10           h06a4308_0
certifi                   2022.12.7        py38h06a4308_0
cffi                      1.15.1                   pypi_0    pypi
charset-normalizer        3.0.1                    pypi_0    pypi
click                     8.1.3                    pypi_0    pypi
cloudpickle               2.2.1                    pypi_0    pypi
colorama                  0.4.6                    pypi_0    pypi
coloredlogs               15.0.1           py38h06a4308_1
configspace               0.4.11                   pypi_0    pypi
cpuonly                   2.0                           0    pytorch
cryptography              39.0.0                   pypi_0    pypi
cycler                    0.11.0             pyhd8ed1ab_0    conda-forge
cython                    0.29.32          py38h6a678d5_0
dask                      2023.1.1                 pypi_0    pypi
distributed               2023.1.1                 pypi_0    pypi
fftw                      3.3.9                h27cfd23_1
flit-core                 3.6.0              pyhd3eb1b0_0
freetype                  2.12.1               h4a9f257_0
fsspec                    2023.1.0                 pypi_0    pypi
giflib                    5.2.1                h5eee18b_1
gmp                       6.2.1                h295c915_3
gmpy2                     2.1.2            py38heeb90bb_0
heapdict                  1.0.1                    pypi_0    pypi
humanfriendly             10.0             py38h06a4308_1
idna                      3.4                      pypi_0    pypi
importlib-metadata        6.0.0                    pypi_0    pypi
intel-openmp              2021.4.0          h06a4308_3561
jinja2                    3.1.2                    pypi_0    pypi
jpeg                      9e                   h7f8727e_0
kiwisolver                1.4.4            py38h6a678d5_0
krb5                      1.19.4               h568e23c_0
lcms2                     2.12                 h3be6417_0
ld_impl_linux-64          2.38                 h1181459_1
lerc                      3.0                  h295c915_0
libcurl                   7.87.0               h91b91d3_0
libdeflate                1.8                  h7f8727e_5
libedit                   3.1.20221030         h5eee18b_0
libev                     4.33                 h7f8727e_1
libffi                    3.4.2                h6a678d5_6
libgcc-ng                 12.2.0              h65d4601_19    conda-forge
libgfortran-ng            11.2.0               h00389a5_1
libgfortran5              11.2.0               h1234567_1
libnghttp2                1.46.0               hce63b2e_0
libpng                    1.6.37               hbc83047_0
libprotobuf               3.20.3               he621ea3_0
libssh2                   1.10.0               h8f2d780_0
libstdcxx-ng              11.2.0               h1234567_1
libtiff                   4.5.0                h6a678d5_1
libwebp                   1.2.4                h11a3e52_0
libwebp-base              1.2.4                h5eee18b_0
llvm-openmp               14.0.6               h9e868ea_0
locket                    1.0.0                    pypi_0    pypi
lz4-c                     1.9.4                h6a678d5_0
markdown                  3.4.1                    pypi_0    pypi
markdown-it-py            2.1.0                    pypi_0    pypi
markupsafe                2.1.2                    pypi_0    pypi
matplotlib-base           3.4.3            py38hf4fb855_1    conda-forge
mdurl                     0.1.2                    pypi_0    pypi
mkl                       2021.4.0           h06a4308_640
mkl-service               2.4.0            py38h7f8727e_0
mkl_fft                   1.3.1            py38hd3c417c_0
mkl_random                1.2.2            py38h51133e4_0
mmcv-full                 1.3.3                    pypi_0    pypi
```

--------------------------------

### ArcFaceEmbeddingsGenerator.Options Property

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/ArcFaceEmbeddingsGenerator.md

Gets the current configuration options for this generator instance.

```APIDOC
## Properties

### Options

```csharp
public ArcFaceEmbeddingsGeneratorOptions Options { get; }
```

Gets the current configuration options for this generator instance.
```

--------------------------------

### Example Usage of FaceDetectorResult

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/types.md

Iterates through detected faces, printing their location and confidence. Accesses facial landmarks if available.

```csharp
var faces = detector.DetectFaces(image);
foreach (var face in faces)
{
    Console.WriteLine($"Face at {face.Box.Location} with confidence {face.Confidence}");
    if (face.Landmarks != null)
    {
        var leftEye = face.Landmarks[0];
        var rightEye = face.Landmarks[1];
    }
}
```

--------------------------------

### Error Handling for FaceOnnxEmbeddingsGenerator

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/FaceOnnxEmbeddingsGenerator.md

This example demonstrates how to handle potential exceptions during embedding generation and the specific case of attempting to use unsupported alignment methods. It ensures proper resource disposal using a finally block.

```csharp
var embedder = new FaceOnnxEmbeddingsGenerator();

try
{
    var embedding = embedder.GenerateEmbedding(alignedFace);
    // Use embedding...
}
catch (Exception ex)
{
    Console.WriteLine($"Embedding generation failed: {ex.Message}");
}
finally
{
    embedder.Dispose();
}

// Don't call alignment - it's not supported
try
{
    embedder.AlignFaceUsingLandmarks(image, landmarks);
}
catch (NotImplementedException)
{
    Console.WriteLine("Alignment is not supported by FaceOnnxEmbeddingsGenerator");
    Console.WriteLine("Use ArcFaceEmbeddingsGenerator instead");
}
```

--------------------------------

### Complete Eye Analysis Pipeline

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/ImageCalculations.md

Provides a comprehensive example of an eye analysis pipeline, including face detection, landmark extraction, eye box calculation, and eye state detection. It includes validation for eye box size and error handling for eye state detection.

```csharp
using FaceAiSharp;
using FaceAiSharp.Extensions;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;

var detector = FaceAiSharpBundleFactory.CreateFaceDetectorWithLandmarks();
var eyeDetector = FaceAiSharpBundleFactory.CreateEyeStateDetector();
var image = Image.Load<Rgb24>("photo.jpg");

var faces = detector.DetectFaces(image);
foreach (var face in faces)
{
    Console.WriteLine($"Face at {face.Box}");
    
    if (face.Landmarks == null || face.Landmarks.Count < 2)
        continue;
    
    var leftEyeCenter = detector.GetLeftEyeCenter(face.Landmarks);
    var rightEyeCenter = detector.GetRightEyeCenter(face.Landmarks);
    
    // Calculate eye boxes
    var eyeBoxes = ImageCalculations.GetEyeBoxesFromCenterPoints(
        leftEyeCenter,
        rightEyeCenter,
        distanceDivisor: 3.0f
    );
    
    // Validate box size
    var minSize = 16;
    if (eyeBoxes.Left.Width < minSize || eyeBoxes.Right.Width < minSize)
    {
        Console.WriteLine("  Eyes too small for detection");
        continue;
    }
    
    // Get eye state
    try
    {
        using var leftEyeImg = image.CropAligned(eyeBoxes.Left, angle: 0, alignedMaxEdgeSize: 32);
        using var rightEyeImg = image.CropAligned(eyeBoxes.Right, angle: 0, alignedMaxEdgeSize: 32);
        
        var leftOpen = eyeDetector.IsOpen(leftEyeImg);
        var rightOpen = eyeDetector.IsOpen(rightEyeImg);
        
        Console.WriteLine($"  Left eye: {(leftOpen ? "open" : "closed")}");
        Console.WriteLine($"  Right eye: {(rightOpen ? "open" : "closed")}");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"  Error detecting eye state: {ex.Message}");
    }
}

image.Dispose();
detector.Dispose();
eyeDetector.Dispose();
```

--------------------------------

### Basic Face Detection with FaceOnnxDetector

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/FaceOnnxDetector.md

Demonstrates how to initialize FaceOnnxDetector, set confidence and NMS thresholds, load an image, detect faces, and print the number of faces found and their bounding boxes. Remember to dispose of the detector when done.

```csharp
using FaceAiSharp;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;

var detector = new FaceOnnxDetector
{
    ConfidenceThreshold = 0.90f,
    NmsThreshold = 0.4f
};

var image = Image.Load<Rgb24>("photo.jpg");
var faces = detector.DetectFaces(image);

Console.WriteLine($"Found {faces.Count} faces");
foreach (var face in faces)
{
    Console.WriteLine($"  Face: {face.Box}");
}

detector.Dispose();
```

--------------------------------

### Initialize InsightFace Detection Environment

Source: https://github.com/georg-jung/faceaisharp/blob/master/src/dockerfiles/insightface-scrfd/README.md

Commands to activate the Conda environment and navigate to the detection directory.

```bash
conda activate openmmlab
cd ~/insightface/detection/scrfd
# replace path to your pretrained model and
# specify config that corresponds to model
```

--------------------------------

### Build Docker Image with Verbose Output

Source: https://github.com/georg-jung/faceaisharp/blob/master/examples/README.md

Builds the Docker image while displaying all stdout messages for debugging purposes.

```shell
docker build --progress=plain . -f ./../Dockerfile
```

--------------------------------

### FaceOnnxDetector.NmsThreshold Property

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/FaceOnnxDetector.md

Gets or sets the non-maximum suppression (NMS) threshold used for filtering overlapping face detection bounding boxes.

```APIDOC
### NmsThreshold

```csharp
public float NmsThreshold { get; set; } = 0.5f;
```

Gets or sets the non-maximum suppression threshold for filtering overlapping face detections.

| Property | Type | Default | Range | Description |
|----------|------|---------|-------|-------------|
| NmsThreshold | float | 0.5f | 0.0 - 1.0 | NMS threshold for overlap filtering. Lower values remove more overlaps |

**Example:**
```csharp
var detector = new FaceOnnxDetector
{
    NmsThreshold = 0.3f  // Stricter overlap filtering
};
```
```

--------------------------------

### FaceOnnxDetector.ConfidenceThreshold Property

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/FaceOnnxDetector.md

Gets or sets the minimum confidence threshold for face detection. Detections with a confidence score below this value are filtered out before processing.

```APIDOC
## Properties

### ConfidenceThreshold

```csharp
public float ConfidenceThreshold { get; set; } = 0.95f;
```

Gets or sets the minimum confidence threshold for face detection. Detections below this threshold are filtered out.

| Property | Type | Default | Range | Description |
|----------|------|---------|-------|-------------|
| ConfidenceThreshold | float | 0.95f | 0.0 - 1.0 | Minimum confidence score (0-1) for accepting detections. Higher values reduce false positives but may miss some faces |

**Remarks:** Unlike `ScrfdDetector`, `FaceOnnxDetector` applies the threshold before processing, not after model inference.

**Example:**
```csharp
var detector = new FaceOnnxDetector
{
    ConfidenceThreshold = 0.90f  // Less strict
};
```
```

--------------------------------

### Initialize OpenVinoOpenClosedEye0001 from Model Path

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/OpenVinoOpenClosedEye0001.md

Use this constructor when the ONNX model file is accessible on the file system. Ensure the ModelPath in options is correctly set.

```csharp
using FaceAiSharp;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;

var options = new OpenVinoOpenClosedEye0001Options
{
    ModelPath = "/path/to/open_closed_eye.onnx"
};

var eyeDetector = new OpenVinoOpenClosedEye0001(options);
```

--------------------------------

### Create Face Detector Instance

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/FaceAiSharpBundleFactory.md

Creates a face detector instance using the bundled SCRFD model. This detector also supports landmark extraction. Remember to dispose of the detector after use.

```csharp
using FaceAiSharp;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;

var detector = FaceAiSharpBundleFactory.CreateFaceDetector();
var image = Image.Load<Rgb24>("photo.jpg");
var faces = detector.DetectFaces(image);
detector.Dispose();
```

--------------------------------

### Face Alignment with ArcFace and CropAligned

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/ImageExtensions.md

Compares ArcFace's affine-based alignment with the simpler rotation-based alignment provided by CropAligned. Demonstrates detecting faces and applying different alignment methods.

```csharp
var detector = FaceAiSharpBundleFactory.CreateFaceDetectorWithLandmarks();
var embedder = FaceAiSharpBundleFactory.CreateFaceEmbeddingsGenerator();

var faces = detector.DetectFaces(image);
var face = faces.First();
var faceImg = image.Clone();

// Use embedder's affine-based alignment
embedder.AlignFaceUsingLandmarks(faceImg, face.Landmarks!); 

// vs. simple rotation-based alignment
var angle = detector.GetLeftEyeCenter(face.Landmarks!)
    .GetAlignmentAngle(detector.GetRightEyeCenter(face.Landmarks!));
using var rotationAligned = image.CropAligned(Rectangle.Round(face.Box), angle);
```

--------------------------------

### Get Minimum Superset Square for a Rectangle

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/GeometryExtensions.md

Returns a square that perfectly contains the given rectangle, with edges equal to the longer dimension of the input rectangle.

```csharp
internal static Rectangle GetMinimumSupersetSquare(this Rectangle rectangle)
```

--------------------------------

### Cropping with Zero Rotation

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/ImageExtensions.md

Demonstrates the use of CropAligned when no rotation is needed (angle is 0.0f). This effectively acts as a no-op rotation.

```csharp
// Works with zero rotation angle (no-op rotation)
using var face = image.CropAligned(faceArea, angle: 0.0f, alignedMaxEdgeSize: 256);
```

--------------------------------

### Using FaceOnnxEmbeddingsGenerator with IFaceEmbeddingsGenerator Interface

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/FaceOnnxEmbeddingsGenerator.md

This example demonstrates that while FaceOnnxEmbeddingsGenerator can be assigned to the IFaceEmbeddingsGenerator interface, it does not support alignment methods. Attempting to call alignment methods will result in a NotImplementedException.

```csharp
// This works with ArcFaceEmbeddingsGenerator
IFaceEmbeddingsGenerator embedder = 
    FaceAiSharpBundleFactory.CreateFaceEmbeddingsGenerator();
embedder.AlignFaceUsingLandmarks(image, landmarks);

// This fails with FaceOnnxEmbeddingsGenerator
var faceOnnx = new FaceOnnxEmbeddingsGenerator();
// IFaceEmbeddingsGenerator iface = faceOnnx;  // OK
// iface.AlignFaceUsingLandmarks(...);         // Throws NotImplementedException
```

--------------------------------

### Resource Cleanup with 'using' Statement

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/index.md

Demonstrates the correct way to dispose of detectors using a 'using' statement to ensure resources are properly released. This is crucial for managing detector instances.

```csharp
using (var detector = FaceAiSharpBundleFactory.CreateFaceDetector())
{
    var faces = detector.DetectFaces(image);
}
```

--------------------------------

### Custom Session Options for Bundle Factory

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/FaceAiSharpBundleFactory.md

Shows how to configure custom ONNX Runtime session options, such as graph optimization level and GPU acceleration, when creating detector and embedder instances. Pass these options to the respective factory methods.

```csharp
var sessionOptions = new Microsoft.ML.OnnxRuntime.SessionOptions
{
    GraphOptimizationLevel = Microsoft.ML.OnnxRuntime.GraphOptimizationLevel.ORT_ENABLE_ALL,
    // Configure GPU acceleration, execution providers, etc.
};

var detector = FaceAiSharpBundleFactory.CreateFaceDetectorWithLandmarks(sessionOptions);
var embedder = FaceAiSharpBundleFactory.CreateFaceEmbeddingsGenerator(sessionOptions);
```

--------------------------------

### Calculate Area Under ROC Curve (AUC)

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/Metrics.md

Calculates the AUC for binary classifier evaluations. Higher AUC values indicate better classifier performance. Use this to get a single metric summarizing classifier quality.

```csharp
using FaceAiSharp;

// Compare embedding pairs with known ground truth
var estimations = new List<(float Confidence, bool IsMatch)>
{
    (0.95f, true),   // High confidence, actually same person
    (0.85f, true),   // High confidence, actually same person
    (0.15f, false),  // Low confidence, actually different people
    (0.10f, false),  // Low confidence, actually different people
    (0.55f, true),   // Medium confidence, actually same person
};

float auc = Metrics.Auc(estimations);
Console.WriteLine($"AUC: {auc}");
```

--------------------------------

### Import Pickle Module

Source: https://github.com/georg-jung/faceaisharp/blob/master/src/python/arcface-modelzoo-bin-converter.ipynb

Required import for deserializing the LFW dataset binary file.

```python
import pickle
```

--------------------------------

### Load LFW Dataset

Source: https://github.com/georg-jung/faceaisharp/blob/master/src/python/arcface-modelzoo-bin-converter.ipynb

Loads the binary dataset file and returns the image buffers and identity comparison list.

```python
bins, issame_list = pickle.load(open("lfw.bin", 'rb'), encoding='bytes')
```

--------------------------------

### Ensure Image Sizing and Format

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/ImageExtensions.md

Returns an image that matches specified size and pixel format. If the image already conforms, it's returned directly; otherwise, a properly sized clone is created. This internal method optimizes memory usage by avoiding unnecessary copies.

```csharp
(var img, var disp) = image.EnsureProperlySized<Rgb24>(resizeOptions, throwIfResizeRequired: false);
using var usingDisp = disp;  // Safe disposal even if null
// Use img...
```

--------------------------------

### Get Eye Boxes from Center Points

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/ImageCalculations.md

Estimates bounding boxes for eyes based on their center points. The method assumes that eye box size is proportional to the distance between the eyes. Use this when you have the center coordinates of both eyes and need to define their bounding boxes.

```csharp
using FaceAiSharp;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;

var detector = FaceAiSharpBundleFactory.CreateFaceDetectorWithLandmarks();
var image = Image.Load<Rgb24>("photo.jpg");

var faces = detector.DetectFaces(image);
var face = faces.First();

if (face.Landmarks != null)
{
    var leftEyeCenter = detector.GetLeftEyeCenter(face.Landmarks);
    var rightEyeCenter = detector.GetRightEyeCenter(face.Landmarks);
    
    // Get eye boxes
    var eyeBoxes = ImageCalculations.GetEyeBoxesFromCenterPoints(
        leftEyeCenter,
        rightEyeCenter,
        distanceDivisor: 3.0f
    );
    
    Console.WriteLine($"Left eye box: {eyeBoxes.Left}");
    Console.WriteLine($"Right eye box: {eyeBoxes.Right}");
}
```

--------------------------------

### Create Face Detector with Custom SessionOptions

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/configuration.md

Instantiate a face detector using the FaceAiSharpBundleFactory with custom ONNX Runtime session options. This allows fine-tuning of the inference engine.

```csharp
var sessionOptions = new SessionOptions
{
    GraphOptimizationLevel = GraphOptimizationLevel.ORT_ENABLE_ALL
};

var detector = FaceAiSharpBundleFactory.CreateFaceDetectorWithLandmarks(sessionOptions);
var embedder = FaceAiSharpBundleFactory.CreateFaceEmbeddingsGenerator(sessionOptions);
var eyeDetector = FaceAiSharpBundleFactory.CreateEyeStateDetector(sessionOptions);
```

--------------------------------

### Configure ONNX Runtime Session for GPU Acceleration

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/configuration.md

Set up ONNX Runtime session options for GPU acceleration using CUDA, TensorRT, or CoreML. Enables graph optimization.

```csharp
using Microsoft.ML.OnnxRuntime;

var sessionOptions = new SessionOptions
{
    GraphOptimizationLevel = GraphOptimizationLevel.ORT_ENABLE_ALL
};

// Add GPU execution provider
sessionOptions.AppendExecutionProvider_CUDA();  // CUDA for NVIDIA GPUs
// or
sessionOptions.AppendExecutionProvider_Tensorrt();  // TensorRT
// or
sessionOptions.AppendExecutionProvider_CoreML();  // CoreML for Apple devices

var detector = new ScrfdDetector(options, sessionOptions);
```

--------------------------------

### OpenVinoOpenClosedEye0001 Constructors

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/OpenVinoOpenClosedEye0001.md

Initializes a new instance of the OpenVinoOpenClosedEye0001 class. You can initialize it either by providing a model path or by passing the model as a byte array.

```APIDOC
## Constructor 1: From Model Path

```csharp
public OpenVinoOpenClosedEye0001(OpenVinoOpenClosedEye0001Options options, SessionOptions? sessionOptions = null)
```

Initializes a new instance of `OpenVinoOpenClosedEye0001` using an ONNX model file path.

### Parameters

* **options** (OpenVinoOpenClosedEye0001Options) - Required - Configuration options including the required ModelPath
* **sessionOptions** (SessionOptions?) - Optional - ONNX Runtime session options for customizing inference behavior

**Throws:** `ArgumentException` if `options.ModelPath` is null or empty.

### Example

```csharp
var options = new OpenVinoOpenClosedEye0001Options
{
    ModelPath = "/path/to/open_closed_eye.onnx"
};

var eyeDetector = new OpenVinoOpenClosedEye0001(options);
```

## Constructor 2: From In-Memory Model

```csharp
public OpenVinoOpenClosedEye0001(byte[] model, OpenVinoOpenClosedEye0001Options? options = null, SessionOptions? sessionOptions = null)
```

Initializes a new instance of `OpenVinoOpenClosedEye0001` using an ONNX model stored in memory.

### Parameters

* **model** (byte[]) - Required - The ONNX model data as a byte array. Must be OpenVINO's open-closed-eye-0001 with 1x3x32x32 BGR input
* **options** (OpenVinoOpenClosedEye0001Options?) - Optional - Configuration options. If null, a new instance with defaults is created
* **sessionOptions** (SessionOptions?) - Optional - ONNX Runtime session options for customizing inference behavior

**Throws:** `ArgumentNullException` if `model` is null.

### Example

```csharp
byte[] modelData = await File.ReadAllBytesAsync("open_closed_eye.onnx");
var eyeDetector = new OpenVinoOpenClosedEye0001(modelData);
```
```

--------------------------------

### Initialize FaceOnnxDetector

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/FaceOnnxDetector.md

Initializes a new instance of FaceOnnxDetector with default settings. No model file path is required as the detector uses FaceONNX's internal models.

```csharp
using FaceAiSharp;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;

var detector = new FaceOnnxDetector();
var image = Image.Load<Rgb24>("face.jpg");
var faces = detector.DetectFaces(image);
detector.Dispose();
```

--------------------------------

### Configure SessionOptions for Memory Optimization

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/configuration.md

Optimize ONNX Runtime session for lower memory usage by setting the execution mode to sequential. Note that this may result in slower inference.

```csharp
var sessionOptions = new SessionOptions
{
    GraphOptimizationLevel = GraphOptimizationLevel.ORT_ENABLE_ALL,
    ExecutionMode = ExecutionMode.ORT_SEQUENTIAL  // Lower memory, slower
};

var detector = new ScrfdDetector(options, sessionOptions);
```

--------------------------------

### Optimized Image Cropping with Max Edge Size

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/ImageExtensions.md

Demonstrates performance optimization by specifying `alignedMaxEdgeSize` in `CropAligned`. This resizes the image before rotation, significantly reducing computational cost for large images.

```csharp
// Extracting a profile picture from a high-resolution image
var image = Image.Load<Rgb24>("4k_photo.jpg");  // e.g., 4000x3000

// Without maxEdgeSize: rotates full 4000x3000 image
using var fullRes = image.CropAligned(faceArea, angle, alignedMaxEdgeSize: null);

// With maxEdgeSize: resizes before rotation, much faster
using var optimized = image.CropAligned(faceArea, angle, alignedMaxEdgeSize: 512);
```

--------------------------------

### Construct Model Path using Path.Combine

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/configuration.md

Use `Path.Combine` for constructing model file paths to ensure cross-platform compatibility. This is the recommended approach for managing model file locations.

```csharp
// Recommended: Use Path.Combine for cross-platform compatibility
var baseDir = AppContext.BaseDirectory;
var modelPath = Path.Combine(baseDir, "models", "scrfd_2.5g_kps.onnx");

var options = new ScrfdDetectorOptions { ModelPath = modelPath };
var detector = new ScrfdDetector(options);
```

--------------------------------

### Basic Face Detection

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/index.md

This snippet shows how to perform basic face detection using the FaceAiSharp library. It initializes a face detector and iterates through the detected faces, printing their bounding box and confidence score.

```csharp
var detector = FaceAiSharpBundleFactory.CreateFaceDetector();
var faces = detector.DetectFaces(image);
foreach (var face in faces)
    Console.WriteLine($"Face: {face.Box}, Confidence: {face.Confidence}");
```

--------------------------------

### Initialize OpenVinoOpenClosedEye0001 from In-Memory Model

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/OpenVinoOpenClosedEye0001.md

Use this constructor when the ONNX model is loaded into memory as a byte array. This is useful for embedded scenarios or when the model is downloaded dynamically.

```csharp
byte[] modelData = await File.ReadAllBytesAsync("open_closed_eye.onnx");
var eyeDetector = new OpenVinoOpenClosedEye0001(modelData);
```

--------------------------------

### CreateFaceDetectorWithLandmarks

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/FaceAiSharpBundleFactory.md

Creates a face detector instance with facial landmark extraction using the bundled SCRFD model.

```APIDOC
## CreateFaceDetectorWithLandmarks

### Description
Creates a face detector instance with facial landmark extraction using the bundled SCRFD model.

### Method
```csharp
public static IFaceDetectorWithLandmarks CreateFaceDetectorWithLandmarks(SessionOptions? sessionOptions = null)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **sessionOptions** (SessionOptions?) - Optional - ONNX Runtime session options for customizing inference behavior

### Returns
`IFaceDetectorWithLandmarks` - A configured ScrfdDetector instance

### Model
SCRFD 2.5G KPS (Knowledge Point System)

### Example
```csharp
var detector = FaceAiSharpBundleFactory.CreateFaceDetectorWithLandmarks();
var faces = detector.DetectFaces(image);

foreach (var face in faces)
{
    if (face.Landmarks != null)
    {
        var leftEye = detector.GetLeftEyeCenter(face.Landmarks);
        var rightEye = detector.GetRightEyeCenter(face.Landmarks);
    }
}
```
```

--------------------------------

### Face Recognition Threshold Calibration and Matching

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/Metrics.md

Demonstrates calibrating a face recognition system by finding an optimal threshold using historical data and then applying that threshold for real-time matching.

```csharp
// Create a calibration dataset
var calibrationPairs = LoadCalibrationDataset();

// Find optimal threshold for your specific use case
var threshold = Metrics.FindThreshold(calibrationPairs);

// Use threshold for face matching
var embedder = FaceAiSharpBundleFactory.CreateFaceEmbeddingsGenerator();
var detector = FaceAiSharpBundleFactory.CreateFaceDetectorWithLandmarks();

var reference = LoadReferenceEmbedding();
var candidate = GenerateEmbedding(detector, embedder, testImage);

var similarity = reference.Dot(candidate);
if (similarity >= threshold)
    Console.WriteLine("Match");
else
    Console.WriteLine("No match");
```

--------------------------------

### Initialize ScrfdDetector from Model Path

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/ScrfdDetector.md

Use this constructor when the ONNX model file is accessible via a file path. Configure detector behavior and ONNX Runtime session options as needed.

```csharp
using FaceAiSharp;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;

var options = new ScrfdDetectorOptions
{
    ModelPath = "/path/to/scrfd_2.5g_kps.onnx",
    ConfidenceThreshold = 0.5f,
    NonMaxSupressionThreshold = 0.4f
};

var detector = new ScrfdDetector(options);
var image = Image.Load<Rgb24>("face.jpg");
var faces = detector.DetectFaces(image);
detector.Dispose();
```

--------------------------------

### Configure ScrfdDetector with Custom Options

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/configuration.md

Set custom thresholds and input size for the SCRFD facial landmark detector. Ensures proper model path is provided.

```csharp
using FaceAiSharp;

var options = new ScrfdDetectorOptions
{
    ModelPath = "/path/to/scrfd_2.5g_kps.onnx",
    ConfidenceThreshold = 0.45f,      // Detect lower-confidence faces
    NonMaxSupressionThreshold = 0.3f, // Stricter duplicate filtering
    AutoResizeInputToModelDimensions = true,
    MaximumInputSize = new Size(800, 800)
};

var detector = new ScrfdDetector(options);
var faces = detector.DetectFaces(image);
detector.Dispose();
```

--------------------------------

### Create Face Detector with Landmarks

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/FaceAiSharpBundleFactory.md

Creates a face detector instance that includes facial landmark extraction using the bundled SCRFD model. This is useful for detailed facial analysis.

```csharp
var detector = FaceAiSharpBundleFactory.CreateFaceDetectorWithLandmarks();
var faces = detector.DetectFaces(image);

foreach (var face in faces)
{
    if (face.Landmarks != null)
    {
        var leftEye = detector.GetLeftEyeCenter(face.Landmarks);
        var rightEye = detector.GetRightEyeCenter(face.Landmarks);
    }
}
```

--------------------------------

### ScrfdDetector Constructor (Model Path)

Source: https://github.com/georg-jung/faceaisharp/blob/master/_autodocs/api-reference/ScrfdDetector.md

Initializes a new instance of ScrfdDetector using an ONNX model file path. This constructor requires configuration options including the model path and optionally allows for custom ONNX Runtime session options.

```APIDOC
## ScrfdDetector(ScrfdDetectorOptions options, SessionOptions? sessionOptions = null)

### Description
Initializes a new instance of `ScrfdDetector` using an ONNX model file path. This constructor requires configuration options including the model path and optionally allows for custom ONNX Runtime session options.

### Parameters
#### Path Parameters
- **options** (ScrfdDetectorOptions) - Required - Configuration options including the required ModelPath and detector behavior settings
- **sessionOptions** (SessionOptions?) - Optional - ONNX Runtime session options for customizing inference behavior

### Throws
- `ArgumentException` if `options.ModelPath` is null or empty.

### Example
```csharp
var options = new ScrfdDetectorOptions
{
    ModelPath = "/path/to/scrfd_2.5g_kps.onnx",
    ConfidenceThreshold = 0.5f,
    NonMaxSupressionThreshold = 0.4f
};

var detector = new ScrfdDetector(options);
var image = Image.Load<Rgb24>("face.jpg");
var faces = detector.DetectFaces(image);
detector.Dispose();
```
```