UniFace: All-in-One Face Analysis Library

3.5.0 · active · verified Wed Apr 15

UniFace is a lightweight, production-ready Python library built on ONNX Runtime for comprehensive face analysis. It provides high-performance capabilities for face detection, recognition, tracking, 106-point landmark detection, face parsing, gaze estimation, age, and gender detection, with hardware acceleration across various platforms. The library is actively maintained, with its current version being 3.5.0, and receives regular updates adding new features and models.

Warnings

breaking UniFace v3.0.0 introduced a redesigned unified API with standardized return types. Code written for versions prior to 3.0.0 may require updates to align with the new API format and data structures.
Fix: Review the official documentation and migration guides for UniFace v3.0.0 to understand the new API structure and update your code accordingly.
gotcha The library automatically downloads and caches models upon their first use. The default cache location is `~/.uniface/models`. This can be an issue in environments with restricted network access, limited disk space, or specific security policies.
Fix: Ensure network connectivity for initial model downloads. You can programmatically override the cache directory or pre-download models for offline deployments if needed. Check the documentation for `verify_model_weights` and environment variable options.
gotcha There have been inconsistent statements regarding Python 3.10 support. While PyPI and `pyproject.toml` for v3.5.0 indicate support for Python `>=3.10,<3.15`, the v3.1.1 changelog noted a drop of Python 3.10 support (setting minimum to 3.11), which was seemingly re-added in v3.3.0. For the latest versions, Python 3.10 is currently listed as supported, but ensure your environment meets the `>=3.10,<3.15` range.
Fix: Adhere to the `requires-python` range specified in the official PyPI metadata (`>=3.10,<3.15`). If you encounter issues with Python 3.10, consider upgrading to Python 3.11 or later within the supported range.
gotcha UniFace uses various underlying models, some of which may have licenses different from UniFace's MIT License. For example, YOLOv5-Face and YOLOv8-Face weights are GPL-3.0, and FairFace weights are CC BY 4.0. Users should be aware of these individual model licenses for compliance.
Fix: Consult the UniFace documentation or the source repositories of specific models if you are redistributing applications or models to ensure compliance with all applicable licenses.
deprecated In v3.1.1, the minimum required `scikit-image` version was bumped to `>=0.26.0`. Older versions of `scikit-image` may cause compatibility issues or unexpected behavior with UniFace versions 3.1.1 and newer.
Fix: Ensure `scikit-image` is updated to version `0.26.0` or higher to maintain compatibility and stability.

Install

pip install uniface Standard Install
pip install uniface[gpu] Install with CUDA support

Imports

RetinaFace

from uniface.detection import RetinaFace

FaceAnalyzer
```
from uniface import FaceAnalyzer
```
ArcFace
```
from uniface.recognition import ArcFace
```

Quickstart

This quickstart demonstrates how to initialize a RetinaFace detector and use it to detect faces in an image. Models are automatically downloaded and cached upon their first use. The example includes creating a dummy image and printing detection results. For real-world use, replace the dummy image with `cv2.imread('your_image.jpg')`.

import cv2
import numpy as np
from uniface.detection import RetinaFace

# Create a dummy image for demonstration
# In a real scenario, replace this with cv2.imread('your_image.jpg')
image = np.zeros((480, 640, 3), dtype=np.uint8)
cv2.putText(image, "Hello UniFace!", (100, 240), cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 2)

# Initialize the face detector (models download on first use)
detector = RetinaFace(confidence_threshold=0.5, nms_threshold=0.4)

# Detect faces in the image
faces = detector.detect(image)

if faces:
    print(f"Found {len(faces)} face(s).")
    for i, face in enumerate(faces, start=1):
        print(f"[Face {i}] Confidence: {face.confidence:.3f}, Bounding Box: {face.bbox}")
        # Optionally, you can draw bounding boxes or process further
        # Example: draw a rectangle around the first face
        if i == 1:
            x, y, w, h = int(face.bbox.x), int(face.bbox.y), int(face.bbox.width), int(face.bbox.height)
            cv2.rectangle(image, (x, y), (x + w, y + h), (0, 255, 0), 2)
else:
    print("No faces detected.")

# You can also use FaceAnalyzer for an all-in-one approach:
# from uniface import FaceAnalyzer
# analyzer = FaceAnalyzer()
# analyzed_faces = analyzer.analyze(image)
# for face in analyzed_faces:
#     print(face.bbox, face.embedding.shape if face.embedding is not None else None)

view raw JSON →