CosmoBiometric.Fingerprint.Zkt 0.2.0

CosmoBiometric

A production-grade, cross-platform fingerprint recognition engine for .NET 10: enrollment, minutiae template generation, template serialization/protection, 1:1 verification, and 1:N identification — consuming captures from the ZKTeco Live20R/SLK20R scanner driven by CosmoUsb (no vendor SDK, no libusb), or from any other source that can produce a FingerprintImage.

Pure managed code, no native dependencies, runs on Windows, Linux, and macOS.

Projects

Quick start

using CosmoBiometric.Fingerprint;
using CosmoBiometric.Fingerprint.Devices.Zkt;
using CosmoBiometric.Fingerprint.Enrollment;
using CosmoBiometric.Fingerprint.Matching;
using CosmoBiometric.Fingerprint.Serialization;

// 1. Capture (any IFingerprintCaptureDevice; here the ZKT scanner)
await using var device = await ZktLive20RCaptureDevice.OpenAsync();
FingerprintImage image = await device.CaptureAsync(cancellationToken);

// 2. Template generation
var generator = new FingerprintTemplateGenerator(
    FingerprintTemplateGeneratorOptions.ForScanner(FingerprintScannerProfile.ZktLive20R()));
FingerprintTemplate template = generator.Generate(image);

// 3. Persist (serialize; encrypt with IFingerprintTemplateProtector before real storage)
byte[] blob = FingerprintTemplateSerializer.Serialize(template);

// 4. Verify a later capture
FingerprintTemplate probe = generator.Generate(await device.CaptureAsync(cancellationToken));
FingerprintMatchResult result = new FingerprintMatcher().Verify(
    FingerprintTemplateSerializer.Deserialize(blob), probe);
Console.WriteLine($"{(result.IsMatch ? "MATCH" : "NO MATCH")} score={result.Score:0.00} " +
    $"({result.MatchedMinutiae} minutiae, rotation {result.RotationDegrees:0.0}°)");

Multi-capture enrollment with retry workflow:

var enrollment = new FingerprintEnrollmentService(generator, new FingerprintMatcher());
FingerprintEnrollmentResult enrolled = await enrollment.EnrollAsync(device, progress, cancellationToken);

Run the demo without hardware:

dotnet run --project samples/FingerprintDemo -- --synthetic

Building

Requires the .NET 10 SDK. The ZKT adapter consumes the CosmoUsb package from nuget.org; the repository is fully self-contained.

dotnet build
dotnet test
dotnet run -c Release --project benchmarks/CosmoBiometric.Fingerprint.Benchmarks -- --filter '*'

Releasing

Packages (CosmoBiometric.Fingerprint.Abstractions, .Fingerprint, .Fingerprint.Diagnostics, .Fingerprint.Zkt) are published to nuget.org by the release workflow when a version tag is pushed:

git tag v0.1.0 && git push origin v0.1.0

The workflow builds, runs the full test suite, packs with the tag's version, pushes to nuget.org (requires the NUGET_API_KEY repository secret), and creates a GitHub release with the packages attached.

Documentation

• Architecture — pipeline stages, algorithms and references, project layering
• Biometric limitations — read before deploying: what is and is not validated
• Threshold calibration — how to tune FAR/FRR for your scanner and population
• Security threat model — template protection, storage, and privacy

Status: what is validated and what is not

Validated end-to-end on real hardware (ZKTeco Live20R over CosmoUsb, Windows 11/WinUSB): capture → 3-sample enrollment → encrypted template storage → verification-with-retry → MATCH, with impostor pairs rejected. The engine was calibrated against 17 real captures of 2 fingers (see calibration): effective sensor resolution measured at ~1000 DPI, hybrid minutiae + ridge-correlation matching at EER ≈ 12%, zero false accepts (0/52) at the demo threshold. Every pipeline stage additionally has synthetic unit tests (80 passing).

Honest limits:

• The calibration dataset is tiny (1 subject, 2 fingers). It demonstrates the system works; it does not establish deployment-grade FAR/FRR. Collect a multi-subject dataset and rerun samples/FingerprintEval before quoting error rates.
• The class-default MatchThreshold (0.25) is generic; the ZKT-calibrated operating point used by the demo is threshold 0.15 with RidgeCorrelationWeight 0.75.
• Match scores are engine-specific similarities in [0, 1], not probabilities; the quality score is application-specific, not NFIQ.

License

Same spirit as CosmoUsb: MIT OR Apache-2.0.