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