martinbadrous
/

Facial-Recognition-Verification

@@ -7,96 +7,85 @@ tags:
 - face-verification
 - biometrics
 - deep-learning
-pipeline_tag: image-similarity
 model-index:
-  - name: Facial Recognition & Verification (Martin Badrous)
-    results:
-      - task:
-          type: image-similarity
-          name: Face Verification
-        dataset:
-          name: LFW
-          type: face-images
-        metrics:
-          - name: Accuracy
-            type: accuracy
-            value: 0.99
 ---
-# 👥 Facial Recognition & Verification
-**Author:** Martin Badrous
-This repository exposes a practical face‑verification pipeline built on top of
-pretrained face recognition models.  Given two photographs, it extracts fixed
-length embeddings and computes their similarity to decide whether they depict
-the same person.  The project is designed for demonstration and research
-purposes and is not intended for biometric authentication in critical
-applications.
 ---
 ## 🧭 Overview
-The original [Facial Recognition](https://github.com/martinbadrous/Facial-Recognition)
-repository provides a modern PyTorch training pipeline for facial expression
-or identity classification.  It features automatic dataset splitting,
-transfer learning with ResNet18 or EfficientNet‑B0, mixed precision and
-extensive logging【689067851530192†L16-L27】.  While powerful, it focuses on
-classification rather than verification.  This project refactors that work
-into a face verification system.  Instead of predicting a discrete label,
-we map each face into a 512‑dimensional embedding space and measure how
-close two embeddings are.
 ---
-## 🏗️ Model Architecture
-We use the [FaceNet](https://huggingface.co/py-feat/facenet) architecture,
-an Inception‑ResNet network pretrained on the VGGFace2 dataset.  The model
-provides a 512‑dimensional embedding for each detected face【547754386862401†L54-L63】.
-During verification, cosine similarity between two embeddings is computed.  A
-similarity close to one indicates matching faces; a low similarity indicates
-different people.
 ---
-## 📦 Dataset
-For evaluation, we refer to the **Labeled Faces in the Wild (LFW)** dataset, a
-benchmark of celebrity face pairs widely used to assess verification
-algorithms.  Each pair is labelled as **same** or **different**.  FaceNet
-achieves approximately 99 % accuracy on LFW when fine‑tuned【547754386862401†L54-L63】.
-Although the dataset is not included here due to licensing, you can evaluate
-your model by downloading LFW from public sources and adapting the code.
 ---
 ## ⚙️ Usage
-Install dependencies using the provided `requirements.txt`:
 ```bash
 python3 -m venv venv
 source venv/bin/activate
 pip install -r requirements.txt
 ```
-Run the Gradio demo locally:
 ```bash
 python app.py
 ```
-Upload two images.  The interface detects faces, extracts embeddings and
-displays whether they belong to the same person along with the cosine
-similarity score.  If no face is detected, an appropriate message is
-returned.
-### Verification API
-The core logic resides in the `src` package.  You can import these utilities
-in your own scripts:
 ```python
 from PIL import Image
@@ -104,6 +93,7 @@ from src.verify_faces import verify_images
 img1 = Image.open('path/to/photo1.jpg')
 img2 = Image.open('path/to/photo2.jpg')
 similarity, is_same = verify_images(img1, img2, threshold=0.8)
 print(f"Cosine similarity: {similarity:.3f}")
 print("Same person" if is_same else "Different people")
@@ -112,39 +102,37 @@ print("Same person" if is_same else "Different people")
 ---
 ## 📈 Performance
-Pretrained FaceNet models typically achieve **≈99 % accuracy** on the LFW
-benchmark, with average cosine similarities > 0.8 for matching pairs and
-< 0.5 for non‑matching pairs【547754386862401†L54-L63】.  Your mileage may
-vary depending on image quality and lighting conditions.  For production
-systems, consider fine‑tuning on domain‑specific data and adjusting the
-threshold.
 ---
 ## ⚠️ Limitations
-- **Bias and fairness:** Pretrained face recognition models may exhibit
-  demographic bias, performing better on some groups than others.  Do not
-  deploy this system for critical decisions (e.g. law enforcement, hiring,
-  access control) without careful evaluation.
-- **Privacy:** Handling biometric data requires compliance with data
-  protection laws (e.g. GDPR).  Always anonymise and secure sensitive
-  images and embeddings.
-- **Security:** This demo does not include anti‑spoofing or liveness
-  detection.  Simple photographs may fool the system.
 ---
 ## 📜 License
-This project is licensed under the MIT License.  See the `LICENSE` file for
-details.
 ---
-## 📫 Citation & Contact
-If you use this project in academic work, please cite the original
-FaceNet paper【547754386862401†L54-L63】.  For questions or collaborations,
-contact [[email protected]](mailto:[email protected]).

 - face-verification
 - biometrics
 - deep-learning
+pipeline_tag: image-feature-extraction
 model-index:
+- name: Facial Recognition & Verification (Martin Badrous)
+  results:
+  - task:
+      type: image-feature-extraction
+      name: Face Verification
+    dataset:
+      name: LFW
+      type: face-images
+    metrics:
+      - name: Accuracy
+        type: accuracy
+        value: 0.99
 ---
+# 👥 Facial Recognition & Verification
+**Author:** Martin Badrous
+This repository exposes a practical **face-verification pipeline** built on top of pretrained face recognition models.
+Given two photographs, it extracts fixed-length embeddings and computes their similarity to decide whether they depict the same person.
+The project is designed for **demonstration and research** purposes and is **not intended for biometric authentication in critical applications**.
 ---
 ## 🧭 Overview
+The original [Facial Recognition GitHub repository](https://github.com/martinbadrous/Facial-Recognition) provides a modern PyTorch training pipeline for **facial expression or identity classification**.
+It features automatic dataset splitting, transfer learning with ResNet18 or EfficientNet-B0, mixed precision and extensive logging.
+While powerful, it focuses on classification rather than verification.
+This Hugging Face version **refactors that work into a face verification system**.
+Instead of predicting a discrete label, we map each face into a **512-dimensional embedding space** and measure how close two embeddings are.
 ---
+## 🧱 Model Architecture
+We use the **FaceNet** architecture — an *Inception-ResNet network* pretrained on the **VGGFace2** dataset.
+The model provides a **512-dimensional embedding** for each detected face.
+During verification, **cosine similarity** between two embeddings is computed:
+- A similarity close to **1.0** → same person
+- A similarity close to **0.0** → different people
+**Reference model:** [py-feat/facenet](https://huggingface.co/py-feat/facenet)
 ---
+## 🧩 Dataset
+Evaluation is based on the **Labeled Faces in the Wild (LFW)** dataset — a benchmark of celebrity face pairs widely used for assessing verification algorithms.
+Each pair is labelled as *same* or *different*.
+FaceNet achieves **≈ 99 % accuracy** on LFW when fine-tuned on VGGFace2.
+Although LFW is not included here (due to licensing), you can evaluate the model by downloading it from public sources and reusing the provided code.
 ---
 ## ⚙️ Usage
+### 1️⃣ Install dependencies
 ```bash
 python3 -m venv venv
 source venv/bin/activate
 pip install -r requirements.txt
 ```
+### 2️⃣ Run the demo locally
 ```bash
 python app.py
 ```
+The Gradio interface will open in your browser.
+Upload two images — the app will detect faces, extract embeddings, and show whether they belong to the same person, along with a similarity score.
+If no face is detected, an appropriate message will be displayed.
+---
+## 🧠 Verification API
+The core logic resides in the `src` package.
+You can import and use these utilities programmatically:
 ```python
 from PIL import Image
 img1 = Image.open('path/to/photo1.jpg')
 img2 = Image.open('path/to/photo2.jpg')
 similarity, is_same = verify_images(img1, img2, threshold=0.8)
 print(f"Cosine similarity: {similarity:.3f}")
 print("Same person" if is_same else "Different people")
 ---
 ## 📈 Performance
+Pretrained **FaceNet** models typically achieve:
+| Metric | Typical Value |
+|---------|----------------|
+| Accuracy (LFW) | ≈ 99 % |
+| Cosine Similarity (same) | > 0.8 |
+| Cosine Similarity (different) | < 0.5 |
+Performance may vary depending on image quality, resolution, and lighting.
+For production systems, fine-tune on domain-specific data and calibrate your similarity threshold.
 ---
 ## ⚠️ Limitations
+- **Bias & Fairness:** Pretrained facial models may exhibit demographic bias — they can perform better on certain ethnicities or genders. Evaluate thoroughly before deployment.
+- **Privacy:** Handle biometric data in compliance with privacy laws (GDPR, HIPAA, etc.). Never store embeddings without consent.
+- **Security:** This demo lacks spoofing or liveness detection — printed photos or digital screens can fool it.
 ---
 ## 📜 License
+This project is licensed under the **MIT License**.
+See the [LICENSE](./LICENSE) file for details.
 ---
+## 📚 Citation & Contact
+If you use this project in academic work, please cite the original FaceNet paper.
+> Schroff et al., *FaceNet: A Unified Embedding for Face Recognition and Clustering*, CVPR 2015.
+> DOI: [10.1109/CVPR.2015.7298682](https://doi.org/10.1109/CVPR.2015.7298682)
+📩 **Contact:** [email protected]
+🧠 **Project Page:** [Hugging Face – Facial-Recognition-Verification](https://huggingface.co/martinbadrous/Facial-Recognition-Verification)