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": {
"vscode": {
"languageId": "plaintext"
}
},
"source": [
"# Face Detection and Alignment with UniFace\n",
"\n",
"[](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/02_face_alignment.ipynb) [](https://www.kaggle.com/code/yakhyokhuja/face-detection-and-alignment-with-uniface)\n",
"\n",
"Detect a face, then align and crop it to the 112x112 input that recognition models expect.\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",
"import numpy as np\n",
"\n",
"import uniface\n",
"from uniface.detection import RetinaFace\n",
"from uniface.face_utils import face_alignment\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 Images and Perform Detection + Alignment"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"image_paths = [\n",
" '../assets/source/age_child.jpg',\n",
" '../assets/source/age_adult.jpg',\n",
" '../assets/source/age_middle.jpg',\n",
" '../assets/source/age_senior.jpg',\n",
" '../assets/source/landmarks_face.jpg',\n",
"]\n",
"\n",
"original_images = []\n",
"detection_images = []\n",
"aligned_images = []\n",
"\n",
"for image_path in image_paths:\n",
" # Load image\n",
" image = cv2.imread(image_path)\n",
" if image is None:\n",
" print(f'Error: Could not read {image_path}')\n",
" continue\n",
"\n",
" # Detect faces\n",
" faces = detector.detect(image)\n",
" if not faces:\n",
" print(f'No faces detected in {image_path}')\n",
" continue\n",
"\n",
" # Draw detections\n",
" bbox_image = image.copy()\n",
" draw_detections(image=bbox_image, faces=faces, vis_threshold=0.6, corner_bbox=True)\n",
"\n",
" # Align first detected face (returns aligned image and inverse transform matrix)\n",
" first_landmarks = faces[0].landmarks\n",
" aligned_image, _ = face_alignment(image, first_landmarks, image_size=112)\n",
"\n",
" # Convert BGR to RGB for visualization\n",
" original_images.append(cv2.cvtColor(image, cv2.COLOR_BGR2RGB))\n",
" detection_images.append(cv2.cvtColor(bbox_image, cv2.COLOR_BGR2RGB))\n",
" aligned_images.append(cv2.cvtColor(aligned_image, cv2.COLOR_BGR2RGB))\n",
"\n",
"print(f'Processed {len(original_images)} images')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 2. Visualize Results"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"fig, axes = plt.subplots(3, len(original_images), figsize=(15, 10))\n",
"\n",
"row_titles = ['Original', 'Detection', 'Aligned']\n",
"\n",
"for row, images in enumerate([original_images, detection_images, aligned_images]):\n",
" for col, img in enumerate(images):\n",
" axes[row, col].imshow(img)\n",
" axes[row, col].axis('off')\n",
" if col == 0:\n",
" axes[row, col].set_title(row_titles[row], fontsize=12, loc='left')\n",
"\n",
"plt.tight_layout()\n",
"plt.show()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Notes\n",
"\n",
"- The 112x112 output size is what recognition models expect. Changing it will degrade embeddings.\n",
"- Alignment needs the 5-point template, so BlazeFace cannot be used here."
]
}
],
"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
}