Realeyes.Liveness 1.0.0

Realeyes Liveness Library - .NET Wrapper

Idiomatic C# wrapper for the Realeyes Liveness Library, providing face detection and liveness checking 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.Liveness

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.Liveness;

// Load the liveness detection model
using var checker = new LivenessChecker("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 checker.DetectFacesAsync(imageHeader);
Console.WriteLine($"Detected {faces.Count} face(s)");

// Check liveness for 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}");

    // Check liveness
    var result = await checker.CheckImageAsync(face);
    Console.WriteLine($"{(result.IsLive ? "LIVE" : "SPOOF")} (score: {result.Score:F2})");
}

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

Liveness Checking Example

using Realeyes.Liveness;

using var checker = new LivenessChecker("model.realZ");

// Detect faces in an image
await using var faces = await checker.DetectFacesAsync(imageHeader);

foreach (var face in faces)
{
    // Perform liveness check
    var result = await checker.CheckImageAsync(face);

    if (result.IsLive)
    {
        Console.WriteLine($"Live face detected! Score: {result.Score:F3}");
    }
    else
    {
        Console.WriteLine($"Spoof detected! Score: {result.Score:F3}");
    }
}

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

Concurrent Operations

The library supports concurrent face detection and liveness checking:

using var checker = new LivenessChecker("model.realZ");

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

Detection Quality

Check the quality of detected faces:

await using var faces = await checker.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, liveness check results could be incorrect");
            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 checker = new LivenessChecker("model.realZ");

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

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

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

2. Reuse LivenessChecker Instance

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

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

3. Handle Errors

try
{
    using var checker = new LivenessChecker("model.realZ");
    var faces = await checker.DetectFacesAsync(imageHeader);
}
catch (LivenessException ex)
{
    Console.WriteLine($"Liveness error: {ex.Message}");
}

License

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