Upload 11 files

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Martin Badrous
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,150 @@
+---
+language: en
+license: mit
+tags:
+- computer-vision
+- face-recognition
+- 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
+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 **≈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]).

app.py

@@ -0,0 +1,52 @@
+"""
+Gradio demo for facial verification.
+
+This script exposes a web interface where users can upload two images and
+receive immediate feedback about whether the faces match.  It utilises
+MTCNN for face detection and InceptionResnetV1 for feature extraction via
+the utilities defined in ``src``.
+"""
+
+import gradio as gr
+from PIL import Image
+
+from src.verify_faces import verify_images
+
+
+def verify_fn(img1: Image.Image, img2: Image.Image) -> str:
+    """Wrap the verification function for Gradio.
+
+    Parameters
+    ----------
+    img1, img2: PIL.Image.Image
+        Input images from the user interface.
+
+    Returns
+    -------
+    str
+        A human‑readable message indicating whether the faces match and the
+        similarity score.
+    """
+    # Run verification.  We rely on CPU to keep the demo accessible on free tier.
+    similarity, is_same, message = verify_images(img1, img2, threshold=0.8, device="cpu")
+    if similarity is None:
+        return message
+    return f"{message}\nCosine similarity: {similarity:.3f}"
+
+
+demo = gr.Interface(
+    fn=verify_fn,
+    inputs=[gr.Image(type="pil", label="Image 1"), gr.Image(type="pil", label="Image 2")],
+    outputs=gr.Textbox(label="Result"),
+    title="Facial Recognition Verification",
+    description=(
+        "Upload two face images to verify if they belong to the same person. "
+        "We use a pretrained FaceNet model to extract 512‑dimensional embeddings "
+        "and compute their cosine similarity. A similarity above 0.8 indicates a match."
+    ),
+    allow_flagging="never",
+)
+
+
+if __name__ == "__main__":
+    demo.launch()

requirements.txt

@@ -0,0 +1,7 @@
+torch>=2.1.0
+torchvision>=0.16.0
+facenet-pytorch>=2.5.2
+numpy>=1.24
+scikit-learn>=1.3
+pillow>=9.0
+gradio>=4.10.0

src/__init__.py

@@ -0,0 +1,17 @@
+"""Facial recognition verification package.
+
+This package groups together utilities for face detection, embedding
+extraction and verification used by the Gradio demo and can be reused in
+other projects.
+"""
+
+from .detect_faces import detect_faces  # noqa: F401
+from .extract_embeddings import extract_embedding  # noqa: F401
+from .verify_faces import verify_images, cosine_similarity  # noqa: F401
+
+__all__ = [
+    "detect_faces",
+    "extract_embedding",
+    "verify_images",
+    "cosine_similarity",
+]

src/detect_faces.py

@@ -0,0 +1,69 @@
+"""
+Face detection utility using MTCNN from facenet_pytorch.
+
+This module exposes a simple function to detect faces in a PIL Image.  It
+returns bounding boxes for all detected faces.  The detection model is
+constructed lazily on the first call to avoid unnecessary GPU/CPU
+initialisation when the module is imported.
+"""
+
+from typing import List, Tuple, Optional
+
+import numpy as np
+from PIL import Image
+
+try:
+    from facenet_pytorch import MTCNN
+except ImportError as exc:
+    raise ImportError(
+        "facenet_pytorch is required for face detection. Install it with `pip install facenet-pytorch`."
+    ) from exc
+
+_mtcnn: Optional[MTCNN] = None
+
+
+def _get_mtcnn(device: str = "cpu") -> MTCNN:
+    """Return a singleton MTCNN detector instance.
+
+    Parameters
+    ----------
+    device: str, optional
+        PyTorch device on which to run the detector.  Defaults to ``"cpu"``.
+
+    Returns
+    -------
+    MTCNN
+        The configured multi-task cascaded CNN detector.
+    """
+    global _mtcnn
+    if _mtcnn is None:
+        _mtcnn = MTCNN(image_size=160, margin=0, keep_all=True, device=device)
+    return _mtcnn
+
+
+def detect_faces(image: Image.Image, device: str = "cpu") -> List[Tuple[float, float, float, float]]:
+    """Detect faces in a PIL image.
+
+    Parameters
+    ----------
+    image: PIL.Image.Image
+        The input image in which to detect faces.
+    device: str, optional
+        Device on which to run the detector (``"cpu"`` or ``"cuda"``).  Defaults to ``"cpu"``.
+
+    Returns
+    -------
+    List[Tuple[float, float, float, float]]
+        A list of bounding boxes (x1, y1, x2, y2) for each detected face.  If
+        no faces are found, returns an empty list.
+    """
+    mtcnn = _get_mtcnn(device)
+    # MTCNN returns (boxes, probs).  We only need boxes.
+    boxes, _ = mtcnn.detect(image)
+    if boxes is None:
+        return []
+    # Convert numpy array of shape (n, 4) into list of tuples.
+    return [tuple(map(float, box)) for box in np.array(boxes)]
+
+
+__all__ = ["detect_faces"]

