README.md

---
title: FER API
emoji: 😊
colorFrom: yellow
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
---

# FER Inference

Production-ready inference system for the Facial Expression Recognition model (87.38% test accuracy).
Built on a ViT-base backbone fine-tuned on AffectNet/FER2013 with domain-adversarial training.

---

## Structure

```
inference/
├── model.py          # FERModel architecture + config constants
├── inference.py      # FERPredictor — main inference engine
├── detect_face.py    # Face detection (MTCNN primary / Haar fallback)
├── predict.py        # CLI for still-image inference
├── predict_video.py  # Real-time webcam / video inference
├── app.py            # Flask web UI (upload or webcam capture)
├── utils.py          # Visualization helpers
├── templates/
│   └── index.html    # Web UI frontend
└── requirements.txt
```

Model weights live in `../models/` (project root), not inside this folder.

---

## Installation

```bash
cd inference
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
```

---

## Quick Start — Python API

```python
from inference import FERPredictor

predictor = FERPredictor()   # loads ../models/model_weights.pth by default

result = predictor.predict_image('photo.jpg')
print(result['emotion'])     # e.g. 'happy'
print(result['confidence'])  # e.g. 0.942

# With face detection
faces = predictor.predict_with_face_detection('group_photo.jpg')
for face in faces:
    print(face['emotion'], face['bbox'])
```

---

## Web UI

```bash
python app.py
# → open http://localhost:5000
```

Upload an image or use the webcam to capture one. Results show annotated image + bar/pie/doughnut chart.

---

## CLI — Still Images

```bash
# Single image
python predict.py --image photo.jpg

# With face detection
python predict.py --image photo.jpg --detect-face

# Folder of images, save annotated output
python predict.py --folder ./test_images/ --detect-face --save-output result.jpg

# Custom weights path
python predict.py --image photo.jpg --weights /path/to/model_weights.pth
```

---

## CLI — Webcam / Video

```bash
python predict_video.py --source 0            # webcam
python predict_video.py --source video.mp4    # video file
python predict_video.py --source 0 --save-output out.mp4
python predict_video.py --source 0 --no-detect   # skip face detection (faster)
```

Press **Q** or **Esc** to quit.

---

## Emotion Classes

| ID | Label    |
|----|----------|
| 0  | angry    |
| 1  | disgust  |
| 2  | fear     |
| 3  | happy    |
| 4  | neutral  |
| 5  | sad      |
| 6  | surprise |

---

## Troubleshooting

| Error | Fix |
|-------|-----|
| `FileNotFoundError: model_weights.pth` | Ensure `models/model_weights.pth` exists at the project root, or pass `--weights` |
| `facenet-pytorch not installed` | `pip install facenet-pytorch` or use `--face-method haar` |
| `No face detected` | Inference falls back to the full image automatically |
| CUDA out of memory | Pass `--device cpu` |
| Slow on CPU | Use `--no-detect` in video mode |