---
title: EduSync Face Recognition
emoji: 👤
colorFrom: indigo
colorTo: purple
sdk: docker
sdk_version: "20.10.12"
python_version: "3.13"
app_file: run.py
pinned: false
---

# Face Recognition Attendance Service

Production-ready face recognition API using FastAPI, MediaPipe, and InsightFace (ArcFace ONNX).
Optimized for CPU usage and fast inference (<100ms per face).

## Architecture

- **FastAPI**: High-performance async web framework.
- **MediaPipe**: Lightweight, real-time 468-point 3D Face Mesh for precise 6-point detection & alignment.
- **InsightFace (ArcFace)**: State-of-the-art face recognition model (ResNet50 or MobileFaceNet) running on ONNX Runtime.
- **MongoDB**: For storing students and embeddings.
- **Docker**: Containerized deployment.

## Prerequisites

- Python 3.9+
- MongoDB instance (Local or Atlas)

## Setup

1. **Install Dependencies**
   ```bash
   pip install -r requirements.txt
   ```

2. **Download Model**
   The application requires the ArcFace ONNX model (`w600k_mbf.onnx` or `w600k_r50.onnx`).
   Run the setup script (if provided) or download manually:
   - Create directory `app/models/`
   - Download `w600k_mbf.onnx` (MobileFaceNet, ~3MB) or `w600k_r50.onnx` (ResNet50, ~170MB).
   - Update `.env` with the correct `MODEL_PATH`.
   
   *Tip: You can extract `w600k_mbf.onnx` from the `buffalo_s.zip` in InsightFace model zoo.*

3. **Configure Environment**
   Rename `.env.example` (if exists) or create `.env`:
   ```ini
   MONGODB_URL=mongodb://localhost:27017
   DB_NAME=sih_attendance_db
   COLLECTION_NAME=student_faces
   FACE_SIMILARITY_THRESHOLD=0.5
   MODEL_PATH=app/models/w600k_mbf.onnx
   ```

4. **Run Server**
   ```bash
   python run.py
   ```
   Or directly with Uvicorn:
   ```bash
   uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
   ```

## API Endpoints

### 1. Register Student
**POST** `/api/v1/register`
- **Form Data**:
  - `student_id`: String
  - `files`: List of images (5-10 recommended)
- **Process**: Detects faces, averages embeddings, saves to DB.

### 2. Mark Attendance
**POST** `/api/v1/mark-attendance`
- **Form Data**:
  - `file`: Single image
- **Process**: Detects face, compares with DB, returns student if confidence > threshold.

## Deployment (Render/Docker)

### Dockerfile
Use the provided `Dockerfile` to build the image.
```bash
docker build -t face-api .
docker run -p 8000:8000 face-api
```

### Render.com
1. Connect Repo.
2. Select Docker runtime.
3. Set Environment Variables (`MONGODB_URL`).
4. Ensure the model file is included in the repo or downloaded during build (e.g., via `wget` in Dockerfile).

## Performance Notes
- **Resize Strategy**: Images are resized to 320x240 for detection speed.
- **Global Model**: ONNX session is initialized once at startup.
- **Concurrency**: FastAPI handles async requests; CPU-bound inference runs in thread pool (default FastAPI behavior for sync routes) or you can offload to `run_in_threadpool`.
  *Current implementation uses standard async def but blocking calls for inference. For high load, consider `def` routes or `await run_in_threadpool`.*

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference