uniface/examples/12_face_recognition.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0",
   "metadata": {},
   "source": [
    "# Face Recognition: RetinaFace → Align → ArcFace\n",
    "\n",
    "<div style=\"display:flex; flex-wrap:wrap; align-items:center;\">\n",
    "  <a style=\"margin-right:10px; margin-bottom:6px;\" href=\"https://pepy.tech/projects/uniface\"><img alt=\"PyPI Downloads\" src=\"https://static.pepy.tech/personalized-badge/uniface?period=total&units=international_system&left_color=grey&right_color=blue&left_text=Downloads\"></a>\n",
    "  <a style=\"margin-right:10px; margin-bottom:6px;\" href=\"https://pypi.org/project/uniface/\"><img alt=\"PyPI Version\" src=\"https://img.shields.io/pypi/v/uniface.svg\"></a>\n",
    "  <a style=\"margin-right:10px; margin-bottom:6px;\" href=\"https://opensource.org/licenses/MIT\"><img alt=\"License\" src=\"https://img.shields.io/badge/License-MIT-blue.svg\"></a>\n",
    "  <a style=\"margin-bottom:6px;\" href=\"https://github.com/yakhyo/uniface\"><img alt=\"GitHub Stars\" src=\"https://img.shields.io/github/stars/yakhyo/uniface.svg?style=social\"></a>\n",
    "</div>\n",
    "\n",
    "**UniFace** is a lightweight, production-ready Python library for face detection, recognition, tracking, landmark analysis, face parsing, gaze estimation, and face attributes.\n",
    "\n",
    "🔗 **GitHub**: [github.com/yakhyo/uniface](https://github.com/yakhyo/uniface) | 📚 **Docs**: [yakhyo.github.io/uniface](https://yakhyo.github.io/uniface)\n",
    "\n",
    "---\n",
    "\n",
    "This notebook demonstrates face recognition **without** the high-level `FaceAnalyzer` wrapper. Each step is handled manually:\n",
    "\n",
    "1. **RetinaFace**: Detects faces and extracts 5-point landmarks.\n",
    "2. **Face Alignment**: Warps each face into a standardized 112x112 crop using the landmarks.\n",
    "3. **ArcFace**: Generates a 512-D L2-normalized embedding from the aligned crop.\n",
    "\n",
    "We compare three test images: `image0.jpg`, `image1.jpg`, and `image5.jpg`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1",
   "metadata": {},
   "source": [
    "## 1. Install UniFace"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2",
   "metadata": {},
   "outputs": [],
   "source": [
    "%pip install -q \"uniface[cpu]\"\n",
    "\n",
    "# Clone repo for assets (Colab only)\n",
    "import os\n",
    "if 'COLAB_GPU' in os.environ or 'COLAB_RELEASE_TAG' in os.environ:\n",
    "    if not os.path.exists('uniface'):\n",
    "        !git clone --depth 1 https://github.com/yakhyo/uniface.git\n",
    "    os.chdir('uniface/examples')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3",
   "metadata": {},
   "source": [
    "## 2. Import Libraries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4",
   "metadata": {},
   "outputs": [],
   "source": [
    "import cv2\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "import matplotlib.patches as patches\n",
    "\n",
    "import uniface\n",
    "from uniface.detection import RetinaFace\n",
    "from uniface.recognition import ArcFace\n",
    "from uniface.face_utils import face_alignment\n",
    "\n",
    "print(f\"UniFace version: {uniface.__version__}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5",
   "metadata": {},
   "source": [
    "## 3. Configuration"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6",
   "metadata": {},
   "outputs": [],
   "source": [
    "IMAGE_PATHS = {\n",
    "    \"image0\": \"../assets/test_images/image0.jpg\",\n",
    "    \"image1\": \"../assets/test_images/image1.jpg\",\n",
    "    \"image5\": \"../assets/test_images/image5.jpg\",\n",
    "}\n",
    "THRESHOLD = 0.4   # Cosine similarity threshold for \"same person\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7",
   "metadata": {},
   "source": [
    "## 4. Initialize Models"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8",
   "metadata": {},
   "outputs": [],
   "source": [
    "detector = RetinaFace(confidence_threshold=0.5)\n",
    "recognizer = ArcFace()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9",
   "metadata": {},
   "source": [
    "## 5. Load Images & Detect Faces\n",
    "\n",
    "We use the detector to find faces and their landmarks in each image."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "10",
   "metadata": {},
   "outputs": [],
   "source": [
    "images = {}\n",
    "faces = {}\n",
    "\n",
    "for name, path in IMAGE_PATHS.items():\n",
    "    img = cv2.imread(path)\n",
    "    if img is None:\n",
    "        raise FileNotFoundError(f\"Cannot read: {path}\")\n",
    "\n",
    "    detected = detector.detect(img)\n",
    "    if not detected:\n",
    "        raise RuntimeError(f\"No face detected in: {path}\")\n",
    "\n",
    "    images[name] = img\n",
    "    faces[name] = detected[0]   # Keep highest-confidence face\n",
    "    print(f\"{name:8s} | {len(detected)} face(s) detected | confidence={faces[name].confidence:.3f}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "11",
   "metadata": {},
   "source": [
    "## 6. Visualize Detections"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "12",
   "metadata": {},
   "outputs": [],
   "source": [
    "LM_COLORS = [\"red\", \"blue\", \"green\", \"cyan\", \"magenta\"]\n",
    "\n",
    "fig, axes = plt.subplots(1, 3, figsize=(15, 5))\n",
    "fig.suptitle(\"Detected Faces & 5-Point Landmarks\", fontweight=\"bold\", fontsize=16)\n",
    "\n",
    "for ax, (name, img) in zip(axes, images.items()):\n",
    "    face = faces[name]\n",
    "    ax.imshow(cv2.cvtColor(img, cv2.COLOR_BGR2RGB))\n",
    "    ax.set_title(f\"{name}\\nconf={face.confidence:.3f}\", fontsize=12)\n",
    "    ax.axis(\"off\")\n",
    "\n",
    "    # Bounding box\n",
    "    x1, y1, x2, y2 = face.bbox.astype(int)\n",
    "    ax.add_patch(patches.Rectangle(\n",
    "        (x1, y1), x2 - x1, y2 - y1,\n",
    "        linewidth=2, edgecolor=\"lime\", facecolor=\"none\"))\n",
    "\n",
    "    # Landmarks\n",
    "    for (lx, ly), c in zip(face.landmarks, LM_COLORS):\n",
    "        ax.plot(lx, ly, \"o\", color=c, markersize=6)\n",
    "\n",
    "plt.tight_layout()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "13",
   "metadata": {},
   "source": [
    "## 7. Face Alignment\n",
    "\n",
    "We warp the detected faces into a standardized 112x112 size. This improves recognition accuracy."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "14",
   "metadata": {},
   "outputs": [],
   "source": [
    "aligned = {}\n",
    "\n",
    "for name, img in images.items():\n",
    "    lm = faces[name].landmarks\n",
    "    crop, _ = face_alignment(img, lm, image_size=(112, 112))\n",
    "    aligned[name] = crop\n",
    "\n",
    "fig, axes = plt.subplots(1, 3, figsize=(12, 4))\n",
    "fig.suptitle(\"Aligned Face Crops (112x112)\", fontweight=\"bold\", fontsize=14)\n",
    "\n",
    "for ax, (name, crop) in zip(axes, aligned.items()):\n",
    "    ax.imshow(cv2.cvtColor(crop, cv2.COLOR_BGR2RGB))\n",
    "    ax.set_title(name, fontsize=12)\n",
    "    ax.axis(\"off\")\n",
    "\n",
    "plt.tight_layout()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "15",
   "metadata": {},
   "source": [
    "## 8. Extract Embeddings\n",
    "\n",
    "We pass the aligned crops to ArcFace to get the 512-D vectors."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "16",
   "metadata": {},
   "outputs": [],
   "source": [
    "embeddings = {}\n",
    "\n",
    "for name, crop in aligned.items():\n",
    "    # landmarks=None because image is already aligned\n",
    "    emb = recognizer.get_normalized_embedding(crop, landmarks=None)\n",
    "    embeddings[name] = emb\n",
    "    print(f\"{name:8s} | embedding shape={emb.shape} | L2-norm={np.linalg.norm(emb):.4f}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "17",
   "metadata": {},
   "source": [
    "## 9. Pairwise Cosine Similarity\n",
    "\n",
    "Since embeddings are normalized, cosine similarity is just the dot product."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "18",
   "metadata": {},
   "outputs": [],
   "source": [
    "names = list(embeddings.keys())\n",
    "n = len(names)\n",
    "sim_matrix = np.zeros((n, n))\n",
    "\n",
    "for i, ni in enumerate(names):\n",
    "    for j, nj in enumerate(names):\n",
    "        # Use squeeze() to handle (1, 512) shapes if present\n",
    "        sim_matrix[i, j] = float(np.dot(embeddings[ni].squeeze(), embeddings[nj].squeeze()))\n",
    "\n",
    "# Print comparison results\n",
    "pairs = [(names[i], names[j]) for i in range(n) for j in range(i + 1, n)]\n",
    "for a, b in pairs:\n",
    "    s = float(np.dot(embeddings[a].squeeze(), embeddings[b].squeeze()))\n",
    "    verdict = \"✓ Same person\" if s >= THRESHOLD else \"✗ Different people\"\n",
    "    print(f\"{a} vs {b}: similarity={s:.4f} → {verdict}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "19",
   "metadata": {},
   "source": [
    "## 10. Similarity Heatmap"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "20",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots(figsize=(8, 6))\n",
    "im = ax.imshow(sim_matrix, vmin=0, vmax=1, cmap=\"viridis\")\n",
    "plt.colorbar(im, ax=ax, label=\"Cosine similarity\")\n",
    "\n",
    "ax.set_xticks(range(n))\n",
    "ax.set_yticks(range(n))\n",
    "ax.set_xticklabels(names, rotation=30, ha=\"right\")\n",
    "ax.set_yticklabels(names)\n",
    "ax.set_title(\"Pairwise Face Similarity (ArcFace)\", fontweight=\"bold\")\n",
    "\n",
    "for i in range(n):\n",
    "    for j in range(n):\n",
    "        val = sim_matrix[i, j]\n",
    "        ax.text(j, i, f\"{val:.2f}\",\n",
    "                ha=\"center\", va=\"center\",\n",
    "                color=\"black\" if val >= 0.6 else \"white\",\n",
    "                fontsize=12, fontweight=\"bold\")\n",
    "\n",
    "plt.tight_layout()\n",
    "plt.show()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "base",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.13.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}