KYNEX.FaceRecognition.SDK 1.0.1

🎭 KYNEX Face Recognition SDK

SDK profissional para reconhecimento facial offline usando TensorFlow Lite, desenvolvido especificamente para .NET MAUI Android.

🚀 Características Principais

• ✅ 100% Offline - Funciona sem internet ou serviços em nuvem
• ✅ MAUI Android - Desenvolvido especificamente para .NET MAUI Android
• ✅ TensorFlow Lite - Inferência rápida e eficiente com MobileFaceNet
• ✅ Injeção de Dependência - Integração nativa com Microsoft.Extensions.DependencyInjection
• ✅ Logging Integrado - Suporte completo ao Microsoft.Extensions.Logging
• ✅ Thread-Safe - Seguro para uso em aplicações multi-threaded
• ✅ Eventos em Tempo Real - Sistema de eventos para reconhecimento contínuo
• ✅ Configurável - Múltiplas opções de configuração e thresholds
• ✅ Performance Otimizada - Pool de buffers e cache de embeddings médios

📦 Instalação

Via NuGet Package Manager

Install-Package KYNEX.FaceRecognition.SDK

Via .NET CLI

dotnet add package KYNEX.FaceRecognition.SDK

Via PackageReference

<PackageReference Include="KYNEX.FaceRecognition.SDK" Version="1.0.0" />

🔧 Configuração Rápida

MAUI Application

using KYNEX.FaceRecognition.SDK.Extensions;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            });

        // Adicionar SDK
        builder.Services.AddFaceRecognitionSDK(config =>
        {
            config.BaseThreshold = 0.52f;
            config.EnableFaceAlignment = false;
        });

        return builder.Build();
    }
}

🎯 Uso Básico

1. Inicialização

var faceService = serviceProvider.GetRequiredService<IFaceRecognitionService>();

// Configurar o SDK
var config = new FaceRecognitionConfig
{
    BaseThreshold = 0.52f,
    EnableFaceAlignment = false,
    EnableIlluminationNormalization = false
};

await faceService.InitializeAsync(config);

2. Registro de Faces

// Registrar uma face
var result = await faceService.RegisterFaceAsync(
    profileId: "user001",
    faceImage: skBitmap
);

if (result.Success)
{
    Console.WriteLine($"Perfil registrado: {result.RegisteredProfile?.Id}");
}

// Registrar múltiplas faces para melhor precisão
var images = new[] { image1Bitmap, image2Bitmap, image3Bitmap };
foreach (var image in images)
{
    await faceService.RegisterFaceAsync("user001", image);
}

3. Reconhecimento

// Reconhecer face
var recognition = await faceService.RecognizeFaceAsync(faceImage);

if (recognition.Success)
{
    Console.WriteLine($"Face reconhecida: {recognition.RecognizedProfile?.Name}");
    Console.WriteLine($"Score: {recognition.SimilarityScore:F3}");
}
else
{
    Console.WriteLine($"Não reconhecido: {recognition.Message}");
}

4. Eventos em Tempo Real

// Subscrever eventos
faceService.OnFaceRecognized += (sender, args) =>
{
    Console.WriteLine($"Face reconhecida: {args.Result.RecognizedProfile?.Name}");
    Console.WriteLine($"Score: {args.Result.SimilarityScore:F3}");
};

faceService.OnError += (sender, args) =>
{
    Console.WriteLine($"Erro: {args.Message}");
    if (args.Exception != null)
    {
        Console.WriteLine($"Detalhes: {args.Exception.Message}");
    }
};

⚙️ Configurações Avançadas

FaceRecognitionConfig

var config = new FaceRecognitionConfig
{
    // Thresholds de Reconhecimento
    BaseThreshold = 0.52f,              // Threshold base (0.0-1.0)
    MaxInputSize = 112,                 // Tamanho de entrada (MobileFaceNet)
    
    // Funcionalidades Opcionais
    EnableFaceAlignment = false,         // Alinhamento automático de faces
    EnableIlluminationNormalization = false, // Normalização de iluminação
    EnableImageEnhancement = false,     // Melhoria de qualidade de imagem
    EnableAdaptiveThreshold = false,     // Threshold adaptativo por qualidade
    EnableAverageEmbeddings = false     // Uso de embeddings médios
};

Interpretação de Thresholds