src/extract_embeddings.py

@@ -0,0 +1,78 @@
+"""
+Facial embedding extraction using FaceNet (InceptionResnetV1).
+
+This module wraps the FaceNet model from facenet_pytorch to produce
+512‑dimensional embeddings for detected faces.  It relies on MTCNN
+for cropping the largest face in the image.  If no face is detected, it
+returns ``None``.
+"""
+
+from typing import Optional
+
+import numpy as np
+from PIL import Image
+import torch
+
+try:
+    from facenet_pytorch import MTCNN, InceptionResnetV1
+except ImportError as exc:
+    raise ImportError(
+        "facenet_pytorch is required for embedding extraction. Install it with `pip install facenet-pytorch`."
+    ) from exc
+
+_mtcnn: Optional[MTCNN] = None
+_resnet: Optional[InceptionResnetV1] = None
+
+
+def _get_models(device: str = "cpu") -> tuple[MTCNN, InceptionResnetV1]:
+    """Initialise and cache MTCNN and InceptionResnet models.
+
+    Parameters
+    ----------
+    device: str, optional
+        Device on which to run the models.  Defaults to ``"cpu"``.
+
+    Returns
+    -------
+    tuple[MTCNN, InceptionResnetV1]
+        The face detector and feature extractor.
+    """
+    global _mtcnn, _resnet
+    if _mtcnn is None:
+        _mtcnn = MTCNN(image_size=160, margin=0, select_largest=True, device=device)
+    if _resnet is None:
+        _resnet = InceptionResnetV1(pretrained="vggface2").eval().to(device)
+    return _mtcnn, _resnet
+
+
+def extract_embedding(image: Image.Image, device: str = "cpu") -> Optional[np.ndarray]:
+    """Extract a 512‑dimensional face embedding from an image.
+
+    Parameters
+    ----------
+    image: PIL.Image.Image
+        The input image containing a face.
+    device: str, optional
+        Device on which to run the models.  Defaults to ``"cpu"``.
+
+    Returns
+    -------
+    np.ndarray or None
+        A numpy array of shape (512,) containing the embedding.  If no face
+        is detected, returns ``None``.
+    """
+    mtcnn, resnet = _get_models(device)
+    # Detect face and crop to 160x160.  MTCNN returns a tensor of shape (3, 160, 160).
+    face, prob = mtcnn(image, return_prob=True)
+    if face is None:
+        return None
+    # Add batch dimension and send to device.
+    face = face.to(device).unsqueeze(0)
+    # Extract embedding.
+    with torch.no_grad():
+        emb = resnet(face)
+    # Return as 1D numpy array on CPU.
+    return emb.squeeze(0).cpu().numpy()
+
+
+__all__ = ["extract_embedding"]

src/verify_faces.py

@@ -0,0 +1,66 @@
+"""
+Face verification utilities.
+
+This module provides functions to compare face embeddings and decide
+whether two faces belong to the same person.  It relies on
+``extract_embeddings.extract_embedding`` to obtain the embeddings.
+"""
+
+from typing import Tuple, Optional
+
+import numpy as np
+from PIL import Image
+
+from .extract_embeddings import extract_embedding
+
+
+def cosine_similarity(a: np.ndarray, b: np.ndarray) -> float:
+    """Compute the cosine similarity between two vectors.
+
+    Parameters
+    ----------
+    a, b: np.ndarray
+        1D vectors of the same length.
+
+    Returns
+    -------
+    float
+        The cosine similarity ranging from -1 (opposite) to 1 (identical).
+    """
+    return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)))
+
+
+def verify_images(img1: Image.Image, img2: Image.Image, threshold: float = 0.8, device: str = "cpu") -> Tuple[Optional[float], bool, str]:
+    """Verify whether two images depict the same person.
+
+    This function detects faces in each image, extracts embeddings and
+    computes the cosine similarity.  A threshold decides whether the
+    similarity represents the same identity.
+
+    Parameters
+    ----------
+    img1, img2: PIL.Image.Image
+        The two images to compare.
+    threshold: float, optional
+        Similarity threshold above which the faces are considered the
+        same person.  Defaults to 0.8.
+    device: str, optional
+        Device to run the embedding extraction on.  Defaults to ``"cpu"``.
+
+    Returns
+    -------
+    Tuple[Optional[float], bool, str]
+        A tuple of (similarity score, decision, message).  If no face is
+        detected in either image, the similarity is ``None`` and the
+        decision is ``False``.
+    """
+    emb1 = extract_embedding(img1, device=device)
+    emb2 = extract_embedding(img2, device=device)
+    if emb1 is None or emb2 is None:
+        return None, False, "Face not detected in one or both images."
+    sim = cosine_similarity(emb1, emb2)
+    is_same = sim >= threshold
+    return sim, is_same, "Same person" if is_same else "Different people"
+
+
+__all__ = ["verify_images", "cosine_similarity"]