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": [
"# Face Verification: One-to-One Face Comparison\n",
"\n",
"[](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/03_face_verification.ipynb) [](https://www.kaggle.com/code/yakhyokhuja/face-verification-one-to-one-face-comparison)\n",
"\n",
"Compare two face images and decide whether they show the same person.\n",
"\n",
"<img src=\"https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/verification.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",
"\n",
"import uniface\n",
"from uniface.analyzer import FaceAnalyzer\n",
"from uniface.detection import RetinaFace\n",
"from uniface.recognition import ArcFace\n",
"\n",
"print(uniface.__version__)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We need detection and recognition models for face verification.\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"analyzer = FaceAnalyzer(\n",
" detector=RetinaFace(confidence_threshold=0.5),\n",
" recognizer=ArcFace()\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 1. Load Two Faces\n",
"\n",
"Two photographs of the same person, fourteen years apart."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"image_path1 = '../assets/source/verify_now_2010.jpg'\n",
"image_path2 = '../assets/source/verify_now_2024.jpg'\n",
"\n",
"image1 = cv2.imread(image_path1)\n",
"image2 = cv2.imread(image_path2)\n",
"\n",
"# Analyze faces\n",
"faces1 = analyzer.analyze(image1)\n",
"faces2 = analyzer.analyze(image2)\n",
"\n",
"print(f'Detected {len(faces1)} and {len(faces2)} faces')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 2. Look at Both Images"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"fig, axes = plt.subplots(1, 2, figsize=(10, 5))\n",
"\n",
"axes[0].imshow(cv2.cvtColor(image1, cv2.COLOR_BGR2RGB))\n",
"axes[0].set_title('Image 1')\n",
"axes[0].axis('off')\n",
"\n",
"axes[1].imshow(cv2.cvtColor(image2, cv2.COLOR_BGR2RGB))\n",
"axes[1].set_title('Image 2')\n",
"axes[1].axis('off')\n",
"\n",
"plt.tight_layout()\n",
"plt.show()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 3. Compute Similarity\n",
"\n",
"`compute_similarity()` is a dot product between two normalised embeddings, so it returns\n",
"the cosine similarity."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"if faces1 and faces2:\n",
" face1 = faces1[0]\n",
" face2 = faces2[0]\n",
"\n",
" similarity = face1.compute_similarity(face2)\n",
" print(f'Similarity: {similarity:.4f}')\n",
"else:\n",
" print('Error: Could not detect faces')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 4. Decide With a Threshold"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"THRESHOLD = 0.4 # the library default, matching FAISS.search\n",
"\n",
"if faces1 and faces2:\n",
" is_same_person = similarity > THRESHOLD\n",
"\n",
" print(f'Similarity: {similarity:.4f}')\n",
" print(f'Threshold: {THRESHOLD}')\n",
" print(f'Result: {\"Same person\" if is_same_person else \"Different people\"}')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 5. Compare Several Pairs\n",
"\n",
"The same person against themselves, then each of them against a different person."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"image_pairs = [\n",
" ('../assets/source/verify_now_2010.jpg', '../assets/source/verify_now_2014.jpg'),\n",
" ('../assets/source/verify_now_2014.jpg', '../assets/source/verify_now_2024.jpg'),\n",
" ('../assets/source/verify_now_2010.jpg', '../assets/source/verify_now_2024.jpg'),\n",
" ('../assets/source/verify_now_2024.jpg', '../assets/source/age_adult.jpg'),\n",
"]\n",
"\n",
"print('Comparing multiple pairs:')\n",
"for img1_path, img2_path in image_pairs:\n",
" img1 = cv2.imread(img1_path)\n",
" img2 = cv2.imread(img2_path)\n",
"\n",
" faces_a = analyzer.analyze(img1)\n",
" faces_b = analyzer.analyze(img2)\n",
"\n",
" if faces_a and faces_b:\n",
" sim = faces_a[0].compute_similarity(faces_b[0])\n",
"\n",
" img1_name = img1_path.split('/')[-1]\n",
" img2_name = img2_path.split('/')[-1]\n",
"\n",
" print(f'{img1_name} vs {img2_name}: {sim:.4f}')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Notes\n",
"\n",
"- 0.4 is the library default, the same value `FAISS.search` uses.\n",
"- No single threshold fits every dataset. Long time gaps, low resolution and scanned prints all\n",
" pull genuine scores down, so a real match can land below 0.6. Measure a few known pairs from\n",
" your own images before choosing a number."
]
}
],
"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
}