🎭 Real-Time Face Recognition & System Unlock

An advanced Real-Time Face Recognition & Access Unlock System powered by deep learning embeddings (InsightFace) and a calibrated Support Vector Machine (SVM) classifier.

It detects faces from live webcam feeds, estimates age and gender, predicts recognition probabilities, and displays real-time access security status (UNLOCKED vs LOCKED).

---

🎯 Features

• 🟢 Real-Time Access Control: Instantly toggles STATUS: UNLOCKED (green corner HUD) when authorized user is detected, and STATUS: LOCKED (red corner HUD) for unknown individuals.
• 👤 Demographics & HUD Overlay: Live real-time age range and gender estimation for every detected face.
• 🧬 Deep Learning Embeddings: Extracts 512-dimensional facial feature vectors using InsightFace's buffalo_l architecture.
• ⚡ SVM Binary Classifier: Highly efficient Linear Support Vector Machine trained with calibrated probability output.
• 🔄 Automated Data Augmentation: Automatically generates 7+ variations per face photo (rotations, horizontal flips, HSV brightness shifts) so you only need 10-20 photos to achieve high accuracy.
• 📥 LFW Dataset Downloader: Built-in script to fetch and organize ~2000 negative face samples from the Labeled Faces in the Wild (LFW) dataset.
• 🎭 Faceless Privacy Mode: Optional mode covering faces with dynamic solid overlays—ideal for privacy-conscious video production or live streaming.

---

🏗️ System Architecture

                                  LIVE CAMERA FEED
                                         │
                                         ▼
                             InsightFace (Buffalo_L)
                                         │
                         ┌───────────────┴───────────────┐
                         ▼                               ▼
                 Face Detection               Demographics Extraction
                   & 512-D Vector               (Age & Gender Output)
                         │                               │
                         ▼                               │
                 Linear SVM Model                        │
               (Probability Score)                       │
                         │                               │
                         └───────────────┬───────────────┘
                                         ▼
                             Real-Time HUD Render Engine
                     [ STATUS: UNLOCKED / LOCKED | MATCH % ]

---

🚀 Quick Start Guide

1. Clone the Repository

git clone https://github.com/YOUR_USERNAME/face-recognition.git
cd face-recognition

2. Install Dependencies

Ensure Python 3.8+ is installed, then run:

pip install -r requirements.txt

3. Download Negative Background Dataset

Download ~2000 negative face samples from the LFW dataset (used to train the classifier on non-user faces):

python .prerun/download_lfw.py

4. Add Your Face Photos

Place 10-30 clear photos of your face inside the my_faces/ directory:

• Use standard formats (.jpg, .jpeg, .png).
• Include diverse lighting, angles, and expressions for best accuracy.

5. Train the Face Classifier

Run the training pipeline (applies data augmentation and builds your custom model):

python .prerun/train_model.py

This will save the trained model to .model/face_classifier.pkl.

6. Run Live System Unlock

Launch the main recognition system:

python main.py

Press q at any time to exit the camera feed.

---

⚙️ Configuration

Tuning Confidence Threshold

Adjust the authorization threshold in main.py:

CONFIDENCE_THRESHOLD = 0.85  # Default: 85% probability required for UNLOCKED

Threshold	Sensitivity Level	Recommended Use Case
0.90+	High Security	Strict unlock, avoids false positives
0.85	Balanced	Optimal for daily use
0.75	Lenient	Low light or extreme facial angles

Faceless Privacy Mode

To cover faces with solid color overlays instead of HUD wireframes (useful for streaming/tutorials):

In main.py:

FACELESS_MODE = True  # Set to True to hide face behind solid status fill

---

📁 Directory Structure

face-recognition/
├── main.py                    # Main real-time application & HUD system
├── requirements.txt           # Python library dependencies
├── .gitignore                 # Excludes models, datasets & virtual environments
├── README.md                  # Project documentation
│
├── my_faces/                  # User face images folder (Positive training set)
│   └── .gitkeep               # Keeps folder structure tracked in git
│
├── negative_faces/            # Non-user face dataset (Negative training set)
│   └── .gitkeep               # Automatically populated by download_lfw.py
│
├── .prerun/
│   ├── download_lfw.py        # Automated LFW negative dataset downloader
│   └── train_model.py         # Data augmentation & SVM training pipeline
│
└── .model/                    # Generated after running train_model.py (git-ignored)
    ├── face_classifier.pkl    # Trained SVM model binary
    └── embeddings_cache.pkl   # Fast cache for negative face embeddings

---

🛠️ GPU Acceleration (Optional)

For higher FPS on NVIDIA GPUs:

1. Uninstall CPU ONNX Runtime:

   pip uninstall onnxruntime
   

2. Install GPU ONNX Runtime:

   pip install onnxruntime-gpu
   

3. Update provider in main.py and .prerun/train_model.py:

   providers=['CUDAExecutionProvider', 'CPUExecutionProvider']
   

---

❓ FAQ & Troubleshooting

Q: "Model file not found" error when running main.py

You must train the model first! Run python .prerun/download_lfw.py, place face images in my_faces/, and execute python .prerun/train_model.py.

Q: Camera feed is laggy

Lower the detection size in main.py: change det_size=(640, 640) to det_size=(320, 320) or enable GPU acceleration.

Q: Can I train the system to recognize multiple authorized individuals?

Yes! Modify .prerun/train_model.py to use a multi-class classifier (e.g. svm.SVC with multi-class labels instead of binary 0/1 labels).

---

📄 License

This project is licensed under the MIT License.

---

🙏 Acknowledgments & Credits

• InsightFace for state-of-the-art face detection and embedding extraction.
• Scikit-learn for robust SVM classification models.
• LFW Dataset for negative facial benchmark samples.
• OpenCV for vision processing and rendering.