uniface/README.md

UniFace: All-in-One Face Analysis Library

uniface is a lightweight face detection library designed for high-performance face localization and landmark detection. The library supports ONNX models and provides utilities for bounding box visualization and landmark plotting. To train RetinaFace model, see https://github.com/yakhyo/retinaface-pytorch.

---

Features

• Age and gender detection (Planned).
• Face recognition (Planned).
• Face Alignment (Added: 2024-11-21).
• High-speed face detection using ONNX models (Added: 2024-11-20).
• Accurate facial landmark localization (e.g., eyes, nose, and mouth) (Added: 2024-11-20).
• Easy-to-use API for inference and visualization (Added: 2024-11-20).

---

Installation

The easiest way to install UniFace is via PyPI. This will automatically install the library along with its prerequisites.

pip install uniface

To work with the latest version of UniFace, which may not yet be released on PyPI, you can install it directly from the repository:

git clone https://github.com/yakhyo/uniface.git
cd uniface
pip install .

---

Quick Start

Initialize the Model

from uniface import RetinaFace

# Initialize the RetinaFace model
uniface_inference = RetinaFace(
    model="retinaface_mnet_v2",  # Model name
    conf_thresh=0.5,             # Confidence threshold
    pre_nms_topk=5000,           # Pre-NMS Top-K detections
    nms_thresh=0.4,              # NMS IoU threshold
    post_nms_topk=750            # Post-NMS Top-K detections
)

Run Inference

Inference on image:

import cv2
from uniface.visualization import draw_detections

# Load an image
image_path = "assets/test.jpg"
original_image = cv2.imread(image_path)

# Perform inference
boxes, landmarks = uniface_inference.detect(original_image)

# Visualize results
draw_detections(original_image, (boxes, landmarks), vis_threshold=0.6)

# Save the output image
output_path = "output.jpg"
cv2.imwrite(output_path, original_image)
print(f"Saved output image to {output_path}")

Inference on video:

import cv2
from uniface.visualization import draw_detections

# Initialize the webcam
cap = cv2.VideoCapture(0)

if not cap.isOpened():
    print("Error: Unable to access the webcam.")
    exit()

while True:
    # Capture a frame from the webcam
    ret, frame = cap.read()
    if not ret:
        print("Error: Failed to read frame.")
        break

    # Perform inference
    boxes, landmarks = uniface_inference.detect(frame)

    # Draw detections on the frame
    draw_detections(frame, (boxes, landmarks), vis_threshold=0.6)

    # Display the output
    cv2.imshow("Webcam Inference", frame)

    # Exit if 'q' is pressed
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

# Release the webcam and close all OpenCV windows
cap.release()
cv2.destroyAllWindows()

---

Evaluation results of available models on WiderFace

RetinaFace Models	Easy	Medium	Hard
retinaface_mnet025	88.48%	87.02%	80.61%
retinaface_mnet050	89.42%	87.97%	82.40%
retinaface_mnet_v1	90.59%	89.14%	84.13%
retinaface_mnet_v2	91.70%	91.03%	86.60%
retinaface_r18	92.50%	91.02%	86.63%
retinaface_r34	94.16%	93.12%	88.90%

API Reference

RetinaFace Class

Initialization

RetinaFace(
    model: str,
    conf_thresh: float = 0.5,
    pre_nms_topk: int = 5000,
    nms_thresh: float = 0.4,
    post_nms_topk: int = 750
)

Parameters:

• model (str): Name of the model to use. Supported models:
  • retinaface_mnet025, retinaface_mnet050, retinaface_mnet_v1, retinaface_mnet_v2
  • retinaface_r18, retinaface_r34
• conf_thresh (float, default=0.5): Minimum confidence score for detections.
• pre_nms_topk (int, default=5000): Max detections to keep before NMS.
• nms_thresh (float, default=0.4): IoU threshold for Non-Maximum Suppression.
• post_nms_topk (int, default=750): Max detections to keep after NMS.

---

detect Method

detect(
    image: np.ndarray,
    max_num: int = 0,
    metric: str = "default",
    center_weight: float = 2.0
) -> Tuple[np.ndarray, np.ndarray]

Description: Detects faces in the given image and returns bounding boxes and landmarks.

Parameters:

• image (np.ndarray): Input image in BGR format.
• max_num (int, default=0): Maximum number of faces to return. 0 means return all.
• metric (str, default="default"): Metric for prioritizing detections:
  • "default": Prioritize detections closer to the image center.
  • "max": Prioritize larger bounding box areas.
• center_weight (float, default=2.0): Weight for prioritizing center-aligned faces.

Returns:

• bounding_boxes (np.ndarray): Array of detections as [x_min, y_min, x_max, y_max, confidence].
• landmarks (np.ndarray): Array of landmarks as [(x1, y1), ..., (x5, y5)].

---

Visualization Utilities

draw_detections

draw_detections(
    image: np.ndarray,
    detections: Tuple[np.ndarray, np.ndarray],
    vis_threshold: float
) -> None

Description: Draws bounding boxes and landmarks on the given image.

Parameters:

• image (np.ndarray): The input image in BGR format.
• detections (Tuple[np.ndarray, np.ndarray]): A tuple of bounding boxes and landmarks.
• vis_threshold (float): Minimum confidence score for visualization.

---

Contributing

We welcome contributions to enhance the library! Feel free to:

• Submit bug reports or feature requests.
• Fork the repository and create a pull request.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Acknowledgments

• Based on the RetinaFace model for face detection (https://github.com/yakhyo/retinaface-pytorch).
• Inspired by InsightFace and other face detection projects.

---