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