---
language: en
license: mit
tags:
- computer-vision
- face-recognition
- 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
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")
```

---

## 📈 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:** martin.badrous@gmail.com  
🧠 **Project Page:** [Hugging Face – Facial-Recognition-Verification](https://huggingface.co/martinbadrous/Facial-Recognition-Verification)