Introduction

What is UFME?

UFME (Universal Face Matching Engine) is an open-source face recognition service. You give it a photo of a face; it tells you who that person is by searching a database of enrolled faces. It handles the entire process — detecting the face, checking image quality, guarding against spoofs and morphed photos, extracting a biometric template, and searching a compressed vector index — in a single API call that returns results in under 300 ms.

It is designed for cooperative, consent-based identity verification (border control, access management, document de-duplication) at scales from thousands to hundreds of millions of enrolled faces.

Design targets: Multi-million face gallery, 60 million annual 1:N searches, sub-300 ms end-to-end latency, 97%+ recall.

Is UFME right for you?

Use UFME if you need to:

• Search a face photo against a gallery and get ranked matches (1:N search)
• Verify that a face matches a specific enrolled identity (1:1 verification)
• Enrol and manage face templates with partition isolation
• Run security gates (anti-spoofing, morphing detection, quality assessment) as part of the pipeline

UFME is not designed for:

• Real-time video surveillance or tracking
• Emotion recognition or behavioural analysis
• Use without the knowledge and consent of the individuals involved

See the Responsible Use guidelines for ethical requirements and prohibited uses.

How it works

UFME receives a probe image, runs it through a quality-gated biometric pipeline, and searches a sharded FAISS vector index to return ranked candidate matches — or performs enrolment, verification, or deletion against the gallery. See Request Flow for a detailed walkthrough with diagrams.

1:N Gallery Search

1:1 Identity Verification

Key capabilities

• 1:N face search against multi-million-entry galleries using sharded FAISS IndexIVFPQ
• 1:1 face verification — probe vs enrolled subject with partition isolation
• Presentation attack detection (PAD) — physical and digital spoofs rejected before matching (ISO 30107-3)
• Morphing attack detection (MAD) — blended document photos rejected at enrolment
• ISO/IEC 29794-5 quality gates — configurable accept/reject policy, not hardcoded thresholds
• Age estimation — InsightFace genderage model, produces age in years as pipeline metadata
• Head pose estimation — ResNet-18 rotation matrix model, yaw/pitch/roll in degrees; extreme-yaw gate rejects unprocessable profiles
• Deepfake detection — ViT-based binary classifier; optional post-align pipeline stage with configurable threshold
• Face attribute analysis — gender classification from the InsightFace genderage model
• Face super-resolution — Real-ESRGAN x4plus upscaling as an optional pre-detect stage for low-resolution inputs
• Mask-aware recognition — w600k_mbf (ArcFace MobileFaceNet from InsightFace buffalo_sc) as an optional recognition model for occluded faces
• Hexagonal architecture — any detection model, vector store, or transport layer is swappable without touching domain logic

Quick start

# Install Python dependencies
make install

# Download models
make models

# Run tests
make test

# Start the API server
make demo

The REST gateway starts on http://localhost:8080. See the REST API reference for endpoint documentation.

Project layout

src/
├── core/           # Domain logic — zero external dependencies
│   ├── ports/      # Protocol interfaces for all operations
│   ├── domain/     # Pure data types, template operations, scoring
│   └── orchestration/  # Search / Verify / Enrol / Delete orchestrators
├── adapters/
│   ├── inbound/    # REST gateway, gRPC gateway
│   └── outbound/   # FAISS client, ONNX inference, PAD, MAD, OFIQ,
│                   # age, head pose, deepfake, face attributes, super-resolution
├── pipeline/       # Detection → Alignment → Quality → Extraction stages
└── infra/          # Config, logging, health checks
rust/               # Rust hot-path modules (FAISS bindings, compaction)
deploy/             # Dockerfiles, Kubernetes manifests, Helm charts
terraform/          # AWS EKS Terraform modules