Metadata-Version: 2.4
Name: facestack
Version: 0.0.4
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](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

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

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

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