README.md

metadata

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

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

---

Quick Start — Python API

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

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

# 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

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