yakhyo/uniface

UniFace – a unified Python library for face‑related AI tasks

What it is – UniFace bundles a collection of state‑of‑the‑art deep‑learning models for everything you might want to do with a human face: detection, landmarking, 3‑D mesh, parsing/segmentation, portrait matting, gaze & head‑pose estimation, demographic attributes (age, sex, race), emotion, liveness‑spoof detection, quality scoring, recognition (embeddings), anonymisation, and even a FAISS‑backed vector store for fast similarity search. All models are wrapped behind a single, consistent Python API.

Why it matters – Instead of stitching together dozens of separate repos, you install one package (pip install "uniface[cpu]" or "uniface[gpu]") and get a production‑ready, lightweight solution that works on CPUs, Apple Silicon, and NVIDIA CUDA. Weights are downloaded automatically on first use and verified with SHA‑256, so you don’t have to manage model files yourself.

Key components

Task	Provided models
Face detection	RetinaFace, SCRFD, CenterFace, YOLOv5‑Face, YOLOv8‑Face, BlazeFace
Recognition	AdaFace, ArcFace, EdgeFace, MobileFace, SphereFace
Tracking	BYTETracker (persistent IDs)
Landmarks	2d106det (106 pts), PIPNet (98/68), Face‑Mesh (468/478 3‑D)
Parsing / Segmentation	BiSeNet (19 classes), XSeg
Portrait matting	MODNet (trimap‑free)
Gaze	MobileGaze (ResNet‑18/34/50, MobileNetV2)
Head pose	6‑D rotation → pitch/yaw/roll
Demographics	AgeGender, FairFace (age group, sex, race)
Emotion	AffectNet‑7 / AffectNet‑8
Face states	FaceAttribNet (eyes, glasses, mask, etc.)
Quality	eDifFIQA (tiny/small/medium/large)
Anti‑spoofing	MiniFASNet
Anonymisation	5 blur‑based methods
Vector store	FAISS‑backed embedding search

Typical usage – The high‑level FaceAnalyzer runs detection, alignment and (optionally) any attribute predictors you pass:

import cv2
from uniface import FaceAnalyzer, FairFace

analyzer = FaceAnalyzer(predictors=[FairFace()])
for face in analyzer.analyze(cv2.imread('photo.jpg')):
    print(face.bbox, face.sex, face.age_group, face.embedding.shape)

bbox, confidence, landmarks and embedding are always populated; other fields stay None until you add the corresponding predictor.

Installation

# CPU or Apple Silicon
pip install "uniface[cpu]"
# NVIDIA GPU with CUDA
pip install "uniface[gpu]"
# Get the latest pre‑release
pip install --pre "uniface[cpu]"

The package follows semantic versioning on PyPI and provides separate extras for CPU vs. GPU dependencies.

Documentation & community – Full docs, quick‑start guide, model zoo, and Jupyter notebooks are hosted at https://yakhyo.github.io/uniface/. A Discord server and GitHub issue tracker are available for support and contributions.

License – The code is MIT‑licensed. Some pretrained weights have their own licences, so check the Model licences page before commercial deployment.

---

UniFace is not related to the commercial product Uniface by Rocket Software.