{"id":28452589,"url":"https://github.com/coderkun12/real-time-face-detection","last_synced_at":"2025-07-02T04:31:07.369Z","repository":{"id":295757293,"uuid":"991142701","full_name":"coderkun12/Real-Time-Face-Detection","owner":"coderkun12","description":"This is a project that creates a real-time face detector. It uses face-embeddings and cosine similarity to detect faces real-time.","archived":false,"fork":false,"pushed_at":"2025-05-27T07:34:57.000Z","size":14,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-06T18:12:07.890Z","etag":null,"topics":["artificial-intelligence","cosine-similarity","face-embedding","face-recognition","machine-learning","object-detection","opencv","tkinter"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coderkun12.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-05-27T07:29:03.000Z","updated_at":"2025-05-27T09:20:00.000Z","dependencies_parsed_at":"2025-05-27T08:51:50.644Z","dependency_job_id":null,"html_url":"https://github.com/coderkun12/Real-Time-Face-Detection","commit_stats":null,"previous_names":["coderkun12/real-time-face-detection"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/coderkun12/Real-Time-Face-Detection","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderkun12%2FReal-Time-Face-Detection","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderkun12%2FReal-Time-Face-Detection/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderkun12%2FReal-Time-Face-Detection/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderkun12%2FReal-Time-Face-Detection/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coderkun12","download_url":"https://codeload.github.com/coderkun12/Real-Time-Face-Detection/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderkun12%2FReal-Time-Face-Detection/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263074392,"owners_count":23409753,"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":["artificial-intelligence","cosine-similarity","face-embedding","face-recognition","machine-learning","object-detection","opencv","tkinter"],"created_at":"2025-06-06T18:11:58.140Z","updated_at":"2025-07-02T04:31:07.353Z","avatar_url":"https://github.com/coderkun12.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stabilized Face Recognition System\n\nThis Python project implements a real-time face recognition system with enhanced stability and accuracy. It leverages **OpenCV** for video capture and basic face detection, **DeepFace** for robust face encoding, and a custom **FaceTracker** class for smoothing and stabilizing face detections across frames. The system can learn new faces interactively and stores known face data for future recognition.\n\n---\n\n## Features\n\n* **Real-time Face Detection:** Utilizes Haar Cascades with optimized parameters for robust initial face detection.\n* **Face Tracking and Stabilization:** A custom `FaceTracker` class smooths bounding box movements and increases confidence in detected faces over multiple frames, reducing jitters and false positives.\n* **Deep Learning-based Face Recognition:** Employs **DeepFace** (specifically the FaceNet model) to generate high-dimensional face embeddings for accurate recognition.\n* **Interactive Unknown Face Learning:** When an unknown, stable face is detected, a pop-up dialog (Tkinter) prompts the user to enter the person's name, allowing for on-the-fly enrollment.\n* **Persistent Data Storage:** Known face encodings and names are saved using `pickle` and `json` files, respectively, ensuring that learned faces are remembered across sessions.\n* **Recognition Caching:** Caches recognition results for stable faces to avoid redundant processing, improving performance.\n* **Visual Feedback:** Displays bounding boxes, recognized names, confidence levels, and stability indicators on the live video feed.\n\n---\n\n## Prerequisites\n\nBefore running the system, ensure you have the following installed:\n\n* Python 3.7+\n* OpenCV\n* DeepFace\n* TensorFlow (a backend for DeepFace)\n* Scikit-learn (for `cosine_similarity`)\n* Tkinter (usually comes pre-installed with Python)\n\nYou can install the necessary Python packages using pip:\n\n```bash\npip install opencv-python deepface tensorflow scikit-learn\n```\n\n**Note:** DeepFace can be resource-intensive. A GPU can significantly speed up the embedding generation process if TensorFlow is configured to use it.\n\n---\n\n## How to Run\n\n1.  **Save the Code:** Save the provided Python code as a `.py` file (e.g., `face_recognition_system.py`).\n2.  **Run from Terminal:** Open your terminal or command prompt, navigate to the directory where you saved the file, and run:\n\n    ```bash\n    python face_recognition_system.py\n    ```\n3.  **Interact:**\n    * The system will start capturing video from your default webcam.\n    * Faces will be detected and tracked.\n    * If a stable, unknown face is detected, a dialog box will appear asking for the person's name.\n        * Enter a name and press \"OK\" to add the face to the database.\n        * Press \"Cancel\" or close the dialog to skip adding the face.\n    * Recognized faces will be labeled with their names and confidence scores.\n    * Press 'q' to quit the application.\n\n---\n\n## Project Structure and Key Components\n\n* **`FaceTracker` Class:**\n    * Manages the state of detected faces across frames.\n    * Uses a **smoothing factor** to create stable bounding boxes.\n    * `min_confidence_frames`: Defines how many consecutive frames a face must be detected to be considered \"stable\" for recognition processing.\n    * `_find_best_match` and `_calculate_overlap`: Help in associating new detections with existing tracked faces using Intersection Over Union (IOU).\n    * `processed_unknown_faces`: A set to ensure that the \"ask for name\" dialog for a specific unknown face only appears once.\n\n* **`FaceRecognitionSystem` Class:**\n    * **Initialization:** Loads pre-existing face data (`face_data.pkl`, `face_names.json`). Initializes OpenCV's Haar Cascade for face detection and sets up the video capture.\n    * **`load_face_data()` / `save_face_data()`:** Handles the serialization and deserialization of face encodings and names.\n    * **`get_face_encoding(face_img)`:** The core function that uses `DeepFace.represent()` to get a 128-dimensional embedding for a given face image. Includes validation for face image quality (size, brightness, pixel variation).\n    * **`recognize_face(face_encoding)`:** Compares a new face encoding against known encodings using **cosine similarity** to find the best match.\n    * **`detect_faces_stable(frame)`:** Improves upon basic Haar Cascade detection by applying image preprocessing (histogram equalization, Gaussian blur) and stricter filtering parameters (`minNeighbors`, `minSize`, `maxSize`, aspect ratio checks) to reduce false positives.\n    * **`ask_for_name()`:** A Tkinter-based function to prompt the user for input when an unknown face is encountered. Runs in the main thread to avoid UI issues.\n    * **`add_new_face(face_encoding, name)`:** Adds a new face's encoding and name to the database and saves the updated data.\n    * **`recognition_cache`:** A dictionary to store recent recognition results for `face_id`s, preventing redundant DeepFace calls.\n    * **`should_process_unknown_face()`:** Implements logic to decide when an unknown face is sufficiently stable and \"unknown\" enough to warrant asking the user for a name.\n    * **`run_recognition()`:** The main loop:\n        * Captures frames.\n        * Calls `detect_faces_stable` to get initial detections.\n        * Updates the `face_tracker`.\n        * Periodically (every `recognition_interval` frames) processes stable faces for recognition using cached results or by computing new embeddings.\n        * If a stable, unknown face is detected and hasn't been processed before, it triggers the `ask_for_name` dialog.\n        * Draws bounding boxes and labels on the frame.\n\n---\n\n## Customization and Tuning\n\n* **`FaceTracker` Parameters:**\n    * `smoothing_factor` (default: 0.8): Higher values lead to smoother, less responsive bounding boxes. Lower values make them more reactive to movement.\n    * `min_confidence_frames` (default: 3): Number of frames a face must be consistently detected before it's considered stable. Increase this for higher stability, decrease for faster recognition of new faces.\n\n* **`FaceRecognitionSystem` Parameters:**\n    * `confidence_threshold` (default: 0.7): The cosine similarity score above which a face is considered recognized. Adjust this based on your desired strictness. Higher values mean fewer false positives but potentially more \"Unknown\" classifications.\n    * `cache_timeout` (default: 3.0 seconds): How long a recognition result is cached for a specific tracked face. Increase this for more performance but potentially slower updates if someone changes identity mid-stream (unlikely for a single person).\n    * `recognition_interval` (default: 8 frames): How often DeepFace recognition is performed on stable faces. Increasing this reduces CPU/GPU load but might make recognition appear slightly less responsive.\n    * **`detectMultiScale` parameters:** Experiment with `scaleFactor`, `minNeighbors`, `minSize`, `maxSize` in `detect_faces_stable` for your specific lighting conditions and camera setup.\n    * **`should_process_unknown_face` logic:** The current logic requires `confidence \u003e= 15` (very stable) and `confidence \u003c 0.45` (very low similarity to known faces). Adjust these thresholds if you want to be more or less aggressive in prompting for unknown faces.\n\n---\n\n## Troubleshooting\n\n* **\"Error loading face data\"**: This is usually harmless on the first run as `face_data.pkl` and `face_names.json` won't exist yet. They will be created when you add the first face.\n* **\"Make sure you have installed...\"**: If you see this, double-check your `pip install` commands.\n* **Slow performance / High CPU/GPU usage:** DeepFace can be computationally intensive.\n    * Ensure your TensorFlow installation is optimized for your hardware (e.g., using GPU if available).\n    * Increase `recognition_interval`.\n    * Reduce `CAP_PROP_FPS` in `self.video_capture.set()`.\n* **Poor detection or recognition:**\n    * Ensure good lighting conditions.\n    * Try adjusting the Haar Cascade parameters in `detect_faces_stable()`.\n    * Make sure the faces are reasonably sized and clear when adding them to the database.\n    * Adjust `confidence_threshold`.\n* **Tkinter dialog not appearing or freezing:** Tkinter dialogs need to run in the main thread. The current implementation tries to handle this, but if you're embedding this into a larger application, be mindful of threading issues.\n\n---\n\nFeel free to experiment with the parameters to optimize performance and accuracy for your specific environment!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoderkun12%2Freal-time-face-detection","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoderkun12%2Freal-time-face-detection","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoderkun12%2Freal-time-face-detection/lists"}