Realeyes.DemographicEstimation 1.2.0

Realeyes Demographic Estimation Library - .NET Wrapper

C# wrapper for the Realeyes Demographic Estimation Library, providing face detection and demographic estimation (age, gender, age uncertainty) capabilities.

Features

• Face Detection: Detect faces in images with bounding boxes, landmarks, and confidence scores
• Demographic Estimation: Estimate age, gender, and age uncertainty for detected faces
• Asynchronous API: Non-blocking callback-based operations for high performance
• Cross-platform: Supports Windows (x64), Linux (x64, ARM64)
• Type-safe: Strongly-typed C# wrapper over native C API

Installation

dotnet add package Realeyes.DemographicEstimation

Quick Start

using Realeyes.DemographicEstimation;

// Create estimator with model file
using var estimator = new DemographicEstimator("model.realZ");

// Prepare image
var imageHeader = new ImageHeader(
    data: imageBytes,
    width: 640,
    height: 480,
    stride: 640 * 3,
    format: ImageFormat.RGB
);

// Detect faces
using var faces = await estimator.DetectFacesAsync(imageHeader);

// Estimate demographics for each face
foreach (var face in faces)
{
    var result = await estimator.EstimateAsync(face);

    Console.WriteLine($"Age: {result.Age}");
    Console.WriteLine($"Gender: {result.Gender}");
    Console.WriteLine($"Age Uncertainty: {result.AgeUncertainty}");
}

Concurrent Operations

The library supports concurrent face detection and estimation:

using var estimator = new DemographicEstimator("model.realZ");

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

Detection Quality

Check the quality of detected faces:

await using var faces = await estimator.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 estimator = new DemographicEstimator("model.realZ");

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

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

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

2. Reuse DemographicEstimator Instance

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

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

3. Handle Errors

try
{
    using var estimator = new DemographicEstimator("model.realZ");
    var faces = await estimator.DetectFacesAsync(imageHeader);
}
catch (DemographicEstimationException ex)
{
    Console.WriteLine($"Demographic estimation error: {ex.Message}");
}

License

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