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
# Copyright 2025-2026 Yakhyokhuja Valikhujaev
# Author: Yakhyokhuja Valikhujaev
# GitHub: https://github.com/yakhyo
"""Shared drawing helpers for the demo tools (attribute cards and face parsing overlays).
OpenCV-only, so the tools need nothing beyond UniFace's own dependencies. These live in
``tools/`` on purpose: they style the demos and are not part of the ``uniface`` API.
"""
from __future__ import annotations
from dataclasses import dataclass
import cv2
import numpy as np
ACCENT = (225, 235, 120) # BGR teal used for boxes, confidence bars and percentages
CARD_BG = (17, 17, 17)
CARD_ALPHA = 0.78
MUTED = (180, 180, 180)
WHITE = (255, 255, 255)
FONT = cv2.FONT_HERSHEY_SIMPLEX
FONT_BOLD = cv2.FONT_HERSHEY_DUPLEX
def ui_scale(image: np.ndarray) -> float:
"""Scale factor for overlay sizes, relative to a 1080 px short edge."""
return float(np.clip(min(image.shape[:2]) / 1080.0, 0.45, 2.0))
# --------------------------------------------------------------------------- boxes
def draw_corner_box(
image: np.ndarray,
bbox: np.ndarray | list[float],
color: tuple[int, int, int] = ACCENT,
thickness: int | None = None,
corner_frac: float = 0.22,
) -> None:
"""Draw a thin full rectangle with bold corners, in place.
Args:
image: BGR image to draw on.
bbox: Box as [x1, y1, x2, y2].
color: Line color in BGR.
thickness: Corner thickness in pixels. Defaults to a value scaled to the image.
corner_frac: Corner length as a fraction of the box side.
"""
x1, y1, x2, y2 = (round(v) for v in bbox[:4])
t = thickness or max(2, round(4 * ui_scale(image)))
overlay = image.copy()
cv2.rectangle(overlay, (x1, y1), (x2, y2), color, 1, cv2.LINE_AA)
cv2.addWeighted(overlay, 0.45, image, 0.55, 0, dst=image)
lx, ly = int((x2 - x1) * corner_frac), int((y2 - y1) * corner_frac)
for x, y, sx, sy in ((x1, y1, 1, 1), (x2, y1, -1, 1), (x1, y2, 1, -1), (x2, y2, -1, -1)):
cv2.line(image, (x, y), (x + sx * lx, y), color, t, cv2.LINE_AA)
cv2.line(image, (x, y), (x, y + sy * ly), color, t, cv2.LINE_AA)
# --------------------------------------------------------------------------- attribute cards
@dataclass
class Card:
"""Content of one attribute card.
Attributes:
title: Small grey caption, e.g. ``'Emotion'``.
value: Main value in large type, e.g. ``'Happy'``.
confidence: Optional score in [0, 1], shown as a percentage and a bar.
subtitle: Optional second line, e.g. ``'Male · Age 37'``.
"""
title: str
value: str
confidence: float | None = None
subtitle: str | None = None
def _card_size(card: Card, s: float) -> tuple[int, int, dict]:
pad = int(20 * s)
sizes = {
'title': (0.55 * s, max(1, round(1.2 * s))),
'value': (1.05 * s, max(1, round(1.8 * s))),
'pct': (0.6 * s, max(1, round(1.4 * s))),
'sub': (0.6 * s, max(1, round(1.4 * s))),
}
def tw(text, key, font=FONT):
sc, th = sizes[key]
return cv2.getTextSize(text, font, sc, th)[0]
w_title, h_title = tw(card.title, 'title')
w_value, h_value = tw(card.value, 'value', FONT_BOLD)
w_pct = tw(f'{card.confidence * 100:.0f}%', 'pct')[0] + int(14 * s) if card.confidence is not None else 0
w_sub, h_sub = tw(card.subtitle, 'sub') if card.subtitle else (0, 0)
width = max(w_title, w_value + w_pct, w_sub, int(220 * s)) + 2 * pad
height = pad + h_title + int(14 * s) + h_value + pad // 2
if card.confidence is not None:
height += int(16 * s)
if card.subtitle:
height += h_sub + int(14 * s)
height += pad // 2
return width, height, {'pad': pad, 'sizes': sizes, 'h_title': h_title, 'h_value': h_value, 'h_sub': h_sub}
def _render_card(image: np.ndarray, card: Card, x: int, y: int, s: float) -> None:
w, h, m = _card_size(card, s)
H, W = image.shape[:2]
x0, y0, x1, y1 = max(x, 0), max(y, 0), min(x + w, W), min(y + h, H)
if x1 <= x0 or y1 <= y0:
return
# translucent rounded background, blended only inside the card's region
roi = image[y0:y1, x0:x1]
bg = roi.copy()
r = int(18 * s)
rx0, ry0, rx1, ry1 = x - x0, y - y0, x - x0 + w - 1, y - y0 + h - 1
cv2.rectangle(bg, (rx0 + r, ry0), (rx1 - r, ry1), CARD_BG, -1)
cv2.rectangle(bg, (rx0, ry0 + r), (rx1, ry1 - r), CARD_BG, -1)
for cx, cy in ((rx0 + r, ry0 + r), (rx1 - r, ry0 + r), (rx0 + r, ry1 - r), (rx1 - r, ry1 - r)):
cv2.circle(bg, (cx, cy), r, CARD_BG, -1, cv2.LINE_AA)
cv2.addWeighted(bg, CARD_ALPHA, roi, 1 - CARD_ALPHA, 0, dst=roi)
pad, sz = m['pad'], m['sizes']
tx = x + pad
ty = y + pad + m['h_title']
cv2.putText(image, card.title, (tx, ty), FONT, sz['title'][0], MUTED, sz['title'][1], cv2.LINE_AA)
ty += int(14 * s) + m['h_value']
cv2.putText(image, card.value, (tx, ty), FONT_BOLD, sz['value'][0], WHITE, sz['value'][1], cv2.LINE_AA)
if card.confidence is not None:
pct = f'{card.confidence * 100:.0f}%'
pw = cv2.getTextSize(pct, FONT, sz['pct'][0], sz['pct'][1])[0][0]
cv2.putText(image, pct, (x + w - pad - pw, ty), FONT, sz['pct'][0], ACCENT, sz['pct'][1], cv2.LINE_AA)
by = ty + int(12 * s)
bh = max(2, int(5 * s))
cv2.rectangle(image, (tx, by), (x + w - pad, by + bh), (70, 70, 70), -1)
fill = tx + int((w - 2 * pad) * float(np.clip(card.confidence, 0, 1)))
cv2.rectangle(image, (tx, by), (fill, by + bh), ACCENT, -1)
ty = by + bh
if card.subtitle:
ty += int(14 * s) + m['h_sub']
cv2.putText(image, card.subtitle, (tx, ty), FONT, sz['sub'][0], WHITE, sz['sub'][1], cv2.LINE_AA)
def _overlaps(a, b) -> bool:
return not (a[2] <= b[0] or b[2] <= a[0] or a[3] <= b[1] or b[3] <= a[1])
def draw_attribute_cards(
image: np.ndarray,
items: list[tuple[np.ndarray, Card]],
*,
draw_boxes: bool = True,
) -> None:
"""Draw a corner box and an attribute card for every face, in place.
Cards are placed beside their face (right, then left), or below / above it when the
sides are taken, avoiding the other faces and cards so several people stay readable.
Args:
image: BGR image to draw on.
items: One ``(bbox, Card)`` per face, bbox as [x1, y1, x2, y2].
draw_boxes: Also draw the corner box around each face.
"""
s = ui_scale(image)
H, W = image.shape[:2]
gap, margin = int(16 * s), int(10 * s)
boxes = [tuple(float(v) for v in b[:4]) for b, _ in items]
if draw_boxes:
for b in boxes:
draw_corner_box(image, b)
placed: list[tuple[int, int, int, int]] = []
order = sorted(range(len(items)), key=lambda k: boxes[k][0]) # left -> right
for rank, k in enumerate(order):
x1, y1, x2, y2 = boxes[k]
card = items[k][1]
w, h, _ = _card_size(card, s)
cx = (x1 + x2) / 2 - w / 2
# outer side first when several faces sit next to each other
sides = ['left', 'right'] if (len(order) > 1 and rank == 0) else ['right', 'left']
candidates = {
'right': (x2 + gap, y1),
'left': (x1 - gap - w, y1),
'below': (x1 if rank == 0 and len(order) > 1 else cx, y2 + gap),
'above': (cx, y1 - gap - h),
}
if len(order) > 1 and rank == len(order) - 1:
candidates['below'] = (x2 - w, y2 + gap)
chosen = None
for name in [*sides, 'below', 'above']:
px, py = candidates[name]
px = int(np.clip(px, margin, max(margin, W - w - margin)))
py = int(np.clip(py, margin, max(margin, H - h - margin)))
rect = (px, py, px + w, py + h)
others = [boxes[j] for j in range(len(boxes)) if j != k]
if any(_overlaps(rect, o) for o in placed + others) or _overlaps(rect, boxes[k]):
continue
chosen = (px, py)
break
if chosen is None: # crowded frame: fall back to just below the face
chosen = (int(np.clip(cx, margin, max(margin, W - w - margin))), int(min(y2 + gap, H - h - margin)))
placed.append((chosen[0], chosen[1], chosen[0] + w, chosen[1] + h))
_render_card(image, card, chosen[0], chosen[1], s)
# --------------------------------------------------------------------------- face parsing
# CelebAMask-HQ classes predicted by BiSeNet. Only face parts are coloured; background,
# neck, clothing and accessories stay untouched so there is no visible crop rectangle.
PARSING_COLORS_BGR = {
1: (150, 196, 255), # skin
2: (255, 90, 120), # left brow
3: (255, 90, 120), # right brow
4: (255, 200, 90), # left eye
5: (255, 200, 90), # right eye
6: (90, 230, 255), # eyeglasses
7: (90, 140, 255), # left ear
8: (90, 140, 255), # right ear
10: (225, 235, 120), # nose
11: (135, 105, 255), # mouth
12: (110, 70, 255), # upper lip
13: (110, 70, 255), # lower lip
17: (255, 120, 170), # hair
}
def _parsing_lut(alpha: float, skin_alpha: float) -> tuple[np.ndarray, np.ndarray]:
lut = np.zeros((256, 3), np.float32)
lut_a = np.zeros(256, np.float32)
for cls, color in PARSING_COLORS_BGR.items():
lut[cls] = color
lut_a[cls] = skin_alpha if cls == 1 else alpha
return lut, lut_a
def draw_face_parsing(
image: np.ndarray,
mask: np.ndarray,
region: tuple[int, int, int, int] | None = None,
*,
alpha: float = 0.62,
skin_alpha: float = 0.38,
contours: bool = True,
) -> None:
"""Overlay a face-parsing mask on the image, in place.
Args:
image: BGR image to draw on (the full frame).
mask: Class-id mask from ``BiSeNet.parse``. Either full-frame sized, or the size of
``region`` when the face was parsed from a crop.
region: ``(x1, y1, x2, y2)`` of the crop the mask belongs to; None if full-frame.
alpha: Opacity for face parts.
skin_alpha: Opacity for skin, kept lighter so the face stays readable.
contours: Draw thin white lines between parts.
"""
x1, y1, x2, y2 = region if region is not None else (0, 0, image.shape[1], image.shape[0])
roi = image[y1:y2, x1:x2]
if roi.size == 0:
return
m = mask.astype(np.uint8)
if m.shape[:2] != roi.shape[:2]:
m = cv2.resize(m, (roi.shape[1], roi.shape[0]), interpolation=cv2.INTER_NEAREST)
lut, lut_a = _parsing_lut(alpha, skin_alpha)
color = lut[m]
a = lut_a[m]
sigma = max(0.6, min(roi.shape[:2]) / 400) # soften the class edges a touch
color = cv2.GaussianBlur(color, (0, 0), sigma)
a = cv2.GaussianBlur(a, (0, 0), sigma)[..., None]
out = roi.astype(np.float32) * (1 - a) + color * a
if contours:
shown = np.where(lut_a[m] > 0, m, 0).astype(np.uint8)
edges = cv2.Canny(shown, 0, 0) > 0
out[edges] = out[edges] * 0.4 + 255 * 0.6
roi[:] = np.clip(out, 0, 255).astype(np.uint8)