Face Recognition System

Real-time face detection and recognition system

한국어 문서

Project Overview

A system providing real-time face recognition through camera integration and a web-based dashboard.

Key Features

• Real-time camera integration
• Face recognition using Hugging Face models
• Web-based monitoring dashboard
• Face registration and management
• Multi-sample face matching for improved accuracy
• Real-time statistics (detected faces, recognized faces, FPS)

Tech Stack

• Backend: Python 3.9+, FastAPI, OpenCV
• ML: InsightFace (buffalo_l), PyTorch
• Frontend: React 19, Vite, Tailwind CSS, React Router
• Testing: Playwright E2E Testing
• DevOps: Git, GitHub

Documentation

• PRD (Product Requirements)
• Project Plan
• Learning Workbook - Technical learning guide for project managers
• API Guide - FastAPI server usage guide
• Troubleshooting Guide - Installation and execution issues

Project Structure

faceReco/
├── backend/                # Backend server
│   ├── app.py             # Main application
│   ├── models/            # ML model modules
│   │   ├── face_detection.py      # Haar Cascade face detection
│   │   ├── face_recognition.py    # InsightFace face recognition
│   │   └── face_database.py       # Face database management
│   ├── camera/            # Camera processing module
│   ├── api/               # API endpoints
│   ├── data/              # Face database
│   │   ├── face_database.json     # Metadata
│   │   ├── embeddings/            # Face embeddings (512-dim)
│   │   └── faces/                 # Face images
│   └── requirements.txt   # Python dependencies
├── frontend/              # Frontend (React + Vite)
│   ├── src/
│   │   ├── components/         # UI components
│   │   ├── pages/              # Pages (Dashboard, FaceRegistration, FaceList)
│   │   ├── services/           # API services
│   │   └── utils/              # Utilities
│   ├── tests/                  # Playwright E2E tests
│   └── package.json
├── docs/                  # Documentation
├── tests/                 # Test code
├── PRD.md                 # Product Requirements
├── PROJECT_PLAN.md        # Project Plan
└── README.md              # This file

Project Status

Current Status: Milestone 5 - Web Dashboard Development In Progress 🚧

Completed Tasks

Milestone 1: Initial Project Setup ✅

• GitHub repository creation
• Project directory structure setup
• Python virtual environment configuration
• Basic dependency package installation
• Documentation (PRD, PROJECT_PLAN, README)

Milestone 2: Camera Integration and Basic Face Detection ✅

• OpenCV camera handler implementation
• Real-time video stream processing
• Haar Cascade face detection implementation
• Face region bounding box display
• Unit test creation

Milestone 3: ML Model Integration ✅

• InsightFace buffalo_l model selection
• FaceRecognizer class implementation (face embedding extraction)
• FaceDatabase class implementation (face database management)
• Face registration feature implementation
• Face recognition and matching feature implementation
• Unit test creation

Milestone 4: Backend API Development ✅

• FastAPI project initialization
• API endpoint design and implementation
• CORS configuration
• Real-time video streaming API
• Face registration/query/deletion API
• API documentation (Swagger UI)
• Real-time statistics API

Milestone 5: Web Dashboard Development 🚧

• React + Vite frontend project initialization
• Basic layout structure (Header, Sidebar, Layout)
• Page components (Dashboard, FaceRegistration, FaceList)
• API client setup (Axios)
• Real-time camera monitoring with statistics
• Face registration page with camera capture
• Face list management with duplicate detection
• Playwright E2E testing setup
• Comprehensive testing and optimization

Next Steps

• Integration testing and performance optimization (Milestone 5)
• Deployment documentation and Docker containerization (Milestone 6)

Getting Started

Prerequisites

• Python 3.8 or higher
• Git
• Webcam (for camera features)
• Node.js 18+ (for frontend)

Installation

1. Clone Repository

   git clone https://github.com/quirinal36/faceReco.git
   cd faceReco

2. Create and Activate Python Virtual Environment

   # Create virtual environment
   python3 -m venv venv
   
   # Activate virtual environment (Linux/Mac)
   source venv/bin/activate
   
   # Activate virtual environment (Windows)
   venv\Scripts\activate

3. Install Dependencies

   cd backend
   
   # Option 1: Production environment (recommended)
   pip install -r requirements.txt
   
   # Option 2: Minimal install (for quick testing)
   pip install -r requirements-minimal.txt
   
   # Option 3: Development environment (for developers)
   pip install -r requirements-dev.txt

   Requirements File Descriptions:

   • requirements.txt - Production environment (full features)
   • requirements-minimal.txt - Minimal environment (fast install, limited features)
   • requirements-dev.txt - Development environment (includes testing, linting, documentation tools)

   Important: InsightFace installation issues may occur on Windows.

   • Recommended Solution: Refer to Solution 1 or 2 in Troubleshooting Guide
   • Install Visual Studio Build Tools or use Conda environment

4. Verify Installation

   # Check installed packages
   python test_installation.py

   Note: On first run, InsightFace buffalo_l model will be downloaded automatically (~600MB)

Running the Application

🚀 Quick Start (Recommended)

Method 1: Using npm scripts (Most convenient)

