facestack 0.0.4

Modular, production-grade face recognition system with swappable backends

FaceStack

A modular, production-ready face recognition system covering detection, alignment, recognition, tracking, attendance logging, cloud APIs, edge deployment, and a web dashboard.

Built as an educational project with 31 notebooks, but architected for real-world use.

Features

• 3 face detectors: SCRFD, YuNet, MediaPipe — see MODEL_CHOICES.md for the curation rationale
• 3 face recognizers: ArcFace, AdaFace, SFace
• 3 aligners: Five-point, MediaPipe Mesh, InsightFace
• Anti-spoofing: Liveness detection to prevent photo/video attacks
• Multi-camera tracking: Centroid tracker with entry/exit zone logic
• Attendance system: Automatic logging with cooldown, daily summaries, CSV/JSON/Excel export
• 4 cloud backends: AWS Rekognition, Azure Face, Google Vision, Face++
• Edge deployment: ONNX export, TensorRT optimization, Raspberry Pi and Jetson configs
• Web dashboard: Streamlit app with live feed, enrollment, attendance, benchmark, and settings
• CLI interface: Full-featured command-line tool

Quick Start

# Clone and install
git clone https://github.com/fullstackcv/facestack.git
cd facestack
pip install -e .

# Download models
python scripts/download_models.py

# Run with webcam (SCRFD + ArcFace by default)
python app.py

# Run with custom backends
python app.py --detector yunet --recognizer sface

# Launch web dashboard
python app.py --dashboard

CLI Usage

# Live recognition
python app.py                                           # Webcam, default backends
python app.py --detector mediapipe --recognizer adaface # Custom combo
python app.py --source video.mp4                        # Video file
python app.py --source rtsp://camera:554/stream         # RTSP stream
python app.py --anti-spoof                              # Enable liveness detection

# Enrollment
python app.py --enroll --name "Alice" --images ./photos/alice/
python app.py --enroll --name "Bob" --images ./photos/bob/ --employee-id EMP002

# Benchmark
python app.py --benchmark --source test_video.mp4

# Export attendance
python app.py --export --format csv --output attendance.csv
python app.py --export --format json --date 2026-04-15

# Dashboard
python app.py --dashboard

Web Dashboard

Launch with python app.py --dashboard or streamlit run dashboard/app.py.

Page	Description
Live Feed	Real-time camera feed with face detection, recognition, and FPS
Enrollment	Upload photos to register new people
Attendance	View logs, daily summaries, hourly charts, export data
Benchmark	Compare detector/recognizer combos on FPS and latency
Settings	Configure backends, thresholds, device, anti-spoof

Architecture

facestack/
├── detection/          # 3 detector backends (SCRFD, YuNet, MediaPipe)
├── alignment/          # 3 aligner backends (Five-point, MediaPipe, InsightFace)
├── recognition/        # 3 recognizer backends (ArcFace, AdaFace, SFace)
├── tracking/           # Centroid tracker, cooldown, entry/exit zones
├── antispoof/          # Liveness detection
├── database/           # SQLAlchemy models, FAISS search, attendance, export
├── cloud/              # AWS, Azure, Google, Face++ backends + cost calculator
├── deploy/             # Raspberry Pi, Jetson Nano, laptop configs
├── utils/              # Video, drawing, benchmark, ONNX, TensorRT utilities
├── config.py           # Pydantic configuration
└── pipeline.py         # Main orchestrator: detect → align → recognize → track → log

Project Structure

facestack/
├── facestack/        # Core Python package
├── dashboard/          # Streamlit web dashboard (5 pages)
├── notebooks/          # 31 educational Jupyter notebooks
├── tests/              # Comprehensive test suite
├── scripts/            # Utility scripts
│   ├── download_models.py
│   ├── cost_analysis.py
│   ├── export_onnx.py
│   └── optimize_tensorrt.py
├── docker/             # Docker deployment
│   ├── Dockerfile.laptop
│   ├── Dockerfile.pi
│   ├── Dockerfile.jetson
│   └── docker-compose.yml
├── models/             # Model weights (gitignored, downloaded via script)
├── data/               # Sample data
└── app.py              # CLI entry point

Notebooks

31 notebooks covering the full journey from classical methods to production deployment:

#	Topic	Key Concepts
01-07	Detection	Haar, HOG, SSD, MTCNN, RetinaFace, SCRFD, YuNet, benchmarks
08-10	Alignment	Dlib landmarks, MediaPipe, alignment pipeline
11-13	Classical Recognition	Eigenfaces, Fisherfaces, LBPH
14-19	Deep Recognition	FaceNet, ArcFace, AdaFace, DeepFace, InsightFace, benchmarks
20-23	System	Multi-camera tracking, anti-spoofing, attendance, entry/exit
24-27	Cloud APIs	AWS Rekognition, Azure Face, Google Vision, Face++, cost analysis
28-30	Edge	ONNX export, Raspberry Pi deployment, Jetson TensorRT
31	Integration	Full app walkthrough, CLI, dashboard, packaging

Configuration

FaceStack uses Pydantic for validated configuration:

from facestack.config import FaceStackConfig

config = FaceStackConfig(
    detector="scrfd",
    recognizer="arcface",
    aligner="five_point",
    device="cpu",              # cpu, cuda, or tensorrt
    recognition_threshold=0.6,
    anti_spoof=True,
    cooldown_seconds=300,
    database_url="sqlite:///facestack.db",
)

Environment variables also work (prefix FACESTACK_):

export FACESTACK_DETECTOR=yunet
export FACESTACK_DEVICE=cuda

Docker Deployment

# Desktop / Laptop
docker build -f docker/Dockerfile.laptop -t facestack:laptop .
docker run --device /dev/video0 -p 8501:8501 facestack:laptop

# Raspberry Pi
docker build -f docker/Dockerfile.pi -t facestack:pi .

# Jetson (with TensorRT)
docker build -f docker/Dockerfile.jetson -t facestack:jetson .
docker run --runtime nvidia --device /dev/video0 facestack:jetson

# Full stack (app + db + dashboard)
docker compose -f docker/docker-compose.yml up

Cloud APIs

Provider	Setup	Cost (10K detect)
AWS Rekognition	IAM user + AmazonRekognitionFullAccess	~$10
Azure Face	Cognitive Services resource	~$10
Google Vision	Vision API enabled + service account	~$15
Face++	API key from console.faceplusplus.com	~$0 (free tier)

# Cost analysis
python scripts/cost_analysis.py

Testing

# Run all tests
pytest tests/ -v

# Run specific test module
pytest tests/test_dashboard.py -v

# Run with coverage
pytest tests/ --cov=facestack --cov-report=term-missing

Requirements

• Python 3.10+
• OpenCV 4.8+
• NumPy, Pydantic, SQLAlchemy
• FAISS (for embedding search)
• Streamlit (for dashboard)
• Optional: ONNX Runtime, TensorRT, boto3, azure SDK, google-cloud-vision

License

MIT

Author

Vikas Gupta