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.

5.8 KB
Raw Blame
{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Head Pose Estimation 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/11_head_pose_estimation.ipynb) [![Open in Kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://www.kaggle.com/code/yakhyokhuja/head-pose-estimation-with-uniface)\n",
    "\n",
    "Read the pitch, yaw and roll of a head from a face crop.\n",
    "\n",
    "<img src=\"https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/headpose.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 numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "from pathlib import Path\n",
    "from PIL import Image\n",
    "\n",
    "import uniface\n",
    "from uniface.detection import RetinaFace\n",
    "from uniface.headpose import HeadPose\n",
    "from uniface.draw import draw_head_pose\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 head pose estimator (default: ResNet18 backbone)\n",
    "head_pose = HeadPose()\n",
    "\n",
    "print(\"Models initialized successfully!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Process All Test Images\n",
    "\n",
    "Display original images in the first row and head-pose-annotated images in the second row."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get all test images\n",
    "demo_dir = Path('../assets/source')\n",
    "demo_images = [demo_dir / n for n in ('pose_left.jpg', 'pose_center.jpg', 'pose_right.jpg',)]\n",
    "\n",
    "original_images = []\n",
    "annotated_images = []\n",
    "\n",
    "for img_path in demo_images:\n",
    "    image = cv2.imread(str(img_path))\n",
    "    if image is None:\n",
    "        continue\n",
    "\n",
    "    # Store original (BGR -> RGB for display)\n",
    "    original_images.append(cv2.cvtColor(image, cv2.COLOR_BGR2RGB))\n",
    "\n",
    "    # Detect faces and estimate head pose\n",
    "    faces = detector.detect(image)\n",
    "\n",
    "    for face in faces:\n",
    "        x1, y1, x2, y2 = map(int, face.bbox)\n",
    "        face_crop = image[y1:y2, x1:x2]\n",
    "\n",
    "        if face_crop.size == 0:\n",
    "            continue\n",
    "\n",
    "        result = head_pose.estimate(face_crop)\n",
    "        draw_head_pose(image, face.bbox, result.pitch, result.yaw, result.roll)\n",
    "\n",
    "        print(f\"{img_path.name}: pitch={result.pitch:.1f}°, yaw={result.yaw:.1f}°, roll={result.roll:.1f}°\")\n",
    "\n",
    "    annotated_images.append(cv2.cvtColor(image, cv2.COLOR_BGR2RGB))\n",
    "\n",
    "print(f\"\\nProcessed {len(original_images)} images\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Visualize Results\n",
    "\n",
    "**First row**: Original images  \n",
    "**Second row**: Images with head pose 3D cube overlay"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "num_images = len(original_images)\n",
    "\n",
    "# Create figure with 2 rows\n",
    "fig, axes = plt.subplots(2, num_images, figsize=(5 * num_images, 10))\n",
    "\n",
    "if num_images == 1:\n",
    "    axes = axes.reshape(2, 1)\n",
    "\n",
    "for i in range(num_images):\n",
    "    axes[0, i].imshow(original_images[i])\n",
    "    axes[0, i].set_title('Original', fontsize=12)\n",
    "    axes[0, i].axis('off')\n",
    "\n",
    "    axes[1, i].imshow(annotated_images[i])\n",
    "    axes[1, i].set_title('Head Pose', fontsize=12)\n",
    "    axes[1, i].axis('off')\n",
    "\n",
    "plt.tight_layout()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Notes\n",
    "\n",
    "- `pitch`, `yaw` and `roll` come back in degrees, unlike gaze, which uses radians.\n",
    "- Yaw stays believable across a wide range, but pitch and roll degrade once a face turns much\n",
    "  past 60 degrees, because too little of it remains visible."
   ]
  }
 ],
 "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
}