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

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

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}");
}

Realeyes/Realeyes.Livenessv1.0.0

Get Started

Readme

Realeyes Liveness Library - .NET Wrapper

Features

Installation

Quick Start

Liveness Checking Example

Concurrent Operations

Detection Quality

Image Format Support

Best Practices

1. Always Dispose Resources

2. Reuse LivenessChecker Instance

3. Handle Errors

License

Realeyes/Realeyes.Livenessv1.0.0

Get Started

Readme

Realeyes Liveness Library - .NET Wrapper

Features

Installation

Quick Start

Liveness Checking Example

Concurrent Operations

Detection Quality

Image Format Support

Best Practices

1. Always Dispose Resources

2. Reuse LivenessChecker Instance

3. Handle Errors

License