Skip to content

UniFace: A Unified Face Analysis Library for Python | Detection, alignment, landmarks, face-mesh, recognition, parsing, gaze, attributes and anti-spoofing under one API.

8.0 KB
Raw Blame
{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Face Attribute Detection with UniFace\n",
    "\n",
    "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/14_face_attributes.ipynb) [![Open in Kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://www.kaggle.com/code/yakhyokhuja/face-attribute-detection-with-uniface)\n",
    "\n",
    "FaceAttribNet reads five independent binary states per face: left and right eye openness, eyeglasses, face mask, and sunglasses.\n",
    "\n",
    "<img src=\"https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/face_states_alt.jpg\" width=\"100%\">\n",
    "\n",
    "---\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",
    "## Setup\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%pip install -q \"uniface[cpu]\"\n",
    "\n",
    "# Clone repo for assets (Colab / Kaggle only)\n",
    "import os\n",
    "if any(k in os.environ for k in ('COLAB_GPU', 'COLAB_RELEASE_TAG', 'KAGGLE_KERNEL_RUN_TYPE')):\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": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import cv2\n",
    "import matplotlib.pyplot as plt\n",
    "from pathlib import Path\n",
    "\n",
    "import uniface\n",
    "from uniface.attribute import FaceAttribNet\n",
    "from uniface.detection import RetinaFace\n",
    "\n",
    "print(f\"UniFace version: {uniface.__version__}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Initialize face detector\n",
    "detector = RetinaFace(confidence_threshold=0.5)\n",
    "\n",
    "# Initialize face attribute model\n",
    "face_attrib = FaceAttribNet()\n",
    "\n",
    "print(\"Models initialized successfully!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Process All Test Images\n",
    "\n",
    "Each face gets a `FaceStateResult` with five **independent** probabilities: `left_eye_open`, `right_eye_open`, `eyeglasses`, `mask`, `sunglasses`.\n",
    "\n",
    "> These come from independent binary heads. They do not sum to 1 and several can be high at once (a face can wear both sunglasses and a mask). Threshold each attribute separately; never `argmax`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "THRESHOLD = 0.5\n",
    "CROP = 512\n",
    "\n",
    "# the source photos differ in aspect ratio and framing, so crop each to the same square\n",
    "SUBJECTS = [\n",
    "    ('age_adult.jpg', 'eyes open'),\n",
    "    ('mesh_face.jpg', 'no accessories'),\n",
    "    ('state_b_glasses.jpg', 'glasses'),\n",
    "    ('state_b_sunglasses.jpg', 'sunglasses'),\n",
    "    ('state_b_mask.jpg', 'mask'),\n",
    "]\n",
    "demo_dir = Path('../assets/source')\n",
    "\n",
    "\n",
    "def face_panel(path, margin=0.5):\n",
    "    \"\"\"Square crop centred on the largest face, so every panel is the same size.\"\"\"\n",
    "    image = cv2.imread(str(path))\n",
    "    faces = detector.detect(image)\n",
    "    if not faces:\n",
    "        return None, None\n",
    "    face = max(faces, key=lambda f: f.bbox[2] - f.bbox[0])\n",
    "    x1, y1, x2, y2 = face.bbox\n",
    "    cx, cy = (x1 + x2) / 2, (y1 + y2) / 2\n",
    "    h, w = image.shape[:2]\n",
    "    half = min(max(x2 - x1, y2 - y1) * (1 + margin) / 2, w / 2, h / 2)\n",
    "    cx = min(max(cx, half), w - half)\n",
    "    cy = min(max(cy, half), h - half)\n",
    "    crop = image[int(cy - half):int(cy + half), int(cx - half):int(cx + half)]\n",
    "    crop = cv2.resize(crop, (CROP, CROP), interpolation=cv2.INTER_CUBIC)\n",
    "    faces = detector.detect(crop)\n",
    "    if not faces:\n",
    "        return None, None\n",
    "    return crop, face_attrib.predict(crop, max(faces, key=lambda f: f.bbox[2] - f.bbox[0]))\n",
    "\n",
    "\n",
    "panels = []\n",
    "for name, label in SUBJECTS:\n",
    "    crop, result = face_panel(demo_dir / name)\n",
    "    if crop is None:\n",
    "        print(f'{name}: no face found')\n",
    "        continue\n",
    "    panels.append((cv2.cvtColor(crop, cv2.COLOR_BGR2RGB), result, label))\n",
    "    print(f'{label:<12} {\", \".join(result.labels(THRESHOLD)) or \"none\"}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Visualize Results\n",
    "\n",
    "**First row**: Original images\n",
    "**Second row**: Faces annotated with the attributes above the threshold"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, axes = plt.subplots(1, len(panels), figsize=(2.9 * len(panels), 4.6))\n",
    "\n",
    "for ax, (crop, result, label) in zip(axes, panels):\n",
    "    ax.imshow(crop)\n",
    "    ax.set_title(label, fontsize=12)\n",
    "    ax.axis('off')\n",
    "\n",
    "    # the five heads are independent, so print every probability rather than a winner\n",
    "    for i, (name, prob) in enumerate(result.as_dict().items()):\n",
    "        on = prob > THRESHOLD\n",
    "        ax.text(0.0, -0.05 - i * 0.075, name, transform=ax.transAxes, fontsize=9,\n",
    "                family='monospace', color='#111' if on else '#999', va='top')\n",
    "        ax.text(1.0, -0.05 - i * 0.075, f'{\"True \" if on else \"False\"} {prob:.2f}',\n",
    "                transform=ax.transAxes, fontsize=9, family='monospace',\n",
    "                color='#0a7d3f' if on else '#999', va='top', ha='right')\n",
    "\n",
    "plt.tight_layout()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Inspect a Single Prediction\n",
    "\n",
    "`predict()` returns a `FaceStateResult` and also writes the probabilities back onto the `Face` object (`face.left_eye_open`, `face.right_eye_open`, `face.eyeglasses`, `face.mask`, `face.sunglasses`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "image = cv2.imread(str(demo_dir / 'state_b_sunglasses.jpg'))\n",
    "face = detector.detect(image)[0]\n",
    "\n",
    "result = face_attrib.predict(image, face)\n",
    "\n",
    "print(result)\n",
    "print()\n",
    "for name, prob in result.as_dict().items():\n",
    "    marker = '✔' if prob > THRESHOLD else '✘'\n",
    "    print(f\"  {marker} {name} {prob:.4f}\")\n",
    "\n",
    "print()\n",
    "print(f\"Face enriched: sunglasses={face.sunglasses:.4f}, left_eye_open={face.left_eye_open:.4f}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Notes\n",
    "\n",
    "- The five values come from independent binary heads. They do not sum to 1, and more than one\n",
    "  can be high at once, so threshold each separately and never use `argmax`.\n",
    "- A face in sunglasses usually reads `sunglasses` true and both eyes false, because the lenses\n",
    "  hide the eyes."
   ]
  }
 ],
 "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": 4
}