title	FaceVision AI
emoji	🧠
colorFrom	indigo
colorTo	purple
sdk	docker
app_port	7860
pinned	false

🧠 FaceVision AI

Real-time face detection, recognition & analytics — in a premium, glassmorphic interface.

Built with React 19 · TypeScript · Vite · Tailwind CSS · Framer Motion on the front and FastAPI · OpenCV on the back.

---

✨ Overview

FaceVision AI is a full-stack, production-quality web application that detects and recognises faces from images and live webcam streams. It ships with a marketing landing page, an analytics dashboard, and dedicated tools for detection, recognition, live tracking, history and settings — all wrapped in a fast, animated, fully responsive dark/light UI.

🚀 Features

• Face Detection — drag & drop an image, get bounding boxes, pixel coordinates, per-face confidence and processing time, plus a downloadable annotated image.
• Face Recognition — compare a known face against a target image with a similarity percentage and a clear match / no-match verdict.
• Live Webcam — real-time detection over your camera feed with a canvas overlay, live FPS and latency counters, and start/stop controls.
• Analytics Dashboard — stat cards, a smooth activity chart, a recognition donut, recent activity and quick actions.
• History — search, filter, delete and export (CSV / JSON) every result.
• Settings — theme switch, runtime backend URL, confidence threshold, output toggles and profile — all persisted locally.
• Polish — glassmorphism, gradients, Framer Motion animations, skeleton loaders, toast notifications and a mobile-first responsive layout.

🧱 Tech stack

Layer	Technologies
Frontend	React 19, TypeScript, Vite, Tailwind CSS v4, Framer Motion, Lucide, Axios, React Router
Backend	FastAPI, Uvicorn, OpenCV, NumPy, Pydantic, SQLite (+ optional face_recognition)

📁 Project structure

FaceVision-AI/
├── frontend/                 # React + TypeScript + Vite app
│   └── src/
│       ├── components/       # ui · landing · dashboard · shared
│       ├── pages/            # Landing · Dashboard · Detect · Recognize · Webcam · History · Settings
│       ├── services/         # axios api layer + faceService
│       ├── context/          # Settings + Toast providers
│       ├── hooks/            # useSettings · useToast · useHealth
│       ├── lib/              # utilities
│       └── types/            # shared TypeScript interfaces
├── backend/                  # FastAPI service (see backend/README.md)
│   └── app/
│       ├── routers/          # detect · recognize · webcam · history · health
│       ├── services/         # detector · recognizer · history
│       ├── models/           # Pydantic schemas
│       ├── core/ · utils/    # logging, runtime, image helpers
│       └── main.py
└── README.md

🛠 Getting started

1. Backend

cd backend
python -m venv venv
# Windows: venv\Scripts\activate   |   macOS/Linux: source venv/bin/activate
pip install -r requirements.txt
python run.py            # → http://localhost:8000  (docs at /docs)

2. Frontend

cd frontend
npm install
cp .env.example .env     # optional — defaults to http://localhost:8000
npm run dev              # → http://localhost:5173

Open http://localhost:5173, head to the dashboard, and run your first detection. You can change the backend URL anytime from the in-app Settings page.

🔌 API

Method	Endpoint	Purpose
GET	/api/health	Status + model capabilities
POST	/api/detect	Detect faces in an image
POST	/api/recognize	Compare two faces
POST	/api/webcam	Fast per-frame detection
GET	/api/history	List history
DELETE	/api/history/{id}	Delete a record
DELETE	/api/history	Clear history
GET	/api/stats	Dashboard statistics

⚙️ Configuration

• Frontend — VITE_API_URL (.env) sets the default backend URL; the Settings page overrides it at runtime (stored in localStorage).
• Backend — environment variables prefixed with FV_ (see backend/.env.example).

🎯 Accuracy notes

The backend runs with zero external model downloads using OpenCV's Haar cascade. For higher accuracy you can, optionally:

• Add the ResNet-10 SSD model files to backend/models/ for DNN detection.
• pip install face_recognition for identity-grade recognition (dlib embeddings).

Both upgrades are picked up automatically — see backend/models/README.md.

📦 Build for production

cd frontend && npm run build     # outputs to frontend/dist

Serve frontend/dist from any static host and point it at your deployed FastAPI backend via VITE_API_URL or the Settings page.

📄 License

MIT — free to use, modify and build upon.