Face Attribute Detection

Tip

The models and functionality in this repository are being integrated into UniFace — an all-in-one face analysis toolkit.

PyTorch inference, ONNX export, and ONNX Runtime inference for FaceAttribNet — a lightweight model that predicts five face attributes at once from a 128×128 face crop. Uses UniFace for face detection.

Models

Model	Params	Input	PyTorch (.pt)	ONNX
FaceAttribNet	10.84M	128x128	Link	Link

The .pt is an unmodified mirror of the original checkpoint. The .onnx is re-exported from it at opset 17 with a dynamic batch dimension, as a single self-contained file (loadable on onnxruntime>=1.16), numerically identical to the original export.

Attributes

The model outputs five probabilities in [0, 1]: left_eye_open, right_eye_open, eyeglasses, mask, sunglasses — in that order.

Important

These are five independent binary heads, not one 5-way softmax: values do not sum to 1 and several can be high at once. Threshold each attribute separately; never argmax.

Installation

pip install -r requirements.txt

Download the weights from the release (the .onnx alone is enough for inference):

mkdir -p weights
curl -L -o weights/face_attrib_net.onnx https://github.com/yakhyo/face-attribute/releases/download/weights/face_attrib_net.onnx
curl -L -o weights/detection_only_05302025.pt https://github.com/yakhyo/face-attribute/releases/download/weights/detection_only_05302025.pt

Demo

Attributes above the detection threshold (0.5), predicted per face:

Sunglasses	Tinted sunglasses	Face mask	Eyeglasses	Eyes closed
sunglasses 1.000	sunglasses 0.993, eyes still detected open	mask 1.000	eyeglasses 0.999	eye openness ≤ 0.16
sunglasses 0.999		mask 1.000	eyeglasses 0.903

Multiple faces: only the left person triggers eyeglasses (0.893)

python onnx_inference.py assets/test_images/*.jpg --save-dir assets/results

Test photos are free-license images from Pexels.

Inference

The model takes a 128×128 face crop. Both scripts take full images and handle detection and cropping for you.

PyTorch

python main.py assets/test_images/group.jpg

ONNX

python onnx_inference.py assets/test_images/group.jpg

Sources can be image paths or webcam indices, freely mixed. A numeric source opens that camera with a live annotated preview:

python onnx_inference.py 0                        # default webcam; q/ESC quits
python onnx_inference.py 0 --save-dir snapshots   # press s to save an annotated frame

import cv2
from models import FaceAttribute
from uniface.detection import SCRFD

detector = SCRFD()
attrib = FaceAttribute('weights/face_attrib_net.onnx')

image = cv2.imread('image.jpg')
for face in detector.detect(image):
    result = attrib.predict(image, face.bbox)
    print(result.as_dict())            # {'left_eye_open': 0.99, ...}
    print(result.labels(threshold=0.5))  # e.g. ['left_eye_open', 'right_eye_open', 'eyeglasses']

Preprocessing

Aspect-preserving resize to 128×128 (centered letterbox), RGB, values in [0, 1]. Mean/std normalization is baked into the model graph — do not normalize again.

ONNX Export

python onnx_export.py -w weights/detection_only_05302025.pt -o weights/face_attrib_net.onnx

The export is verified against the PyTorch reference on the spot. --dynamic enables a dynamic batch dimension.

Reference

• AI Hub Models — face_attrib_net — Original model, architecture, and weights
• UniFace — Face detection

License

BSD-3-Clause