face-reidentification

Real-Time Face Re-Identification with FAISS, ArcFace & SCRFD

Downloads

Key Features

Real-Time Face Recognition: Live processing from webcam or video files with optimized performance
Production-Ready Accuracy: State-of-the-art SCRFD + ArcFace models for reliable detection and recognition
Intelligent Processing: Smart batch optimization that adapts to face count for optimal performance
Scalable Vector Search: FAISS-powered similarity search with thread-safe database operations
Flexible Model Selection: Multiple model sizes available to balance speed vs accuracy for your use case
Robust Resource Management: Built-in memory leak prevention and automatic cleanup for long-running applications

Performance Optimizations

Intelligent Batch Processing: Automatically switches between sequential and parallel processing based on face count
Thread-Safe Database: Robust FAISS integration with proper resource management
Memory Efficient: Context managers ensure proper cleanup and prevent memory leaks
Optimized for Video: Designed for typical video scenarios (1-5 faces per frame)

[!NOTE] Place your target face images in the assets/faces/ directory. The filenames will be used as identity labels during recognition.

Architecture

The system combines three powerful components:

SCRFD (Paper): Efficient face detection
ArcFace (Paper): Robust face recognition
FAISS: Fast similarity search for face re-identification

Available Models

Category	Model	Size	Description
Detection	SCRFD 500M	2.41 MB	Lightweight face detection
Detection	SCRFD 2.5G	3.14 MB	Balanced performance
Detection	SCRFD 10G	16.1 MB	High accuracy
Recognition	ArcFace MobileFace	12.99 MB	Mobile-friendly recognition
Recognition	ArcFace ResNet-50	166 MB	High-accuracy recognition

Project Structure

├── assets/
│   ├── demo.mp4
│   |── in_video.mp4
|   └── faces/           # Place target face images here
│     ├── face1.jpg
│     ├── face2.jpg
│     └── ...
├── database/           # FAISS database implementation
├── models/            # Neural network models
├── weights/           # Model weights (download required)
├── utils/            # Helper functions
├── main.py           # Main application entry
└── requirements.txt  # Dependencies

Getting Started

Prerequisites

[!IMPORTANT] Make sure you have Python 3.7+ installed on your system.

Installation

Clone the repository:

git clone https://github.com/yakyo/face-reidentification.git
cd face-reidentification

Install dependencies:
```
pip install -r requirements.txt
```
Download model weights:

Click to see download links 📥

| Model | Download Link | Size | |-------|--------------|------| | SCRFD 500M | [det_500m.onnx](https://github.com/yakhyo/face-reidentification/releases/download/v0.0.1/det_500m.onnx) | 2.41 MB | | SCRFD 2.5G | [det_2.5g.onnx](https://github.com/yakhyo/face-reidentification/releases/download/v0.0.1/det_2.5g.onnx) | 3.14 MB | | SCRFD 10G | [det_10g.onnx](https://github.com/yakhyo/face-reidentification/releases/download/v0.0.1/det_10g.onnx) | 16.1 MB | | ArcFace MobileFace | [w600k_mbf.onnx](https://github.com/yakhyo/face-reidentification/releases/download/v0.0.1/w600k_mbf.onnx) | 12.99 MB | | ArcFace ResNet-50 | [w600k_r50.onnx](https://github.com/yakhyo/face-reidentification/releases/download/v0.0.1/w600k_r50.onnx) | 166 MB |

Quick download (Linux/Mac):

sh download.sh

Add target faces: Place face images in assets/faces/ directory. The filename will be used as the person’s identity.

Usage

Basic Usage

python main.py --source assets/in_video.mp4

Command Line Arguments

[!TIP] Use these arguments to customize the recognition behavior:

usage: main.py [-h] [--det-weight DET_WEIGHT] [--rec-weight REC_WEIGHT] 
               [--similarity-thresh SIMILARITY_THRESH] [--confidence-thresh CONFIDENCE_THRESH]
               [--faces-dir FACES_DIR] [--source SOURCE] [--max-num MAX_NUM]

Argument	Description	Default
`--det-weight`	Detection model path	`weights/det_10g.onnx`
`--rec-weight`	Recognition model path	`weights/w600k_r50.onnx`
`--similarity-thresh`	Face similarity threshold	`0.4`
`--confidence-thresh`	Detection confidence threshold	`0.5`
`--faces-dir`	Target faces directory	`assets/faces`
`--source`	Video source (file or camera index)	`0`
`--max-num`	Max faces per frame	`5`
`--db-path`	Custom database storage location	`./database/face_database`
`--update-db`	Force rebuild face database	`False`
`--output`	Specify output video path	`output_video.mp4`

Technical Notes

Database Behavior

Face database automatically saves/loads from disk
Intelligent processing: sequential for <10 faces, parallel for larger batches
Thread-safe operations with proper resource cleanup

Performance Tips

Typical video processing: Sequential processing is automatically used for 1-5 faces per frame
Threading optimization: Parallel processing kicks in only for 10+ faces (rare in normal video)
GPU acceleration: Install onnxruntime-gpu for faster model inference
Memory efficiency: Context managers ensure proper resource cleanup in long-running applications
Database persistence: Face database automatically saves/loads, avoiding rebuild on restart

References

[!NOTE] This project builds upon the following research: