Realeyes.FaceVerification 1.5.2

Realeyes Face Verification Library - .NET Wrapper

Idiomatic C# wrapper for the Realeyes Face Verification Library, providing face detection, embedding extraction, and face comparison capabilities.

Features

• Async/Await Support: All I/O-bound operations use modern async patterns
• Type Safety: Strong typing with records and enums
• Resource Management: Proper IDisposable implementation with SafeHandle
• Cross-Platform: Works on Windows, Linux, and macOS

Installation

dotnet add package Realeyes.FaceVerification

Note: The package includes native libraries for multiple platforms (Windows, Linux, macOS) in the standard NuGet layout (runtimes/{rid}/native/). The library automatically resolves the correct native library for your platform.

Quick Start

using Realeyes.FaceVerification;

// Load the face verification model
using var verifier = new FaceVerifier("model.realZ");

// Prepare image data (example: BGR format)
byte[] imageData = LoadImageData(); // Your image loading logic
var imageHeader = new ImageHeader(
    data: imageData,
    width: 640,
    height: 480,
    stride: 640 * 3,
    format: ImageFormat.BGR
);

// Detect faces (use 'await using' for automatic disposal)
await using var faces = await verifier.DetectFacesAsync(imageHeader);
Console.WriteLine($"Detected {faces.Count} face(s)");

// Process each detected face
foreach (var face in faces)
{
    Console.WriteLine($"Face at ({face.BoundingBox.X}, {face.BoundingBox.Y})");
    Console.WriteLine($"Confidence: {face.Confidence:F2}");
    Console.WriteLine($"Quality: {face.DetectionQuality}");

    // Extract face embedding
    var embedding = await verifier.EmbedFaceAsync(face);
    Console.WriteLine($"Embedding size: {embedding.Length}");
}

// Faces are automatically disposed at the end of the block

Face Comparison Example

using Realeyes.FaceVerification;

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

// Detect faces in two images
await using var faces1 = await verifier.DetectFacesAsync(image1Header);
await using var faces2 = await verifier.DetectFacesAsync(image2Header);

if (faces1.Count > 0 && faces2.Count > 0)
{
    // Extract embeddings
    var embedding1 = await verifier.EmbedFaceAsync(faces1[0]);
    var embedding2 = await verifier.EmbedFaceAsync(faces2[0]);

    // Compare faces
    var match = verifier.CompareFaces(embedding1, embedding2);

    if (match.ExceedsThreshold(0.3f))
    {
        Console.WriteLine($"Same person! Similarity: {match.Similarity:F3}");
    }
    else
    {
        Console.WriteLine($"Different people. Similarity: {match.Similarity:F3}");
    }
}

// Faces are automatically disposed at the end of the block

Concurrent Operations

The library supports concurrent face detection and embedding:

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

// Process multiple images concurrently
var tasks = images.Select(img => verifier.DetectFacesAsync(img));
var results = await Task.WhenAll(tasks);

Detection Quality

Check the quality of detected faces:

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

foreach (var face in faces)
{
    switch (face.DetectionQuality)
    {
        case DetectionQuality.Good:
            Console.WriteLine("Good quality face");
            break;
        case DetectionQuality.BadQuality:
            Console.WriteLine("Warning: Low quality face detected");
            break;
        case DetectionQuality.MaybeRolled:
            Console.WriteLine("Warning: Face may be rolled, embeddings could be inaccurate");
            break;
    }
}

Image Format Support

The library supports various image formats:

// Grayscale (1 byte per pixel)
var grayImage = new ImageHeader(data, width, height, width, ImageFormat.Grayscale);

// RGB (3 bytes per pixel)
var rgbImage = new ImageHeader(data, width, height, width * 3, ImageFormat.RGB);

// RGBA (4 bytes per pixel)
var rgbaImage = new ImageHeader(data, width, height, width * 4, ImageFormat.RGBA);

// BGR (3 bytes per pixel) - common in OpenCV
var bgrImage = new ImageHeader(data, width, height, width * 3, ImageFormat.BGR);

// BGRA (4 bytes per pixel)
var bgraImage = new ImageHeader(data, width, height, width * 4, ImageFormat.BGRA);

Best Practices

1. Always Dispose Resources

// Use 'using' statements for automatic disposal
using var verifier = new FaceVerifier("model.realZ");

// Use 'await using' for FaceList returned from DetectFacesAsync
await using var faces = await verifier.DetectFacesAsync(imageHeader);

// Process faces - they'll be automatically disposed when the block ends
foreach (var face in faces)
{
    var embedding = await verifier.EmbedFaceAsync(face);
    // Process embedding...
}

// Or explicitly dispose if needed
var facesManual = await verifier.DetectFacesAsync(imageHeader);
try
{
    // Process faces...
}
finally
{
    facesManual.Dispose(); // Disposes all Face objects in the collection
}

2. Reuse FaceVerifier Instance

// Create once, reuse for multiple operations
using var verifier = new FaceVerifier("model.realZ");

foreach (var imagePath in imagePaths)
{
    var imageData = LoadImage(imagePath);
    var faces = await verifier.DetectFacesAsync(imageData);
    // Process faces...
}

3. Handle Errors

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

License

Copyright Realeyes OU 2012-2025. All rights reserved. Proprietary software.