📊 Modelos de Dados

FaceProfile

public class FaceProfile
{
    public string Id { get; set; }                    // Identificador único
    public string Name { get; set; }                  // Nome de exibição
    public List<float[]> Embeddings { get; set; }     // Embeddings faciais (192D)
    public DateTime RegistrationDate { get; set; }    // Data de registro
}

FaceRecognitionResult

public class FaceRecognitionResult
{
    public bool Success { get; set; }                 // Sucesso do reconhecimento
    public string Message { get; set; }               // Mensagem descritiva
    public FaceProfile? RecognizedProfile { get; set; } // Perfil reconhecido
    public float SimilarityScore { get; set; }       // Score de similaridade
    public DetectedFace? DetectedFace { get; set; }  // Dados da face detectada
}

FaceRegistrationResult

public class FaceRegistrationResult
{
    public bool Success { get; set; }                 // Sucesso do registro
    public string Message { get; set; }               // Mensagem descritiva
    public FaceProfile? RegisteredProfile { get; set; } // Perfil criado/atualizado
}

🔌 Interfaces Disponíveis

• IFaceRecognitionService - Serviço principal de reconhecimento facial
• FaceRecognitionConfig - Configurações do sistema
• FaceProfile - Modelo de perfil facial
• FaceRecognitionResult - Resultado de reconhecimento
• FaceRegistrationResult - Resultado de registro

🚀 Exemplos Avançados

Reconhecimento em Tempo Real

public class RealtimeRecognitionService
{
    private readonly IFaceRecognitionService _faceService;
    private readonly Timer _timer;
    private bool _isRunning = false;

    public RealtimeRecognitionService(IFaceRecognitionService faceService)
    {
        _faceService = faceService;
        _timer = new Timer(ProcessFrame, null, Timeout.Infinite, 1000);
        
        // Subscrever eventos
        _faceService.OnFaceRecognized += OnFaceRecognized;
        _faceService.OnError += OnError;
    }

    public void StartRecognition()
    {
        _isRunning = true;
        _timer.Change(0, 1000); // Processar a cada 1 segundo
    }

    public void StopRecognition()
    {
        _isRunning = false;
        _timer.Change(Timeout.Infinite, Timeout.Infinite);
    }

    private async void ProcessFrame(object? state)
    {
        if (!_isRunning) return;

        try
        {
            var imageData = await CaptureCurrentFrame();
            using var bitmap = SKBitmap.Decode(imageData);
            await _faceService.RecognizeFaceAsync(bitmap);
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Erro no processamento: {ex.Message}");
        }
    }

    private void OnFaceRecognized(object? sender, FaceRecognitionEventArgs e)
    {
        Console.WriteLine($"🎯 Face reconhecida: {e.Result.RecognizedProfile?.Name}");
        Console.WriteLine($"📊 Score: {e.Result.SimilarityScore:F3}");
    }

    private void OnError(object? sender, FaceRecognitionErrorEventArgs e)
    {
        Console.WriteLine($"❌ Erro: {e.Message}");
    }
}

Gerenciamento de Perfis

public class ProfileManager
{
    private readonly IFaceRecognitionService _faceService;

    public ProfileManager(IFaceRecognitionService faceService)
    {
        _faceService = faceService;
    }

    public async Task<List<FaceProfile>> GetAllProfilesAsync()
    {
        return (await _faceService.GetAllFaceProfilesAsync()).ToList();
    }

    public async Task<bool> RemoveProfileAsync(string profileId)
    {
        return await _faceService.RemoveFaceProfileAsync(profileId);
    }

    public async Task<bool> ProfileExistsAsync(string profileId)
    {
        var profiles = await _faceService.GetAllFaceProfilesAsync();
        return profiles.Any(p => p.Id == profileId);
    }

    public async Task<int> GetProfileCountAsync()
    {
        var profiles = await _faceService.GetAllFaceProfilesAsync();
        return profiles.Count();
    }
}

📋 Requisitos do Sistema

Requisitos Mínimos

• .NET 8.0 ou superior
• SkiaSharp 3.119.1+ (incluído automaticamente)
• TensorFlow Lite (incluído no SDK)
• Modelo MobileFaceNet (incluído no SDK)

Plataformas Suportadas

