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.4 KB
Raw Blame
{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Face 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/01_face_detection.ipynb) [![Open in Kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://www.kaggle.com/code/yakhyokhuja/face-detection-with-uniface)\n",
    "\n",
    "Detect faces in an image and read back their boxes, confidences and 5-point landmarks.\n",
    "\n",
    "<img src=\"https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/detection.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 IPython.display as display\n",
    "from PIL import Image\n",
    "\n",
    "import uniface\n",
    "from uniface.detection import RetinaFace\n",
    "from uniface.draw import draw_detections\n",
    "\n",
    "print(uniface.__version__)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "detector = RetinaFace(\n",
    "    confidence_threshold=0.5,\n",
    "    nms_threshold=0.4,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Load and Display Input Image"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "image_path = '../assets/source/detect_group.jpg'\n",
    "pil_image = Image.open(image_path)\n",
    "pil_image"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Detect Faces"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load image\n",
    "image = cv2.imread(image_path)\n",
    "\n",
    "# Detect faces - returns list of Face objects\n",
    "faces = detector.detect(image)\n",
    "print(f'Detected {len(faces)} face(s)')\n",
    "\n",
    "# Draw detections\n",
    "draw_detections(image=image, faces=faces, vis_threshold=0.6, corner_bbox=True)\n",
    "\n",
    "# Display result\n",
    "output_image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)\n",
    "display.display(Image.fromarray(output_image))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Detect Top-K Faces\n",
    "\n",
    "Use `max_num` to limit the number of detected faces.\n",
    "\n",
    "**Top-2 faces**\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "image = cv2.imread(image_path)\n",
    "\n",
    "faces = detector.detect(image, max_num=2)\n",
    "print(f'Detected {len(faces)} face(s)')\n",
    "\n",
    "draw_detections(image=image, faces=faces, vis_threshold=0.6, corner_bbox=True)\n",
    "\n",
    "output_image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)\n",
    "display.display(Image.fromarray(output_image))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Top-5 faces**\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "image = cv2.imread(image_path)\n",
    "\n",
    "faces = detector.detect(image, max_num=5)\n",
    "print(f'Detected {len(faces)} face(s)')\n",
    "\n",
    "draw_detections(image=image, faces=faces, vis_threshold=0.6, corner_bbox=True)\n",
    "\n",
    "output_image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)\n",
    "display.display(Image.fromarray(output_image))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Notes\n",
    "\n",
    "- `landmarks` are the 5-point alignment template (eyes, nose, mouth corners) that recognition\n",
    "  and quality both consume. BlazeFace is the exception: it returns 6 MediaPipe keypoints whose\n",
    "  fourth point is a mouth centre, so it cannot be used for alignment.\n",
    "- `detect(image, max_num=5)` keeps only the strongest faces."
   ]
  }
 ],
 "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": 2
}