https://github.com/jvtesteves/face_recognition_system
Real-time face detection and recognition system built from scratch in Python. Utilizes MTCNN for multi-face detection, FaceNet (InceptionResnetV1) for embedding extraction, and Euclidean distance for comparison. Allows training new identities via webcam captures and labels faces as known or “Unknown.”
https://github.com/jvtesteves/face_recognition_system
computer-vision deep-learning face-detection face-embedding face-recognition facenet machine-learning mtcnn opencv python pytorch real-time
Last synced: 4 months ago
JSON representation
Real-time face detection and recognition system built from scratch in Python. Utilizes MTCNN for multi-face detection, FaceNet (InceptionResnetV1) for embedding extraction, and Euclidean distance for comparison. Allows training new identities via webcam captures and labels faces as known or “Unknown.”
- Host: GitHub
- URL: https://github.com/jvtesteves/face_recognition_system
- Owner: jvtesteves
- Created: 2025-04-29T13:29:24.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2025-04-29T13:40:50.000Z (5 months ago)
- Last Synced: 2025-05-04T13:17:45.796Z (5 months ago)
- Topics: computer-vision, deep-learning, face-detection, face-embedding, face-recognition, facenet, machine-learning, mtcnn, opencv, python, pytorch, real-time
- Language: Python
- Homepage:
- Size: 13.7 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Face Recognition System
A complete real-time face detection and recognition system built from scratch with Python, OpenCV and `facenet-pytorch`. Features:
- Multi-face detection in live video (webcam)
- Automatic face crop capture for training
- Embedding extraction using a pretrained FaceNet (InceptionResnetV1)
- Real-time recognition by comparing embeddings against a template database
- “Known” vs. “Unknown” classification with adjustable threshold---
## 📁 Directory Structure
```
face_recognition_system/
│
├── dataset/ # Generated at runtime (not committed)
│ └── joao/ # Training images per identity
│
├── detectors/ # (Optional) Custom detection modules
├── embeddings/ # (Optional) Custom embedding/extraction modules
├── utils/ # (Optional) Helper functions (logging, I/O, etc.)
│
├── .gitignore # Ignores venv, dataset, embeddings, caches
├── requirements.txt # Project dependencies
├── capture_faces.py # Capture face crops from original frame
├── detect_faces_mtcnn.py # Real-time detection test with MTCNN
├── extract_embeddings.py # Extracts and saves embeddings to `embeddings.pt`
├── recognize_faces.py # Real-time recognition using stored templates
└── README.md # This file
```---
## ⚙️ Prerequisites
- Python 3.8+
- Git
- Integrated or USB webcam
- (Optional) CUDA-enabled GPU for faster inference### Dependencies
```bash
pip install -r requirements.txt
```Your `requirements.txt` might include:
```text
opencv-python
torch
torchvision
facenet-pytorch
pillow
```---
## 🚀 Installation Guide
1. **Clone the repo**
```bash
git clone https://github.com/your-username/face_recognition_system.git
cd face_recognition_system
```2. **Create and activate a virtual environment**
```bash
python -m venv .venv
source .venv/bin/activate # macOS/Linux
.venv\Scripts\activate # Windows
```3. **Install dependencies**
```bash
pip install -r requirements.txt
```4. **macOS SSL certificates** (if you see SSL errors when downloading weights)
- Run **Install Certificates.command** located in `/Applications/Python 3.x/`.---
## 🛠️ Usage
### 1. Test MTCNN detection
```bash
python detect_faces_mtcnn.py
```Opens your webcam and draws green boxes around all detected faces.
---
### 2. Capture training images
```bash
python capture_faces.py
```- Captures 20 face crops (160×160) from the webcam into `dataset//`.
- Press `ESC` to stop early.---
### 3. Extract embeddings
```bash
python extract_embeddings.py
```- Loads images from `dataset/` and extracts 512-dim embeddings with FaceNet.
- Saves a dictionary of tensors to `embeddings.pt`.---
### 4. Real-time recognition
```bash
python recognize_faces.py
```- Loads `embeddings.pt`, computes the average template per identity.
- Detects faces, extracts embeddings and compares to templates.
- Displays identity (green) or “Unknown” (red) with distance score.**Sensitivity threshold**
Edit at the top of `recognize_faces.py`:```python
threshold = 0.8 # 0.6 = stricter, 1.0 = more lenient
```---
## 🔧 How to Add New Identities
1. Change `person_name` in `capture_faces.py` (and create `dataset//`).
2. Run the script to capture faces for the new identity.
3. Run `extract_embeddings.py` again to update `embeddings.pt`.
4. Now `recognize_faces.py` will recognize the new name as well.---
## 💡 Best Practices & Tips
- **Alignment**: use facial landmarks (eyes, nose) to align and normalize faces before embedding.
- **Cosine similarity**: swap Euclidean distance for `F.cosine_similarity()` for greater robustness.
- **Logging**: record recognition events to CSV for later analysis.
- **GUI**: consider Streamlit or Flask for a simple web interface.---
## 📄 License
This project is licensed under the **MIT License**. See [LICENSE](LICENSE) for details.
---
## 🤝 Contributing
1. Fork this repository.
2. Create a feature branch: `git checkout -b my-feature`.
3. Commit your changes: `git commit -m "Add my feature"`.
4. Push to the branch: `git push origin my-feature`.
5. Open a Pull Request.---
## 📫 Contact
João Victor Tavares Esteves
✉️ [joaovtesteves2002@gmail.com](mailto:joaovtesteves2002@gmail.com)
🌐 [GitHub](https://github.com/jvtesteves)