Skip to content

README.md

Latest commit

 

History

History
99 lines (61 loc) · 3.07 KB

README.md

File metadata and controls

99 lines (61 loc) · 3.07 KB

Smart Needle 📍

AI-Powered Face Recognition for Student Attendance. Local. Fast. Private.

Smart Needle is a 100% local, privacy-first facial similarity engine that registers student identities, encodes them into deep face embeddings, and automatically detects who appears in any class or group photo — no cloud, no external APIs, no data leaving your machine.

✨ Key Features

  • 🔒 Privacy First — All face detection and embedding runs locally on your device. Your photos never leave your machine.
  • 🧠 ArcFace Embeddings — Powered by InsightFace's buffalo_l model for stable 512-dimensional face vectors with strong identity separation.
  • ⚡ Smart Rebuild — Hash-based change detection means only modified or new identity folders get reprocessed. Adding one student? Only that student gets recalculated.
  • 👥 Many-to-Many Detection — Upload a class photo and get back a structured report of which students are present, with confidence scores and bounding boxes.
  • 🎚️ Threshold Slider — Adjust match sensitivity in real time. Lower it for noisy group photos, raise it for stricter matching.
  • 🖼️ Annotated Output — Every result image is saved with bounding boxes and name labels drawn on detected faces.

🛠️ Tech Stack

  • Backend: Python (FastAPI, InsightFace, OpenCV, Uvicorn)
  • Face Model: ArcFace buffalo_l via ONNX Runtime (CPU & GPU)
  • Embedding Storage: Smart Pickle (hash-tracked, incremental)
  • Frontend: Single-file HTML/CSS/JS dashboard — no build step required

🚀 Quick Start

Prerequisites

  • Python 3.9–3.11
  • pip or conda

1. Clone the repo

git clone https://github.com/UnityAppSuite/Smart-Needle.git
cd Smart-Needle

2. Set up the backend

cd backend
python -m venv venv

# Activate (Windows)
venv\Scripts\activate

# Activate (Mac/Linux)
source venv/bin/activate

pip install -r requirements.txt

First run downloads the buffalo_l model (~500MB) automatically. Subsequent starts take ~10 seconds.

3. Configure your paths

Open backend/app/core/config.py and set your base path:

_BACKEND = r"C:\path\to\Smart-Needle\backend"   # Windows
SIMILARITY_THRESHOLD = 0.30

4. Start the API

uvicorn main:app --reload --port 8000

5. Open the UI

In a second terminal, from the project root:

python -m http.server 5500

Open http://localhost:5500/smart-needle-ui.html in Chrome or Edge.

📖 Usage Guide

  1. Add References — Create one folder per student inside backend/app/data/reference/. Name each folder with the student's ID or name and put their photos inside.

  2. Build Embeddings — Go to Dashboard → ⚡ Smart Rebuild. The engine processes only new or changed folders.

  3. Recognize Faces — Go to Recognize, upload any scene image (noisy, multi-face, crowded), and see every detected face matched to an identity.

  4. Search by Person — Go to Search, pick a student name, and find every image in your collection where that student appears.