Create comprehensive README with video preview, technology stack, and usage guide
This commit is contained in:
Cris Charles committed
1 parent
8f2b9672ec
commit
dbfc5d5a34
1 file changed
+200
-3
@@ -1,5 +1,202 @@
|
|||||||
# Utut
|
# 🎯 Face Recognition System
|
||||||
|
|
||||||
hahahaha
|
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.
|
||||||
|
|
||||||
https://youtu.be/mfxB-nz5uZc?si=uCxKkgvkQgT33Dtd
|
---
|
||||||
|
|
||||||
|
## 📹 Demo Video
|
||||||
|
|
||||||
|
[](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
|
||||||
Reference in new issue
Block a user