{"id":27857326,"url":"https://github.com/jvtesteves/face_recognition_system","last_synced_at":"2025-06-23T00:37:04.975Z","repository":{"id":290572864,"uuid":"974901538","full_name":"jvtesteves/face_recognition_system","owner":"jvtesteves","description":"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.”","archived":false,"fork":false,"pushed_at":"2025-04-29T13:40:50.000Z","size":14,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-04T13:17:45.796Z","etag":null,"topics":["computer-vision","deep-learning","face-detection","face-embedding","face-recognition","facenet","machine-learning","mtcnn","opencv","python","pytorch","real-time"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jvtesteves.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-29T13:29:24.000Z","updated_at":"2025-04-30T02:01:23.000Z","dependencies_parsed_at":"2025-04-29T14:47:49.907Z","dependency_job_id":"d2998188-9eda-423a-b36f-a15148770bad","html_url":"https://github.com/jvtesteves/face_recognition_system","commit_stats":null,"previous_names":["jvtesteves/face_recognition_system"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jvtesteves/face_recognition_system","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jvtesteves%2Fface_recognition_system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jvtesteves%2Fface_recognition_system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jvtesteves%2Fface_recognition_system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jvtesteves%2Fface_recognition_system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jvtesteves","download_url":"https://codeload.github.com/jvtesteves/face_recognition_system/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jvtesteves%2Fface_recognition_system/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261391048,"owners_count":23151660,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["computer-vision","deep-learning","face-detection","face-embedding","face-recognition","facenet","machine-learning","mtcnn","opencv","python","pytorch","real-time"],"created_at":"2025-05-04T13:17:43.853Z","updated_at":"2025-06-23T00:36:59.929Z","avatar_url":"https://github.com/jvtesteves.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Face Recognition System\n\nA complete real-time face detection and recognition system built from scratch with Python, OpenCV and `facenet-pytorch`. Features:\n\n- Multi-face detection in live video (webcam)  \n- Automatic face crop capture for training  \n- Embedding extraction using a pretrained FaceNet (InceptionResnetV1)  \n- Real-time recognition by comparing embeddings against a template database  \n- “Known” vs. “Unknown” classification with adjustable threshold  \n\n---\n\n## 📁 Directory Structure\n\n```\nface_recognition_system/\n│\n├── dataset/                  # Generated at runtime (not committed)\n│   └── joao/                 # Training images per identity\n│\n├── detectors/                # (Optional) Custom detection modules\n├── embeddings/               # (Optional) Custom embedding/extraction modules\n├── utils/                    # (Optional) Helper functions (logging, I/O, etc.)\n│\n├── .gitignore                # Ignores venv, dataset, embeddings, caches\n├── requirements.txt          # Project dependencies\n├── capture_faces.py          # Capture face crops from original frame\n├── detect_faces_mtcnn.py     # Real-time detection test with MTCNN\n├── extract_embeddings.py     # Extracts and saves embeddings to `embeddings.pt`\n├── recognize_faces.py        # Real-time recognition using stored templates\n└── README.md                 # This file\n```\n\n---\n\n## ⚙️ Prerequisites\n\n- Python 3.8+  \n- Git  \n- Integrated or USB webcam  \n- (Optional) CUDA-enabled GPU for faster inference  \n\n### Dependencies\n\n```bash\npip install -r requirements.txt\n```\n\nYour `requirements.txt` might include:\n\n```text\nopencv-python\ntorch\ntorchvision\nfacenet-pytorch\npillow\n```\n\n---\n\n## 🚀 Installation Guide\n\n1. **Clone the repo**  \n   ```bash\n   git clone https://github.com/your-username/face_recognition_system.git\n   cd face_recognition_system\n   ```\n\n2. **Create and activate a virtual environment**  \n   ```bash\n   python -m venv .venv\n   source .venv/bin/activate    # macOS/Linux\n   .venv\\Scripts\\activate       # Windows\n   ```\n\n3. **Install dependencies**  \n   ```bash\n   pip install -r requirements.txt\n   ```\n\n4. **macOS SSL certificates** (if you see SSL errors when downloading weights)  \n   - Run **Install Certificates.command** located in `/Applications/Python 3.x/`.\n\n---\n\n## 🛠️ Usage\n\n### 1. Test MTCNN detection\n\n```bash\npython detect_faces_mtcnn.py\n```\n\nOpens your webcam and draws green boxes around all detected faces.\n\n---\n\n### 2. Capture training images\n\n```bash\npython capture_faces.py\n```\n\n- Captures 20 face crops (160×160) from the webcam into `dataset/\u003cidentity\u003e/`.  \n- Press `ESC` to stop early.\n\n---\n\n### 3. Extract embeddings\n\n```bash\npython extract_embeddings.py\n```\n\n- Loads images from `dataset/` and extracts 512-dim embeddings with FaceNet.  \n- Saves a dictionary of tensors to `embeddings.pt`.\n\n---\n\n### 4. Real-time recognition\n\n```bash\npython recognize_faces.py\n```\n\n- Loads `embeddings.pt`, computes the average template per identity.  \n- Detects faces, extracts embeddings and compares to templates.  \n- Displays identity (green) or “Unknown” (red) with distance score.\n\n**Sensitivity threshold**  \nEdit at the top of `recognize_faces.py`:\n\n```python\nthreshold = 0.8  # 0.6 = stricter, 1.0 = more lenient\n```\n\n---\n\n## 🔧 How to Add New Identities\n\n1. Change `person_name` in `capture_faces.py` (and create `dataset/\u003cname\u003e/`).  \n2. Run the script to capture faces for the new identity.  \n3. Run `extract_embeddings.py` again to update `embeddings.pt`.  \n4. Now `recognize_faces.py` will recognize the new name as well.\n\n---\n\n## 💡 Best Practices \u0026 Tips\n\n- **Alignment**: use facial landmarks (eyes, nose) to align and normalize faces before embedding.  \n- **Cosine similarity**: swap Euclidean distance for `F.cosine_similarity()` for greater robustness.  \n- **Logging**: record recognition events to CSV for later analysis.  \n- **GUI**: consider Streamlit or Flask for a simple web interface.\n\n---\n\n## 📄 License\n\nThis project is licensed under the **MIT License**. See [LICENSE](LICENSE) for details.\n\n---\n\n## 🤝 Contributing\n\n1. Fork this repository.  \n2. Create a feature branch: `git checkout -b my-feature`.  \n3. Commit your changes: `git commit -m \"Add my feature\"`.  \n4. Push to the branch: `git push origin my-feature`.  \n5. Open a Pull Request.\n\n---\n\n## 📫 Contact\n\nJoão Victor Tavares Esteves  \n✉️ [joaovtesteves2002@gmail.com](mailto:joaovtesteves2002@gmail.com)  \n🌐 [GitHub](https://github.com/jvtesteves)  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjvtesteves%2Fface_recognition_system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjvtesteves%2Fface_recognition_system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjvtesteves%2Fface_recognition_system/lists"}