# Getting Started with .NET API

# Prerequisites

.NET 8.0+

# Installation

dotnet add package Realeyes.FaceVerification

# Quick Start Example

using Realeyes.FaceVerification;
using OpenCvSharp;

using var verifier = new FaceVerifier("model/model.realZ");

using var image1 = Cv2.ImRead("image1.jpg");
using var image2 = Cv2.ImRead("image2.jpg");

var imageData1 = image1.ToBytes();
var imageData2 = image2.ToBytes();

var header1 = new ImageHeader(imageData1, image1.Width, image1.Height,
    image1.Width * image1.Channels(), ImageFormat.BGR);
var header2 = new ImageHeader(imageData2, image2.Width, image2.Height,
    image2.Width * image2.Channels(), ImageFormat.BGR);

// Detect faces in parallel
using var faces1 = await verifier.DetectFacesAsync(header1);
using var faces2 = await verifier.DetectFacesAsync(header2);

// Embed all faces
var embeddings1 = new List<float[]>();
foreach (var face in faces1)
    embeddings1.Add(await verifier.EmbedFaceAsync(face));

var embeddings2 = new List<float[]>();
foreach (var face in faces2)
    embeddings2.Add(await verifier.EmbedFaceAsync(face));

// Compare embeddings
for (int i = 0; i < embeddings1.Count; i++)
    for (int j = 0; j < embeddings2.Count; j++)
        if (verifier.CompareFaces(embeddings1[i], embeddings2[j]).Similarity > 0.3f)
            Console.WriteLine("Match found!");

# Common Patterns

# Async/Await

Face detection and embedding are asynchronous. Use await to get results:

using var faces = await verifier.DetectFacesAsync(header);
var embedding = await verifier.EmbedFaceAsync(faces[0]);

# Resource Management

FaceVerifier, Face, and FaceList implement IDisposable. Always use using statements to ensure native resources are released:

using var verifier = new FaceVerifier("model.realZ");
using var faces = await verifier.DetectFacesAsync(header);

FaceList also implements IAsyncDisposable:

await using var faces = await verifier.DetectFacesAsync(header);

# Error Handling

Operations throw FaceVerificationException on failure:

try
{
    using var verifier = new FaceVerifier("model.realZ");
    using var faces = await verifier.DetectFacesAsync(header);
}
catch (FaceVerificationException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Standard .NET exceptions are also thrown for invalid arguments:

ArgumentNullException — null parameters
ArgumentException — invalid values (e.g., mismatched embedding lengths)
ArgumentOutOfRangeException — non-positive image dimensions
ObjectDisposedException — accessing disposed objects

# 3rd Party Face Detector

Create a Face from an external detector by specifying image, landmarks, bounding box, and confidence:

var landmarks = new Point2d[]
{
    new(100f, 120f),  // left eye
    new(160f, 120f),  // right eye
    new(130f, 155f),  // nose tip
    new(105f, 180f),  // left mouth corner
    new(155f, 180f),  // right mouth corner
};

using var face = new Face(header, landmarks, new BoundingBox(80, 90, 100, 120), 0.95f);
var embedding = await verifier.EmbedFaceAsync(face);

# Next Steps

.NET API Reference