# Install frontend dependencies (first time only)
npm run install-all

# Run backend + frontend simultaneously
npm run dev

Method 2: Using run scripts

# Windows
start-dev.bat

# Linux/Mac
./start-dev.sh

After server starts:

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

---

Individual Execution (Manual)

Virtual environment activation required:

source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate     # Windows
cd backend

1. Face Registration (Add new faces)

python app.py --mode register --camera-id 0

• Spacebar: Capture face
• Enter name and press Enter
• q: Exit

2. Face Recognition (Real-time recognition)

python app.py --mode face_recognition --camera-id 0

• Registered faces: Green box + name + confidence
• Unregistered faces: Red box + "Unknown"
• q: Exit

3. Face Detection Demo (Haar Cascade)

python app.py --mode face_detection --camera-id 0

4. Camera Test

python app.py --mode camera --camera-id 0

5. API Server (FastAPI) 🆕

# Method 1: Using app.py
python app.py --mode server

# Method 2: Direct server.py execution
python server.py

After server starts:

• API Docs: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• Health Check: http://localhost:8000/api/health

API Endpoints:

• POST /api/face/register - Register face
• GET /api/faces/list - List registered faces
• DELETE /api/face/{id} - Delete face
• GET /api/camera/stream - Real-time video streaming
• GET /api/camera/stats - Real-time statistics
• POST /api/faces/merge/{name} - Merge duplicate faces

For detailed usage, see API Guide.

6. Individual Module Execution

# Test camera handler
python -m camera.camera_handler

# Face detection demo
python -m models.face_detection

# Face recognition module test
python -m models.face_recognition

Notes:

• Webcam access permission required
• Press 'q' to exit the program
• Camera access may be restricted in WSL environments

Development Environment Setup

1. Code Formatting

   # Code formatting with Black
   black backend/

2. Running Tests

   # Backend tests with pytest
   pytest tests/
   
   # Frontend E2E tests with Playwright
   cd frontend
   npx playwright test

Development Guide

Development Workflow

1. Create or select an issue
2. Create new branch (git checkout -b feature/issue-name)
3. Write code and tests
4. Commit and push
5. Create Pull Request

Coding Style

• Python: Follow PEP 8, use Black formatter
• Write docstrings for functions and classes
• Write test code (recommended)
• React: Use functional components with hooks

Testing

• Backend: pytest for unit tests
• Frontend: Playwright for E2E tests
• Test coverage goal: >80%

GitHub Issues and Milestones

Project progress can be tracked at GitHub Issues.

Milestones

• Milestone 1: Initial Project Setup ✅
• Milestone 2: Camera Integration and Basic Face Detection ✅
• Milestone 3: ML Model Integration ✅
• Milestone 4: Backend API Development ✅
• Milestone 5: Web Dashboard Development 🚧
• Milestone 6: Integration and Deployment Preparation

Screenshots

Dashboard - Real-time Face Monitoring

The main dashboard provides real-time face detection and recognition with live statistics including detected faces count, recognized faces count, and processing speed (FPS).

Face Registration

Register new faces through the web interface with camera capture and multi-language support.

Face List Management

View and manage all registered faces with options for deletion and duplicate detection.

Features

Multi-Sample Face Recognition

• Register multiple photos of the same person for improved accuracy
• Automatic duplicate detection and merging
• Uses maximum similarity among all samples for recognition

Real-time Statistics Dashboard

• Live face detection count
• Recognition success rate
• Processing speed (FPS)
• Updated every second

Comprehensive Testing

• Playwright E2E tests for frontend
• Webcam mocking for testing without hardware
• API integration tests

Internationalization (i18n)

• Multi-language support (English/Korean)
• Easy language switching
• Localized UI components

How to Use

1. Initial Setup

1. Clone the repository and install dependencies (see Installation)
2. Start both backend and frontend servers:

   npm run dev

3. Access the web dashboard at http://localhost:5173

2. Registering Faces

1. Navigate to Face Registration page from the sidebar
2. Allow camera access when prompted
3. Position your face in the camera view
4. Click Capture button to take a photo
5. Enter a name for the person
6. Click Register to save the face

Tips:

• Ensure good lighting for better recognition
• Capture multiple angles for improved accuracy
• Keep your face centered in the frame

3. Monitoring Dashboard

1. Go to the Dashboard page
2. The system will automatically start detecting and recognizing faces
3. View real-time statistics:
   • Detected Faces: Total faces detected in the current frame
   • Recognized Faces: Number of faces matched with registered persons
   • FPS: Processing speed in frames per second

Camera Feed:

• Green boxes: Recognized faces (with name and confidence score)
• Red boxes: Unregistered/unknown faces

4. Managing Registered Faces

1. Navigate to Face List page
2. View all registered faces with their details
3. Use the Delete button to remove faces
4. System automatically detects duplicate entries

5. Testing Without a Camera

The system includes Playwright E2E tests that work without physical hardware:

cd frontend
npm test

6. API Integration

For developers integrating with the backend API:

• API Documentation: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• See API Guide for detailed endpoint documentation

License

TBD

---

Last Updated: 2026-02-09