# 🎯 Face Recognition System

A high-performance real-time face recognition application built with **MediaPipe**, **DeepFace**, and **OpenCV**. Optimized for speed with threading to maintain smooth video streaming while performing face detection and recognition in the background.

---

## 📹 Demo Video

[![Face Recognition Demo](https://img.youtube.com/vi/mfxB-nz5uZc/maxresdefault.jpg)](https://youtu.be/mfxB-nz5uZc?si=uCxKkgvkQgT33Dtd)

**Watch the full demo:** [YouTube - Face Recognition Demo](https://youtu.be/mfxB-nz5uZc?si=uCxKkgvkQgT33Dtd)

---

## 🚀 Features

- **Real-Time Face Detection**: Runs at 60 FPS using MediaPipe's BlazeFace model
- **Asynchronous Recognition**: Non-blocking face identification using threading
- **Fast Face Matching**: ArcFace model for accurate face comparison
- **Smooth UI**: Instant visual feedback with bounding boxes and FPS counter
- **Unknown Face Detection**: Displays "Unknown" for unrecognized faces

---

## 🛠️ Technology Stack

### Core Libraries

| Technology | Purpose |
|-----------|---------|
| **MediaPipe** | High-speed face detection using BlazeFace model |
| **DeepFace** | Face recognition and matching with ArcFace |
| **OpenCV (cv2)** | Video capture and real-time frame processing |
| **TensorFlow** | Deep learning framework for neural networks |
| **Keras** | High-level neural networks API |
| **Threading** | Asynchronous face recognition to prevent video lag |

### Additional Dependencies

| Package | Version | Purpose |
|---------|---------|---------|
| NumPy | ≥1.14.0 | Numerical computing |
| Pandas | ≥0.23.4 | Data manipulation |
| Pillow | ≥5.2.0 | Image processing |
| MTCNN | ≥0.1.0 | Face detection alternative |
| RetinaFace | ≥0.0.14 | Enhanced face detection |
| Flask | ≥1.1.2 | Web API framework |
| Flask-CORS | ≥4.0.1 | Cross-origin resource sharing |
| Gunicorn | ≥20.1.0 | WSGI HTTP Server |
| Python-dotenv | ≥1.0.1 | Environment variable management |

---

## 📋 Requirements

- **Python 3.11** (tested on Python 3.11)
- **Webcam/Camera** for real-time capture
- **Trained Face Database**: Store face images in `known_faces/` directory

---

## ⚙️ Installation

### 1. Clone the Repository
```bash
git clone https://github.com/ssbg04/facerecog.git
cd facerecog
```

### 2. Create Virtual Environment
```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

### 3. Install Dependencies
```bash
pip install -r requirements.txt
```

### 4. Download MediaPipe Model
The BlazeFace model file (`blaze_face_short_range.tflite`) needs to be in the project root directory. Download from:
- [MediaPipe Model Zoo](https://developers.google.com/mediapipe/solutions/vision/face_detector)

---

## 🏃 Usage

### Basic Usage
```bash
python app.py
```

The application will:
1. Open your webcam
2. Display a window titled "Smooth Face Recognition"
3. Detect faces in real-time
4. Identify known faces from the database
5. Show FPS counter in the top-left corner

**Press `Q` to quit**

### Prepare Your Face Database

Create a `known_faces/` directory and organize it as follows:
```
known_faces/
├── person1.jpg
├── person2.jpg
├── john_doe.jpg
└── ...
```

The system extracts names from filenames (before the file extension).

---

## 🎨 How It Works

### Architecture

```
Input Frame
    ↓
[Detection] ← MediaPipe (60 FPS) - Detects face locations
    ↓
[Threading] ← Async Recognition - Doesn't block video
    ↓
[Recognition] ← DeepFace/ArcFace - Identifies face
    ↓
[UI Render] ← OpenCV - Draws bounding box + name
    ↓
Display Output (Smooth Video Stream)
```

### Key Optimizations

1. **High-Speed Detection**: MediaPipe's lightweight BlazeFace runs at 60 FPS
2. **Async Processing**: Face recognition runs on a separate thread
3. **Early Stopping**: Only recognizes when a new face is detected
4. **Efficient Cropping**: Uses `enforce_detection=False` for faster matching

---

## 📊 Performance

- **Detection FPS**: ~60 FPS
- **Recognition Time**: ~100-500ms (depends on database size)
- **Smooth Video**: Yes - threading prevents frame drops

---

## 🔧 Configuration

Edit the following variables in `app.py`:

```python
DB_PATH = "known_faces"              # Path to face database
MODEL_PATH = 'blaze_face_short_range.tflite'  # MediaPipe model
```

---

## 🐛 Troubleshooting

| Issue | Solution |
|-------|----------|
| Model file not found | Download `blaze_face_short_range.tflite` to project root |
| Webcam not working | Check camera permissions or try `cv2.VideoCapture(1)` |
| Slow performance | Reduce image resolution or database size |
| "Unknown" for known faces | Verify image quality and lighting in database |

---

## 📝 License

No specific license specified. Please check the repository for details.

---

## 👤 Author

**ssbg04** - [GitHub Profile](https://github.com/ssbg04)

---

## 🤝 Contributing

Feel free to fork, modify, and submit pull requests!

---

## 📚 References

- [MediaPipe Face Detection](https://developers.google.com/mediapipe/solutions/vision/face_detector)
- [DeepFace GitHub](https://github.com/serengp/deepface)
- [OpenCV Documentation](https://docs.opencv.org/)
- [TensorFlow Documentation](https://www.tensorflow.org/)

---

**Last Updated**: June 2026 | **Status**: Active Development