Metadata-Version: 2.4
Name: facestack
Version: 0.0.6
Summary: Modular, production-grade face recognition system with swappable backends
Author: Vikas
License-Expression: MIT
Project-URL: Homepage, https://github.com/fullstackcv/facestack
Project-URL: Repository, https://github.com/fullstackcv/facestack
Project-URL: Issues, https://github.com/fullstackcv/facestack/issues
Keywords: face-recognition,face-detection,face-alignment,attendance-system,computer-vision,deep-learning,opencv,scrfd,arcface,adaface,sface,yunet,mediapipe,insightface,anti-spoofing,liveness-detection,onnx,tensorrt,edge-deployment,raspberry-pi,jetson-nano,aws-rekognition,azure-face-api,streamlit-dashboard
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.24
Requires-Dist: opencv-contrib-python>=4.8
Requires-Dist: pydantic>=2.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: streamlit>=1.30
Requires-Dist: requests>=2.28
Requires-Dist: alembic>=1.12
Provides-Extra: onnx
Requires-Dist: onnxruntime>=1.16; extra == "onnx"
Provides-Extra: gpu
Requires-Dist: onnxruntime-gpu>=1.16; extra == "gpu"
Provides-Extra: cloud
Requires-Dist: boto3>=1.28; extra == "cloud"
Requires-Dist: google-cloud-vision>=3.4; extra == "cloud"
Requires-Dist: azure-cognitiveservices-vision-face>=0.6; extra == "cloud"
Requires-Dist: msrest>=0.7; extra == "cloud"
Provides-Extra: aws
Requires-Dist: boto3>=1.28; extra == "aws"
Provides-Extra: azure
Requires-Dist: azure-cognitiveservices-vision-face>=0.6; extra == "azure"
Requires-Dist: msrest>=0.7; extra == "azure"
Provides-Extra: google
Requires-Dist: google-cloud-vision>=3.4; extra == "google"
Provides-Extra: mediapipe
Requires-Dist: mediapipe>=0.10; extra == "mediapipe"
Provides-Extra: insightface
Requires-Dist: insightface>=0.7; extra == "insightface"
Provides-Extra: faiss
Requires-Dist: faiss-cpu>=1.7; extra == "faiss"
Provides-Extra: edge
Requires-Dist: onnxruntime>=1.16; extra == "edge"
Provides-Extra: all
Requires-Dist: onnxruntime>=1.16; extra == "all"
Requires-Dist: mediapipe>=0.10; extra == "all"
Requires-Dist: insightface>=0.7; extra == "all"
Requires-Dist: faiss-cpu>=1.7; extra == "all"
Requires-Dist: boto3>=1.28; extra == "all"
Requires-Dist: google-cloud-vision>=3.4; extra == "all"
Requires-Dist: azure-cognitiveservices-vision-face>=0.6; extra == "all"
Requires-Dist: msrest>=0.7; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"
Dynamic: license-file

# 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](https://gist.github.com/vikasgupta-github/90a17faf728239e60ef2ffc039f28408) 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

### Option A — pip install (self-contained)

```bash
pip install "facestack[onnx]"

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

# Run with webcam (SCRFD + ArcFace by default)
facestack

# Run with custom backends
facestack --detector yunet --recognizer sface

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

### Option B — from a repo checkout (for contributors)

```bash
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

```bash
# 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:

```python
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_`):
```bash
export FACESTACK_DETECTOR=yunet
export FACESTACK_DEVICE=cuda
```

## Docker Deployment

```bash
# 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) |

```bash
# Cost analysis
facestack-cost-analysis            # or: python scripts/cost_analysis.py
```

## Testing

```bash
# 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
