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 Attribute Detection with UniFace\n",
"\n",
"[](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/14_face_attributes.ipynb) [](https://www.kaggle.com/code/yakhyokhuja/face-attribute-detection-with-uniface)\n",
"\n",
"FaceAttribNet reads five independent binary states per face: left and right eye openness, eyeglasses, face mask, and sunglasses.\n",
"\n",
"<img src=\"https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/face_states_alt.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",
"from pathlib import Path\n",
"\n",
"import uniface\n",
"from uniface.attribute import FaceAttribNet\n",
"from uniface.detection import RetinaFace\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 face attribute model\n",
"face_attrib = FaceAttribNet()\n",
"\n",
"print(\"Models initialized successfully!\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 1. Process All Test Images\n",
"\n",
"Each face gets a `FaceStateResult` with five **independent** probabilities: `left_eye_open`, `right_eye_open`, `eyeglasses`, `mask`, `sunglasses`.\n",
"\n",
"> These come from independent binary heads. They do not sum to 1 and several can be high at once (a face can wear both sunglasses and a mask). Threshold each attribute separately; never `argmax`."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"THRESHOLD = 0.5\n",
"CROP = 512\n",
"\n",
"# the source photos differ in aspect ratio and framing, so crop each to the same square\n",
"SUBJECTS = [\n",
" ('age_adult.jpg', 'eyes open'),\n",
" ('mesh_face.jpg', 'no accessories'),\n",
" ('state_b_glasses.jpg', 'glasses'),\n",
" ('state_b_sunglasses.jpg', 'sunglasses'),\n",
" ('state_b_mask.jpg', 'mask'),\n",
"]\n",
"demo_dir = Path('../assets/source')\n",
"\n",
"\n",
"def face_panel(path, margin=0.5):\n",
" \"\"\"Square crop centred on the largest face, so every panel is the same size.\"\"\"\n",
" image = cv2.imread(str(path))\n",
" faces = detector.detect(image)\n",
" if not faces:\n",
" return None, None\n",
" face = max(faces, key=lambda f: f.bbox[2] - f.bbox[0])\n",
" x1, y1, x2, y2 = face.bbox\n",
" cx, cy = (x1 + x2) / 2, (y1 + y2) / 2\n",
" h, w = image.shape[:2]\n",
" half = min(max(x2 - x1, y2 - y1) * (1 + margin) / 2, w / 2, h / 2)\n",
" cx = min(max(cx, half), w - half)\n",
" cy = min(max(cy, half), h - half)\n",
" crop = image[int(cy - half):int(cy + half), int(cx - half):int(cx + half)]\n",
" crop = cv2.resize(crop, (CROP, CROP), interpolation=cv2.INTER_CUBIC)\n",
" faces = detector.detect(crop)\n",
" if not faces:\n",
" return None, None\n",
" return crop, face_attrib.predict(crop, max(faces, key=lambda f: f.bbox[2] - f.bbox[0]))\n",
"\n",
"\n",
"panels = []\n",
"for name, label in SUBJECTS:\n",
" crop, result = face_panel(demo_dir / name)\n",
" if crop is None:\n",
" print(f'{name}: no face found')\n",
" continue\n",
" panels.append((cv2.cvtColor(crop, cv2.COLOR_BGR2RGB), result, label))\n",
" print(f'{label:<12} {\", \".join(result.labels(THRESHOLD)) or \"none\"}')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 2. Visualize Results\n",
"\n",
"**First row**: Original images\n",
"**Second row**: Faces annotated with the attributes above the threshold"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"fig, axes = plt.subplots(1, len(panels), figsize=(2.9 * len(panels), 4.6))\n",
"\n",
"for ax, (crop, result, label) in zip(axes, panels):\n",
" ax.imshow(crop)\n",
" ax.set_title(label, fontsize=12)\n",
" ax.axis('off')\n",
"\n",
" # the five heads are independent, so print every probability rather than a winner\n",
" for i, (name, prob) in enumerate(result.as_dict().items()):\n",
" on = prob > THRESHOLD\n",
" ax.text(0.0, -0.05 - i * 0.075, name, transform=ax.transAxes, fontsize=9,\n",
" family='monospace', color='#111' if on else '#999', va='top')\n",
" ax.text(1.0, -0.05 - i * 0.075, f'{\"True \" if on else \"False\"} {prob:.2f}',\n",
" transform=ax.transAxes, fontsize=9, family='monospace',\n",
" color='#0a7d3f' if on else '#999', va='top', ha='right')\n",
"\n",
"plt.tight_layout()\n",
"plt.show()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 3. Inspect a Single Prediction\n",
"\n",
"`predict()` returns a `FaceStateResult` and also writes the probabilities back onto the `Face` object (`face.left_eye_open`, `face.right_eye_open`, `face.eyeglasses`, `face.mask`, `face.sunglasses`)."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"image = cv2.imread(str(demo_dir / 'state_b_sunglasses.jpg'))\n",
"face = detector.detect(image)[0]\n",
"\n",
"result = face_attrib.predict(image, face)\n",
"\n",
"print(result)\n",
"print()\n",
"for name, prob in result.as_dict().items():\n",
" marker = '✔' if prob > THRESHOLD else '✘'\n",
" print(f\" {marker} {name} {prob:.4f}\")\n",
"\n",
"print()\n",
"print(f\"Face enriched: sunglasses={face.sunglasses:.4f}, left_eye_open={face.left_eye_open:.4f}\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Notes\n",
"\n",
"- The five values come from independent binary heads. They do not sum to 1, and more than one\n",
" can be high at once, so threshold each separately and never use `argmax`.\n",
"- A face in sunglasses usually reads `sunglasses` true and both eyes false, because the lenses\n",
" hide the eyes."
]
}
],
"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
}