facestack 0.1.0

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: YuNet (default), MediaPipe, SCRFD — see MODEL_CHOICES.md for the curation rationale
• 3 face recognizers: SFace (default), ArcFace, AdaFace
• 3 aligners: Five-point (default), 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

Option A — pip install (self-contained)

pip install "facestack[onnx]"

# Download models (writes to ./models/)
facestack-download-models

# Run with webcam (YuNet + SFace by default — Apache-2.0, commercial-safe)
facestack

# Opt in to InsightFace (SCRFD + ArcFace) — higher accuracy, non-commercial license
facestack-download-models --insightface     # prompts for license acceptance
facestack --detector scrfd --recognizer arcface

# Launch web dashboard
facestack --dashboard          # or: facestack-dashboard

Model licensing. FaceStack defaults to YuNet + SFace (Apache-2.0, free for commercial use). SCRFD, ArcFace, and AdaFace are distributed under non-commercial research licenses; instantiating those backends emits a NonCommercialLicenseWarning, and facestack-download-models --insightface prompts before fetching their weights. See MODELS.md for details.

Option B — from a repo checkout (for contributors)

git clone https://github.com/fullstackcv/facestack.git
cd facestack
pip install -e ".[onnx]"

python scripts/download_models.py   # (thin shim — same as facestack-download-models)
python app.py                       # (thin shim — same as the `facestack` command)

Both options expose the same CLI. The app.py and scripts/*.py files at the repo root are kept as thin shims so notebook, blog, and Makefile references continue to work unchanged.

CLI Usage

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

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

# Benchmark
facestack --benchmark --source test_video.mp4

# Export attendance
facestack --export --format csv --output attendance.csv
facestack --export --format json --date 2026-04-15

# Dashboard
facestack --dashboard

Web Dashboard

Launch with facestack --dashboard, facestack-dashboard, or streamlit run facestack/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 (everything installable ships here)
│   ├── detection/          # Detector backends
│   ├── alignment/          # Aligner backends
│   ├── recognition/        # Recognizer backends
│   ├── tracking/
│   ├── antispoof/
│   ├── database/
│   ├── cloud/
│   ├── deploy/
│   ├── utils/
│   ├── dashboard/          # Streamlit dashboard (5 pages)
│   ├── scripts/            # CLI scripts (download_models, enroll, etc.)
│   ├── cli.py              # `facestack` console entry point
│   ├── config.py
│   └── pipeline.py
├── app.py                  # Thin shim → facestack.cli:main
├── scripts/                # Thin shims → facestack.scripts.*
├── dashboard/app.py        # Thin shim → facestack.dashboard.app (runpy)
├── notebooks/              # 31 educational Jupyter notebooks
├── tests/                  # Test suite
├── docker/                 # Dockerfile.laptop / .pi / .jetson + compose
├── models/                 # Model weights (gitignored, downloaded via script)
└── data/                   # Sample data

Pip-installed users get a self-contained package: the dashboard, scripts, and CLI all live inside facestack/ and are wired through console entry points. Repo users keep the familiar python app.py / python scripts/X.py UX via one-line shims.

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="yunet",          # default; use "scrfd" for InsightFace (non-commercial)
    recognizer="sface",        # default; use "arcface"/"adaface" for InsightFace (non-commercial)
    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
facestack-cost-analysis            # or: 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