• ✅ Android (API 21+) - Única plataforma suportada
• ❌ Windows - Não suportado
• ❌ macOS - Não suportado
• ❌ iOS - Não suportado
• ❌ Linux - Não suportado

Dependências

<PackageReference Include="Xamarin.TensorFlow.Lite" Version="2.16.1.7" />
<PackageReference Include="SkiaSharp" Version="3.119.1" />
<PackageReference Include="SkiaSharp.Views.Maui.Controls" Version="3.119.1" />
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.0" />
<PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="8.0.0" />

🎯 Casos de Uso

🔐 Controle de Acesso

• Sistemas de segurança - Reconhecimento para liberação de portas
• Controle de acesso físico - Entrada em edifícios e salas
• Dispositivos IoT - Controle de dispositivos inteligentes

🌐 Aplicações Web

• Autenticação biométrica - Login por reconhecimento facial
• Sistemas de CRM - Identificação automática de clientes
• Plataformas de e-commerce - Personalização baseada em reconhecimento

📱 Apps Mobile

• Login biométrico - Alternativa segura a senhas
• Apps de segurança - Controle de acesso a funcionalidades
• Aplicações de saúde - Identificação de pacientes

🏢 Sistemas Empresariais

• Controle de ponto - Registro de entrada/saída
• Sistemas de RH - Identificação de funcionários
• Plataformas de eventos - Check-in automático

🔧 Troubleshooting

Problemas Comuns

1. Modelo não encontrado

Erro: "Modelo TFLite não encontrado no SDK"

Solução: Verifique se o arquivo mobilefacenet_fp16_112x112_192d.tflite está incluído como EmbeddedResource.

2. Threshold muito baixo/alto

Problema: Muitos falsos positivos ou negativos

Solução: Ajuste o BaseThreshold:

• Falsos positivos: Aumente o threshold (0.6-0.8)
• Falsos negativos: Diminua o threshold (0.3-0.5)

3. Performance lenta

Problema: Reconhecimento muito lento

Solução:

• Use imagens menores (redimensione para 112x112)
• Desabilite funcionalidades opcionais
• Use menos embeddings por perfil

4. Erro de inicialização

Erro: "FaceEmbedder não foi inicializado"

Solução: Sempre chame InitializeAsync() antes de usar o serviço.

Logs de Debug

// Habilitar logs detalhados
services.AddLogging(builder =>
{
    builder.AddConsole();
    builder.SetMinimumLevel(LogLevel.Debug);
});

// Configurar SDK com logs
services.AddFaceRecognitionSDK(config =>
{
    config.EnableDebugLogs = true;
});

📈 Performance e Otimização

Métricas Típicas

• Inicialização: ~200-500ms (primeira vez)
• Reconhecimento: ~50-150ms por face
• Registro: ~100-200ms por imagem
• Uso de Memória: ~50-100MB (incluindo modelo)

Dicas de Otimização

1. Use imagens pequenas - Redimensione para 112x112 antes do processamento
2. Limite embeddings por perfil - 3-5 embeddings são suficientes
3. Cache resultados - Armazene resultados de reconhecimento frequentes
4. Processe em background - Use threads separadas para operações pesadas

🤝 Contribuição

Contribuições são bem-vindas! Por favor:

1. Fork o repositório
2. Crie uma branch para sua feature (git checkout -b feature/nova-funcionalidade)
3. Commit suas mudanças (git commit -am 'Adiciona nova funcionalidade')
4. Push para a branch (git push origin feature/nova-funcionalidade)
5. Abra um Pull Request

Diretrizes de Contribuição

• Siga as convenções de código C#
• Adicione testes para novas funcionalidades
• Atualize a documentação quando necessário
• Use mensagens de commit descritivas

📝 Licença

Este projeto está licenciado sob a MIT License - veja o arquivo LICENSE para detalhes.

🆘 Suporte

• Documentação: Wiki do GitHub
• Issues: GitHub Issues
• Discussões: GitHub Discussions
• Email: alexsandro@itplug.com.br

🏆 Reconhecimentos

• TensorFlow Lite - Framework de inferência
• MobileFaceNet - Modelo de reconhecimento facial
• SkiaSharp - Processamento de imagens
• Microsoft - .NET e MAUI

Desenvolvido com ❤️ pela equipe ITPLUG

Para mais informações, visite itplug.com.br