UniFace: A Unified Face Analysis Library for Python | Detection, alignment, landmarks, face-mesh, recognition, parsing, gaze, attributes and anti-spoofing under one API.
Python computer-visiondeep-learningface-alignmentface-analysisface-anonymizationface-anti-spoofingface-attributesface-detectionface-meshface-parsingface-quality-assessmentface-recognitionface-segmentationface-trackingfacial-landmarksgaze-estimationhead-pose-estimationonnxruntimeportrait-mattingpython
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Gaze Estimation with UniFace\n",
"\n",
"[](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/08_gaze_estimation.ipynb) [](https://www.kaggle.com/code/yakhyokhuja/gaze-estimation-with-uniface)\n",
"\n",
"Estimate which way a person is looking from a face crop.\n",
"\n",
"<img src=\"https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/gaze.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.gaze import MobileGaze\n",
"from uniface.draw import draw_gaze\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 gaze estimator (uses ResNet34 by default)\n",
"gaze_estimator = MobileGaze()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 1. Process All Test Images\n",
"\n",
"Display original images in the first row and gaze-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 ('gaze_away.jpg', 'gaze_averted.jpg', 'gaze_right.jpg',)]\n",
"\n",
"# Store original and processed images\n",
"original_images = []\n",
"processed_images = []\n",
"\n",
"for image_path in demo_images:\n",
" print(f\"Processing: {image_path.name}\")\n",
"\n",
" # Load image\n",
" image = cv2.imread(str(image_path))\n",
" original = image.copy()\n",
"\n",
" # Detect faces\n",
" faces = detector.detect(image)\n",
" print(f' Detected {len(faces)} face(s)')\n",
"\n",
" # Estimate gaze for each face\n",
" for i, face in enumerate(faces):\n",
" x1, y1, x2, y2 = map(int, face.bbox[:4])\n",
" face_crop = image[y1:y2, x1:x2]\n",
"\n",
" if face_crop.size > 0:\n",
" gaze = gaze_estimator.estimate(face_crop)\n",
" pitch_deg = np.degrees(gaze.pitch)\n",
" yaw_deg = np.degrees(gaze.yaw)\n",
"\n",
" print(f' Face {i+1}: pitch={pitch_deg:.1f}°, yaw={yaw_deg:.1f}°')\n",
"\n",
" # Draw gaze without angle text\n",
" draw_gaze(image, face.bbox, gaze.pitch, gaze.yaw, draw_angles=False)\n",
"\n",
" # Convert BGR to RGB for display\n",
" original_rgb = cv2.cvtColor(original, cv2.COLOR_BGR2RGB)\n",
" processed_rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)\n",
"\n",
" original_images.append(original_rgb)\n",
" processed_images.append(processed_rgb)\n",
"\n",
"print(f\"\\nProcessed {len(demo_images)} images\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 2. Visualize Results\n",
"\n",
"**First row**: Original images \n",
"**Second row**: Images with gaze direction arrows"
]
},
{
"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=(4*num_images, 8))\n",
"\n",
"# Handle case where there's only one image\n",
"if num_images == 1:\n",
" axes = axes.reshape(2, 1)\n",
"\n",
"# First row: Original images\n",
"for i, img in enumerate(original_images):\n",
" axes[0, i].imshow(img)\n",
" axes[0, i].set_title(f'Original {i}', fontsize=12)\n",
" axes[0, i].axis('off')\n",
"\n",
"# Second row: Gaze-annotated images\n",
"for i, img in enumerate(processed_images):\n",
" axes[1, i].imshow(img)\n",
" axes[1, i].set_title(f'Gaze Estimation {i}', 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` and `yaw` come back in radians, not degrees. Use `np.degrees()` before printing them.\n",
"- `MobileGaze()` loads ResNet-34. Pass `model_name=` for one of the other backbones.\n",
"- Gaze is where the eyes point, which is not the same as where the head points. Notebook 11\n",
" covers the latter."
]
}
],
"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
}