README.md

metadata

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

   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:

   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

   python run.py
   

   Or directly with Uvicorn:

   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.

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