feat: Add head pose estimation model (#99)

* feat: Add Head Pose Estimation  with 6 different models

* chore: Update jupyter notebook examples

* docs: Update head pose estimation related docs

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.11"
       - uses: pre-commit/action@v3.0.1
 
   test:
@@ -34,9 +34,11 @@ jobs:
         include:
           # Full Python range on Linux (fastest runner)
           - os: ubuntu-latest
-            python-version: "3.10"
+            python-version: "3.11"
           - os: ubuntu-latest
             python-version: "3.13"
+          - os: ubuntu-latest
+            python-version: "3.14"
           - os: macos-latest
             python-version: "3.13"
           - os: windows-latest

.github/workflows/docs.yml

@@ -2,7 +2,8 @@ name: Deploy docs
 
 on:
   push:
-    branches: [main]
+    tags:
+      - "v*.*.*"
   workflow_dispatch:
 
 permissions:

.github/workflows/publish.yml

@@ -54,7 +54,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.13"]
+        python-version: ["3.11", "3.13"]
 
     steps:
       - name: Checkout code
@@ -92,7 +92,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.11"
           cache: 'pip'
 
       - name: Install build tools

CONTRIBUTING.md

@@ -59,12 +59,12 @@ This project uses [Ruff](https://docs.astral.sh/ruff/) for linting and formattin
 #### General Rules
 
 - **Line length:** 120 characters maximum
-- **Python version:** 3.10+ (use modern syntax)
+- **Python version:** 3.11+ (use modern syntax)
 - **Quote style:** Single quotes for strings, double quotes for docstrings
 
 #### Type Hints
 
-Use modern Python 3.10+ type hints (PEP 585 and PEP 604):
+Use modern Python 3.11+ type hints (PEP 585 and PEP 604):
 
 ```python
 # Preferred (modern)
@@ -184,6 +184,9 @@ Example notebooks demonstrating library usage:
 | Face Parsing       | [06_face_parsing.ipynb](examples/06_face_parsing.ipynb)             |
 | Face Anonymization | [07_face_anonymization.ipynb](examples/07_face_anonymization.ipynb) |
 | Gaze Estimation    | [08_gaze_estimation.ipynb](examples/08_gaze_estimation.ipynb)       |
+| Face Segmentation  | [09_face_segmentation.ipynb](examples/09_face_segmentation.ipynb)   |
+| Face Vector Store  | [10_face_vector_store.ipynb](examples/10_face_vector_store.ipynb)   |
+| Head Pose Estimation | [11_head_pose_estimation.ipynb](examples/11_head_pose_estimation.ipynb) |
 
 ## Questions?
 

README.md

@@ -3,7 +3,7 @@
 <div align="center">
 
 [![PyPI Version](https://img.shields.io/pypi/v/uniface.svg?label=Version)](https://pypi.org/project/uniface/)
-[![Python Version](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
+[![Python Version](https://img.shields.io/badge/Python-3.11%2B-blue)](https://www.python.org/)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Github Build Status](https://github.com/yakhyo/uniface/actions/workflows/ci.yml/badge.svg)](https://github.com/yakhyo/uniface/actions)
 [![PyPI Downloads](https://static.pepy.tech/personalized-badge/uniface?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=BLUE&left_text=Downloads)](https://pepy.tech/projects/uniface)
@@ -14,7 +14,7 @@
 </div>
 
 <div align="center">
-    <img src="https://raw.githubusercontent.com/yakhyo/uniface/main/.github/logos/new/uniface_rounded_q80.webp" width="90%" alt="UniFace - All-in-One Open-Source Face Analysis Library">
+    <img src="https://raw.githubusercontent.com/yakhyo/uniface/main/.github/logos/uniface_rounded_q80.webp" width="90%" alt="UniFace - All-in-One Open-Source Face Analysis Library">
 </div>
 
 ---
@@ -31,7 +31,9 @@
 - **Facial Landmarks** — 106-point landmark localization module (separate from 5-point detector landmarks)
 - **Face Parsing** — BiSeNet semantic segmentation (19 classes), XSeg face masking
 - **Gaze Estimation** — Real-time gaze direction with MobileGaze
+- **Head Pose Estimation** — 3D head orientation (pitch, yaw, roll) with 6D rotation representation
 - **Attribute Analysis** — Age, gender, race (FairFace), and emotion
+- **Vector Indexing** — FAISS-backed embedding store for fast multi-identity search
 - **Anti-Spoofing** — Face liveness detection with MiniFASNet
 - **Face Anonymization** — 5 blur methods for privacy protection
 - **Hardware Acceleration** — ARM64 (Apple Silicon), CUDA (NVIDIA), CPU
@@ -59,6 +61,12 @@ git clone https://github.com/yakhyo/uniface.git
 cd uniface && pip install -e .
 ```
 
+**FAISS vector indexing**
+
+```bash
+pip install faiss-cpu   # or faiss-gpu for CUDA
+```
+
 **Optional dependencies**
 - Emotion model uses TorchScript and requires `torch`:
   `pip install torch` (choose the correct build for your OS/CUDA)
@@ -165,6 +173,24 @@ Full documentation: https://yakhyo.github.io/uniface/
 | [API Reference](https://yakhyo.github.io/uniface/modules/detection/) | Detailed module documentation |
 | [Tutorials](https://yakhyo.github.io/uniface/recipes/image-pipeline/) | Step-by-step workflow examples |
 | [Guides](https://yakhyo.github.io/uniface/concepts/overview/) | Architecture and design principles |
+| [Datasets](https://yakhyo.github.io/uniface/datasets/) | Training data and evaluation benchmarks |
+
+---
+
+## Datasets
+
+| Task | Training Dataset | Models |
+|------|-----------------|--------|
+| Detection | WIDER FACE | RetinaFace, SCRFD, YOLOv5-Face, YOLOv8-Face |
+| Recognition | MS1MV2 | MobileFace, SphereFace |
+| Recognition | WebFace600K | ArcFace |
+| Recognition | WebFace4M / 12M | AdaFace |
+| Gaze | Gaze360 | MobileGaze |
+| Head Pose | 300W-LP | HeadPose (ResNet, MobileNet) |
+| Parsing | CelebAMask-HQ | BiSeNet |
+| Attributes | CelebA, FairFace, AffectNet | AgeGender, FairFace, Emotion |
+
+> See [Datasets documentation](https://yakhyo.github.io/uniface/datasets/) for download links, benchmarks, and details.
 
 ---
 
@@ -181,6 +207,8 @@ Full documentation: https://yakhyo.github.io/uniface/
 | [07_face_anonymization.ipynb](examples/07_face_anonymization.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/07_face_anonymization.ipynb) | Privacy-preserving blur |
 | [08_gaze_estimation.ipynb](examples/08_gaze_estimation.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/08_gaze_estimation.ipynb) | Gaze direction estimation |
 | [09_face_segmentation.ipynb](examples/09_face_segmentation.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/09_face_segmentation.ipynb) | Face segmentation with XSeg |
+| [10_face_vector_store.ipynb](examples/10_face_vector_store.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/10_face_vector_store.ipynb) | FAISS-backed face database |
+| [11_head_pose_estimation.ipynb](examples/11_head_pose_estimation.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/11_head_pose_estimation.ipynb) | Head pose estimation (pitch, yaw, roll) |
 
 ---
 
@@ -209,6 +237,7 @@ If you plan commercial use, verify model license compatibility.
 | Parsing | [face-parsing](https://github.com/yakhyo/face-parsing) | ✓ | BiSeNet Face Parsing |
 | Parsing | [face-segmentation](https://github.com/yakhyo/face-segmentation) | - | XSeg Face Segmentation |
 | Gaze | [gaze-estimation](https://github.com/yakhyo/gaze-estimation) | ✓ | MobileGaze Training |
+| Head Pose | [head-pose-estimation](https://github.com/yakhyo/head-pose-estimation) | ✓ | Head Pose Training (6DRepNet-style) |
 | Anti-Spoofing | [face-anti-spoofing](https://github.com/yakhyo/face-anti-spoofing) | - | MiniFASNet Inference |
 | Attributes | [fairface-onnx](https://github.com/yakhyo/fairface-onnx) | - | FairFace ONNX Inference |
 

docs/concepts/execution-providers.md

@@ -39,16 +39,20 @@ recognizer = ArcFace(providers=['CPUExecutionProvider'])
 detector = RetinaFace(providers=['CUDAExecutionProvider', 'CPUExecutionProvider'])
 ```
 
-All model classes accept the `providers` parameter:
+All **ONNX-based** model classes accept the `providers` parameter:
 
 - Detection: `RetinaFace`, `SCRFD`, `YOLOv5Face`, `YOLOv8Face`
 - Recognition: `ArcFace`, `AdaFace`, `MobileFace`, `SphereFace`
 - Landmarks: `Landmark106`
 - Gaze: `MobileGaze`
-- Parsing: `BiSeNet`
+- Parsing: `BiSeNet`, `XSeg`
 - Attributes: `AgeGender`, `FairFace`
 - Anti-Spoofing: `MiniFASNet`
 
+!!! note "Non-ONNX components"
+    - **Emotion** uses TorchScript and selects its device automatically (`mps` / `cuda` / `cpu`). It does **not** accept the `providers` parameter.
+    - **BlurFace** is a pure OpenCV utility and does not load any model.
+
 ---
 
 ## Check Available Providers

docs/concepts/inputs-outputs.md

@@ -106,6 +106,27 @@ print(f"Yaw: {np.degrees(result.yaw):.1f}°")
 
 ---
 
+### HeadPoseResult
+
+```python
+@dataclass(frozen=True)
+class HeadPoseResult:
+    pitch: float  # Rotation around X-axis (degrees), + = looking down
+    yaw: float    # Rotation around Y-axis (degrees), + = looking right
+    roll: float   # Rotation around Z-axis (degrees), + = tilting clockwise
+```
+
+**Usage:**
+
+```python
+result = head_pose.estimate(face_crop)
+print(f"Pitch: {result.pitch:.1f}°")
+print(f"Yaw: {result.yaw:.1f}°")
+print(f"Roll: {result.roll:.1f}°")
+```
+
+---
+
 ### SpoofingResult
 
 ```python
@@ -144,11 +165,11 @@ class AttributeResult:
 
 ```python
 # AgeGender model
-result = age_gender.predict(image, face.bbox)
+result = age_gender.predict(image, face)
 print(f"{result.sex}, {result.age} years old")
 
 # FairFace model
-result = fairface.predict(image, face.bbox)
+result = fairface.predict(image, face)
 print(f"{result.sex}, {result.age_group}, {result.race}")
 ```
 
@@ -171,7 +192,7 @@ Face recognition models return normalized 512-dimensional embeddings:
 
 ```python
 embedding = recognizer.get_normalized_embedding(image, landmarks)
-print(f"Shape: {embedding.shape}")  # (1, 512)
+print(f"Shape: {embedding.shape}")  # (512,)
 print(f"Norm: {np.linalg.norm(embedding):.4f}")  # ~1.0
 ```
 

docs/concepts/overview.md

@@ -23,6 +23,7 @@ graph TB
         LMK[Landmarks]
         ATTR[Attributes]
         GAZE[Gaze]
+        HPOSE[Head Pose]
         PARSE[Parsing]
         SPOOF[Anti-Spoofing]
         PRIV[Privacy]
@@ -32,6 +33,10 @@ graph TB
         TRK[BYTETracker]
     end
 
+    subgraph Indexing
+        IDX[FAISS Vector Store]
+    end
+
     subgraph Output
         FACE[Face Objects]
     end
@@ -41,10 +46,12 @@ graph TB
     DET --> LMK
     DET --> ATTR
     DET --> GAZE
+    DET --> HPOSE
     DET --> PARSE
     DET --> SPOOF
     DET --> PRIV
     DET --> TRK
+    REC --> IDX
     REC --> FACE
     LMK --> FACE
     ATTR --> FACE
@@ -57,12 +64,14 @@ graph TB
 
 ### 1. ONNX-First
 
-All models use ONNX Runtime for inference:
+UniFace runs inference primarily via ONNX Runtime for core components:
 
 - **Cross-platform**: Same models work on macOS, Linux, Windows
 - **Hardware acceleration**: Automatic selection of optimal provider
 - **Production-ready**: No Python-only dependencies for inference
 
+Some optional components (e.g., emotion TorchScript, torchvision NMS) require PyTorch.
+
 ### 2. Minimal Dependencies
 
 Core dependencies are kept minimal:
@@ -112,9 +121,11 @@ uniface/
 ├── attribute/      # Age, gender, emotion, race
 ├── parsing/        # Face semantic segmentation
 ├── gaze/           # Gaze estimation
+├── headpose/       # Head pose estimation
 ├── spoofing/       # Anti-spoofing
 ├── privacy/        # Face anonymization
-├── types.py        # Dataclasses (Face, GazeResult, etc.)
+├── indexing/       # Vector indexing (FAISS)
+├── types.py        # Dataclasses (Face, GazeResult, HeadPoseResult, etc.)
 ├── constants.py    # Model weights and URLs
 ├── model_store.py  # Model download and caching
 ├── onnx_utils.py   # ONNX Runtime utilities
@@ -150,7 +161,7 @@ for face in faces:
     embedding = recognizer.get_normalized_embedding(image, face.landmarks)
 
     # Attributes
-    attrs = age_gender.predict(image, face.bbox)
+    attrs = age_gender.predict(image, face)
 
     print(f"Face: {attrs.sex}, {attrs.age} years")
 ```
@@ -175,8 +186,7 @@ fairface = FairFace()
 analyzer = FaceAnalyzer(
     detector,
     recognizer=recognizer,
-    age_gender=age_gender,
-    fairface=fairface,
+    attributes=[age_gender, fairface],
 )
 
 faces = analyzer.analyze(image)

docs/contributing.md

@@ -32,7 +32,7 @@ ruff check . --fix
 **Guidelines:**
 
 - Line length: 120
-- Python 3.10+ type hints
+- Python 3.11+ type hints
 - Google-style docstrings
 
 ---

docs/datasets.md

@@ -0,0 +1,348 @@
+# Datasets
+
+Overview of all training datasets and evaluation benchmarks used by UniFace models.
+
+---
+
+## Quick Reference
+
+| Task        | Dataset                                          | Scale                  | Models                                      |
+| ----------- | ------------------------------------------------ | ---------------------- | ------------------------------------------- |
+| Detection   | [WIDER FACE](#wider-face)                        | 32K images             | RetinaFace, SCRFD, YOLOv5-Face, YOLOv8-Face |
+| Recognition | [MS1MV2](#ms1mv2)                                | 5.8M images, 85.7K IDs | MobileFace, SphereFace                      |
+| Recognition | [WebFace600K](#webface600k)                      | 600K images            | ArcFace                                     |
+| Recognition | [WebFace4M / WebFace12M](#webface4m--webface12m) | 4M / 12M images        | AdaFace                                     |
+| Gaze        | [Gaze360](#gaze360)                              | 238 subjects           | MobileGaze                                  |
+| Parsing     | [CelebAMask-HQ](#celebamask-hq)                  | 30K images             | BiSeNet                                     |
+| Attributes  | [CelebA](#celeba)                                | 200K images            | AgeGender                                   |
+| Attributes  | [FairFace](#fairface)                            | Balanced demographics  | FairFace                                    |
+| Attributes  | [AffectNet](#affectnet)                          | Emotion labels         | Emotion                                     |
+
+---
+
+## Training Datasets
+
+### Face Detection
+
+#### WIDER FACE
+
+Large-scale face detection benchmark with images across 61 event categories. Contains faces with a high degree of variability in scale, pose, occlusion, expression, and illumination.
+
+| Property | Value                                       |
+| -------- | ------------------------------------------- |
+| Images   | ~32,000 (train/val/test split)              |
+| Faces    | ~394,000 annotated                          |
+| Subsets  | Easy, Medium, Hard                          |
+| Used by  | RetinaFace, SCRFD, YOLOv5-Face, YOLOv8-Face |
+
+!!! info "Download & References"
+**Paper**: [WIDER FACE: A Face Detection Benchmark](https://arxiv.org/abs/1511.06523)
+
+    **Download**: [http://shuoyang1213.me/WIDERFACE/](http://shuoyang1213.me/WIDERFACE/)
+
+---
+
+### Face Recognition
+
+#### MS1MV2
+
+Refined version of the MS-Celeb-1M dataset, cleaned by InsightFace. Widely used for training face recognition models.
+
+| Property   | Value                          |
+| ---------- | ------------------------------ |
+| Identities | 85.7K                          |
+| Images     | 5.8M                           |
+| Format     | Aligned and cropped to 112x112 |
+| Used by    | MobileFace, SphereFace         |
+
+!!! info "Download"
+**Kaggle (aligned 112x112)**: [ms1m-arcface-dataset](https://www.kaggle.com/datasets/yakhyokhuja/ms1m-arcface-dataset) (from InsightFace)
+
+    **Training code**: [yakhyo/face-recognition](https://github.com/yakhyo/face-recognition)
+
+---
+
+#### WebFace600K
+
+Medium-scale face recognition dataset from the WebFace series.
+
+| Property | Value   |
+| -------- | ------- |
+| Images   | ~600K   |
+| Used by  | ArcFace |
+
+!!! info "Source"
+**Origin**: [InsightFace](https://github.com/deepinsight/insightface)
+
+    **Paper**: [ArcFace: Additive Angular Margin Loss for Deep Face Recognition](https://arxiv.org/abs/1801.07698)
+
+---
+
+#### WebFace4M / WebFace12M
+
+Large-scale face recognition datasets from the WebFace260M collection. Used for training AdaFace models with adaptive quality-aware margin.
+
+| Property | WebFace4M     | WebFace12M     |
+| -------- | ------------- | -------------- |
+| Images   | ~4M           | ~12M           |
+| Used by  | AdaFace IR_18 | AdaFace IR_101 |
+
+!!! info "Source"
+**Paper**: [AdaFace: Quality Adaptive Margin for Face Recognition](https://arxiv.org/abs/2204.00964)
+
+    **Original code**: [mk-minchul/AdaFace](https://github.com/mk-minchul/AdaFace)
+
+---
+
+#### CASIA-WebFace
+
+Smaller-scale face recognition dataset suitable for academic research and lighter training runs.
+
+| Property   | Value                          |
+| ---------- | ------------------------------ |
+| Identities | 10.6K                          |
+| Images     | 491K                           |
+| Format     | Aligned and cropped to 112x112 |
+| Used by    | Alternative training set       |
+
+!!! info "Download"
+**Kaggle (aligned 112x112)**: [webface-112x112](https://www.kaggle.com/datasets/yakhyokhuja/webface-112x112) (from OpenSphere)
+
+---
+
+#### VGGFace2
+
+Large-scale dataset with wide variations in pose, age, illumination, ethnicity, and profession.
+
+| Property   | Value                          |
+| ---------- | ------------------------------ |
+| Identities | 8.6K                           |
+| Images     | 3.1M                           |
+| Format     | Aligned and cropped to 112x112 |
+| Used by    | Alternative training set       |
+
+!!! info "Download"
+**Kaggle (aligned 112x112)**: [vggface2-112x112](https://www.kaggle.com/datasets/yakhyokhuja/vggface2-112x112) (from OpenSphere)
+
+---
+
+### Gaze Estimation
+
+#### Gaze360
+
+Large-scale gaze estimation dataset collected in indoor and outdoor environments with diverse head poses and wide gaze ranges (up to 360 degrees).
+
+| Property    | Value                 |
+| ----------- | --------------------- |
+| Subjects    | 238                   |
+| Environment | Indoor and outdoor    |
+| Used by     | All MobileGaze models |
+
+!!! info "Download & Preprocessing"
+**Download**: [gaze360.csail.mit.edu/download.php](https://gaze360.csail.mit.edu/download.php)
+
+    **Preprocessing**: [GazeHub - Gaze360](https://phi-ai.buaa.edu.cn/Gazehub/3D-dataset/#gaze360)
+
+!!! note "UniFace Models"
+All MobileGaze models shipped with UniFace are trained exclusively on Gaze360 for 200 epochs.
+
+**Dataset structure:**
+
+```
+data/
+└── Gaze360/
+    ├── Image/
+    └── Label/
+```
+
+---
+
+#### MPIIFaceGaze
+
+Dataset for appearance-based gaze estimation from laptop webcam images of participants during everyday laptop usage. Supported by the gaze estimation training code but not used for the UniFace pretrained weights.
+
+| Property    | Value                                    |
+| ----------- | ---------------------------------------- |
+| Subjects    | 15                                       |
+| Environment | Everyday laptop usage                    |
+| Used by     | Supported (not used for UniFace weights) |
+
+!!! info "Download & Preprocessing"
+**Download**: [MPIIFaceGaze download page](https://www.mpi-inf.mpg.de/departments/computer-vision-and-machine-learning/research/gaze-based-human-computer-interaction/its-written-all-over-your-face-full-face-appearance-based-gaze-estimation)
+
+    **Preprocessing**: [GazeHub - MPIIFaceGaze](https://phi-ai.buaa.edu.cn/Gazehub/3D-dataset/#mpiifacegaze)
+
+**Dataset structure:**
+
+```
+data/
+└── MPIIFaceGaze/
+    ├── Image/
+    └── Label/
+```
+
+---
+
+### Head Pose Estimation
+
+#### 300W-LP
+
+Large-scale synthesized face dataset with large pose variations, generated from 300W by face profiling. Used for training head pose estimation models.
+
+| Property    | Value                         |
+| ----------- | ----------------------------- |
+| Images      | ~122,000 (synthesized)        |
+| Source      | 300W (profiled)               |
+| Pose range  | ±90° yaw                     |
+| Evaluation  | AFLW2000                      |
+| Used by     | All HeadPose models           |
+
+!!! info "Download & Reference"
+    **Paper**: [Face Alignment Across Large Poses: A 3D Solution](https://arxiv.org/abs/1511.07212)
+
+    **Training code**: [yakhyo/head-pose-estimation](https://github.com/yakhyo/head-pose-estimation)
+
+!!! note "UniFace Models"
+    All HeadPose models shipped with UniFace are trained on 300W-LP and evaluated on AFLW2000.
+
+---
+
+### Face Parsing
+
+#### CelebAMask-HQ
+
+High-quality face parsing dataset with pixel-level annotations for 19 facial component classes.
+
+| Property   | Value                        |
+| ---------- | ---------------------------- |
+| Images     | 30,000                       |
+| Classes    | 19 facial components         |
+| Resolution | High quality                 |
+| Used by    | BiSeNet (ResNet18, ResNet34) |
+
+!!! info "Source"
+**GitHub**: [switchablenorms/CelebAMask-HQ](https://github.com/switchablenorms/CelebAMask-HQ)
+
+    **Training code**: [yakhyo/face-parsing](https://github.com/yakhyo/face-parsing)
+
+**Dataset structure:**
+
+```
+dataset/
+├── images/           # Input face images
+│   ├── image1.jpg
+│   └── ...
+└── labels/           # Segmentation masks
+    ├── image1.png
+    └── ...
+```
+
+---
+
+### Attribute Analysis
+
+#### CelebA
+
+Large-scale face attributes dataset widely used for training age and gender prediction models.
+
+| Property   | Value                |
+| ---------- | -------------------- |
+| Images     | ~200K                |
+| Attributes | 40 binary attributes |
+| Used by    | AgeGender            |
+
+!!! info "Reference"
+**Paper**: [Deep Learning Face Attributes in the Wild](https://arxiv.org/abs/1411.7766)
+
+---
+
+#### FairFace
+
+Face attribute dataset designed for balanced representation across race, gender, and age groups. Provides more equitable predictions compared to imbalanced datasets.
+
+| Property   | Value                               |
+| ---------- | ----------------------------------- |
+| Attributes | Race (7), Gender (2), Age Group (9) |
+| Used by    | FairFace                            |
+| License    | CC BY 4.0                           |
+
+!!! info "Reference"
+**Paper**: [FairFace: Face Attribute Dataset for Balanced Race, Gender, and Age](https://arxiv.org/abs/1908.04913)
+
+    **ONNX inference**: [yakhyo/fairface-onnx](https://github.com/yakhyo/fairface-onnx)
+
+---
+
+#### AffectNet
+
+Large-scale facial expression dataset for emotion recognition training.
+
+| Property | Value                                                                   |
+| -------- | ----------------------------------------------------------------------- |
+| Classes  | 7 or 8 (Neutral, Happy, Sad, Surprise, Fear, Disgust, Angry + Contempt) |
+| Used by  | Emotion (AFFECNET7, AFFECNET8)                                          |
+
+!!! info "Reference"
+**Paper**: [AffectNet: A Database for Facial Expression, Valence, and Arousal Computing in the Wild](https://ieeexplore.ieee.org/document/8013713)
+
+---
+
+## Evaluation Benchmarks
+
+### Face Detection
+
+#### WIDER FACE Validation Set
+
+The standard benchmark for face detection models. Results are reported across three difficulty subsets.
+
+| Subset | Criteria                                      |
+| ------ | --------------------------------------------- |
+| Easy   | Large, clear, unoccluded faces                |
+| Medium | Moderate scale and occlusion                  |
+| Hard   | Small, heavily occluded, or challenging faces |
+
+See [Model Zoo - Detection](models.md#face-detection-models) for per-model accuracy on each subset.
+
+---
+
+### Face Recognition
+
+Recognition models are evaluated across multiple benchmarks. Aligned 112x112 validation datasets are available as a single download.
+
+!!! info "Download"
+**Kaggle**: [agedb-30-calfw-cplfw-lfw-aligned-112x112](https://www.kaggle.com/datasets/yakhyokhuja/agedb-30-calfw-cplfw-lfw-aligned-112x112)
+
+| Benchmark    | Description                                                       | Used by                         |
+| ------------ | ----------------------------------------------------------------- | ------------------------------- |
+| **LFW**      | Labeled Faces in the Wild - standard face verification benchmark  | ArcFace, MobileFace, SphereFace |
+| **CALFW**    | Cross-Age LFW - face verification across age gaps                 | MobileFace, SphereFace          |
+| **CPLFW**    | Cross-Pose LFW - face verification across pose variations         | MobileFace, SphereFace          |
+| **AgeDB-30** | Age database with 30-year age gaps                                | ArcFace, MobileFace, SphereFace |
+| **CFP-FP**   | Celebrities in Frontal-Profile - frontal vs. profile verification | ArcFace                         |
+| **IJB-B**    | IARPA Janus Benchmark B - TAR@FAR=0.01%                           | AdaFace                         |
+| **IJB-C**    | IARPA Janus Benchmark C - TAR@FAR=1e-4                            | AdaFace, ArcFace                |
+
+See [Model Zoo - Recognition](models.md#face-recognition-models) for per-model accuracy on each benchmark.
+
+---
+
+### Gaze Estimation
+
+| Benchmark            | Metric        | Description                                  |
+| -------------------- | ------------- | -------------------------------------------- |
+| **Gaze360 test set** | MAE (degrees) | Mean Absolute Error in gaze angle prediction |
+
+See [Model Zoo - Gaze](models.md#gaze-estimation-models) for per-model MAE scores.
+
+---
+
+## Training Repositories
+
+For training your own models or reproducing results, see the following repositories:
+
+| Task        | Repository                                                                | Datasets Supported              |
+| ----------- | ------------------------------------------------------------------------- | ------------------------------- |
+| Detection   | [yakhyo/retinaface-pytorch](https://github.com/yakhyo/retinaface-pytorch) | WIDER FACE                      |
+| Recognition | [yakhyo/face-recognition](https://github.com/yakhyo/face-recognition)     | MS1MV2, CASIA-WebFace, VGGFace2 |
+| Gaze        | [yakhyo/gaze-estimation](https://github.com/yakhyo/gaze-estimation)       | Gaze360, MPIIFaceGaze           |
+| Parsing     | [yakhyo/face-parsing](https://github.com/yakhyo/face-parsing)             | CelebAMask-HQ                   |

docs/index.md

@@ -13,14 +13,14 @@ template: home.html
 <p class="hero-subtitle">All-in-One Open-Source Face Analysis Library</p>
 
 [![PyPI Version](https://img.shields.io/pypi/v/uniface.svg?label=Version)](https://pypi.org/project/uniface/)
-[![Python Version](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
+[![Python Version](https://img.shields.io/badge/Python-3.11%2B-blue)](https://www.python.org/)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Github Build Status](https://github.com/yakhyo/uniface/actions/workflows/ci.yml/badge.svg)](https://github.com/yakhyo/uniface/actions)
 [![PyPI Downloads](https://static.pepy.tech/personalized-badge/uniface?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=BLUE&left_text=Downloads)](https://pepy.tech/projects/uniface)
 [![Kaggle Badge](https://img.shields.io/badge/Notebooks-Kaggle?label=Kaggle&color=blue)](https://www.kaggle.com/yakhyokhuja/code)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?logo=discord&logoColor=white)](https://discord.gg/wdzrjr7R5j)
 
-<!-- <img src="https://raw.githubusercontent.com/yakhyo/uniface/main/.github/logos/new/uniface_rounded_q80.webp" alt="UniFace - All-in-One Open-Source Face Analysis Library" style="max-width: 70%; margin: 1rem 0;"> -->
+<!-- <img src="https://raw.githubusercontent.com/yakhyo/uniface/main/.github/logos/uniface_rounded_q80.webp" alt="UniFace - All-in-One Open-Source Face Analysis Library" style="max-width: 70%; margin: 1rem 0;"> -->
 
 [Get Started](quickstart.md){ .md-button .md-button--primary }
 [View on GitHub](https://github.com/yakhyo/uniface){ .md-button }
@@ -59,6 +59,11 @@ BiSeNet semantic segmentation with 19 facial component classes.
 Real-time gaze direction prediction with MobileGaze models.
 </div>
 
+<div class="feature-card" markdown>
+### :material-axis-arrow: Head Pose
+3D head orientation (pitch, yaw, roll) estimation with 6D rotation models.
+</div>
+
 <div class="feature-card" markdown>
 ### :material-motion-play: Tracking
 Multi-object tracking with BYTETracker for persistent face IDs across video frames.
@@ -74,31 +79,35 @@ Face liveness detection with MiniFASNet to prevent fraud.
 Face anonymization with 5 blur methods for privacy protection.
 </div>
 
+<div class="feature-card" markdown>
+### :material-database-search: Vector Indexing
+FAISS-backed embedding store for fast multi-identity face search.
+</div>
+
 </div>
 
 ---
 
 ## Installation
 
-=== "Standard"
+UniFace runs inference primarily via **ONNX Runtime**; some optional components (e.g., emotion TorchScript, torchvision NMS) require **PyTorch**.
 
-    ```bash
-    pip install uniface
-    ```
+**Standard**
+```bash
+pip install uniface
+```
 
-=== "GPU (CUDA)"
+**GPU (CUDA)**
+```bash
+pip install uniface[gpu]
+```
 
-    ```bash
-    pip install uniface[gpu]
-    ```
-
-=== "From Source"
-
-    ```bash
-    git clone https://github.com/yakhyo/uniface.git
-    cd uniface
-    pip install -e .
-    ```
+**From Source**
+```bash
+git clone https://github.com/yakhyo/uniface.git
+cd uniface
+pip install -e .
+```
 
 ---
 

docs/installation.md

@@ -6,7 +6,7 @@ This guide covers all installation options for UniFace.
 
 ## Requirements
 
-- **Python**: 3.10 or higher
+- **Python**: 3.11 or higher
 - **Operating Systems**: macOS, Linux, Windows
 
 ---
@@ -55,11 +55,10 @@ pip install uniface[gpu]
 
 **Requirements:**
 
-- CUDA 11.x or 12.x
-- cuDNN 8.x
+- `uniface[gpu]` automatically installs `onnxruntime-gpu`. Requirements depend on the ORT version and execution provider.
 
 !!! info "CUDA Compatibility"
-    See [ONNX Runtime GPU requirements](https://onnxruntime.ai/docs/execution-providers/CUDA-ExecutionProvider.html) for detailed compatibility matrix.
+    See the [ONNX Runtime GPU compatibility matrix](https://onnxruntime.ai/docs/execution-providers/CUDA-ExecutionProvider.html) for matching CUDA and cuDNN versions.
 
 Verify GPU installation:
 
@@ -71,6 +70,19 @@ print("Available providers:", ort.get_available_providers())
 
 ---
 
+### FAISS Vector Indexing
+
+For fast multi-identity face search using a FAISS index:
+
+```bash
+pip install faiss-cpu   # CPU
+pip install faiss-gpu   # NVIDIA GPU (CUDA)
+```
+
+See the [Indexing module](modules/indexing.md) for usage.
+
+---
+
 ### CPU-Only (All Platforms)
 
 ```bash
@@ -107,12 +119,20 @@ UniFace has minimal dependencies:
 |---------|---------|
 | `numpy` | Array operations |
 | `opencv-python` | Image processing |
-| `onnx` | ONNX model format support |
 | `onnxruntime` | Model inference |
 | `scikit-image` | Geometric transforms |
 | `requests` | Model download |
 | `tqdm` | Progress bars |
 
+**Optional:**
+
+| Package | Install extra | Purpose |
+|---------|---------------|---------|
+| `faiss-cpu` / `faiss-gpu` | `pip install faiss-cpu` | FAISS vector indexing |
+| `onnxruntime-gpu` | `uniface[gpu]` | CUDA acceleration |
+| `torch` | `pip install torch` | Emotion model uses TorchScript |
+| `torchvision` | `pip install torchvision` | Faster NMS for YOLO detectors |
+
 ---
 
 ## Verify Installation
@@ -139,11 +159,11 @@ print("Installation successful!")
 
 ### Import Errors
 
-If you encounter import errors, ensure you're using Python 3.10+:
+If you encounter import errors, ensure you're using Python 3.11+:
 
 ```bash
 python --version
-# Should show: Python 3.10.x or higher
+# Should show: Python 3.11.x or higher
 ```
 
 ### Model Download Issues

docs/models.md

@@ -8,7 +8,7 @@ Complete guide to all available models and their performance characteristics.
 
 ### RetinaFace Family
 
-RetinaFace models are trained on the WIDER FACE dataset.
+RetinaFace models are trained on the [WIDER FACE](datasets.md#wider-face) dataset.
 
 | Model Name     | Params | Size  | Easy   | Medium | Hard   |
 | -------------- | ------ | ----- | ------ | ------ | ------ |
@@ -28,7 +28,7 @@ RetinaFace models are trained on the WIDER FACE dataset.
 
 ### SCRFD Family
 
-SCRFD (Sample and Computation Redistribution for Efficient Face Detection) models trained on WIDER FACE dataset.
+SCRFD (Sample and Computation Redistribution for Efficient Face Detection) models trained on [WIDER FACE](datasets.md#wider-face) dataset.
 
 | Model Name       | Params | Size  | Easy   | Medium | Hard   |
 | ---------------- | ------ | ----- | ------ | ------ | ------ |
@@ -44,7 +44,7 @@ SCRFD (Sample and Computation Redistribution for Efficient Face Detection) model
 
 ### YOLOv5-Face Family
 
-YOLOv5-Face models provide detection with 5-point facial landmarks, trained on WIDER FACE dataset.
+YOLOv5-Face models provide detection with 5-point facial landmarks, trained on [WIDER FACE](datasets.md#wider-face) dataset.
 
 | Model Name     | Size | Easy   | Medium | Hard   |
 | -------------- | ---- | ------ | ------ | ------ |
@@ -93,7 +93,7 @@ Face recognition using adaptive margin based on image quality.
 | `IR_101`  | IR-101   | WebFace12M  | 249 MB | -         | 97.66%    |
 
 !!! info "Training Data & Accuracy"
-    **Dataset**: WebFace4M (4M images) / WebFace12M (12M images)
+    **Dataset**: [WebFace4M / WebFace12M](datasets.md#webface4m--webface12m) (4M / 12M images)
 
     **Accuracy**: IJB-B and IJB-C benchmarks, TAR@FAR=0.01%
 
@@ -113,7 +113,7 @@ Face recognition using additive angular margin loss.
 | `RESNET`  | ResNet50  | 43.6M  | 166MB | 99.83% | 99.33% | 98.23%   | 97.25% |
 
 !!! info "Training Data"
-    **Dataset**: Trained on WebFace600K (600K images)
+    **Dataset**: Trained on [WebFace600K](datasets.md#webface600k) (600K images)
 
     **Accuracy**: IJB-C accuracy reported as TAR@FAR=1e-4
 
@@ -131,7 +131,7 @@ Lightweight face recognition models with MobileNet backbones.
 | `MNET_V3_LARGE` | MobileNetV3-L    | 3.52M  | 10MB | 99.53% | 94.56% | 86.79% | 95.13%   |
 
 !!! info "Training Data"
-    **Dataset**: Trained on MS1M-V2 (5.8M images, 85K identities)
+    **Dataset**: Trained on [MS1MV2](datasets.md#ms1mv2) (5.8M images, 85K identities)
 
     **Accuracy**: Evaluated on LFW, CALFW, CPLFW, and AgeDB-30 benchmarks
 
@@ -147,7 +147,7 @@ Face recognition using angular softmax loss.
 | `SPHERE36` | Sphere36 | 34.6M  | 92MB | 99.72% | 95.64% | 89.92% | 96.83%   |
 
 !!! info "Training Data"
-    **Dataset**: Trained on MS1M-V2 (5.8M images, 85K identities)
+    **Dataset**: Trained on [MS1MV2](datasets.md#ms1mv2) (5.8M images, 85K identities)
 
     **Accuracy**: Evaluated on LFW, CALFW, CPLFW, and AgeDB-30 benchmarks
 
@@ -187,7 +187,7 @@ Facial landmark localization model.
 | `AgeGender` | Age, Gender | 2.1M   | 8MB  |
 
 !!! info "Training Data"
-    **Dataset**: Trained on CelebA
+    **Dataset**: Trained on [CelebA](datasets.md#celeba)
 
 !!! warning "Accuracy Note"
     Accuracy varies by demographic and image quality. Test on your specific use case.
@@ -201,7 +201,7 @@ Facial landmark localization model.
 | `FairFace` | Race, Gender, Age Group | -      | 44MB  |
 
 !!! info "Training Data"
-    **Dataset**: Trained on FairFace dataset with balanced demographics
+    **Dataset**: Trained on [FairFace](datasets.md#fairface) dataset with balanced demographics
 
 !!! tip "Equitable Predictions"
     FairFace provides more equitable predictions across different racial and gender groups.
@@ -224,7 +224,7 @@ Facial landmark localization model.
 **Classes (8)**: Above + Contempt
 
 !!! info "Training Data"
-    **Dataset**: Trained on AffectNet
+    **Dataset**: Trained on [AffectNet](datasets.md#affectnet)
 
 !!! note "Accuracy Note"
     Emotion detection accuracy depends heavily on facial expression clarity and cultural context.
@@ -235,7 +235,7 @@ Facial landmark localization model.
 
 ### MobileGaze Family
 
-Gaze direction prediction models trained on Gaze360 dataset. Returns pitch (vertical) and yaw (horizontal) angles in radians.
+Gaze direction prediction models trained on [Gaze360](datasets.md#gaze360) dataset. Returns pitch (vertical) and yaw (horizontal) angles in radians.
 
 | Model Name     | Params | Size    | MAE*  |
 | -------------- | ------ | ------- | ----- |
@@ -248,7 +248,7 @@ Gaze direction prediction models trained on Gaze360 dataset. Returns pitch (vert
 *MAE (Mean Absolute Error) in degrees on Gaze360 test set - lower is better
 
 !!! info "Training Data"
-    **Dataset**: Trained on Gaze360 (indoor/outdoor scenes with diverse head poses)
+    **Dataset**: Trained on [Gaze360](datasets.md#gaze360) (indoor/outdoor scenes with diverse head poses)
 
     **Training**: 200 epochs with classification-based approach (binned angles)
 
@@ -257,6 +257,33 @@ Gaze direction prediction models trained on Gaze360 dataset. Returns pitch (vert
 
 ---
 
+## Head Pose Estimation Models
+
+### HeadPose Family
+
+Head pose estimation models using 6D rotation representation. Trained on [300W-LP](datasets.md#300w-lp) dataset, evaluated on AFLW2000. Returns pitch, yaw, and roll angles in degrees.
+
+| Model Name     | Backbone | Size    | MAE*  |
+| -------------- | -------- | ------- | ----- |
+| `RESNET18` :material-check-circle: | ResNet18 | 43 MB   | 5.22° |
+| `RESNET34`   | ResNet34 | 82 MB   | 5.07° |
+| `RESNET50`   | ResNet50 | 91 MB   | 4.83° |
+| `MOBILENET_V2` | MobileNetV2 | 9.6 MB  | 5.72° |
+| `MOBILENET_V3_SMALL` | MobileNetV3-Small | 4.8 MB  | 6.31° |
+| `MOBILENET_V3_LARGE` | MobileNetV3-Large | 16 MB   | 5.58° |
+
+*MAE (Mean Absolute Error) in degrees on AFLW2000 test set — lower is better
+
+!!! info "Training Data"
+    **Dataset**: Trained on [300W-LP](datasets.md#300w-lp) (synthesized large-pose faces from 300W)
+
+    **Method**: 6D rotation representation (rotation matrix → Euler angles)
+
+!!! note "Input Requirements"
+    Requires face crop as input. Use face detection first to obtain bounding boxes.
+
+---
+
 ## Face Parsing Models
 
 ### BiSeNet Family
@@ -269,7 +296,7 @@ BiSeNet (Bilateral Segmentation Network) models for semantic face parsing. Segme
 | `RESNET34`   | 24.1M  | 89.2 MB | 19      |
 
 !!! info "Training Data"
-    **Dataset**: Trained on CelebAMask-HQ
+    **Dataset**: Trained on [CelebAMask-HQ](datasets.md#celebamask-hq)
 
     **Architecture**: BiSeNet with ResNet backbone
 
@@ -372,6 +399,7 @@ See [Model Cache & Offline Use](concepts/model-cache-offline.md) for full detail
 - **AdaFace ONNX**: [yakhyo/adaface-onnx](https://github.com/yakhyo/adaface-onnx) - ONNX export and inference
 - **Face Recognition Training**: [yakhyo/face-recognition](https://github.com/yakhyo/face-recognition) - ArcFace, MobileFace, SphereFace training code
 - **Gaze Estimation Training**: [yakhyo/gaze-estimation](https://github.com/yakhyo/gaze-estimation) - MobileGaze training code and pretrained weights
+- **Head Pose Estimation**: [yakhyo/head-pose-estimation](https://github.com/yakhyo/head-pose-estimation) - 6D rotation head pose estimation training and ONNX models
 - **Face Parsing Training**: [yakhyo/face-parsing](https://github.com/yakhyo/face-parsing) - BiSeNet training code and pretrained weights
 - **Face Segmentation**: [yakhyo/face-segmentation](https://github.com/yakhyo/face-segmentation) - XSeg ONNX Inference
 - **Face Anti-Spoofing**: [yakhyo/face-anti-spoofing](https://github.com/yakhyo/face-anti-spoofing) - MiniFASNet ONNX inference (weights from [minivision-ai/Silent-Face-Anti-Spoofing](https://github.com/minivision-ai/Silent-Face-Anti-Spoofing))

docs/modules/attributes.md

@@ -30,9 +30,10 @@ age_gender = AgeGender()
 faces = detector.detect(image)
 
 for face in faces:
-    result = age_gender.predict(image, face.bbox)
+    result = age_gender.predict(image, face)
     print(f"Gender: {result.sex}")  # "Female" or "Male"
     print(f"Age: {result.age} years")
+    # face.gender and face.age are also set automatically
 ```
 
 ### Output
@@ -64,10 +65,11 @@ fairface = FairFace()
 faces = detector.detect(image)
 
 for face in faces:
-    result = fairface.predict(image, face.bbox)
+    result = fairface.predict(image, face)
     print(f"Gender: {result.sex}")
     print(f"Age Group: {result.age_group}")
     print(f"Race: {result.race}")
+    # face.gender, face.age_group, face.race are also set automatically
 ```
 
 ### Output
@@ -132,7 +134,7 @@ emotion = Emotion(model_name=DDAMFNWeights.AFFECNET7)
 faces = detector.detect(image)
 
 for face in faces:
-    result = emotion.predict(image, face.landmarks)
+    result = emotion.predict(image, face)
     print(f"Emotion: {result.emotion}")
     print(f"Confidence: {result.confidence:.2%}")
 ```
@@ -179,6 +181,22 @@ emotion = Emotion(model_name=DDAMFNWeights.AFFECNET8)
 
 ---
 
+## Factory Function
+
+Use `create_attribute_predictor()` for dynamic model selection:
+
+```python
+from uniface import create_attribute_predictor
+
+age_gender = create_attribute_predictor('age_gender')
+fairface = create_attribute_predictor('fairface')
+emotion = create_attribute_predictor('emotion')
+```
+
+Available model names: `'age_gender'`, `'fairface'`, `'emotion'`.
+
+---
+
 ## Combining Models
 
 ### Full Attribute Analysis
@@ -195,10 +213,10 @@ faces = detector.detect(image)
 
 for face in faces:
     # Get exact age from AgeGender
-    ag_result = age_gender.predict(image, face.bbox)
+    ag_result = age_gender.predict(image, face)
 
     # Get race from FairFace
-    ff_result = fairface.predict(image, face.bbox)
+    ff_result = fairface.predict(image, face)
 
     print(f"Gender: {ag_result.sex}")
     print(f"Exact Age: {ag_result.age}")
@@ -215,7 +233,7 @@ from uniface.detection import RetinaFace
 
 analyzer = FaceAnalyzer(
     RetinaFace(),
-    age_gender=AgeGender(),
+    attributes=[AgeGender()],
 )
 
 faces = analyzer.analyze(image)
@@ -257,7 +275,7 @@ def draw_attributes(image, face, result):
 
 # Usage
 for face in faces:
-    result = age_gender.predict(image, face.bbox)
+    result = age_gender.predict(image, face)
     image = draw_attributes(image, face, result)
 
 cv2.imwrite("attributes.jpg", image)

docs/modules/gaze.md

@@ -267,6 +267,7 @@ gaze = create_gaze_estimator()  # Returns MobileGaze
 
 ## Next Steps
 
+- [Head Pose Estimation](headpose.md) - 3D head orientation
 - [Anti-Spoofing](spoofing.md) - Face liveness detection
 - [Privacy](privacy.md) - Face anonymization
 - [Video Recipe](../recipes/video-webcam.md) - Real-time processing

docs/modules/headpose.md

@@ -0,0 +1,232 @@
+# Head Pose Estimation
+
+Head pose estimation predicts the 3D orientation of a person's head (pitch, yaw, and roll angles).
+
+---
+
+## Available Models
+
+| Model | Backbone | Size | MAE* |
+|-------|----------|------|------|
+| **ResNet18** :material-check-circle: | ResNet18 | 43 MB | 5.22° |
+| ResNet34 | ResNet34 | 82 MB | 5.07° |
+| ResNet50 | ResNet50 | 91 MB | 4.83° |
+| MobileNetV2 | MobileNetV2 | 9.6 MB | 5.72° |
+| MobileNetV3-Small | MobileNetV3 | 4.8 MB | 6.31° |
+| MobileNetV3-Large | MobileNetV3 | 16 MB | 5.58° |
+
+*MAE = Mean Absolute Error on AFLW2000 test set (lower is better)
+
+---
+
+## Basic Usage
+
+```python
+import cv2
+from uniface.detection import RetinaFace
+from uniface.headpose import HeadPose
+
+detector = RetinaFace()
+head_pose = HeadPose()
+
+image = cv2.imread("photo.jpg")
+faces = detector.detect(image)
+
+for face in faces:
+    # Crop face
+    x1, y1, x2, y2 = map(int, face.bbox)
+    face_crop = image[y1:y2, x1:x2]
+
+    if face_crop.size > 0:
+        # Estimate head pose
+        result = head_pose.estimate(face_crop)
+        print(f"Pitch: {result.pitch:.1f}°, Yaw: {result.yaw:.1f}°, Roll: {result.roll:.1f}°")
+```
+
+---
+
+## Model Variants
+
+```python
+from uniface.headpose import HeadPose
+from uniface.constants import HeadPoseWeights
+
+# Default (ResNet18, recommended balance of speed and accuracy)
+hp = HeadPose()
+
+# Lightweight for mobile/edge
+hp = HeadPose(model_name=HeadPoseWeights.MOBILENET_V3_SMALL)
+
+# Higher accuracy
+hp = HeadPose(model_name=HeadPoseWeights.RESNET50)
+```
+
+---
+
+## Output Format
+
+```python
+result = head_pose.estimate(face_crop)
+
+# HeadPoseResult dataclass
+result.pitch  # Rotation around X-axis in degrees
+result.yaw    # Rotation around Y-axis in degrees
+result.roll   # Rotation around Z-axis in degrees
+```
+
+### Angle Convention
+
+```
+          pitch > 0 (looking down)
+               │
+               │
+yaw < 0  ─────┼───── yaw > 0
+(looking left) │     (looking right)
+               │
+          pitch < 0 (looking up)
+
+roll > 0 = clockwise tilt
+roll < 0 = counter-clockwise tilt
+```
+
+- **Pitch**: Rotation around X-axis (positive = looking down)
+- **Yaw**: Rotation around Y-axis (positive = looking right)
+- **Roll**: Rotation around Z-axis (positive = tilting clockwise)
+
+---
+
+## Visualization
+
+### 3D Cube (default)
+
+The default visualization draws a wireframe cube oriented to match the head pose.
+
+```python
+from uniface.draw import draw_head_pose
+
+faces = detector.detect(image)
+
+for face in faces:
+    x1, y1, x2, y2 = map(int, face.bbox)
+    face_crop = image[y1:y2, x1:x2]
+
+    if face_crop.size > 0:
+        result = head_pose.estimate(face_crop)
+
+        # Draw cube on image (default)
+        draw_head_pose(image, face.bbox, result.pitch, result.yaw, result.roll)
+
+cv2.imwrite("headpose_output.jpg", image)
+```
+
+### Axis Visualization
+
+```python
+from uniface.draw import draw_head_pose
+
+# X/Y/Z coordinate axes
+draw_head_pose(image, face.bbox, result.pitch, result.yaw, result.roll, draw_type='axis')
+```
+
+### Low-Level Drawing Functions
+
+```python
+from uniface.draw import draw_head_pose_cube, draw_head_pose_axis
+
+# Draw cube directly
+draw_head_pose_cube(image, yaw=10.0, pitch=-5.0, roll=2.0, bbox=[100, 100, 250, 280])
+
+# Draw axes directly
+draw_head_pose_axis(image, yaw=10.0, pitch=-5.0, roll=2.0, bbox=[100, 100, 250, 280])
+```
+
+---
+
+## Real-Time Head Pose Tracking
+
+```python
+import cv2
+from uniface.detection import RetinaFace
+from uniface.headpose import HeadPose
+from uniface.draw import draw_head_pose
+
+detector = RetinaFace()
+head_pose = HeadPose()
+
+cap = cv2.VideoCapture(0)
+
+while True:
+    ret, frame = cap.read()
+    if not ret:
+        break
+
+    faces = detector.detect(frame)
+
+    for face in faces:
+        x1, y1, x2, y2 = map(int, face.bbox)
+        face_crop = frame[y1:y2, x1:x2]
+
+        if face_crop.size > 0:
+            result = head_pose.estimate(face_crop)
+            draw_head_pose(frame, face.bbox, result.pitch, result.yaw, result.roll)
+
+    cv2.imshow("Head Pose Estimation", frame)
+
+    if cv2.waitKey(1) & 0xFF == ord('q'):
+        break
+
+cap.release()
+cv2.destroyAllWindows()
+```
+
+---
+
+## Use Cases
+
+### Driver Drowsiness Detection
+
+```python
+def is_head_drooping(result, pitch_threshold=-15):
+    """Check if the head is drooping (looking down significantly)."""
+    return result.pitch < pitch_threshold
+
+result = head_pose.estimate(face_crop)
+if is_head_drooping(result):
+    print("Warning: Head drooping detected")
+```
+
+### Attention Monitoring
+
+```python
+def is_facing_forward(result, threshold=20):
+    """Check if the person is facing roughly forward."""
+    return (
+        abs(result.pitch) < threshold
+        and abs(result.yaw) < threshold
+        and abs(result.roll) < threshold
+    )
+
+result = head_pose.estimate(face_crop)
+if is_facing_forward(result):
+    print("Facing forward")
+else:
+    print("Looking away")
+```
+
+---
+
+## Factory Function
+
+```python
+from uniface.headpose import create_head_pose_estimator
+
+hp = create_head_pose_estimator()  # Returns HeadPose
+```
+
+---
+
+## Next Steps
+
+- [Gaze Estimation](gaze.md) - Eye gaze direction
+- [Anti-Spoofing](spoofing.md) - Face liveness detection
+- [Video Recipe](../recipes/video-webcam.md) - Real-time processing

docs/modules/indexing.md

@@ -0,0 +1,172 @@
+# Indexing
+
+FAISS-backed vector store for fast similarity search over embeddings.
+
+!!! info "Optional dependency"
+    ```bash
+    pip install faiss-cpu
+    ```
+
+---
+
+## FAISS
+
+```python
+from uniface.indexing import FAISS
+```
+
+A thin wrapper around a FAISS `IndexFlatIP` (inner-product) index. Vectors
+**must** be L2-normalised before adding so that inner product equals cosine
+similarity. The store does not normalise internally.
+
+Each vector is paired with a metadata `dict` that can carry any
+JSON-serialisable payload (person ID, name, source path, etc.).
+
+### Constructor
+
+```python
+store = FAISS(embedding_size=512, db_path="./vector_index")
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `embedding_size` | `int` | `512` | Dimension of embedding vectors |
+| `db_path` | `str` | `"./vector_index"` | Directory for persisting index and metadata |
+
+---
+
+### Methods
+
+#### `add(embedding, metadata)`
+
+Add a single embedding with associated metadata.
+
+```python
+store.add(embedding, {"person_id": "alice", "source": "photo.jpg"})
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `embedding` | `np.ndarray` | L2-normalised embedding vector |
+| `metadata` | `dict[str, Any]` | Arbitrary JSON-serialisable key-value pairs |
+
+---
+
+#### `search(embedding, threshold=0.4)`
+
+Find the closest match for a query embedding.
+
+```python
+result, similarity = store.search(query_embedding, threshold=0.4)
+if result:
+    print(result["person_id"], similarity)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `embedding` | `np.ndarray` | — | L2-normalised query vector |
+| `threshold` | `float` | `0.4` | Minimum cosine similarity to accept a match |
+
+**Returns:** `(metadata, similarity)` if a match is found, or `(None, similarity)` when below threshold or the index is empty.
+
+---
+
+#### `remove(key, value)`
+
+Remove all entries where `metadata[key] == value` and rebuild the index.
+
+```python
+removed = store.remove("person_id", "bob")
+print(f"Removed {removed} entries")
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `key` | `str` | Metadata key to match |
+| `value` | `Any` | Value to match |
+
+**Returns:** Number of entries removed.
+
+---
+
+#### `save()`
+
+Persist the FAISS index and metadata to disk.
+
+```python
+store.save()
+```
+
+Writes two files to `db_path`:
+
+- `faiss_index.bin` — binary FAISS index
+- `metadata.json` — JSON array of metadata dicts
+
+---
+
+#### `load()`
+
+Load a previously saved index and metadata.
+
+```python
+store = FAISS(db_path="./vector_index")
+loaded = store.load()  # True if files exist
+```
+
+**Returns:** `True` if loaded successfully, `False` if files are missing.
+
+**Raises:** `RuntimeError` if files exist but cannot be read.
+
+---
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `size` | `int` | Number of vectors in the index |
+| `len(store)` | `int` | Same as `size` |
+
+---
+
+## Example: End-to-End
+
+```python
+import cv2
+from uniface.detection import RetinaFace
+from uniface.recognition import ArcFace
+from uniface.indexing import FAISS
+
+detector = RetinaFace()
+recognizer = ArcFace()
+
+# Build
+store = FAISS(db_path="./my_index")
+
+image = cv2.imread("alice.jpg")
+faces = detector.detect(image)
+embedding = recognizer.get_normalized_embedding(image, faces[0].landmarks)
+store.add(embedding, {"person_id": "alice"})
+store.save()
+
+# Search
+store2 = FAISS(db_path="./my_index")
+store2.load()
+
+query = cv2.imread("unknown.jpg")
+faces = detector.detect(query)
+emb = recognizer.get_normalized_embedding(query, faces[0].landmarks)
+
+result, sim = store2.search(emb)
+if result:
+    print(f"Matched: {result['person_id']} (similarity: {sim:.3f})")
+else:
+    print(f"No match (similarity: {sim:.3f})")
+```
+
+---
+
+## See Also
+
+- [Face Search Recipe](../recipes/face-search.md) - Building and querying indexes
+- [Recognition Module](recognition.md) - Embedding extraction
+- [Thresholds Guide](../concepts/thresholds-calibration.md) - Tuning similarity thresholds

docs/notebooks.md

@@ -17,6 +17,8 @@ Run UniFace examples directly in your browser with Google Colab, or download and
 | [Face Anonymization](https://github.com/yakhyo/uniface/blob/main/examples/07_face_anonymization.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/07_face_anonymization.ipynb) | Privacy-preserving blur |
 | [Gaze Estimation](https://github.com/yakhyo/uniface/blob/main/examples/08_gaze_estimation.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/08_gaze_estimation.ipynb) | Gaze direction estimation |
 | [Face Segmentation](https://github.com/yakhyo/uniface/blob/main/examples/09_face_segmentation.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/09_face_segmentation.ipynb) | Face segmentation with XSeg |
+| [Face Vector Store](https://github.com/yakhyo/uniface/blob/main/examples/10_face_vector_store.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/10_face_vector_store.ipynb) | FAISS-backed face database |
+| [Head Pose Estimation](https://github.com/yakhyo/uniface/blob/main/examples/11_head_pose_estimation.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/11_head_pose_estimation.ipynb) | 3D head orientation estimation |
 
 ---
 

docs/quickstart.md

@@ -80,7 +80,6 @@ Compare two faces:
 
 ```python
 import cv2
-import numpy as np
 from uniface.detection import RetinaFace
 from uniface.recognition import ArcFace
 
@@ -97,12 +96,13 @@ faces1 = detector.detect(image1)
 faces2 = detector.detect(image2)
 
 if faces1 and faces2:
-    # Extract embeddings
+    # Extract embeddings (normalized 1-D vectors)
     emb1 = recognizer.get_normalized_embedding(image1, faces1[0].landmarks)
     emb2 = recognizer.get_normalized_embedding(image2, faces2[0].landmarks)
 
-    # Compute similarity (cosine similarity)
-    similarity = np.dot(emb1, emb2.T)[0][0]
+    # Compute cosine similarity
+    from uniface import compute_similarity
+    similarity = compute_similarity(emb1, emb2, normalized=True)
 
     # Interpret result
     if similarity > 0.6:
@@ -135,7 +135,7 @@ faces = detector.detect(image)
 
 # Predict attributes
 for i, face in enumerate(faces):
-    result = age_gender.predict(image, face.bbox)
+    result = age_gender.predict(image, face)
     print(f"Face {i+1}: {result.sex}, {result.age} years old")
 ```
 
@@ -164,7 +164,7 @@ image = cv2.imread("photo.jpg")
 faces = detector.detect(image)
 
 for i, face in enumerate(faces):
-    result = fairface.predict(image, face.bbox)
+    result = fairface.predict(image, face)
     print(f"Face {i+1}: {result.sex}, {result.age_group}, {result.race}")
 ```
 
@@ -234,6 +234,36 @@ cv2.imwrite("gaze_output.jpg", image)
 
 ---
 
+## Head Pose Estimation
+
+```python
+import cv2
+from uniface.detection import RetinaFace
+from uniface.headpose import HeadPose
+from uniface.draw import draw_head_pose
+
+detector = RetinaFace()
+head_pose = HeadPose()
+
+image = cv2.imread("photo.jpg")
+faces = detector.detect(image)
+
+for i, face in enumerate(faces):
+    x1, y1, x2, y2 = map(int, face.bbox[:4])
+    face_crop = image[y1:y2, x1:x2]
+
+    if face_crop.size > 0:
+        result = head_pose.estimate(face_crop)
+        print(f"Face {i+1}: pitch={result.pitch:.1f}°, yaw={result.yaw:.1f}°, roll={result.roll:.1f}°")
+
+        # Draw 3D cube visualization
+        draw_head_pose(image, face.bbox, result.pitch, result.yaw, result.roll)
+
+cv2.imwrite("headpose_output.jpg", image)
+```
+
+---
+
 ## Face Parsing
 
 Segment face into semantic components:
@@ -424,6 +454,7 @@ For detailed model comparisons and benchmarks, see the [Model Zoo](models.md).
 | Recognition | `ArcFace`, `AdaFace`, `MobileFace`, `SphereFace` |
 | Tracking | `BYTETracker` |
 | Gaze | `MobileGaze` (ResNet18/34/50, MobileNetV2, MobileOneS0) |
+| Head Pose | `HeadPose` (ResNet18/34/50, MobileNetV2/V3) |
 | Parsing | `BiSeNet` (ResNet18/34) |
 | Attributes | `AgeGender`, `FairFace`, `Emotion` |
 | Anti-Spoofing | `MiniFASNet` (V1SE, V2) |
@@ -470,11 +501,13 @@ from uniface.recognition import ArcFace, AdaFace
 from uniface.attribute import AgeGender, FairFace
 from uniface.landmark import Landmark106
 from uniface.gaze import MobileGaze
+from uniface.headpose import HeadPose
 from uniface.parsing import BiSeNet, XSeg
 from uniface.privacy import BlurFace
 from uniface.spoofing import MiniFASNet
 from uniface.tracking import BYTETracker
 from uniface.analyzer import FaceAnalyzer
+from uniface.indexing import FAISS  # pip install faiss-cpu
 from uniface.draw import draw_detections, draw_tracks
 ```
 

docs/recipes/face-search.md

@@ -1,179 +1,166 @@
 # Face Search
 
-Build a face search system for finding people in images.
+Find and identify people in images and video streams.
 
-!!! note "Work in Progress"
-    This page contains example code patterns. Test thoroughly before using in production.
+UniFace supports two search approaches:
+
+| Approach             | Use case                                         | Tool                    |
+| -------------------- | ------------------------------------------------ | ----------------------- |
+| **Reference search** | "Is this specific person in the video?"          | `tools/search.py`       |
+| **Vector search**    | "Who is this?" against a database of known faces | `tools/faiss_search.py` |
 
 ---
 
-## Basic Face Database
+## Reference Search (single image)
+
+Compare every detected face against a single reference photo:
 
 ```python
+import cv2
 import numpy as np
+from uniface.detection import RetinaFace
+from uniface.recognition import ArcFace
+from uniface.face_utils import compute_similarity
+
+detector = RetinaFace()
+recognizer = ArcFace()
+
+ref_image = cv2.imread("reference.jpg")
+ref_faces = detector.detect(ref_image)
+ref_embedding = recognizer.get_normalized_embedding(ref_image, ref_faces[0].landmarks)
+
+query_image = cv2.imread("group_photo.jpg")
+faces = detector.detect(query_image)
+
+for face in faces:
+    embedding = recognizer.get_normalized_embedding(query_image, face.landmarks)
+    sim = compute_similarity(ref_embedding, embedding)
+
+    label = f"Match ({sim:.2f})" if sim > 0.4 else f"Unknown ({sim:.2f})"
+    print(label)
+```
+
+**CLI tool:**
+
+```bash
+python tools/search.py --reference ref.jpg --source video.mp4
+python tools/search.py --reference ref.jpg --source 0  # webcam
+```
+
+---
+
+## Vector Search (FAISS index)
+
+For identifying faces against a database of many known people, use the
+[`FAISS`](../modules/indexing.md) vector store.
+
+!!! info "Install extra"
+`bash
+    pip install faiss-cpu
+    `
+
+### Build an index
+
+Organise face images in person sub-folders:
+
+```
+dataset/
+├── alice/
+│   ├── 001.jpg
+│   └── 002.jpg
+├── bob/
+│   └── 001.jpg
+└── charlie/
+    ├── 001.jpg
+    └── 002.jpg
+```
+
+```python
 import cv2
 from pathlib import Path
 from uniface.detection import RetinaFace
 from uniface.recognition import ArcFace
+from uniface.indexing import FAISS
 
-class FaceDatabase:
-    def __init__(self):
-        self.detector = RetinaFace()
-        self.recognizer = ArcFace()
-        self.embeddings = {}
+detector = RetinaFace()
+recognizer = ArcFace()
+store = FAISS(db_path="./my_index")
 
-    def add_face(self, person_id, image):
-        """Add a face to the database."""
-        faces = self.detector.detect(image)
-        if not faces:
-            raise ValueError(f"No face found for {person_id}")
+for person_dir in sorted(Path("dataset").iterdir()):
+    if not person_dir.is_dir():
+        continue
+    for img_path in person_dir.glob("*.jpg"):
+        image = cv2.imread(str(img_path))
+        faces = detector.detect(image)
+        if faces:
+            emb = recognizer.get_normalized_embedding(image, faces[0].landmarks)
+            store.add(emb, {"person_id": person_dir.name, "source": str(img_path)})
 
-        face = max(faces, key=lambda f: f.confidence)
-        embedding = self.recognizer.get_normalized_embedding(image, face.landmarks)
-        self.embeddings[person_id] = embedding
-        return True
-
-    def search(self, image, threshold=0.6):
-        """Search for faces in an image."""
-        faces = self.detector.detect(image)
-        results = []
-
-        for face in faces:
-            embedding = self.recognizer.get_normalized_embedding(image, face.landmarks)
-
-            best_match = None
-            best_similarity = -1
-
-            for person_id, db_embedding in self.embeddings.items():
-                similarity = np.dot(embedding, db_embedding.T)[0][0]
-                if similarity > best_similarity:
-                    best_similarity = similarity
-                    best_match = person_id
-
-            results.append({
-                'bbox': face.bbox,
-                'match': best_match if best_similarity >= threshold else None,
-                'similarity': best_similarity
-            })
-
-        return results
-
-    def save(self, path):
-        """Save database to file."""
-        np.savez(path, embeddings=dict(self.embeddings))
-
-    def load(self, path):
-        """Load database from file."""
-        data = np.load(path, allow_pickle=True)
-        self.embeddings = data['embeddings'].item()
-
-# Usage
-db = FaceDatabase()
-
-# Add faces
-for image_path in Path("known_faces/").glob("*.jpg"):
-    person_id = image_path.stem
-    image = cv2.imread(str(image_path))
-    try:
-        db.add_face(person_id, image)
-        print(f"Added: {person_id}")
-    except ValueError as e:
-        print(f"Skipped: {e}")
-
-# Save database
-db.save("face_database.npz")
-
-# Search
-query_image = cv2.imread("group_photo.jpg")
-results = db.search(query_image)
-
-for r in results:
-    if r['match']:
-        print(f"Found: {r['match']} (similarity: {r['similarity']:.3f})")
+store.save()
+print(f"Index saved: {store}")
 ```
 
----
+**CLI tool:**
 
-## Visualization
+```bash
+python tools/faiss_search.py build --faces-dir dataset/ --db-path ./my_index
+```
+
+### Search against the index
 
 ```python
 import cv2
+from uniface.detection import RetinaFace
+from uniface.recognition import ArcFace
+from uniface.indexing import FAISS
 
-def visualize_search_results(image, results):
-    """Draw search results on image."""
-    for r in results:
-        x1, y1, x2, y2 = map(int, r['bbox'])
+detector = RetinaFace()
+recognizer = ArcFace()
 
-        if r['match']:
-            color = (0, 255, 0)  # Green for match
-            label = f"{r['match']} ({r['similarity']:.2f})"
-        else:
-            color = (0, 0, 255)  # Red for unknown
-            label = f"Unknown ({r['similarity']:.2f})"
+store = FAISS(db_path="./my_index")
+store.load()
 
-        cv2.rectangle(image, (x1, y1), (x2, y2), color, 2)
-        cv2.putText(image, label, (x1, y1 - 10),
-                    cv2.FONT_HERSHEY_SIMPLEX, 0.6, color, 2)
+image = cv2.imread("query.jpg")
+faces = detector.detect(image)
 
-    return image
+for face in faces:
+    embedding = recognizer.get_normalized_embedding(image, face.landmarks)
+    result, similarity = store.search(embedding, threshold=0.4)
 
-# Usage
-results = db.search(image)
-annotated = visualize_search_results(image.copy(), results)
-cv2.imwrite("search_result.jpg", annotated)
+    if result:
+        print(f"Matched: {result['person_id']} ({similarity:.2f})")
+    else:
+        print(f"Unknown ({similarity:.2f})")
 ```
 
----
+**CLI tool:**
 
-## Real-Time Search
+```bash
+python tools/faiss_search.py run --db-path ./my_index --source video.mp4
+python tools/faiss_search.py run --db-path ./my_index --source 0  # webcam
+```
+
+### Manage the index
 
 ```python
-import cv2
+from uniface.indexing import FAISS
 
-def realtime_search(db):
-    """Real-time face search from webcam."""
-    cap = cv2.VideoCapture(0)
+store = FAISS(db_path="./my_index")
+store.load()
 
-    while True:
-        ret, frame = cap.read()
-        if not ret:
-            break
+print(f"Total vectors: {len(store)}")
 
-        results = db.search(frame, threshold=0.5)
+removed = store.remove("person_id", "bob")
+print(f"Removed {removed} entries")
 
-        for r in results:
-            x1, y1, x2, y2 = map(int, r['bbox'])
-
-            if r['match']:
-                color = (0, 255, 0)
-                label = r['match']
-            else:
-                color = (0, 0, 255)
-                label = "Unknown"
-
-            cv2.rectangle(frame, (x1, y1), (x2, y2), color, 2)
-            cv2.putText(frame, label, (x1, y1 - 10),
-                        cv2.FONT_HERSHEY_SIMPLEX, 0.6, color, 2)
-
-        cv2.imshow("Face Search", frame)
-
-        if cv2.waitKey(1) & 0xFF == ord('q'):
-            break
-
-    cap.release()
-    cv2.destroyAllWindows()
-
-# Usage
-db = FaceDatabase()
-db.load("face_database.npz")
-realtime_search(db)
+store.save()
 ```
 
 ---
 
 ## See Also
 
+- [Indexing Module](../modules/indexing.md) - Full `FAISS` API reference
 - [Recognition Module](../modules/recognition.md) - Face recognition details
-- [Batch Processing](batch-processing.md) - Process multiple files
 - [Video & Webcam](video-webcam.md) - Real-time processing
 - [Concepts: Thresholds](../concepts/thresholds-calibration.md) - Tuning similarity thresholds

docs/recipes/image-pipeline.md

@@ -34,7 +34,7 @@ def process_image(image_path):
         embedding = recognizer.get_normalized_embedding(image, face.landmarks)
 
         # Step 3: Predict attributes
-        attrs = age_gender.predict(image, face.bbox)
+        attrs = age_gender.predict(image, face)
 
         results.append({
             'face_id': i,
@@ -83,7 +83,7 @@ age_gender = AgeGender()
 analyzer = FaceAnalyzer(
     detector,
     recognizer=recognizer,
-    age_gender=age_gender,
+    attributes=[age_gender],
 )
 
 # Process image
@@ -109,11 +109,12 @@ import numpy as np
 from uniface.attribute import AgeGender, FairFace
 from uniface.detection import RetinaFace
 from uniface.gaze import MobileGaze
+from uniface.headpose import HeadPose
 from uniface.landmark import Landmark106
 from uniface.recognition import ArcFace
 from uniface.parsing import BiSeNet
 from uniface.spoofing import MiniFASNet
-from uniface.draw import draw_detections, draw_gaze
+from uniface.draw import draw_detections, draw_gaze, draw_head_pose
 
 class FaceAnalysisPipeline:
     def __init__(self):
@@ -124,6 +125,7 @@ class FaceAnalysisPipeline:
         self.fairface = FairFace()
         self.landmarker = Landmark106()
         self.gaze = MobileGaze()
+        self.head_pose = HeadPose()
         self.parser = BiSeNet()
         self.spoofer = MiniFASNet()
 
@@ -145,12 +147,12 @@ class FaceAnalysisPipeline:
             )
 
             # Attributes
-            ag_result = self.age_gender.predict(image, face.bbox)
+            ag_result = self.age_gender.predict(image, face)
             result['age'] = ag_result.age
             result['gender'] = ag_result.sex
 
             # FairFace attributes
-            ff_result = self.fairface.predict(image, face.bbox)
+            ff_result = self.fairface.predict(image, face)
             result['age_group'] = ff_result.age_group
             result['race'] = ff_result.race
 
@@ -167,6 +169,13 @@ class FaceAnalysisPipeline:
                 result['gaze_pitch'] = gaze_result.pitch
                 result['gaze_yaw'] = gaze_result.yaw
 
+            # Head pose estimation
+            if face_crop.size > 0:
+                hp_result = self.head_pose.estimate(face_crop)
+                result['head_pitch'] = hp_result.pitch
+                result['head_yaw'] = hp_result.yaw
+                result['head_roll'] = hp_result.roll
+
             # Face parsing
             if face_crop.size > 0:
                 result['parsing_mask'] = self.parser.parse(face_crop)
@@ -189,6 +198,7 @@ for i, r in enumerate(results):
     print(f"  Gender: {r['gender']}, Age: {r['age']}")
     print(f"  Race: {r['race']}, Age Group: {r['age_group']}")
     print(f"  Gaze: pitch={np.degrees(r['gaze_pitch']):.1f}°")
+    print(f"  Head Pose: P={r['head_pitch']:.1f}° Y={r['head_yaw']:.1f}° R={r['head_roll']:.1f}°")
     print(f"  Real: {r['is_real']} ({r['spoof_confidence']:.1%})")
 ```
 
@@ -220,7 +230,7 @@ def visualize_analysis(image_path, output_path):
         cv2.rectangle(image, (x1, y1), (x2, y2), (0, 255, 0), 2)
 
         # Age and gender
-        attrs = age_gender.predict(image, face.bbox)
+        attrs = age_gender.predict(image, face)
         label = f"{attrs.sex}, {attrs.age}y"
         cv2.putText(image, label, (x1, y1 - 10),
                     cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 255, 0), 2)
@@ -268,6 +278,11 @@ def results_to_json(results):
             'gaze': {
                 'pitch_deg': float(np.degrees(r['gaze_pitch'])) if 'gaze_pitch' in r else None,
                 'yaw_deg': float(np.degrees(r['gaze_yaw'])) if 'gaze_yaw' in r else None
+            },
+            'head_pose': {
+                'pitch': float(r['head_pitch']) if 'head_pitch' in r else None,
+                'yaw': float(r['head_yaw']) if 'head_yaw' in r else None,
+                'roll': float(r['head_roll']) if 'head_roll' in r else None
             }
         }
         output.append(item)
@@ -291,3 +306,4 @@ with open('results.json', 'w') as f:
 - [Face Search](face-search.md) - Build a search system
 - [Detection Module](../modules/detection.md) - Detection options
 - [Recognition Module](../modules/recognition.md) - Recognition details
+- [Head Pose Module](../modules/headpose.md) - Head orientation estimation

docs/recipes/video-webcam.md

@@ -175,3 +175,4 @@ while True:
 - [Batch Processing](batch-processing.md) - Process multiple files
 - [Detection Module](../modules/detection.md) - Detection options
 - [Gaze Module](../modules/gaze.md) - Gaze estimation
+- [Head Pose Module](../modules/headpose.md) - Head orientation estimation

examples/01_face_detection.ipynb

@@ -51,7 +51,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "2.0.0\n"
+      "3.2.0\n"
      ]
     }
    ],
@@ -62,7 +62,7 @@
     "\n",
     "import uniface\n",
     "from uniface.detection import RetinaFace\n",
-    "from uniface.visualization import draw_detections\n",
+    "from uniface.draw import draw_detections\n",
     "\n",
     "print(uniface.__version__)"
    ]
@@ -162,7 +162,7 @@
     "landmarks = [f.landmarks for f in faces]\n",
     "\n",
     "# Draw detections\n",
-    "draw_detections(image=image, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=0.6, fancy_bbox=True)\n",
+    "draw_detections(image=image, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=0.6, corner_bbox=True)\n",
     "\n",
     "# Display result\n",
     "output_image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)\n",
@@ -214,7 +214,7 @@
     "scores = [f.confidence for f in faces]\n",
     "landmarks = [f.landmarks for f in faces]\n",
     "\n",
-    "draw_detections(image=image, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=0.6, fancy_bbox=True)\n",
+    "draw_detections(image=image, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=0.6, corner_bbox=True)\n",
     "\n",
     "output_image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)\n",
     "display.display(Image.fromarray(output_image))"
@@ -261,7 +261,7 @@
     "scores = [f.confidence for f in faces]\n",
     "landmarks = [f.landmarks for f in faces]\n",
     "\n",
-    "draw_detections(image=image, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=0.6, fancy_bbox=True)\n",
+    "draw_detections(image=image, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=0.6, corner_bbox=True)\n",
     "\n",
     "output_image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)\n",
     "display.display(Image.fromarray(output_image))"

examples/02_face_alignment.ipynb

@@ -55,7 +55,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "2.0.0\n"
+      "3.2.0\n"
      ]
     }
    ],
@@ -67,7 +67,7 @@
     "import uniface\n",
     "from uniface.detection import RetinaFace\n",
     "from uniface.face_utils import face_alignment\n",
-    "from uniface.visualization import draw_detections\n",
+    "from uniface.draw import draw_detections\n",
     "\n",
     "print(uniface.__version__)"
    ]
@@ -142,7 +142,7 @@
     "    bboxes = [f.bbox for f in faces]\n",
     "    scores = [f.confidence for f in faces]\n",
     "    landmarks = [f.landmarks for f in faces]\n",
-    "    draw_detections(image=bbox_image, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=0.6, fancy_bbox=True)\n",
+    "    draw_detections(image=bbox_image, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=0.6, corner_bbox=True)\n",
     "\n",
     "    # Align first detected face (returns aligned image and inverse transform matrix)\n",
     "    first_landmarks = faces[0].landmarks\n",

examples/03_face_verification.ipynb

@@ -44,7 +44,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "2.0.0\n"
+      "3.2.0\n"
      ]
     }
    ],

examples/06_face_parsing.ipynb

@@ -15,7 +15,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 1,
    "metadata": {},
    "outputs": [
     {
@@ -53,7 +53,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "UniFace version: 2.0.0\n"
+      "UniFace version: 3.2.0\n"
      ]
     }
    ],
@@ -66,7 +66,7 @@
     "import uniface\n",
     "from uniface.parsing import BiSeNet\n",
     "from uniface.constants import ParsingWeights\n",
-    "from uniface.visualization import vis_parsing_maps\n",
+    "from uniface.draw import vis_parsing_maps\n",
     "\n",
     "print(f\"UniFace version: {uniface.__version__}\")"
    ]
@@ -82,15 +82,7 @@
    "cell_type": "code",
    "execution_count": 3,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "✓ Model loaded (CoreML (Apple Silicon))\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "# Initialize face parser (uses ResNet18 by default)\n",
     "parser = BiSeNet(model_name=ParsingWeights.RESNET34) # use resnet34 for better accuracy"

examples/08_gaze_estimation.ipynb

@@ -51,7 +51,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "UniFace version: 2.0.0\n"
+      "UniFace version: 3.2.0\n"
      ]
     }
    ],
@@ -65,7 +65,7 @@
     "import uniface\n",
     "from uniface.detection import RetinaFace\n",
     "from uniface.gaze import MobileGaze\n",
-    "from uniface.visualization import draw_gaze\n",
+    "from uniface.draw import draw_gaze\n",
     "\n",
     "print(f\"UniFace version: {uniface.__version__}\")"
    ]
@@ -110,19 +110,19 @@
      "text": [
       "Processing: image0.jpg\n",
       "  Detected 1 face(s)\n",
-      "    Face 1: pitch=-0.0°, yaw=7.1°\n",
+      "    Face 1: pitch=7.1°, yaw=-0.0°\n",
       "Processing: image1.jpg\n",
       "  Detected 1 face(s)\n",
-      "    Face 1: pitch=-3.3°, yaw=-5.6°\n",
+      "    Face 1: pitch=-5.6°, yaw=-3.3°\n",
       "Processing: image2.jpg\n",
       "  Detected 1 face(s)\n",
-      "    Face 1: pitch=-3.9°, yaw=-0.3°\n",
+      "    Face 1: pitch=-0.3°, yaw=-3.9°\n",
       "Processing: image3.jpg\n",
       "  Detected 1 face(s)\n",
-      "    Face 1: pitch=-22.1°, yaw=1.0°\n",
+      "    Face 1: pitch=1.0°, yaw=-22.1°\n",
       "Processing: image4.jpg\n",
       "  Detected 1 face(s)\n",
-      "    Face 1: pitch=2.1°, yaw=5.0°\n",
+      "    Face 1: pitch=5.0°, yaw=2.1°\n",
       "\n",
       "Processed 5 images\n"
      ]

examples/09_face_segmentation.ipynb

@@ -53,7 +53,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "UniFace version: 2.2.1\n"
+      "UniFace version: 3.2.0\n"
      ]
     }
    ],
@@ -364,7 +364,7 @@
    ],
    "source": [
     "from uniface.parsing import BiSeNet\n",
-    "from uniface.visualization import vis_parsing_maps\n",
+    "from uniface.draw import vis_parsing_maps\n",
     "\n",
     "# Load image and detect\n",
     "image = cv2.imread(\"../assets/einstien.png\")\n",
@@ -481,13 +481,21 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "base",
    "language": "python",
    "name": "python3"
   },
   "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
    "name": "python",
-   "version": "3.10.0"
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.5"
   }
  },
  "nbformat": 4,

mkdocs.yml

@@ -135,6 +135,7 @@ nav:
       - Quickstart: quickstart.md
       - Notebooks: notebooks.md
       - Model Zoo: models.md
+      - Datasets: datasets.md
   - Tutorials:
       - Image Pipeline: recipes/image-pipeline.md
       - Video & Webcam: recipes/video-webcam.md
@@ -150,8 +151,10 @@ nav:
       - Attributes: modules/attributes.md
       - Parsing: modules/parsing.md
       - Gaze: modules/gaze.md
+      - Head Pose: modules/headpose.md
       - Anti-Spoofing: modules/spoofing.md
       - Privacy: modules/privacy.md
+      - Indexing: modules/indexing.md
   - Guides:
       - Overview: concepts/overview.md
       - Inputs & Outputs: concepts/inputs-outputs.md

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uniface"
-version = "3.0.0"
+version = "3.2.0"
 description = "UniFace: A Comprehensive Library for Face Detection, Recognition, Tracking, Landmark Analysis, Face Parsing, Gaze Estimation, Age, and Gender Detection"
 readme = "README.md"
 license = "MIT"
@@ -9,7 +9,7 @@ maintainers = [
     { name = "Yakhyokhuja Valikhujaev", email = "yakhyo9696@gmail.com" },
 ]
 
-requires-python = ">=3.10,<3.14"
+requires-python = ">=3.11,<3.15"
 keywords = [
     "face-detection",
     "face-recognition",
@@ -29,22 +29,22 @@ keywords = [
 ]
 
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "Intended Audience :: Science/Research",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
 ]
 
 dependencies = [
     "numpy>=1.21.0",
     "opencv-python>=4.5.0",
     "onnxruntime>=1.16.0",
-    "scikit-image>=0.19.0",
+    "scikit-image>=0.26.0",
     "scipy>=1.7.0",
     "requests>=2.28.0",
     "tqdm>=4.64.0",
@@ -73,7 +73,7 @@ uniface = ["py.typed"]
 
 [tool.ruff]
 line-length = 120
-target-version = "py310"
+target-version = "py311"
 exclude = [
     ".git",
     ".ruff_cache",

requirements.txt

@@ -1,7 +1,7 @@
 numpy>=1.21.0
 opencv-python>=4.5.0
 onnxruntime>=1.16.0
-scikit-image>=0.19.0
+scikit-image>=0.26.0
 scipy>=1.7.0
 requests>=2.28.0
 tqdm>=4.64.0

tests/test_age_gender.py

@@ -9,6 +9,14 @@ import numpy as np
 import pytest
 
 from uniface.attribute import AgeGender, AttributeResult
+from uniface.types import Face
+
+
+def _make_face(bbox: list[int] | np.ndarray) -> Face:
+    """Helper: build a minimal Face from a bounding box."""
+    bbox = np.asarray(bbox)
+    landmarks = np.zeros((5, 2), dtype=np.float32)
+    return Face(bbox=bbox, confidence=0.99, landmarks=landmarks)
 
 
 @pytest.fixture
@@ -22,30 +30,30 @@ def mock_image():
 
 
 @pytest.fixture
-def mock_bbox():
-    return [100, 100, 300, 300]
+def mock_face():
+    return _make_face([100, 100, 300, 300])
 
 
 def test_model_initialization(age_gender_model):
     assert age_gender_model is not None, 'AgeGender model initialization failed.'
 
 
-def test_prediction_output_format(age_gender_model, mock_image, mock_bbox):
-    result = age_gender_model.predict(mock_image, mock_bbox)
+def test_prediction_output_format(age_gender_model, mock_image, mock_face):
+    result = age_gender_model.predict(mock_image, mock_face)
     assert isinstance(result, AttributeResult), f'Result should be AttributeResult, got {type(result)}'
     assert isinstance(result.gender, int), f'Gender should be int, got {type(result.gender)}'
     assert isinstance(result.age, int), f'Age should be int, got {type(result.age)}'
     assert isinstance(result.sex, str), f'Sex should be str, got {type(result.sex)}'
 
 
-def test_gender_values(age_gender_model, mock_image, mock_bbox):
-    result = age_gender_model.predict(mock_image, mock_bbox)
+def test_gender_values(age_gender_model, mock_image, mock_face):
+    result = age_gender_model.predict(mock_image, mock_face)
     assert result.gender in [0, 1], f'Gender should be 0 (Female) or 1 (Male), got {result.gender}'
     assert result.sex in ['Female', 'Male'], f'Sex should be Female or Male, got {result.sex}'
 
 
-def test_age_range(age_gender_model, mock_image, mock_bbox):
-    result = age_gender_model.predict(mock_image, mock_bbox)
+def test_age_range(age_gender_model, mock_image, mock_face):
+    result = age_gender_model.predict(mock_image, mock_face)
     assert 0 <= result.age <= 120, f'Age should be between 0 and 120, got {result.age}'
 
 
@@ -57,39 +65,52 @@ def test_different_bbox_sizes(age_gender_model, mock_image):
     ]
 
     for bbox in test_bboxes:
-        result = age_gender_model.predict(mock_image, bbox)
+        face = _make_face(bbox)
+        result = age_gender_model.predict(mock_image, face)
         assert result.gender in [0, 1], f'Failed for bbox {bbox}'
         assert 0 <= result.age <= 120, f'Age out of range for bbox {bbox}'
 
 
-def test_different_image_sizes(age_gender_model, mock_bbox):
+def test_different_image_sizes(age_gender_model):
     test_sizes = [(480, 640, 3), (720, 1280, 3), (1080, 1920, 3)]
+    face = _make_face([100, 100, 300, 300])
 
     for size in test_sizes:
         mock_image = np.random.randint(0, 255, size, dtype=np.uint8)
-        result = age_gender_model.predict(mock_image, mock_bbox)
+        result = age_gender_model.predict(mock_image, face)
         assert result.gender in [0, 1], f'Failed for image size {size}'
         assert 0 <= result.age <= 120, f'Age out of range for image size {size}'
 
 
-def test_consistency(age_gender_model, mock_image, mock_bbox):
-    result1 = age_gender_model.predict(mock_image, mock_bbox)
-    result2 = age_gender_model.predict(mock_image, mock_bbox)
+def test_consistency(age_gender_model, mock_image, mock_face):
+    result1 = age_gender_model.predict(mock_image, mock_face)
+    result2 = age_gender_model.predict(mock_image, mock_face)
 
     assert result1.gender == result2.gender, 'Same input should produce same gender prediction'
     assert result1.age == result2.age, 'Same input should produce same age prediction'
 
 
+def test_face_enrichment(age_gender_model, mock_image, mock_face):
+    """predict() must write gender & age back to the Face object."""
+    assert mock_face.gender is None
+    assert mock_face.age is None
+
+    result = age_gender_model.predict(mock_image, mock_face)
+
+    assert mock_face.gender == result.gender
+    assert mock_face.age == result.age
+
+
 def test_bbox_list_format(age_gender_model, mock_image):
-    bbox_list = [100, 100, 300, 300]
-    result = age_gender_model.predict(mock_image, bbox_list)
+    face = _make_face([100, 100, 300, 300])
+    result = age_gender_model.predict(mock_image, face)
     assert result.gender in [0, 1], 'Should work with bbox as list'
     assert 0 <= result.age <= 120, 'Age should be in valid range'
 
 
 def test_bbox_array_format(age_gender_model, mock_image):
-    bbox_array = np.array([100, 100, 300, 300])
-    result = age_gender_model.predict(mock_image, bbox_array)
+    face = _make_face(np.array([100, 100, 300, 300]))
+    result = age_gender_model.predict(mock_image, face)
     assert result.gender in [0, 1], 'Should work with bbox as numpy array'
     assert 0 <= result.age <= 120, 'Age should be in valid range'
 
@@ -103,7 +124,8 @@ def test_multiple_predictions(age_gender_model, mock_image):
 
     results = []
     for bbox in bboxes:
-        result = age_gender_model.predict(mock_image, bbox)
+        face = _make_face(bbox)
+        result = age_gender_model.predict(mock_image, face)
         results.append(result)
 
     assert len(results) == 3, 'Should have 3 predictions'
@@ -112,28 +134,26 @@ def test_multiple_predictions(age_gender_model, mock_image):
         assert 0 <= result.age <= 120
 
 
-def test_age_is_positive(age_gender_model, mock_image, mock_bbox):
+def test_age_is_positive(age_gender_model, mock_image, mock_face):
     for _ in range(5):
-        result = age_gender_model.predict(mock_image, mock_bbox)
+        result = age_gender_model.predict(mock_image, mock_face)
         assert result.age >= 0, f'Age should be non-negative, got {result.age}'
 
 
-def test_output_format_for_visualization(age_gender_model, mock_image, mock_bbox):
-    result = age_gender_model.predict(mock_image, mock_bbox)
+def test_output_format_for_visualization(age_gender_model, mock_image, mock_face):
+    result = age_gender_model.predict(mock_image, mock_face)
     text = f'{result.sex}, {result.age}y'
     assert isinstance(text, str), 'Should be able to format as string'
     assert 'Male' in text or 'Female' in text, 'Text should contain gender'
     assert 'y' in text, "Text should contain 'y' for years"
 
 
-def test_attribute_result_fields(age_gender_model, mock_image, mock_bbox):
+def test_attribute_result_fields(age_gender_model, mock_image, mock_face):
     """Test that AttributeResult has correct fields for AgeGender model."""
-    result = age_gender_model.predict(mock_image, mock_bbox)
+    result = age_gender_model.predict(mock_image, mock_face)
 
-    # AgeGender should set gender and age
     assert result.gender is not None
     assert result.age is not None
 
-    # AgeGender should NOT set race and age_group (FairFace only)
     assert result.race is None
     assert result.age_group is None

tests/test_factory.py

@@ -9,12 +9,14 @@ import numpy as np
 import pytest
 
 from uniface import (
+    create_attribute_predictor,
     create_detector,
     create_landmarker,
     create_recognizer,
     list_available_detectors,
 )
-from uniface.constants import RetinaFaceWeights, SCRFDWeights
+from uniface.attribute import AgeGender, FairFace
+from uniface.constants import AgeGenderWeights, FairFaceWeights, RetinaFaceWeights, SCRFDWeights
 from uniface.spoofing import MiniFASNet, create_spoofer
 
 
@@ -165,7 +167,7 @@ def test_recognizer_inference_from_factory():
 
     embedding = recognizer.get_embedding(mock_image)
     assert embedding is not None, 'Recognizer should return embedding'
-    assert embedding.shape[1] == 512, 'Should return 512-dimensional embedding'
+    assert embedding.shape == (1, 512), 'get_embedding should return (1, 512) with batch dimension'
 
 
 def test_landmarker_inference_from_factory():
@@ -236,3 +238,19 @@ def test_create_spoofer_with_providers():
     """Test that create_spoofer forwards providers kwarg without TypeError."""
     spoofer = create_spoofer(providers=['CPUExecutionProvider'])
     assert isinstance(spoofer, MiniFASNet), 'Should return MiniFASNet instance'
+
+
+# create_attribute_predictor tests
+def test_create_attribute_predictor_age_gender():
+    predictor = create_attribute_predictor(AgeGenderWeights.DEFAULT)
+    assert isinstance(predictor, AgeGender), 'Should return AgeGender instance'
+
+
+def test_create_attribute_predictor_fairface():
+    predictor = create_attribute_predictor(FairFaceWeights.DEFAULT)
+    assert isinstance(predictor, FairFace), 'Should return FairFace instance'
+
+
+def test_create_attribute_predictor_invalid():
+    with pytest.raises(ValueError, match='Unsupported attribute model'):
+        create_attribute_predictor('invalid_model')

tests/test_headpose.py

@@ -0,0 +1,115 @@
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from uniface import HeadPose, HeadPoseResult, create_head_pose_estimator
+from uniface.headpose import BaseHeadPoseEstimator
+from uniface.headpose.models import HeadPose as HeadPoseModel
+
+
+def test_create_head_pose_estimator_default():
+    """Test creating a head pose estimator with default parameters."""
+    estimator = create_head_pose_estimator()
+    assert isinstance(estimator, HeadPose), 'Should return HeadPose instance'
+
+
+def test_create_head_pose_estimator_aliases():
+    """Test that factory accepts all documented aliases."""
+    for alias in ('headpose', 'head_pose', '6drepnet'):
+        estimator = create_head_pose_estimator(alias)
+        assert isinstance(estimator, HeadPose), f"Alias '{alias}' should return HeadPose"
+
+
+def test_create_head_pose_estimator_invalid():
+    """Test that invalid method raises ValueError."""
+    with pytest.raises(ValueError, match='Unsupported head pose estimation method'):
+        create_head_pose_estimator('invalid_method')
+
+
+def test_head_pose_inference():
+    """Test that HeadPose can run inference on a mock image."""
+    estimator = HeadPose()
+    mock_image = np.random.randint(0, 255, (224, 224, 3), dtype=np.uint8)
+    result = estimator.estimate(mock_image)
+
+    assert isinstance(result, HeadPoseResult), 'Should return HeadPoseResult'
+    assert isinstance(result.pitch, float), 'pitch should be float'
+    assert isinstance(result.yaw, float), 'yaw should be float'
+    assert isinstance(result.roll, float), 'roll should be float'
+
+
+def test_head_pose_callable():
+    """Test that HeadPose is callable via __call__."""
+    estimator = HeadPose()
+    mock_image = np.random.randint(0, 255, (224, 224, 3), dtype=np.uint8)
+    result = estimator(mock_image)
+
+    assert isinstance(result, HeadPoseResult), '__call__ should return HeadPoseResult'
+
+
+def test_head_pose_result_repr():
+    """Test HeadPoseResult repr formatting."""
+    result = HeadPoseResult(pitch=10.5, yaw=-20.3, roll=5.1)
+    repr_str = repr(result)
+    assert 'HeadPoseResult' in repr_str
+    assert '10.5' in repr_str
+    assert '-20.3' in repr_str
+    assert '5.1' in repr_str
+
+
+def test_head_pose_result_frozen():
+    """Test that HeadPoseResult is immutable."""
+    result = HeadPoseResult(pitch=1.0, yaw=2.0, roll=3.0)
+    with pytest.raises(AttributeError):
+        result.pitch = 99.0  # type: ignore[misc]
+
+
+def test_rotation_matrix_to_euler_identity():
+    """Test that identity rotation matrix gives zero angles."""
+    identity = np.eye(3).reshape(1, 3, 3)
+    euler = HeadPoseModel.rotation_matrix_to_euler(identity)
+
+    assert euler.shape == (1, 3), 'Should return (1, 3) shaped array'
+    np.testing.assert_allclose(euler[0], [0.0, 0.0, 0.0], atol=1e-5)
+
+
+def test_rotation_matrix_to_euler_90deg_yaw():
+    """Test 90-degree yaw rotation."""
+    angle = np.radians(90)
+    R = np.array(
+        [
+            [np.cos(angle), 0, np.sin(angle)],
+            [0, 1, 0],
+            [-np.sin(angle), 0, np.cos(angle)],
+        ]
+    ).reshape(1, 3, 3)
+    euler = HeadPoseModel.rotation_matrix_to_euler(R)
+
+    np.testing.assert_allclose(euler[0, 1], 90.0, atol=1e-3)
+
+
+def test_rotation_matrix_to_euler_batch():
+    """Test batch processing of rotation matrices."""
+    batch = np.stack([np.eye(3), np.eye(3), np.eye(3)], axis=0)
+    euler = HeadPoseModel.rotation_matrix_to_euler(batch)
+
+    assert euler.shape == (3, 3), 'Batch of 3 should return (3, 3)'
+    np.testing.assert_allclose(euler, 0.0, atol=1e-5)
+
+
+def test_factory_returns_correct_type():
+    """Test that factory function returns BaseHeadPoseEstimator subclass."""
+    estimator = create_head_pose_estimator()
+    assert isinstance(estimator, BaseHeadPoseEstimator), 'Should be BaseHeadPoseEstimator subclass'
+
+
+def test_head_pose_with_providers():
+    """Test that HeadPose accepts providers kwarg."""
+    estimator = HeadPose(providers=['CPUExecutionProvider'])
+    assert isinstance(estimator, HeadPose), 'Should create with explicit providers'

tests/test_recognition.py

@@ -74,7 +74,7 @@ def test_arcface_embedding_shape(arcface_model, mock_aligned_face):
     """
     embedding = arcface_model.get_embedding(mock_aligned_face)
 
-    # ArcFace typically produces 512-dimensional embeddings
+    # ArcFace get_embedding returns raw ONNX output with batch dimension
     assert embedding.shape[1] == 512, f'Expected 512-dim embedding, got {embedding.shape[1]}'
     assert embedding.shape[0] == 1, 'Embedding should have batch dimension of 1'
 
@@ -88,7 +88,8 @@ def test_arcface_normalized_embedding(arcface_model, mock_landmarks):
 
     embedding = arcface_model.get_normalized_embedding(mock_image, mock_landmarks)
 
-    # Check that embedding is normalized (L2 norm ≈ 1.0)
+    # Check shape and normalization
+    assert embedding.shape == (512,), f'Expected shape (512,), got {embedding.shape}'
     norm = np.linalg.norm(embedding)
     assert np.isclose(norm, 1.0, atol=1e-5), f'Normalized embedding should have norm 1.0, got {norm}'
 
@@ -125,7 +126,7 @@ def test_mobileface_embedding_shape(mobileface_model, mock_aligned_face):
     """
     embedding = mobileface_model.get_embedding(mock_aligned_face)
 
-    # MobileFace typically produces 512-dimensional embeddings
+    # MobileFace get_embedding returns raw ONNX output with batch dimension
     assert embedding.shape[1] == 512, f'Expected 512-dim embedding, got {embedding.shape[1]}'
     assert embedding.shape[0] == 1, 'Embedding should have batch dimension of 1'
 
@@ -138,6 +139,7 @@ def test_mobileface_normalized_embedding(mobileface_model, mock_landmarks):
 
     embedding = mobileface_model.get_normalized_embedding(mock_image, mock_landmarks)
 
+    assert embedding.shape == (512,), f'Expected shape (512,), got {embedding.shape}'
     norm = np.linalg.norm(embedding)
     assert np.isclose(norm, 1.0, atol=1e-5), f'Normalized embedding should have norm 1.0, got {norm}'
 
@@ -156,7 +158,7 @@ def test_sphereface_embedding_shape(sphereface_model, mock_aligned_face):
     """
     embedding = sphereface_model.get_embedding(mock_aligned_face)
 
-    # SphereFace typically produces 512-dimensional embeddings
+    # SphereFace get_embedding returns raw ONNX output with batch dimension
     assert embedding.shape[1] == 512, f'Expected 512-dim embedding, got {embedding.shape[1]}'
     assert embedding.shape[0] == 1, 'Embedding should have batch dimension of 1'
 
@@ -169,6 +171,7 @@ def test_sphereface_normalized_embedding(sphereface_model, mock_landmarks):
 
     embedding = sphereface_model.get_normalized_embedding(mock_image, mock_landmarks)
 
+    assert embedding.shape == (512,), f'Expected shape (512,), got {embedding.shape}'
     norm = np.linalg.norm(embedding)
     assert np.isclose(norm, 1.0, atol=1e-5), f'Normalized embedding should have norm 1.0, got {norm}'
 

tools/README.md

@@ -12,9 +12,11 @@ CLI utilities for testing and running UniFace features.
 | `anonymize.py` | Face anonymization/blurring for privacy |
 | `emotion.py` | Emotion detection (7 or 8 emotions) |
 | `gaze.py` | Gaze direction estimation |
+| `headpose.py` | Head pose estimation (pitch, yaw, roll) |
 | `landmarks.py` | 106-point facial landmark detection |
 | `recognize.py` | Face embedding extraction and comparison |
 | `search.py` | Real-time face matching against reference |
+| `faiss_search.py` | FAISS index build and multi-identity face search |
 | `fairface.py` | FairFace attribute prediction (race, gender, age) |
 | `attribute.py` | Age and gender prediction |
 | `spoofing.py` | Face anti-spoofing detection |
@@ -61,6 +63,11 @@ python tools/emotion.py --source 0
 python tools/gaze.py --source assets/test.jpg
 python tools/gaze.py --source 0
 
+# Head pose estimation
+python tools/headpose.py --source assets/test.jpg
+python tools/headpose.py --source 0
+python tools/headpose.py --source 0 --draw-type axis
+
 # Landmarks
 python tools/landmarks.py --source assets/test.jpg
 python tools/landmarks.py --source 0
@@ -108,7 +115,7 @@ python tools/download_model.py  # downloads all
 | Option | Description |
 |--------|-------------|
 | `--source` | Input source: image/video path or camera ID (0, 1, ...) |
-| `--detector` | Choose detector: `retinaface`, `scrfd`, `yolov5face` |
+| `--detector` | Choose detector: `retinaface`, `scrfd`, `yolov5face`, `yolov8face` |
 | `--threshold` | Visualization confidence threshold (default: varies) |
 | `--save-dir` | Output directory (default: `outputs`) |
 

tools/analyze.py

@@ -167,9 +167,9 @@ def run_camera(analyzer, camera_id: int = 0):
 
     while True:
         ret, frame = cap.read()
-        frame = cv2.flip(frame, 1)
         if not ret:
             break
+        frame = cv2.flip(frame, 1)
 
         faces = analyzer.analyze(frame)
 
@@ -201,7 +201,7 @@ def main():
     detector = RetinaFace()
     recognizer = ArcFace()
     age_gender = AgeGender()
-    analyzer = FaceAnalyzer(detector, recognizer, age_gender)
+    analyzer = FaceAnalyzer(detector, recognizer=recognizer, attributes=[age_gender])
 
     source_type = get_source_type(args.source)
 

tools/anonymize.py

@@ -121,9 +121,9 @@ def run_camera(detector, blurrer: BlurFace, camera_id: int = 0):
 
     while True:
         ret, frame = cap.read()
-        frame = cv2.flip(frame, 1)
         if not ret:
             break
+        frame = cv2.flip(frame, 1)
 
         faces = detector.detect(frame)
         if faces:

tools/attribute.py

@@ -60,7 +60,7 @@ def process_image(
     )
 
     for i, face in enumerate(faces):
-        result = age_gender.predict(image, face.bbox)
+        result = age_gender.predict(image, face)
         print(f'  Face {i + 1}: {result.sex}, {result.age} years old')
         draw_age_gender_label(image, face.bbox, result.sex, result.age)
 
@@ -112,7 +112,7 @@ def process_video(
         )
 
         for face in faces:
-            result = age_gender.predict(frame, face.bbox)
+            result = age_gender.predict(frame, face)
             draw_age_gender_label(frame, face.bbox, result.sex, result.age)
 
         cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
@@ -137,9 +137,9 @@ def run_camera(detector, age_gender, camera_id: int = 0, threshold: float = 0.6)
 
     while True:
         ret, frame = cap.read()
-        frame = cv2.flip(frame, 1)
         if not ret:
             break
+        frame = cv2.flip(frame, 1)
 
         faces = detector.detect(frame)
 
@@ -151,7 +151,7 @@ def run_camera(detector, age_gender, camera_id: int = 0, threshold: float = 0.6)
         )
 
         for face in faces:
-            result = age_gender.predict(frame, face.bbox)
+            result = age_gender.predict(frame, face)
             draw_age_gender_label(frame, face.bbox, result.sex, result.age)
 
         cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)

tools/detect.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 import argparse
 import os
 from pathlib import Path
+import time
 
 from _common import get_source_type
 import cv2
@@ -83,6 +84,7 @@ def process_video(
         if not ret:
             break
 
+        t0 = time.perf_counter()
         frame_count += 1
         faces = detector.detect(frame)
         total_faces += len(faces)
@@ -100,7 +102,9 @@ def process_video(
             corner_bbox=True,
         )
 
-        cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+        inference_fps = 1.0 / max(time.perf_counter() - t0, 1e-9)
+        cv2.putText(frame, f'FPS: {inference_fps:.1f}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+        cv2.putText(frame, f'Faces: {len(faces)}', (10, 65), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
         out.write(frame)
 
         if show_preview:
@@ -128,11 +132,12 @@ def run_camera(detector, camera_id: int = 0, threshold: float = 0.6):
 
     print("Press 'q' to quit")
 
+    prev_time = time.perf_counter()
     while True:
         ret, frame = cap.read()
-        frame = cv2.flip(frame, 1)
         if not ret:
             break
+        frame = cv2.flip(frame, 1)
 
         faces = detector.detect(frame)
 
@@ -149,7 +154,11 @@ def run_camera(detector, camera_id: int = 0, threshold: float = 0.6):
             corner_bbox=True,
         )
 
-        cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+        curr_time = time.perf_counter()
+        fps = 1.0 / max(curr_time - prev_time, 1e-9)
+        prev_time = curr_time
+        cv2.putText(frame, f'FPS: {fps:.1f}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+        cv2.putText(frame, f'Faces: {len(faces)}', (10, 65), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
         cv2.imshow('Face Detection', frame)
 
         if cv2.waitKey(1) & 0xFF == ord('q'):

tools/download_model.py

@@ -4,6 +4,7 @@ from uniface.constants import (
     AgeGenderWeights,
     ArcFaceWeights,
     DDAMFNWeights,
+    HeadPoseWeights,
     LandmarkWeights,
     MobileFaceWeights,
     RetinaFaceWeights,
@@ -21,6 +22,7 @@ MODEL_TYPES = {
     'ddamfn': DDAMFNWeights,
     'agegender': AgeGenderWeights,
     'landmark': LandmarkWeights,
+    'headpose': HeadPoseWeights,
 }
 
 

tools/emotion.py

@@ -60,7 +60,7 @@ def process_image(
     )
 
     for i, face in enumerate(faces):
-        result = emotion_predictor.predict(image, face.landmarks)
+        result = emotion_predictor.predict(image, face)
         print(f'  Face {i + 1}: {result.emotion} (confidence: {result.confidence:.3f})')
         draw_emotion_label(image, face.bbox, result.emotion, result.confidence)
 
@@ -112,7 +112,7 @@ def process_video(
         )
 
         for face in faces:
-            result = emotion_predictor.predict(frame, face.landmarks)
+            result = emotion_predictor.predict(frame, face)
             draw_emotion_label(frame, face.bbox, result.emotion, result.confidence)
 
         cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
@@ -137,9 +137,9 @@ def run_camera(detector, emotion_predictor, camera_id: int = 0, threshold: float
 
     while True:
         ret, frame = cap.read()
-        frame = cv2.flip(frame, 1)
         if not ret:
             break
+        frame = cv2.flip(frame, 1)
 
         faces = detector.detect(frame)
 
@@ -151,7 +151,7 @@ def run_camera(detector, emotion_predictor, camera_id: int = 0, threshold: float
         )
 
         for face in faces:
-            result = emotion_predictor.predict(frame, face.landmarks)
+            result = emotion_predictor.predict(frame, face)
             draw_emotion_label(frame, face.bbox, result.emotion, result.confidence)
 
         cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)

tools/fairface.py

@@ -60,7 +60,7 @@ def process_image(
     )
 
     for i, face in enumerate(faces):
-        result = fairface.predict(image, face.bbox)
+        result = fairface.predict(image, face)
         print(f'  Face {i + 1}: {result.sex}, {result.age_group}, {result.race}')
         draw_fairface_label(image, face.bbox, result.sex, result.age_group, result.race)
 
@@ -112,7 +112,7 @@ def process_video(
         )
 
         for face in faces:
-            result = fairface.predict(frame, face.bbox)
+            result = fairface.predict(frame, face)
             draw_fairface_label(frame, face.bbox, result.sex, result.age_group, result.race)
 
         cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
@@ -137,9 +137,9 @@ def run_camera(detector, fairface, camera_id: int = 0, threshold: float = 0.6):
 
     while True:
         ret, frame = cap.read()
-        frame = cv2.flip(frame, 1)
         if not ret:
             break
+        frame = cv2.flip(frame, 1)
 
         faces = detector.detect(frame)
 
@@ -151,7 +151,7 @@ def run_camera(detector, fairface, camera_id: int = 0, threshold: float = 0.6):
         )
 
         for face in faces:
-            result = fairface.predict(frame, face.bbox)
+            result = fairface.predict(frame, face)
             draw_fairface_label(frame, face.bbox, result.sex, result.age_group, result.race)
 
         cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)

tools/faiss_search.py

@@ -0,0 +1,208 @@
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""FAISS index build and multi-identity face search.
+
+Build a vector index from a directory of person sub-folders, then search
+against it in a video or webcam stream.
+
+Usage:
+    python tools/faiss_search.py build --faces-dir dataset/ --db-path ./vector_index
+    python tools/faiss_search.py run   --db-path ./vector_index --source video.mp4
+    python tools/faiss_search.py run   --db-path ./vector_index --source 0  # webcam
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+from _common import IMAGE_EXTENSIONS, get_source_type
+import cv2
+
+from uniface import create_detector, create_recognizer
+from uniface.draw import draw_corner_bbox, draw_text_label
+from uniface.indexing import FAISS
+
+
+def _draw_face(image, bbox, text: str, color: tuple[int, int, int]) -> None:
+    x1, y1, x2, y2 = map(int, bbox[:4])
+    thickness = max(round(sum(image.shape[:2]) / 2 * 0.003), 2)
+    font_scale = max(0.4, min(0.7, (y2 - y1) / 200))
+    draw_corner_bbox(image, (x1, y1, x2, y2), color=color, thickness=thickness)
+    draw_text_label(image, text, x1, y1, bg_color=color, font_scale=font_scale)
+
+
+def process_frame(frame, detector, recognizer, store: FAISS, threshold: float = 0.4):
+    faces = detector.detect(frame)
+    if not faces:
+        return frame
+
+    for face in faces:
+        embedding = recognizer.get_normalized_embedding(frame, face.landmarks)
+        result, sim = store.search(embedding, threshold=threshold)
+
+        text = f'{result["person_id"]} ({sim:.2f})' if result else f'Unknown ({sim:.2f})'
+        color = (0, 255, 0) if result else (0, 0, 255)
+        _draw_face(frame, face.bbox, text, color)
+
+    return frame
+
+
+def process_video(detector, recognizer, store: FAISS, video_path: str, save_dir: str, threshold: float = 0.4):
+    cap = cv2.VideoCapture(video_path)
+    if not cap.isOpened():
+        print(f"Error: Cannot open video file '{video_path}'")
+        return
+
+    fps = cap.get(cv2.CAP_PROP_FPS)
+    width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+    height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+    total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+
+    os.makedirs(save_dir, exist_ok=True)
+    output_path = os.path.join(save_dir, f'{Path(video_path).stem}_faiss_search.mp4')
+    fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+    out = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
+
+    print(f'Processing video: {video_path} ({total_frames} frames)')
+    frame_count = 0
+
+    while True:
+        ret, frame = cap.read()
+        if not ret:
+            break
+
+        frame_count += 1
+        frame = process_frame(frame, detector, recognizer, store, threshold)
+        out.write(frame)
+
+        if frame_count % 100 == 0:
+            print(f'  Processed {frame_count}/{total_frames} frames...')
+
+    cap.release()
+    out.release()
+    print(f'Done! Output saved: {output_path}')
+
+
+def run_camera(detector, recognizer, store: FAISS, camera_id: int = 0, threshold: float = 0.4):
+    cap = cv2.VideoCapture(camera_id)
+    if not cap.isOpened():
+        print(f'Cannot open camera {camera_id}')
+        return
+
+    print("Press 'q' to quit")
+
+    while True:
+        ret, frame = cap.read()
+        if not ret:
+            break
+        frame = cv2.flip(frame, 1)
+
+        frame = process_frame(frame, detector, recognizer, store, threshold)
+
+        cv2.imshow('Vector Search', frame)
+        if cv2.waitKey(1) & 0xFF == ord('q'):
+            break
+
+    cap.release()
+    cv2.destroyAllWindows()
+
+
+def build(args: argparse.Namespace) -> None:
+    faces_dir = Path(args.faces_dir)
+    if not faces_dir.is_dir():
+        print(f"Error: '{faces_dir}' is not a directory")
+        return
+
+    detector = create_detector()
+    recognizer = create_recognizer()
+    store = FAISS(db_path=args.db_path)
+
+    persons = sorted(p.name for p in faces_dir.iterdir() if p.is_dir())
+    if not persons:
+        print(f"Error: No sub-folders found in '{faces_dir}'")
+        return
+
+    print(f'Found {len(persons)} persons: {", ".join(persons)}')
+
+    total_added = 0
+    for person_id in persons:
+        person_dir = faces_dir / person_id
+        images = [f for f in person_dir.iterdir() if f.suffix.lower() in IMAGE_EXTENSIONS]
+
+        added = 0
+        for img_path in images:
+            image = cv2.imread(str(img_path))
+            if image is None:
+                print(f'  Warning: Failed to read {img_path}, skipping')
+                continue
+
+            faces = detector.detect(image)
+            if not faces:
+                print(f'  Warning: No face detected in {img_path}, skipping')
+                continue
+
+            embedding = recognizer.get_normalized_embedding(image, faces[0].landmarks)
+            store.add(embedding, {'person_id': person_id, 'source': str(img_path)})
+            added += 1
+
+        total_added += added
+        if added:
+            print(f'  {person_id}: {added} embeddings added')
+        else:
+            print(f'  {person_id}: no valid faces found')
+
+    store.save()
+    print(f'\nIndex saved to {args.db_path} ({total_added} vectors, {len(persons)} persons)')
+
+
+def run(args: argparse.Namespace) -> None:
+    detector = create_detector()
+    recognizer = create_recognizer()
+
+    store = FAISS(db_path=args.db_path)
+    if not store.load():
+        print(f"Error: No index found at '{args.db_path}'")
+        return
+    print(f'Loaded FAISS index: {store}')
+
+    source_type = get_source_type(args.source)
+
+    if source_type == 'camera':
+        run_camera(detector, recognizer, store, int(args.source), args.threshold)
+    elif source_type == 'video':
+        if not os.path.exists(args.source):
+            print(f'Error: Video not found: {args.source}')
+            return
+        process_video(detector, recognizer, store, args.source, args.save_dir, args.threshold)
+    else:
+        print(f"Error: Source must be a video file or camera ID, not '{args.source}'")
+
+
+def main():
+    parser = argparse.ArgumentParser(description='FAISS vector search')
+    sub = parser.add_subparsers(dest='command', required=True)
+
+    build_p = sub.add_parser('build', help='Build a FAISS index from person sub-folders')
+    build_p.add_argument('--faces-dir', type=str, required=True, help='Directory with person sub-folders')
+    build_p.add_argument('--db-path', type=str, default='./vector_index', help='Where to save the index')
+
+    run_p = sub.add_parser('run', help='Search faces against a FAISS index')
+    run_p.add_argument('--db-path', type=str, required=True, help='Path to saved FAISS index')
+    run_p.add_argument('--source', type=str, required=True, help='Video path or camera ID')
+    run_p.add_argument('--threshold', type=float, default=0.4, help='Similarity threshold')
+    run_p.add_argument('--save-dir', type=str, default='outputs', help='Output directory')
+
+    args = parser.parse_args()
+
+    if args.command == 'build':
+        build(args)
+    elif args.command == 'run':
+        run(args)
+
+
+if __name__ == '__main__':
+    main()

tools/headpose.py

@@ -0,0 +1,181 @@
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""Head pose estimation on detected faces.
+
+Usage:
+    python tools/headpose.py --source path/to/image.jpg
+    python tools/headpose.py --source path/to/video.mp4
+    python tools/headpose.py --source 0  # webcam
+    python tools/headpose.py --source path/to/image.jpg --draw-type axis
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+from _common import get_source_type
+import cv2
+
+from uniface.detection import RetinaFace
+from uniface.draw import draw_head_pose
+from uniface.headpose import HeadPose
+
+
+def process_image(detector, head_pose_estimator, image_path: str, save_dir: str = 'outputs', draw_type: str = 'cube'):
+    """Process a single image."""
+    image = cv2.imread(image_path)
+    if image is None:
+        print(f"Error: Failed to load image from '{image_path}'")
+        return
+
+    faces = detector.detect(image)
+    print(f'Detected {len(faces)} face(s)')
+
+    for i, face in enumerate(faces):
+        bbox = face.bbox
+        x1, y1, x2, y2 = map(int, bbox[:4])
+        face_crop = image[y1:y2, x1:x2]
+
+        if face_crop.size == 0:
+            continue
+
+        result = head_pose_estimator.estimate(face_crop)
+        print(f'  Face {i + 1}: pitch={result.pitch:.1f}°, yaw={result.yaw:.1f}°, roll={result.roll:.1f}°')
+
+        draw_head_pose(image, bbox, result.pitch, result.yaw, result.roll, draw_type=draw_type)
+
+    os.makedirs(save_dir, exist_ok=True)
+    output_path = os.path.join(save_dir, f'{Path(image_path).stem}_headpose.jpg')
+    cv2.imwrite(output_path, image)
+    print(f'Output saved: {output_path}')
+
+
+def process_video(detector, head_pose_estimator, video_path: str, save_dir: str = 'outputs', draw_type: str = 'cube'):
+    """Process a video file."""
+    cap = cv2.VideoCapture(video_path)
+    if not cap.isOpened():
+        print(f"Error: Cannot open video file '{video_path}'")
+        return
+
+    fps = cap.get(cv2.CAP_PROP_FPS)
+    width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+    height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+    total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+
+    os.makedirs(save_dir, exist_ok=True)
+    output_path = os.path.join(save_dir, f'{Path(video_path).stem}_headpose.mp4')
+    fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+    out = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
+
+    print(f'Processing video: {video_path} ({total_frames} frames)')
+    frame_count = 0
+
+    while True:
+        ret, frame = cap.read()
+        if not ret:
+            break
+
+        frame_count += 1
+        faces = detector.detect(frame)
+
+        for face in faces:
+            bbox = face.bbox
+            x1, y1, x2, y2 = map(int, bbox[:4])
+            face_crop = frame[y1:y2, x1:x2]
+
+            if face_crop.size == 0:
+                continue
+
+            result = head_pose_estimator.estimate(face_crop)
+            draw_head_pose(frame, bbox, result.pitch, result.yaw, result.roll, draw_type=draw_type)
+
+        cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+        out.write(frame)
+
+        if frame_count % 100 == 0:
+            print(f'  Processed {frame_count}/{total_frames} frames...')
+
+    cap.release()
+    out.release()
+    print(f'Done! Output saved: {output_path}')
+
+
+def run_camera(detector, head_pose_estimator, camera_id: int = 0, draw_type: str = 'cube'):
+    """Run real-time detection on webcam."""
+    cap = cv2.VideoCapture(camera_id)
+    if not cap.isOpened():
+        print(f'Cannot open camera {camera_id}')
+        return
+
+    print("Press 'q' to quit")
+
+    while True:
+        ret, frame = cap.read()
+        if not ret:
+            break
+
+        frame = cv2.flip(frame, 1)
+        faces = detector.detect(frame)
+
+        for face in faces:
+            bbox = face.bbox
+            x1, y1, x2, y2 = map(int, bbox[:4])
+            face_crop = frame[y1:y2, x1:x2]
+
+            if face_crop.size == 0:
+                continue
+
+            result = head_pose_estimator.estimate(face_crop)
+            draw_head_pose(frame, bbox, result.pitch, result.yaw, result.roll, draw_type=draw_type)
+
+        cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+        cv2.imshow('Head Pose Estimation', frame)
+
+        if cv2.waitKey(1) & 0xFF == ord('q'):
+            break
+
+    cap.release()
+    cv2.destroyAllWindows()
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Run head pose estimation')
+    parser.add_argument('--source', type=str, required=True, help='Image/video path or camera ID (0, 1, ...)')
+    parser.add_argument('--save-dir', type=str, default='outputs', help='Output directory')
+    parser.add_argument(
+        '--draw-type',
+        type=str,
+        default='cube',
+        choices=['cube', 'axis'],
+        help='Visualization type: cube (default) or axis',
+    )
+    args = parser.parse_args()
+
+    detector = RetinaFace()
+    head_pose_estimator = HeadPose()
+
+    source_type = get_source_type(args.source)
+
+    if source_type == 'camera':
+        run_camera(detector, head_pose_estimator, int(args.source), args.draw_type)
+    elif source_type == 'image':
+        if not os.path.exists(args.source):
+            print(f'Error: Image not found: {args.source}')
+            return
+        process_image(detector, head_pose_estimator, args.source, args.save_dir, args.draw_type)
+    elif source_type == 'video':
+        if not os.path.exists(args.source):
+            print(f'Error: Video not found: {args.source}')
+            return
+        process_video(detector, head_pose_estimator, args.source, args.save_dir, args.draw_type)
+    else:
+        print(f"Error: Unknown source type for '{args.source}'")
+        print('Supported formats: images (.jpg, .png, ...), videos (.mp4, .avi, ...), or camera ID (0, 1, ...)')
+
+
+if __name__ == '__main__':
+    main()

tools/landmarks.py

@@ -114,9 +114,9 @@ def run_camera(detector, landmarker, camera_id: int = 0):
 
     while True:
         ret, frame = cap.read()
-        frame = cv2.flip(frame, 1)
         if not ret:
             break
+        frame = cv2.flip(frame, 1)
 
         faces = detector.detect(frame)
 

tools/recognize.py

@@ -41,12 +41,13 @@ def run_inference(detector, recognizer, image_path: str):
 
     print(f'Detected {len(faces)} face(s). Extracting embedding for the first face...')
 
-    landmarks = faces[0].landmarks  # 5-point landmarks for alignment (already np.ndarray)
+    landmarks = faces[0].landmarks
     embedding = recognizer.get_embedding(image, landmarks)
-    norm_embedding = recognizer.get_normalized_embedding(image, landmarks)  # L2 normalized
+    raw_norm = np.linalg.norm(embedding)
+    norm_embedding = embedding.ravel() / raw_norm if raw_norm > 0 else embedding.ravel()
 
     print(f'  Embedding shape: {embedding.shape}')
-    print(f'  L2 norm (raw): {np.linalg.norm(embedding):.4f}')
+    print(f'  L2 norm (raw): {raw_norm:.4f}')
     print(f'  L2 norm (normalized): {np.linalg.norm(norm_embedding):.4f}')
 
 

tools/search.py

@@ -2,11 +2,14 @@
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo
 
-"""Real-time face search: match faces against a reference image.
+"""Single-reference face search on video or webcam.
+
+Given a reference face image, detects faces in the source and shows
+whether each face matches the reference.
 
 Usage:
-    python tools/search.py --reference person.jpg --source 0  # webcam
-    python tools/search.py --reference person.jpg --source video.mp4
+    python tools/search.py --reference ref.jpg --source video.mp4
+    python tools/search.py --reference ref.jpg --source 0  # webcam
 """
 
 from __future__ import annotations
@@ -19,23 +22,12 @@ from _common import get_source_type
 import cv2
 import numpy as np
 
-from uniface.detection import SCRFD, RetinaFace
+from uniface import create_detector, create_recognizer
+from uniface.draw import draw_corner_bbox, draw_text_label
 from uniface.face_utils import compute_similarity
-from uniface.recognition import ArcFace, MobileFace, SphereFace
-
-
-def get_recognizer(name: str):
-    """Get recognizer by name."""
-    if name == 'arcface':
-        return ArcFace()
-    elif name == 'mobileface':
-        return MobileFace()
-    else:
-        return SphereFace()
 
 
 def extract_reference_embedding(detector, recognizer, image_path: str) -> np.ndarray:
-    """Extract embedding from reference image."""
     image = cv2.imread(image_path)
     if image is None:
         raise RuntimeError(f'Failed to load image: {image_path}')
@@ -44,33 +36,34 @@ def extract_reference_embedding(detector, recognizer, image_path: str) -> np.nda
     if not faces:
         raise RuntimeError('No faces found in reference image.')
 
-    landmarks = faces[0].landmarks
-    return recognizer.get_normalized_embedding(image, landmarks)
+    return recognizer.get_normalized_embedding(image, faces[0].landmarks)
+
+
+def _draw_face(image, bbox, text: str, color: tuple[int, int, int]) -> None:
+    x1, y1, x2, y2 = map(int, bbox[:4])
+    thickness = max(round(sum(image.shape[:2]) / 2 * 0.003), 2)
+    font_scale = max(0.4, min(0.7, (y2 - y1) / 200))
+    draw_corner_bbox(image, (x1, y1, x2, y2), color=color, thickness=thickness)
+    draw_text_label(image, text, x1, y1, bg_color=color, font_scale=font_scale)
 
 
 def process_frame(frame, detector, recognizer, ref_embedding: np.ndarray, threshold: float = 0.4):
-    """Process a single frame and return annotated frame."""
     faces = detector.detect(frame)
 
     for face in faces:
-        bbox = face.bbox
-        landmarks = face.landmarks
-        x1, y1, x2, y2 = map(int, bbox)
-
-        embedding = recognizer.get_normalized_embedding(frame, landmarks)
+        embedding = recognizer.get_normalized_embedding(frame, face.landmarks)
         sim = compute_similarity(ref_embedding, embedding)
 
-        label = f'Match ({sim:.2f})' if sim > threshold else f'Unknown ({sim:.2f})'
+        text = f'Match ({sim:.2f})' if sim > threshold else f'Unknown ({sim:.2f})'
         color = (0, 255, 0) if sim > threshold else (0, 0, 255)
-
-        cv2.rectangle(frame, (x1, y1), (x2, y2), color, 2)
-        cv2.putText(frame, label, (x1, y1 - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.6, color, 2)
+        _draw_face(frame, face.bbox, text, color)
 
     return frame
 
 
-def process_video(detector, recognizer, ref_embedding: np.ndarray, video_path: str, save_dir: str, threshold: float):
-    """Process a video file."""
+def process_video(
+    detector, recognizer, video_path: str, save_dir: str, ref_embedding: np.ndarray, threshold: float = 0.4
+):
     cap = cv2.VideoCapture(video_path)
     if not cap.isOpened():
         print(f"Error: Cannot open video file '{video_path}'")
@@ -107,7 +100,6 @@ def process_video(detector, recognizer, ref_embedding: np.ndarray, video_path: s
 
 
 def run_camera(detector, recognizer, ref_embedding: np.ndarray, camera_id: int = 0, threshold: float = 0.4):
-    """Run real-time face search on webcam."""
     cap = cv2.VideoCapture(camera_id)
     if not cap.isOpened():
         print(f'Cannot open camera {camera_id}')
@@ -117,13 +109,13 @@ def run_camera(detector, recognizer, ref_embedding: np.ndarray, camera_id: int =
 
     while True:
         ret, frame = cap.read()
-        frame = cv2.flip(frame, 1)
         if not ret:
             break
+        frame = cv2.flip(frame, 1)
 
         frame = process_frame(frame, detector, recognizer, ref_embedding, threshold)
 
-        cv2.imshow('Face Recognition', frame)
+        cv2.imshow('Face Search', frame)
         if cv2.waitKey(1) & 0xFF == ord('q'):
             break
 
@@ -132,17 +124,10 @@ def run_camera(detector, recognizer, ref_embedding: np.ndarray, camera_id: int =
 
 
 def main():
-    parser = argparse.ArgumentParser(description='Face search using a reference image')
+    parser = argparse.ArgumentParser(description='Single-reference face search')
     parser.add_argument('--reference', type=str, required=True, help='Reference face image')
-    parser.add_argument('--source', type=str, required=True, help='Video path or camera ID (0, 1, ...)')
-    parser.add_argument('--threshold', type=float, default=0.4, help='Match threshold')
-    parser.add_argument('--detector', type=str, default='scrfd', choices=['retinaface', 'scrfd'])
-    parser.add_argument(
-        '--recognizer',
-        type=str,
-        default='arcface',
-        choices=['arcface', 'mobileface', 'sphereface'],
-    )
+    parser.add_argument('--source', type=str, required=True, help='Video path or camera ID')
+    parser.add_argument('--threshold', type=float, default=0.4, help='Similarity threshold')
     parser.add_argument('--save-dir', type=str, default='outputs', help='Output directory')
     args = parser.parse_args()
 
@@ -150,8 +135,8 @@ def main():
         print(f'Error: Reference image not found: {args.reference}')
         return
 
-    detector = RetinaFace() if args.detector == 'retinaface' else SCRFD()
-    recognizer = get_recognizer(args.recognizer)
+    detector = create_detector()
+    recognizer = create_recognizer()
 
     print(f'Loading reference: {args.reference}')
     ref_embedding = extract_reference_embedding(detector, recognizer, args.reference)
@@ -164,10 +149,9 @@ def main():
         if not os.path.exists(args.source):
             print(f'Error: Video not found: {args.source}')
             return
-        process_video(detector, recognizer, ref_embedding, args.source, args.save_dir, args.threshold)
+        process_video(detector, recognizer, args.source, args.save_dir, ref_embedding, args.threshold)
     else:
         print(f"Error: Source must be a video file or camera ID, not '{args.source}'")
-        print('Supported formats: videos (.mp4, .avi, ...) or camera ID (0, 1, ...)')
 
 
 if __name__ == '__main__':

tools/track.py

@@ -134,9 +134,9 @@ def run_camera(
 
     while True:
         ret, frame = cap.read()
-        frame = cv2.flip(frame, 1)
         if not ret:
             break
+        frame = cv2.flip(frame, 1)
 
         # Detect faces
         faces = detector.detect(frame)

uniface/__init__.py

@@ -20,6 +20,7 @@ This library provides unified APIs for:
 - Facial landmarks (106-point detection)
 - Face parsing (semantic segmentation)
 - Gaze estimation
+- Head pose estimation
 - Age, gender, and emotion prediction
 - Face anti-spoofing
 - Privacy/anonymization
@@ -29,14 +30,16 @@ from __future__ import annotations
 
 __license__ = 'MIT'
 __author__ = 'Yakhyokhuja Valikhujaev'
-__version__ = '3.0.0'
+__version__ = '3.2.0'
+
+import contextlib
 
 from uniface.face_utils import compute_similarity, face_alignment
 from uniface.log import Logger, enable_logging
 from uniface.model_store import download_models, get_cache_dir, set_cache_dir, verify_model_weights
 
 from .analyzer import FaceAnalyzer
-from .attribute import AgeGender, Emotion, FairFace
+from .attribute import AgeGender, Emotion, FairFace, create_attribute_predictor
 from .detection import (
     SCRFD,
     RetinaFace,
@@ -46,13 +49,18 @@ from .detection import (
     list_available_detectors,
 )
 from .gaze import MobileGaze, create_gaze_estimator
+from .headpose import HeadPose, create_head_pose_estimator
 from .landmark import Landmark106, create_landmarker
 from .parsing import BiSeNet, XSeg, create_face_parser
 from .privacy import BlurFace
 from .recognition import AdaFace, ArcFace, MobileFace, SphereFace, create_recognizer
 from .spoofing import MiniFASNet, create_spoofer
 from .tracking import BYTETracker
-from .types import AttributeResult, EmotionResult, Face, GazeResult, SpoofingResult
+from .types import AttributeResult, EmotionResult, Face, GazeResult, HeadPoseResult, SpoofingResult
+
+# Optional: FAISS vector store (requires `pip install faiss-cpu`)
+with contextlib.suppress(ImportError):
+    from .indexing import FAISS
 
 __all__ = [
     # Metadata
@@ -66,6 +74,7 @@ __all__ = [
     'create_detector',
     'create_face_parser',
     'create_gaze_estimator',
+    'create_head_pose_estimator',
     'create_landmarker',
     'create_recognizer',
     'create_spoofer',
@@ -85,12 +94,16 @@ __all__ = [
     # Gaze models
     'GazeResult',
     'MobileGaze',
+    # Head pose models
+    'HeadPose',
+    'HeadPoseResult',
     # Parsing models
     'BiSeNet',
     'XSeg',
     # Attribute models
     'AgeGender',
     'AttributeResult',
+    'create_attribute_predictor',
     'Emotion',
     'EmotionResult',
     'FairFace',
@@ -101,6 +114,8 @@ __all__ = [
     'BYTETracker',
     # Privacy
     'BlurFace',
+    # Indexing (optional)
+    'FAISS',
     # Utilities
     'Logger',
     'compute_similarity',

uniface/analyzer.py

@@ -6,8 +6,7 @@ from __future__ import annotations
 
 import numpy as np
 
-from uniface.attribute.age_gender import AgeGender
-from uniface.attribute.fairface import FairFace
+from uniface.attribute.base import Attribute
 from uniface.detection.base import BaseDetector
 from uniface.log import Logger
 from uniface.recognition.base import BaseRecognizer
@@ -21,19 +20,24 @@ class FaceAnalyzer:
 
     This class provides a high-level interface for face analysis by combining
     multiple components: face detection, recognition (embedding extraction),
-    and attribute prediction (age, gender, race).
+    and an extensible list of attribute predictors (age, gender, race,
+    emotion, etc.).
+
+    Any :class:`~uniface.attribute.base.Attribute` subclass can be passed
+    via the ``attributes`` list.  Each predictor's ``predict(image, face)``
+    is called once per detected face, enriching the :class:`Face` in-place.
 
     Args:
         detector: Face detector instance for detecting faces in images.
         recognizer: Optional face recognizer for extracting embeddings.
-        age_gender: Optional age/gender predictor.
-        fairface: Optional FairFace predictor for demographics.
+        attributes: Optional list of ``Attribute`` predictors to run on
+            each detected face (e.g. ``[AgeGender(), FairFace(), Emotion()]``).
 
     Example:
-        >>> from uniface import RetinaFace, ArcFace, FaceAnalyzer
+        >>> from uniface import RetinaFace, ArcFace, AgeGender, FaceAnalyzer
         >>> detector = RetinaFace()
         >>> recognizer = ArcFace()
-        >>> analyzer = FaceAnalyzer(detector, recognizer=recognizer)
+        >>> analyzer = FaceAnalyzer(detector, recognizer=recognizer, attributes=[AgeGender()])
         >>> faces = analyzer.analyze(image)
     """
 
@@ -41,27 +45,23 @@ class FaceAnalyzer:
         self,
         detector: BaseDetector,
         recognizer: BaseRecognizer | None = None,
-        age_gender: AgeGender | None = None,
-        fairface: FairFace | None = None,
+        attributes: list[Attribute] | None = None,
     ) -> None:
         self.detector = detector
         self.recognizer = recognizer
-        self.age_gender = age_gender
-        self.fairface = fairface
+        self.attributes: list[Attribute] = attributes or []
 
         Logger.info(f'Initialized FaceAnalyzer with detector={detector.__class__.__name__}')
         if recognizer:
             Logger.info(f'  - Recognition enabled: {recognizer.__class__.__name__}')
-        if age_gender:
-            Logger.info(f'  - Age/Gender enabled: {age_gender.__class__.__name__}')
-        if fairface:
-            Logger.info(f'  - FairFace enabled: {fairface.__class__.__name__}')
+        for attr in self.attributes:
+            Logger.info(f'  - Attribute enabled: {attr.__class__.__name__}')
 
     def analyze(self, image: np.ndarray) -> list[Face]:
         """Analyze faces in an image.
 
-        Performs face detection and optionally extracts embeddings and
-        predicts attributes for each detected face.
+        Performs face detection, optionally extracts embeddings, and runs
+        every registered attribute predictor on each detected face.
 
         Args:
             image: Input image as numpy array with shape (H, W, C) in BGR format.
@@ -80,24 +80,13 @@ class FaceAnalyzer:
                 except Exception as e:
                     Logger.warning(f'  Face {idx + 1}: Failed to extract embedding: {e}')
 
-            if self.age_gender is not None:
+            for attr in self.attributes:
+                attr_name = attr.__class__.__name__
                 try:
-                    result = self.age_gender.predict(image, face.bbox)
-                    face.gender = result.gender
-                    face.age = result.age
-                    Logger.debug(f'  Face {idx + 1}: Age={face.age}, Gender={face.sex}')
+                    attr.predict(image, face)
+                    Logger.debug(f'  Face {idx + 1}: {attr_name} prediction succeeded')
                 except Exception as e:
-                    Logger.warning(f'  Face {idx + 1}: Failed to predict age/gender: {e}')
-
-            if self.fairface is not None:
-                try:
-                    result = self.fairface.predict(image, face.bbox)
-                    face.gender = result.gender
-                    face.age_group = result.age_group
-                    face.race = result.race
-                    Logger.debug(f'  Face {idx + 1}: AgeGroup={face.age_group}, Gender={face.sex}, Race={face.race}')
-                except Exception as e:
-                    Logger.warning(f'  Face {idx + 1}: Failed to predict FairFace attributes: {e}')
+                    Logger.warning(f'  Face {idx + 1}: {attr_name} prediction failed: {e}')
 
         Logger.info(f'Analysis complete: {len(faces)} face(s) processed')
         return faces
@@ -106,8 +95,6 @@ class FaceAnalyzer:
         parts = [f'FaceAnalyzer(detector={self.detector.__class__.__name__}']
         if self.recognizer:
             parts.append(f'recognizer={self.recognizer.__class__.__name__}')
-        if self.age_gender:
-            parts.append(f'age_gender={self.age_gender.__class__.__name__}')
-        if self.fairface:
-            parts.append(f'fairface={self.fairface.__class__.__name__}')
+        for attr in self.attributes:
+            parts.append(f'{attr.__class__.__name__}')
         return ', '.join(parts) + ')'

uniface/attribute/__init__.py

@@ -12,7 +12,7 @@ from uniface.attribute.age_gender import AgeGender
 from uniface.attribute.base import Attribute
 from uniface.attribute.fairface import FairFace
 from uniface.constants import AgeGenderWeights, DDAMFNWeights, FairFaceWeights
-from uniface.types import AttributeResult, EmotionResult
+from uniface.types import AttributeResult, EmotionResult, Face
 
 try:
     from uniface.attribute.emotion import Emotion
@@ -30,7 +30,7 @@ except ImportError:
         def _initialize_model(self) -> None: ...
         def preprocess(self, image: np.ndarray, *args: Any) -> Any: ...
         def postprocess(self, prediction: Any) -> Any: ...
-        def predict(self, image: np.ndarray, *args: Any) -> Any: ...
+        def predict(self, image: np.ndarray, face: Face) -> Any: ...
 
 
 __all__ = [

uniface/attribute/age_gender.py

@@ -12,7 +12,7 @@ from uniface.face_utils import bbox_center_alignment
 from uniface.log import Logger
 from uniface.model_store import verify_model_weights
 from uniface.onnx_utils import create_onnx_session
-from uniface.types import AttributeResult
+from uniface.types import AttributeResult, Face
 
 __all__ = ['AgeGender']
 
@@ -133,17 +133,20 @@ class AgeGender(Attribute):
         age = int(np.round(prediction[2] * 100))
         return AttributeResult(gender=gender, age=age)
 
-    def predict(self, image: np.ndarray, bbox: list | np.ndarray) -> AttributeResult:
-        """
-        Predicts age and gender for a single face specified by a bounding box.
+    def predict(self, image: np.ndarray, face: Face) -> AttributeResult:
+        """Predict age and gender and enrich the Face in-place.
 
         Args:
-            image (np.ndarray): The full input image in BGR format.
-            bbox (Union[List, np.ndarray]): The face bounding box coordinates [x1, y1, x2, y2].
+            image: The full input image in BGR format.
+            face: Detected face; ``face.bbox`` is used for alignment.
 
         Returns:
-            AttributeResult: Result containing gender (0=Female, 1=Male) and age (in years).
+            ``AttributeResult`` with gender (0=Female, 1=Male) and age (years).
         """
-        face_blob = self.preprocess(image, bbox)
+        face_blob = self.preprocess(image, face.bbox)
         prediction = self.session.run(self.output_names, {self.input_name: face_blob})[0][0]
-        return self.postprocess(prediction)
+        result = self.postprocess(prediction)
+
+        face.gender = result.gender
+        face.age = result.age
+        return result

uniface/attribute/base.py

@@ -2,95 +2,78 @@
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo
 
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
 from typing import Any
 
 import numpy as np
 
-from uniface.types import AttributeResult, EmotionResult
+from uniface.types import AttributeResult, EmotionResult, Face
 
 __all__ = ['Attribute', 'AttributeResult', 'EmotionResult']
 
 
 class Attribute(ABC):
-    """
-    Abstract base class for face attribute models.
+    """Abstract base class for face attribute models.
 
-    This class defines the common interface that all attribute models
-    (e.g., age-gender, emotion) must implement. It ensures a consistent API
-    across different attribute prediction modules in the library, making them
-    interchangeable and easy to use.
+    All attribute models (age-gender, emotion, FairFace, etc.) implement this
+    interface so they can be used interchangeably inside ``FaceAnalyzer``.
+
+    The ``predict`` method accepts an image and a :class:`Face` object.  Each
+    subclass extracts what it needs (bbox, landmarks) from the Face, runs
+    inference, writes the results back to the Face **and** returns a typed
+    result dataclass.
     """
 
     @abstractmethod
     def _initialize_model(self) -> None:
-        """
-        Initializes the underlying model for inference.
-
-        This method should handle loading model weights, creating the
-        inference session (e.g., ONNX Runtime, PyTorch), and any necessary
-        warm-up procedures to prepare the model for prediction.
-        """
+        """Load model weights and create the inference session."""
         raise NotImplementedError('Subclasses must implement the _initialize_model method.')
 
     @abstractmethod
     def preprocess(self, image: np.ndarray, *args: Any) -> Any:
-        """
-        Preprocesses the input data for the model.
-
-        This method should take a raw image and any other necessary data
-        (like bounding boxes or landmarks) and convert it into the format
-        expected by the model's inference engine (e.g., a blob or tensor).
+        """Preprocess the input data for the model.
 
         Args:
-            image (np.ndarray): The input image containing the face, typically
-                                in BGR format.
-            *args: Additional arguments required for preprocessing, such as
-                   bounding boxes or facial landmarks.
+            image: The input image in BGR format.
+            *args: Subclass-specific data (bbox, landmarks, etc.).
 
         Returns:
-            The preprocessed data ready for model inference.
+            Preprocessed data ready for model inference.
         """
         raise NotImplementedError('Subclasses must implement the preprocess method.')
 
     @abstractmethod
     def postprocess(self, prediction: Any) -> Any:
-        """
-        Postprocesses the raw model output into a human-readable format.
-
-        This method takes the raw output from the model's inference and
-        converts it into a meaningful result, such as an age value, a gender
-        label, or an emotion category.
+        """Convert raw model output into a typed result dataclass.
 
         Args:
-            prediction (Any): The raw output from the model's inference.
+            prediction: Raw output from the model.
 
         Returns:
-            The final, processed attributes.
+            An ``AttributeResult`` or ``EmotionResult``.
         """
         raise NotImplementedError('Subclasses must implement the postprocess method.')
 
     @abstractmethod
-    def predict(self, image: np.ndarray, *args: Any) -> Any:
-        """
-        Performs end-to-end attribute prediction on a given image.
+    def predict(self, image: np.ndarray, face: Face) -> AttributeResult | EmotionResult:
+        """Run end-to-end prediction and enrich the Face in-place.
 
-        This method orchestrates the full pipeline: it calls the preprocess,
-        inference, and postprocess steps to return the final, user-friendly
-        attribute prediction.
+        Each subclass extracts what it needs from *face* (e.g. ``face.bbox``
+        or ``face.landmarks``), runs the full preprocess-infer-postprocess
+        pipeline, writes relevant fields back to *face*, and returns the
+        result dataclass.
 
         Args:
-            image (np.ndarray): The input image containing the face.
-            *args: Additional data required for prediction, such as a bounding
-                   box or landmarks.
+            image: The full input image in BGR format.
+            face: Detected face whose attribute fields will be populated.
 
         Returns:
-            The final predicted attributes.
+            The prediction result (``AttributeResult`` or ``EmotionResult``).
         """
         raise NotImplementedError('Subclasses must implement the predict method.')
 
-    def __call__(self, *args, **kwargs) -> Any:
-        """
-        Provides a convenient, callable shortcut for the `predict` method.
-        """
-        return self.predict(*args, **kwargs)
+    def __call__(self, image: np.ndarray, face: Face) -> AttributeResult | EmotionResult:
+        """Callable shortcut for :meth:`predict`."""
+        return self.predict(image, face)

uniface/attribute/emotion.py

@@ -12,7 +12,7 @@ from uniface.constants import DDAMFNWeights
 from uniface.face_utils import face_alignment
 from uniface.log import Logger
 from uniface.model_store import verify_model_weights
-from uniface.types import EmotionResult
+from uniface.types import EmotionResult, Face
 
 __all__ = ['Emotion']
 
@@ -116,14 +116,23 @@ class Emotion(Attribute):
         confidence = float(probabilities[pred_index])
         return EmotionResult(emotion=emotion_label, confidence=confidence)
 
-    def predict(self, image: np.ndarray, landmark: list | np.ndarray) -> EmotionResult:
+    def predict(self, image: np.ndarray, face: Face) -> EmotionResult:
+        """Predict emotion and enrich the Face in-place.
+
+        Args:
+            image: The full input image in BGR format.
+            face: Detected face; ``face.landmarks`` is used for alignment.
+
+        Returns:
+            ``EmotionResult`` with emotion label and confidence score.
         """
-        Predicts the emotion from a single face specified by its landmarks.
-        """
-        input_tensor = self.preprocess(image, landmark)
+        input_tensor = self.preprocess(image, face.landmarks)
         with torch.no_grad():
             output = self.model(input_tensor)
             if isinstance(output, tuple):
                 output = output[0]
 
-        return self.postprocess(output)
+        result = self.postprocess(output)
+        face.emotion = result.emotion
+        face.emotion_confidence = result.confidence
+        return result

uniface/attribute/fairface.py

@@ -11,7 +11,7 @@ from uniface.constants import FairFaceWeights
 from uniface.log import Logger
 from uniface.model_store import verify_model_weights
 from uniface.onnx_utils import create_onnx_session
-from uniface.types import AttributeResult
+from uniface.types import AttributeResult, Face
 
 __all__ = ['AGE_LABELS', 'RACE_LABELS', 'FairFace']
 
@@ -168,29 +168,24 @@ class FairFace(Attribute):
             race=RACE_LABELS[race_idx],
         )
 
-    def predict(self, image: np.ndarray, bbox: list | np.ndarray | None = None) -> AttributeResult:
-        """
-        Predicts race, gender, and age for a face.
+    def predict(self, image: np.ndarray, face: Face) -> AttributeResult:
+        """Predict race, gender, and age and enrich the Face in-place.
 
         Args:
-            image (np.ndarray): The input image in BGR format.
-            bbox (Optional[Union[List, np.ndarray]]): Face bounding box [x1, y1, x2, y2].
-                If None, uses the entire image.
+            image: The full input image in BGR format.
+            face: Detected face; ``face.bbox`` is used for cropping.
 
         Returns:
-            AttributeResult: Result containing:
-                - gender: 0=Female, 1=Male
-                - age_group: Age range string like "20-29"
-                - race: Race/ethnicity label
+            ``AttributeResult`` with gender, age_group, and race.
         """
-        # Preprocess
-        input_blob = self.preprocess(image, bbox)
-
-        # Inference
+        input_blob = self.preprocess(image, face.bbox)
         outputs = self.session.run(self.output_names, {self.input_name: input_blob})
+        result = self.postprocess(outputs)
 
-        # Postprocess
-        return self.postprocess(outputs)
+        face.gender = result.gender
+        face.age_group = result.age_group
+        face.race = result.race
+        return result
 
     @staticmethod
     def _softmax(x: np.ndarray) -> np.ndarray:

uniface/common.py

@@ -16,6 +16,7 @@ __all__ = [
     'distance2bbox',
     'distance2kps',
     'generate_anchors',
+    'letterbox_resize',
     'non_max_suppression',
     'resize_image',
     'xyxy_to_cxcywh',
@@ -277,3 +278,70 @@ def distance2kps(
         preds.append(px)
         preds.append(py)
     return np.stack(preds, axis=-1)
+
+
+def letterbox_resize(
+    image: np.ndarray,
+    target_size: int,
+    fill_value: int = 114,
+) -> tuple[np.ndarray, float, tuple[int, int]]:
+    """Letterbox resize with center padding for YOLO-style detectors.
+
+    Maintains aspect ratio by scaling the image to fit within target_size,
+    then center-pads with a constant fill value. Converts BGR to RGB,
+    normalizes to [0, 1], and transposes to NCHW format.
+
+    This preprocessing strategy is standard for YOLO models and ensures
+    no distortion while maintaining a square input size.
+
+    Args:
+        image: Input image in BGR format with shape (H, W, C).
+        target_size: Target square size (e.g., 640 for 640x640 input).
+        fill_value: Padding fill value (default: 114 for gray background).
+
+    Returns:
+        Tuple of (preprocessed_tensor, scale_ratio, padding):
+            - preprocessed_tensor: Shape (1, 3, target_size, target_size),
+              RGB, normalized [0, 1], NCHW format, float32, contiguous.
+            - scale_ratio: Resize scale factor for coordinate transformation.
+            - padding: Padding offsets as (pad_w, pad_h) for coordinate transformation.
+
+    Example:
+        >>> image = cv2.imread('face.jpg')  # (480, 640, 3)
+        >>> tensor, scale, (pad_w, pad_h) = letterbox_resize(image, 640)
+        >>> tensor.shape
+        (1, 3, 640, 640)
+        >>> # To transform coordinates back to original:
+        >>> x_orig = (x_detected - pad_w) / scale
+        >>> y_orig = (y_detected - pad_h) / scale
+    """
+    # Get original image shape
+    img_h, img_w = image.shape[:2]
+
+    # Calculate scale ratio to fit within target_size
+    scale = min(target_size / img_h, target_size / img_w)
+    new_h, new_w = int(img_h * scale), int(img_w * scale)
+
+    # Resize image maintaining aspect ratio
+    img_resized = cv2.resize(image, (new_w, new_h), interpolation=cv2.INTER_LINEAR)
+
+    # Create padded canvas with fill_value
+    img_padded = np.full((target_size, target_size, 3), fill_value, dtype=np.uint8)
+
+    # Calculate padding to center the image
+    pad_h = (target_size - new_h) // 2
+    pad_w = (target_size - new_w) // 2
+
+    # Place resized image in center of canvas
+    img_padded[pad_h : pad_h + new_h, pad_w : pad_w + new_w] = img_resized
+
+    # Convert BGR to RGB and normalize to [0, 1]
+    img_rgb = cv2.cvtColor(img_padded, cv2.COLOR_BGR2RGB)
+    img_normalized = img_rgb.astype(np.float32) / 255.0
+
+    # Transpose to CHW format and add batch dimension (NCHW)
+    img_transposed = np.transpose(img_normalized, (2, 0, 1))
+    img_batch = np.expand_dims(img_transposed, axis=0)
+    img_batch = np.ascontiguousarray(img_batch)
+
+    return img_batch, scale, (pad_w, pad_h)

uniface/constants.py

@@ -2,9 +2,25 @@
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo
 
+from __future__ import annotations
+
+from dataclasses import dataclass
 from enum import Enum
 
 
+@dataclass(frozen=True, slots=True)
+class ModelInfo:
+    """Model metadata including download URL and SHA-256 hash.
+
+    Attributes:
+        url: Direct download link to the model weights.
+        sha256: SHA-256 checksum for integrity verification.
+    """
+
+    url: str
+    sha256: str
+
+
 # fmt: off
 class SphereFaceWeights(str, Enum):
     """
@@ -140,6 +156,20 @@ class GazeWeights(str, Enum):
     MOBILEONE_S0 = "gaze_mobileone_s0"
 
 
+class HeadPoseWeights(str, Enum):
+    """
+    Head pose estimation models using 6D rotation representation.
+    Trained on 300W-LP dataset, evaluated on AFLW2000.
+    https://github.com/yakhyo/head-pose-estimation
+    """
+    RESNET18           = "headpose_resnet18"
+    RESNET34           = "headpose_resnet34"
+    RESNET50           = "headpose_resnet50"
+    MOBILENET_V2       = "headpose_mobilenetv2"
+    MOBILENET_V3_SMALL = "headpose_mobilenetv3_small"
+    MOBILENET_V3_LARGE = "headpose_mobilenetv3_large"
+
+
 class ParsingWeights(str, Enum):
     """
     Face Parsing: Semantic Segmentation of Facial Components.
@@ -166,125 +196,228 @@ class MiniFASNetWeights(str, Enum):
     https://github.com/yakhyo/face-anti-spoofing
 
     Model Variants:
-    - V1SE: Uses scale=4.0 for face crop (squeese-and-excitation version)
+    - V1SE: Uses scale=4.0 for face crop (squeeze-and-excitation version)
     - V2: Uses scale=2.7 for face crop (improved version)
     """
     V1SE = "minifasnet_v1se"
     V2   = "minifasnet_v2"
 
-
-MODEL_URLS: dict[Enum, str] = {
+# Centralized Model Registry
+MODEL_REGISTRY: dict[Enum, ModelInfo] = {
     # RetinaFace
-    RetinaFaceWeights.MNET_025:      'https://github.com/yakhyo/uniface/releases/download/weights/retinaface_mv1_0.25.onnx',
-    RetinaFaceWeights.MNET_050:      'https://github.com/yakhyo/uniface/releases/download/weights/retinaface_mv1_0.50.onnx',
-    RetinaFaceWeights.MNET_V1:       'https://github.com/yakhyo/uniface/releases/download/weights/retinaface_mv1.onnx',
-    RetinaFaceWeights.MNET_V2:       'https://github.com/yakhyo/uniface/releases/download/weights/retinaface_mv2.onnx',
-    RetinaFaceWeights.RESNET18:      'https://github.com/yakhyo/uniface/releases/download/weights/retinaface_r18.onnx',
-    RetinaFaceWeights.RESNET34:      'https://github.com/yakhyo/uniface/releases/download/weights/retinaface_r34.onnx',
+    RetinaFaceWeights.MNET_025: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/retinaface_mv1_0.25.onnx',
+        sha256='b7a7acab55e104dce6f32cdfff929bd83946da5cd869b9e2e9bdffafd1b7e4a5'
+    ),
+    RetinaFaceWeights.MNET_050: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/retinaface_mv1_0.50.onnx',
+        sha256='d8977186f6037999af5b4113d42ba77a84a6ab0c996b17c713cc3d53b88bfc37'
+    ),
+    RetinaFaceWeights.MNET_V1: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/retinaface_mv1.onnx',
+        sha256='75c961aaf0aff03d13c074e9ec656e5510e174454dd4964a161aab4fe5f04153'
+    ),
+    RetinaFaceWeights.MNET_V2: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/retinaface_mv2.onnx',
+        sha256='3ca44c045651cabeed1193a1fae8946ad1f3a55da8fa74b341feab5a8319f757'
+    ),
+    RetinaFaceWeights.RESNET18: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/retinaface_r18.onnx',
+        sha256='e8b5ddd7d2c3c8f7c942f9f10cec09d8e319f78f09725d3f709631de34fb649d'
+    ),
+    RetinaFaceWeights.RESNET34: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/retinaface_r34.onnx',
+        sha256='bd0263dc2a465d32859555cb1741f2d98991eb0053696e8ee33fec583d30e630'
+    ),
+
     # MobileFace
-    MobileFaceWeights.MNET_025:      'https://github.com/yakhyo/uniface/releases/download/weights/mobilenetv1_0.25.onnx',
-    MobileFaceWeights.MNET_V2:       'https://github.com/yakhyo/uniface/releases/download/weights/mobilenetv2.onnx',
-    MobileFaceWeights.MNET_V3_SMALL: 'https://github.com/yakhyo/uniface/releases/download/weights/mobilenetv3_small.onnx',
-    MobileFaceWeights.MNET_V3_LARGE: 'https://github.com/yakhyo/uniface/releases/download/weights/mobilenetv3_large.onnx',
+    MobileFaceWeights.MNET_025: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/mobilenetv1_0.25.onnx',
+        sha256='eeda7d23d9c2b40cf77fa8da8e895b5697465192648852216074679657f8ee8b'
+    ),
+    MobileFaceWeights.MNET_V2: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/mobilenetv2.onnx',
+        sha256='38b148284dd48cc898d5d4453104252fbdcbacc105fe3f0b80e78954d9d20d89'
+    ),
+    MobileFaceWeights.MNET_V3_SMALL: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/mobilenetv3_small.onnx',
+        sha256='d4acafa1039a82957aa8a9a1dac278a401c353a749c39df43de0e29cc1c127c3'
+    ),
+    MobileFaceWeights.MNET_V3_LARGE: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/mobilenetv3_large.onnx',
+        sha256='0e48f8e11f070211716d03e5c65a3db35a5e917cfb5bc30552358629775a142a'
+    ),
+
     # SphereFace
-    SphereFaceWeights.SPHERE20:      'https://github.com/yakhyo/uniface/releases/download/weights/sphere20.onnx',
-    SphereFaceWeights.SPHERE36:      'https://github.com/yakhyo/uniface/releases/download/weights/sphere36.onnx',
+    SphereFaceWeights.SPHERE20: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/sphere20.onnx',
+        sha256='c02878cf658eb1861f580b7e7144b0d27cc29c440bcaa6a99d466d2854f14c9d'
+    ),
+    SphereFaceWeights.SPHERE36: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/sphere36.onnx',
+        sha256='13b3890cd5d7dec2b63f7c36fd7ce07403e5a0bbb701d9647c0289e6cbe7bb20'
+    ),
+
     # ArcFace
-    ArcFaceWeights.MNET:             'https://github.com/yakhyo/uniface/releases/download/weights/w600k_mbf.onnx',
-    ArcFaceWeights.RESNET:           'https://github.com/yakhyo/uniface/releases/download/weights/w600k_r50.onnx',
+    ArcFaceWeights.MNET: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/w600k_mbf.onnx',
+        sha256='9cc6e4a75f0e2bf0b1aed94578f144d15175f357bdc05e815e5c4a02b319eb4f'
+    ),
+    ArcFaceWeights.RESNET: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/w600k_r50.onnx',
+        sha256='4c06341c33c2ca1f86781dab0e829f88ad5b64be9fba56e56bc9ebdefc619e43'
+    ),
+
     # AdaFace
-    AdaFaceWeights.IR_18:            'https://github.com/yakhyo/adaface-onnx/releases/download/weights/adaface_ir_18.onnx',
-    AdaFaceWeights.IR_101:           'https://github.com/yakhyo/adaface-onnx/releases/download/weights/adaface_ir_101.onnx',
+    AdaFaceWeights.IR_18: ModelInfo(
+        url='https://github.com/yakhyo/adaface-onnx/releases/download/weights/adaface_ir_18.onnx',
+        sha256='6b6a35772fb636cdd4fa86520c1a259d0c41472a76f70f802b351837a00d9870'
+    ),
+    AdaFaceWeights.IR_101: ModelInfo(
+        url='https://github.com/yakhyo/adaface-onnx/releases/download/weights/adaface_ir_101.onnx',
+        sha256='f2eb07d03de0af560a82e1214df799fec5e09375d43521e2868f9dc387e5a43e'
+    ),
+
     # SCRFD
-    SCRFDWeights.SCRFD_10G_KPS:      'https://github.com/yakhyo/uniface/releases/download/weights/scrfd_10g_kps.onnx',
-    SCRFDWeights.SCRFD_500M_KPS:     'https://github.com/yakhyo/uniface/releases/download/weights/scrfd_500m_kps.onnx',
+    SCRFDWeights.SCRFD_10G_KPS: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/scrfd_10g_kps.onnx',
+        sha256='5838f7fe053675b1c7a08b633df49e7af5495cee0493c7dcf6697200b85b5b91'
+    ),
+    SCRFDWeights.SCRFD_500M_KPS: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/scrfd_500m_kps.onnx',
+        sha256='5e4447f50245bbd7966bd6c0fa52938c61474a04ec7def48753668a9d8b4ea3a'
+    ),
+
     # YOLOv5-Face
-    YOLOv5FaceWeights.YOLOV5N:       'https://github.com/yakhyo/yolov5-face-onnx-inference/releases/download/weights/yolov5n_face.onnx',
-    YOLOv5FaceWeights.YOLOV5S:       'https://github.com/yakhyo/yolov5-face-onnx-inference/releases/download/weights/yolov5s_face.onnx',
-    YOLOv5FaceWeights.YOLOV5M:       'https://github.com/yakhyo/yolov5-face-onnx-inference/releases/download/weights/yolov5m_face.onnx',
+    YOLOv5FaceWeights.YOLOV5N: ModelInfo(
+        url='https://github.com/yakhyo/yolov5-face-onnx-inference/releases/download/weights/yolov5n_face.onnx',
+        sha256='eb244a06e36999db732b317c2b30fa113cd6cfc1a397eaf738f2d6f33c01f640'
+    ),
+    YOLOv5FaceWeights.YOLOV5S: ModelInfo(
+        url='https://github.com/yakhyo/yolov5-face-onnx-inference/releases/download/weights/yolov5s_face.onnx',
+        sha256='fc682801cd5880e1e296184a14aea0035486b5146ec1a1389d2e7149cb134bb2'
+    ),
+    YOLOv5FaceWeights.YOLOV5M: ModelInfo(
+        url='https://github.com/yakhyo/yolov5-face-onnx-inference/releases/download/weights/yolov5m_face.onnx',
+        sha256='04302ce27a15bde3e20945691b688e2dd018a10e92dd8932146bede6a49207b2'
+    ),
+
     # YOLOv8-Face
-    YOLOv8FaceWeights.YOLOV8_LITE_S: 'https://github.com/yakhyo/yolov8-face-onnx-inference/releases/download/weights/yolov8-lite-s.onnx',
-    YOLOv8FaceWeights.YOLOV8N:       'https://github.com/yakhyo/yolov8-face-onnx-inference/releases/download/weights/yolov8n-face.onnx',
+    YOLOv8FaceWeights.YOLOV8_LITE_S: ModelInfo(
+        url='https://github.com/yakhyo/yolov8-face-onnx-inference/releases/download/weights/yolov8-lite-s.onnx',
+        sha256='11bc496be01356d2d960085bfd8abb8f103199900a034f239a8a1705a1b31dba'
+    ),
+    YOLOv8FaceWeights.YOLOV8N: ModelInfo(
+        url='https://github.com/yakhyo/yolov8-face-onnx-inference/releases/download/weights/yolov8n-face.onnx',
+        sha256='33f3951af7fc0c4d9b321b29cdcd8c9a59d0a29a8d4bdc01fcb5507d5c714809'
+    ),
+
     # DDAFM
-    DDAMFNWeights.AFFECNET7:         'https://github.com/yakhyo/uniface/releases/download/weights/affecnet7.script',
-    DDAMFNWeights.AFFECNET8:         'https://github.com/yakhyo/uniface/releases/download/weights/affecnet8.script',
+    DDAMFNWeights.AFFECNET7: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/affecnet7.script',
+        sha256='10535bf8b6afe8e9d6ae26cea6c3add9a93036e9addb6adebfd4a972171d015d'
+    ),
+    DDAMFNWeights.AFFECNET8: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/affecnet8.script',
+        sha256='8c66963bc71db42796a14dfcbfcd181b268b65a3fc16e87147d6a3a3d7e0f487'
+    ),
+
     # AgeGender
-    AgeGenderWeights.DEFAULT:        'https://github.com/yakhyo/uniface/releases/download/weights/genderage.onnx',
+    AgeGenderWeights.DEFAULT: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/genderage.onnx',
+        sha256='4fde69b1c810857b88c64a335084f1c3fe8f01246c9a191b48c7bb756d6652fb'
+    ),
+
     # FairFace
-    FairFaceWeights.DEFAULT:         'https://github.com/yakhyo/fairface-onnx/releases/download/weights/fairface.onnx',
+    FairFaceWeights.DEFAULT: ModelInfo(
+        url='https://github.com/yakhyo/fairface-onnx/releases/download/weights/fairface.onnx',
+        sha256='9c8c47d437cd310538d233f2465f9ed0524cb7fb51882a37f74e8bc22437fdbf'
+    ),
+
     # Landmarks
-    LandmarkWeights.DEFAULT:         'https://github.com/yakhyo/uniface/releases/download/weights/2d106det.onnx',
+    LandmarkWeights.DEFAULT: ModelInfo(
+        url='https://github.com/yakhyo/uniface/releases/download/weights/2d106det.onnx',
+        sha256='f001b856447c413801ef5c42091ed0cd516fcd21f2d6b79635b1e733a7109dbf'
+    ),
+
     # Gaze (MobileGaze)
-    GazeWeights.RESNET18:            'https://github.com/yakhyo/gaze-estimation/releases/download/weights/resnet18_gaze.onnx',
-    GazeWeights.RESNET34:            'https://github.com/yakhyo/gaze-estimation/releases/download/weights/resnet34_gaze.onnx',
-    GazeWeights.RESNET50:            'https://github.com/yakhyo/gaze-estimation/releases/download/weights/resnet50_gaze.onnx',
-    GazeWeights.MOBILENET_V2:        'https://github.com/yakhyo/gaze-estimation/releases/download/weights/mobilenetv2_gaze.onnx',
-    GazeWeights.MOBILEONE_S0:        'https://github.com/yakhyo/gaze-estimation/releases/download/weights/mobileone_s0_gaze.onnx',
+    GazeWeights.RESNET18: ModelInfo(
+        url='https://github.com/yakhyo/gaze-estimation/releases/download/weights/resnet18_gaze.onnx',
+        sha256='404fec1efd07ff49f981e47f461c20c2627119e465ec441bbd1c067d3f16e657'
+    ),
+    GazeWeights.RESNET34: ModelInfo(
+        url='https://github.com/yakhyo/gaze-estimation/releases/download/weights/resnet34_gaze.onnx',
+        sha256='c8e6b14f6095d2425241b9302aa663d9a23b7dfb9d43941352b718c91dc7f2cf'
+    ),
+    GazeWeights.RESNET50: ModelInfo(
+        url='https://github.com/yakhyo/gaze-estimation/releases/download/weights/resnet50_gaze.onnx',
+        sha256='bb28d421565adc4dfb665742f8fc80bdef36dd8caa0c87e040e0937f9fdca9a6'
+    ),
+    GazeWeights.MOBILENET_V2: ModelInfo(
+        url='https://github.com/yakhyo/gaze-estimation/releases/download/weights/mobilenetv2_gaze.onnx',
+        sha256='b81312df85c7ac1c1b5f78c573620d22c2719cb839650e15f12dc7eecb7744a4'
+    ),
+    GazeWeights.MOBILEONE_S0: ModelInfo(
+        url='https://github.com/yakhyo/gaze-estimation/releases/download/weights/mobileone_s0_gaze.onnx',
+        sha256='8b4fdc4e3da44733c9a82e7776b411e4a39f94e8e285aee0fc85a548a55f7d9f'
+    ),
+
+    # Head Pose
+    HeadPoseWeights.RESNET18: ModelInfo(
+        url='https://github.com/yakhyo/head-pose-estimation/releases/download/weights/resnet18.onnx',
+        sha256='61c34e877989412980d1ea80c52391250b074abc00d19a6100de5c8e999212ee'
+    ),
+    HeadPoseWeights.RESNET34: ModelInfo(
+        url='https://github.com/yakhyo/head-pose-estimation/releases/download/weights/resnet34.onnx',
+        sha256='8da9f2ce4810298ebea68bd85fba1b6bd11716060c10534596f46be52cc908c9'
+    ),
+    HeadPoseWeights.RESNET50: ModelInfo(
+        url='https://github.com/yakhyo/head-pose-estimation/releases/download/weights/resnet50.onnx',
+        sha256='50c74d57b7663361b8ede83b0e4122546171119ef502ec55b790dbd7fc360260'
+    ),
+    HeadPoseWeights.MOBILENET_V2: ModelInfo(
+        url='https://github.com/yakhyo/head-pose-estimation/releases/download/weights/mobilenetv2.onnx',
+        sha256='1e902872868e483bd0e4f8f4a8ff2a4d61c2ccbca9dadf748e5479b5cc86a9e9'
+    ),
+    HeadPoseWeights.MOBILENET_V3_SMALL: ModelInfo(
+        url='https://github.com/yakhyo/head-pose-estimation/releases/download/weights/mobilenetv3_small.onnx',
+        sha256='e8ae4d932b3d13221638fc72e171603e020c6da28b770753f76146867f40e190'
+    ),
+    HeadPoseWeights.MOBILENET_V3_LARGE: ModelInfo(
+        url='https://github.com/yakhyo/head-pose-estimation/releases/download/weights/mobilenetv3_large.onnx',
+        sha256='3a68815fa00aba41ddc4e014bf631b637caba8619df71160383f1fee8c15a3c9'
+    ),
+
     # Parsing
-    ParsingWeights.RESNET18:         'https://github.com/yakhyo/face-parsing/releases/download/weights/resnet18.onnx',
-    ParsingWeights.RESNET34:         'https://github.com/yakhyo/face-parsing/releases/download/weights/resnet34.onnx',
+    ParsingWeights.RESNET18: ModelInfo(
+        url='https://github.com/yakhyo/face-parsing/releases/download/weights/resnet18.onnx',
+        sha256='0d9bd318e46987c3bdbfacae9e2c0f461cae1c6ac6ea6d43bbe541a91727e33f'
+    ),
+    ParsingWeights.RESNET34: ModelInfo(
+        url='https://github.com/yakhyo/face-parsing/releases/download/weights/resnet34.onnx',
+        sha256='5b805bba7b5660ab7070b5a381dcf75e5b3e04199f1e9387232a77a00095102e'
+    ),
+
     # Anti-Spoofing (MiniFASNet)
-    MiniFASNetWeights.V1SE:          'https://github.com/yakhyo/face-anti-spoofing/releases/download/weights/MiniFASNetV1SE.onnx',
-    MiniFASNetWeights.V2:            'https://github.com/yakhyo/face-anti-spoofing/releases/download/weights/MiniFASNetV2.onnx',
+    MiniFASNetWeights.V1SE: ModelInfo(
+        url='https://github.com/yakhyo/face-anti-spoofing/releases/download/weights/MiniFASNetV1SE.onnx',
+        sha256='ebab7f90c7833fbccd46d3a555410e78d969db5438e169b6524be444862b3676'
+    ),
+    MiniFASNetWeights.V2: ModelInfo(
+        url='https://github.com/yakhyo/face-anti-spoofing/releases/download/weights/MiniFASNetV2.onnx',
+        sha256='b32929adc2d9c34b9486f8c4c7bc97c1b69bc0ea9befefc380e4faae4e463907'
+    ),
+
     # XSeg
-    XSegWeights.DEFAULT:             'https://github.com/yakhyo/face-segmentation/releases/download/weights/xseg.onnx',
+    XSegWeights.DEFAULT: ModelInfo(
+        url='https://github.com/yakhyo/face-segmentation/releases/download/weights/xseg.onnx',
+        sha256='0b57328efcb839d85973164b617ceee9dfe6cfcb2c82e8a033bba9f4f09b27e5'
+    ),
 }
 
-MODEL_SHA256: dict[Enum, str] = {
-    # RetinaFace
-    RetinaFaceWeights.MNET_025:      'b7a7acab55e104dce6f32cdfff929bd83946da5cd869b9e2e9bdffafd1b7e4a5',
-    RetinaFaceWeights.MNET_050:      'd8977186f6037999af5b4113d42ba77a84a6ab0c996b17c713cc3d53b88bfc37',
-    RetinaFaceWeights.MNET_V1:       '75c961aaf0aff03d13c074e9ec656e5510e174454dd4964a161aab4fe5f04153',
-    RetinaFaceWeights.MNET_V2:       '3ca44c045651cabeed1193a1fae8946ad1f3a55da8fa74b341feab5a8319f757',
-    RetinaFaceWeights.RESNET18:      'e8b5ddd7d2c3c8f7c942f9f10cec09d8e319f78f09725d3f709631de34fb649d',
-    RetinaFaceWeights.RESNET34:      'bd0263dc2a465d32859555cb1741f2d98991eb0053696e8ee33fec583d30e630',
-    # MobileFace
-    MobileFaceWeights.MNET_025:      'eeda7d23d9c2b40cf77fa8da8e895b5697465192648852216074679657f8ee8b',
-    MobileFaceWeights.MNET_V2:       '38b148284dd48cc898d5d4453104252fbdcbacc105fe3f0b80e78954d9d20d89',
-    MobileFaceWeights.MNET_V3_SMALL: 'd4acafa1039a82957aa8a9a1dac278a401c353a749c39df43de0e29cc1c127c3',
-    MobileFaceWeights.MNET_V3_LARGE: '0e48f8e11f070211716d03e5c65a3db35a5e917cfb5bc30552358629775a142a',
-    # SphereFace
-    SphereFaceWeights.SPHERE20:      'c02878cf658eb1861f580b7e7144b0d27cc29c440bcaa6a99d466d2854f14c9d',
-    SphereFaceWeights.SPHERE36:      '13b3890cd5d7dec2b63f7c36fd7ce07403e5a0bbb701d9647c0289e6cbe7bb20',
-    # ArcFace
-    ArcFaceWeights.MNET:             '9cc6e4a75f0e2bf0b1aed94578f144d15175f357bdc05e815e5c4a02b319eb4f',
-    ArcFaceWeights.RESNET:           '4c06341c33c2ca1f86781dab0e829f88ad5b64be9fba56e56bc9ebdefc619e43',
-    # AdaFace
-    AdaFaceWeights.IR_18:            '6b6a35772fb636cdd4fa86520c1a259d0c41472a76f70f802b351837a00d9870',
-    AdaFaceWeights.IR_101:           'f2eb07d03de0af560a82e1214df799fec5e09375d43521e2868f9dc387e5a43e',
-    # SCRFD
-    SCRFDWeights.SCRFD_10G_KPS:      '5838f7fe053675b1c7a08b633df49e7af5495cee0493c7dcf6697200b85b5b91',
-    SCRFDWeights.SCRFD_500M_KPS:     '5e4447f50245bbd7966bd6c0fa52938c61474a04ec7def48753668a9d8b4ea3a',
-    # YOLOv5-Face
-    YOLOv5FaceWeights.YOLOV5N:       'eb244a06e36999db732b317c2b30fa113cd6cfc1a397eaf738f2d6f33c01f640',
-    YOLOv5FaceWeights.YOLOV5S:       'fc682801cd5880e1e296184a14aea0035486b5146ec1a1389d2e7149cb134bb2',
-    YOLOv5FaceWeights.YOLOV5M:       '04302ce27a15bde3e20945691b688e2dd018a10e92dd8932146bede6a49207b2',
-    # YOLOv8-Face
-    YOLOv8FaceWeights.YOLOV8_LITE_S: '11bc496be01356d2d960085bfd8abb8f103199900a034f239a8a1705a1b31dba',
-    YOLOv8FaceWeights.YOLOV8N:       '33f3951af7fc0c4d9b321b29cdcd8c9a59d0a29a8d4bdc01fcb5507d5c714809',
-    # DDAFM
-    DDAMFNWeights.AFFECNET7:         '10535bf8b6afe8e9d6ae26cea6c3add9a93036e9addb6adebfd4a972171d015d',
-    DDAMFNWeights.AFFECNET8:         '8c66963bc71db42796a14dfcbfcd181b268b65a3fc16e87147d6a3a3d7e0f487',
-    # AgeGender
-    AgeGenderWeights.DEFAULT:        '4fde69b1c810857b88c64a335084f1c3fe8f01246c9a191b48c7bb756d6652fb',
-    # FairFace
-    FairFaceWeights.DEFAULT:         '9c8c47d437cd310538d233f2465f9ed0524cb7fb51882a37f74e8bc22437fdbf',
-    # Landmark
-    LandmarkWeights.DEFAULT:         'f001b856447c413801ef5c42091ed0cd516fcd21f2d6b79635b1e733a7109dbf',
-    # MobileGaze (trained on Gaze360)
-    GazeWeights.RESNET18:            '404fec1efd07ff49f981e47f461c20c2627119e465ec441bbd1c067d3f16e657',
-    GazeWeights.RESNET34:            'c8e6b14f6095d2425241b9302aa663d9a23b7dfb9d43941352b718c91dc7f2cf',
-    GazeWeights.RESNET50:            'bb28d421565adc4dfb665742f8fc80bdef36dd8caa0c87e040e0937f9fdca9a6',
-    GazeWeights.MOBILENET_V2:        'b81312df85c7ac1c1b5f78c573620d22c2719cb839650e15f12dc7eecb7744a4',
-    GazeWeights.MOBILEONE_S0:        '8b4fdc4e3da44733c9a82e7776b411e4a39f94e8e285aee0fc85a548a55f7d9f',
-    # Face Parsing
-    ParsingWeights.RESNET18:         '0d9bd318e46987c3bdbfacae9e2c0f461cae1c6ac6ea6d43bbe541a91727e33f',
-    ParsingWeights.RESNET34:         '5b805bba7b5660ab7070b5a381dcf75e5b3e04199f1e9387232a77a00095102e',
-    # Anti-Spoofing (MiniFASNet)
-    MiniFASNetWeights.V1SE:          'ebab7f90c7833fbccd46d3a555410e78d969db5438e169b6524be444862b3676',
-    MiniFASNetWeights.V2:            'b32929adc2d9c34b9486f8c4c7bc97c1b69bc0ea9befefc380e4faae4e463907',
-    # XSeg
-    XSegWeights.DEFAULT:             '0b57328efcb839d85973164b617ceee9dfe6cfcb2c82e8a033bba9f4f09b27e5',
-}
+
+# Backward compatibility (optional, can be removed if all code uses MODEL_REGISTRY)
+MODEL_URLS: dict[Enum, str] = {k: v.url for k, v in MODEL_REGISTRY.items()}
+MODEL_SHA256: dict[Enum, str] = {k: v.sha256 for k, v in MODEL_REGISTRY.items()}
 
 CHUNK_SIZE = 8192

uniface/detection/base.py

@@ -5,7 +5,7 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import Any
+from typing import Any, Literal
 
 import numpy as np
 
@@ -119,3 +119,77 @@ class BaseDetector(ABC):
             List of detected Face objects.
         """
         return self.detect(image, **kwargs)
+
+    def _select_top_detections(
+        self,
+        detections: np.ndarray,
+        landmarks: np.ndarray,
+        max_num: int,
+        original_shape: tuple[int, int],
+        metric: Literal['default', 'max'] = 'max',
+        center_weight: float = 2.0,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """Filter detections to keep only top max_num faces.
+
+        Ranks faces by area and/or distance from image center, then selects
+        the top max_num detections.
+
+        Args:
+            detections: Array of shape (N, 5) as [x1, y1, x2, y2, confidence].
+            landmarks: Array of shape (N, 5, 2) for 5-point landmarks.
+            max_num: Maximum number of faces to keep. If 0 or >= N, returns all.
+            original_shape: Original image shape as (height, width).
+            metric: Ranking metric:
+                - 'max': Rank by bounding box area only.
+                - 'default': Rank by area minus center distance penalty.
+            center_weight: Weight for center distance penalty (only used with 'default' metric).
+
+        Returns:
+            Filtered (detections, landmarks) tuple with at most max_num faces.
+        """
+        if max_num <= 0 or detections.shape[0] <= max_num:
+            return detections, landmarks
+
+        # Calculate bounding box areas
+        area = (detections[:, 2] - detections[:, 0]) * (detections[:, 3] - detections[:, 1])
+
+        # Calculate offsets from image center
+        center_y, center_x = original_shape[0] // 2, original_shape[1] // 2
+        offsets = np.vstack(
+            [
+                (detections[:, 0] + detections[:, 2]) / 2 - center_x,
+                (detections[:, 1] + detections[:, 3]) / 2 - center_y,
+            ]
+        )
+        offset_dist_squared = np.sum(np.power(offsets, 2.0), axis=0)
+
+        # Calculate ranking scores based on metric
+        if metric == 'max':
+            scores = area
+        else:
+            scores = area - offset_dist_squared * center_weight
+
+        # Select top max_num by score
+        top_indices = np.argsort(scores)[::-1][:max_num]
+        return detections[top_indices], landmarks[top_indices]
+
+    @staticmethod
+    def _detections_to_faces(detections: np.ndarray, landmarks: np.ndarray) -> list[Face]:
+        """Convert detection arrays to Face objects.
+
+        Args:
+            detections: Array of shape (N, 5) as [x1, y1, x2, y2, confidence].
+            landmarks: Array of shape (N, 5, 2) for 5-point landmarks.
+
+        Returns:
+            List of Face objects.
+        """
+        faces = []
+        for i in range(detections.shape[0]):
+            face = Face(
+                bbox=detections[i, :4],
+                confidence=float(detections[i, 4]),
+                landmarks=landmarks[i],
+            )
+            faces.append(face)
+        return faces

uniface/detection/retinaface.py

@@ -208,42 +208,12 @@ class RetinaFace(BaseDetector):
         # Postprocessing
         detections, landmarks = self.postprocess(outputs, resize_factor, shape=(width, height))
 
-        if max_num > 0 and detections.shape[0] > max_num:
-            # Calculate area of detections
-            areas = (detections[:, 2] - detections[:, 0]) * (detections[:, 3] - detections[:, 1])
+        # Filter to top max_num faces if requested
+        detections, landmarks = self._select_top_detections(
+            detections, landmarks, max_num, (original_height, original_width), metric, center_weight
+        )
 
-            # Calculate offsets from image center
-            center = (original_height // 2, original_width // 2)
-            offsets = np.vstack(
-                [
-                    (detections[:, 0] + detections[:, 2]) / 2 - center[1],
-                    (detections[:, 1] + detections[:, 3]) / 2 - center[0],
-                ]
-            )
-            offset_dist_squared = np.sum(np.power(offsets, 2.0), axis=0)
-
-            # Calculate scores based on the chosen metric
-            if metric == 'max':
-                scores = areas
-            else:
-                scores = areas - offset_dist_squared * center_weight
-
-            # Sort by scores and select top `max_num`
-            sorted_indices = np.argsort(scores)[::-1][:max_num]
-
-            detections = detections[sorted_indices]
-            landmarks = landmarks[sorted_indices]
-
-        faces = []
-        for i in range(detections.shape[0]):
-            face = Face(
-                bbox=detections[i, :4],
-                confidence=float(detections[i, 4]),
-                landmarks=landmarks[i],
-            )
-            faces.append(face)
-
-        return faces
+        return self._detections_to_faces(detections, landmarks)
 
     def postprocess(
         self,

uniface/detection/scrfd.py

@@ -272,38 +272,9 @@ class SCRFD(BaseDetector):
         landmarks = landmarks[order, :, :]
         landmarks = landmarks[keep, :, :].astype(np.float32)
 
-        if 0 < max_num < detections.shape[0]:
-            # Calculate area of detections
-            area = (detections[:, 2] - detections[:, 0]) * (detections[:, 3] - detections[:, 1])
+        # Filter to top max_num faces if requested
+        detections, landmarks = self._select_top_detections(
+            detections, landmarks, max_num, (original_height, original_width), metric, center_weight
+        )
 
-            # Calculate offsets from image center
-            center = (original_height // 2, original_width // 2)
-            offsets = np.vstack(
-                [
-                    (detections[:, 0] + detections[:, 2]) / 2 - center[1],
-                    (detections[:, 1] + detections[:, 3]) / 2 - center[0],
-                ]
-            )
-
-            # Calculate scores based on the chosen metric
-            offset_dist_squared = np.sum(np.power(offsets, 2.0), axis=0)
-            if metric == 'max':
-                values = area
-            else:
-                values = area - offset_dist_squared * center_weight
-
-            # Sort by scores and select top `max_num`
-            sorted_indices = np.argsort(values)[::-1][:max_num]
-            detections = detections[sorted_indices]
-            landmarks = landmarks[sorted_indices]
-
-        faces = []
-        for i in range(detections.shape[0]):
-            face = Face(
-                bbox=detections[i, :4],
-                confidence=float(detections[i, 4]),
-                landmarks=landmarks[i],
-            )
-            faces.append(face)
-
-        return faces
+        return self._detections_to_faces(detections, landmarks)

uniface/detection/yolov5.py

@@ -4,10 +4,9 @@
 
 from typing import Any, Literal
 
-import cv2
 import numpy as np
 
-from uniface.common import non_max_suppression
+from uniface.common import letterbox_resize, non_max_suppression
 from uniface.constants import YOLOv5FaceWeights
 from uniface.log import Logger
 from uniface.model_store import verify_model_weights
@@ -140,45 +139,15 @@ class YOLOv5Face(BaseDetector):
             raise RuntimeError(f"Failed to initialize model session for '{model_path}'") from e
 
     def preprocess(self, image: np.ndarray) -> tuple[np.ndarray, float, tuple[int, int]]:
-        """
-        Preprocess image for inference.
+        """Preprocess image using letterbox resize.
 
         Args:
-            image (np.ndarray): Input image (BGR format)
+            image: Input image in BGR format.
 
         Returns:
-            Tuple[np.ndarray, float, Tuple[int, int]]: Preprocessed image, scale ratio, and padding
+            Tuple of (preprocessed_tensor, scale_ratio, padding).
         """
-        # Get original image shape
-        img_h, img_w = image.shape[:2]
-
-        # Calculate scale ratio
-        scale = min(self.input_size / img_h, self.input_size / img_w)
-        new_h, new_w = int(img_h * scale), int(img_w * scale)
-
-        # Resize image
-        img_resized = cv2.resize(image, (new_w, new_h), interpolation=cv2.INTER_LINEAR)
-
-        # Create padded image
-        img_padded = np.full((self.input_size, self.input_size, 3), 114, dtype=np.uint8)
-
-        # Calculate padding
-        pad_h = (self.input_size - new_h) // 2
-        pad_w = (self.input_size - new_w) // 2
-
-        # Place resized image in center
-        img_padded[pad_h : pad_h + new_h, pad_w : pad_w + new_w] = img_resized
-
-        # Convert to RGB and normalize
-        img_rgb = cv2.cvtColor(img_padded, cv2.COLOR_BGR2RGB)
-        img_normalized = img_rgb.astype(np.float32) / 255.0
-
-        # Transpose to CHW format (HWC -> CHW) and add batch dimension
-        img_transposed = np.transpose(img_normalized, (2, 0, 1))
-        img_batch = np.expand_dims(img_transposed, axis=0)
-        img_batch = np.ascontiguousarray(img_batch)
-
-        return img_batch, scale, (pad_w, pad_h)
+        return letterbox_resize(image, self.input_size)
 
     def inference(self, input_tensor: np.ndarray) -> list[np.ndarray]:
         """Perform model inference on the preprocessed image tensor.
@@ -337,38 +306,9 @@ class YOLOv5Face(BaseDetector):
         if len(detections) == 0:
             return []
 
-        if 0 < max_num < detections.shape[0]:
-            # Calculate area of detections
-            area = (detections[:, 2] - detections[:, 0]) * (detections[:, 3] - detections[:, 1])
+        # Filter to top max_num faces if requested
+        detections, landmarks = self._select_top_detections(
+            detections, landmarks, max_num, (original_height, original_width), metric, center_weight
+        )
 
-            # Calculate offsets from image center
-            center = (original_height // 2, original_width // 2)
-            offsets = np.vstack(
-                [
-                    (detections[:, 0] + detections[:, 2]) / 2 - center[1],
-                    (detections[:, 1] + detections[:, 3]) / 2 - center[0],
-                ]
-            )
-
-            # Calculate scores based on the chosen metric
-            offset_dist_squared = np.sum(np.power(offsets, 2.0), axis=0)
-            if metric == 'max':
-                values = area
-            else:
-                values = area - offset_dist_squared * center_weight
-
-            # Sort by scores and select top `max_num`
-            sorted_indices = np.argsort(values)[::-1][:max_num]
-            detections = detections[sorted_indices]
-            landmarks = landmarks[sorted_indices]
-
-        faces = []
-        for i in range(detections.shape[0]):
-            face = Face(
-                bbox=detections[i, :4],
-                confidence=float(detections[i, 4]),
-                landmarks=landmarks[i],
-            )
-            faces.append(face)
-
-        return faces
+        return self._detections_to_faces(detections, landmarks)

uniface/detection/yolov8.py

@@ -11,10 +11,9 @@ Reference: https://github.com/yakhyo/yolov8-face-onnx-inference
 
 from typing import Any, Literal
 
-import cv2
 import numpy as np
 
-from uniface.common import non_max_suppression
+from uniface.common import letterbox_resize, non_max_suppression
 from uniface.constants import YOLOv8FaceWeights
 from uniface.log import Logger
 from uniface.model_store import verify_model_weights
@@ -151,45 +150,15 @@ class YOLOv8Face(BaseDetector):
             raise RuntimeError(f"Failed to initialize model session for '{model_path}'") from e
 
     def preprocess(self, image: np.ndarray) -> tuple[np.ndarray, float, tuple[int, int]]:
-        """
-        Preprocess image for inference (letterbox resize with center padding).
+        """Preprocess image using letterbox resize.
 
         Args:
-            image (np.ndarray): Input image (BGR format)
+            image: Input image in BGR format.
 
         Returns:
-            Tuple[np.ndarray, float, Tuple[int, int]]: Preprocessed image, scale ratio, and padding (pad_w, pad_h)
+            Tuple of (preprocessed_tensor, scale_ratio, padding).
         """
-        # Get original image shape
-        img_h, img_w = image.shape[:2]
-
-        # Calculate scale ratio
-        scale = min(self.input_size / img_h, self.input_size / img_w)
-        new_h, new_w = int(img_h * scale), int(img_w * scale)
-
-        # Resize image
-        img_resized = cv2.resize(image, (new_w, new_h), interpolation=cv2.INTER_LINEAR)
-
-        # Create padded image with gray background (114, 114, 114)
-        img_padded = np.full((self.input_size, self.input_size, 3), 114, dtype=np.uint8)
-
-        # Calculate padding (center the image)
-        pad_h = (self.input_size - new_h) // 2
-        pad_w = (self.input_size - new_w) // 2
-
-        # Place resized image in center
-        img_padded[pad_h : pad_h + new_h, pad_w : pad_w + new_w] = img_resized
-
-        # Convert BGR to RGB and normalize
-        img_rgb = cv2.cvtColor(img_padded, cv2.COLOR_BGR2RGB)
-        img_normalized = img_rgb.astype(np.float32) / 255.0
-
-        # Transpose to CHW format (HWC -> CHW) and add batch dimension
-        img_transposed = np.transpose(img_normalized, (2, 0, 1))
-        img_batch = np.expand_dims(img_transposed, axis=0)
-        img_batch = np.ascontiguousarray(img_batch)
-
-        return img_batch, scale, (pad_w, pad_h)
+        return letterbox_resize(image, self.input_size)
 
     def inference(self, input_tensor: np.ndarray) -> list[np.ndarray]:
         """Perform model inference on the preprocessed image tensor.
@@ -387,38 +356,9 @@ class YOLOv8Face(BaseDetector):
         if len(detections) == 0:
             return []
 
-        if 0 < max_num < detections.shape[0]:
-            # Calculate area of detections
-            area = (detections[:, 2] - detections[:, 0]) * (detections[:, 3] - detections[:, 1])
+        # Filter to top max_num faces if requested
+        detections, landmarks = self._select_top_detections(
+            detections, landmarks, max_num, (original_height, original_width), metric, center_weight
+        )
 
-            # Calculate offsets from image center
-            center = (original_height // 2, original_width // 2)
-            offsets = np.vstack(
-                [
-                    (detections[:, 0] + detections[:, 2]) / 2 - center[1],
-                    (detections[:, 1] + detections[:, 3]) / 2 - center[0],
-                ]
-            )
-
-            # Calculate scores based on the chosen metric
-            offset_dist_squared = np.sum(np.power(offsets, 2.0), axis=0)
-            if metric == 'max':
-                values = area
-            else:
-                values = area - offset_dist_squared * center_weight
-
-            # Sort by scores and select top `max_num`
-            sorted_indices = np.argsort(values)[::-1][:max_num]
-            detections = detections[sorted_indices]
-            landmarks = landmarks[sorted_indices]
-
-        faces = []
-        for i in range(detections.shape[0]):
-            face = Face(
-                bbox=detections[i, :4],
-                confidence=float(detections[i, 4]),
-                landmarks=landmarks[i],
-            )
-            faces.append(face)
-
-        return faces
+        return self._detections_to_faces(detections, landmarks)

uniface/draw.py

@@ -21,6 +21,9 @@ __all__ = [
     'draw_corner_bbox',
     'draw_detections',
     'draw_gaze',
+    'draw_head_pose',
+    'draw_head_pose_axis',
+    'draw_head_pose_cube',
     'draw_text_label',
     'draw_tracks',
     'vis_parsing_maps',
@@ -356,6 +359,212 @@ def draw_gaze(
         )
 
 
+def draw_head_pose_cube(
+    image: np.ndarray,
+    yaw: float,
+    pitch: float,
+    roll: float,
+    bbox: list[int] | np.ndarray,
+    size: int | None = None,
+) -> None:
+    """Draw a 3D wireframe cube representing head orientation on an image.
+
+    Projects a 3D cube onto the image plane based on yaw, pitch, and roll
+    angles, centered on the face bounding box.
+
+    Modifies the image in-place.
+
+    Args:
+        image: Input image to draw on (modified in-place).
+        yaw: Yaw angle in degrees.
+        pitch: Pitch angle in degrees.
+        roll: Roll angle in degrees.
+        bbox: Bounding box as ``[x_min, y_min, x_max, y_max]``.
+        size: Cube size in pixels. If None, uses the bounding box width.
+
+    Example:
+        >>> from uniface.draw import draw_head_pose_cube
+        >>> draw_head_pose_cube(image, yaw=10.0, pitch=-5.0, roll=2.0, bbox=[100, 100, 250, 280])
+    """
+    x_min, y_min, x_max, y_max = map(int, bbox[:4])
+    if size is None:
+        size = x_max - x_min
+
+    h = size * 0.5
+    yaw_r, pitch_r, roll_r = np.radians([-yaw, pitch, roll])
+
+    cx = (x_min + x_max) * 0.5
+    cy = (y_min + y_max) * 0.5
+
+    cos_y, sin_y = np.cos(yaw_r), np.sin(yaw_r)
+    cos_p, sin_p = np.cos(pitch_r), np.sin(pitch_r)
+    cos_r, sin_r = np.cos(roll_r), np.sin(roll_r)
+
+    ex = np.array([cos_y * cos_r, cos_p * sin_r + cos_r * sin_p * sin_y])
+    ey = np.array([-cos_y * sin_r, cos_p * cos_r - sin_p * sin_y * sin_r])
+    ez = np.array([sin_y, -cos_y * sin_p])
+
+    center = np.array([cx, cy])
+
+    def _pt(v: np.ndarray) -> tuple[int, int]:
+        return (int(v[0]), int(v[1]))
+
+    f0 = center + h * (-ex - ey - ez)
+    f1 = center + h * (+ex - ey - ez)
+    f2 = center + h * (+ex + ey - ez)
+    f3 = center + h * (-ex + ey - ez)
+    b0 = center + h * (-ex - ey + ez)
+    b1 = center + h * (+ex - ey + ez)
+    b2 = center + h * (+ex + ey + ez)
+    b3 = center + h * (-ex + ey + ez)
+
+    red = (0, 0, 255)
+    green = (0, 255, 0)
+    blue = (255, 0, 0)
+
+    # Front face at head (red)
+    cv2.line(image, _pt(f0), _pt(f1), red, 2)
+    cv2.line(image, _pt(f1), _pt(f2), red, 2)
+    cv2.line(image, _pt(f2), _pt(f3), red, 2)
+    cv2.line(image, _pt(f3), _pt(f0), red, 2)
+
+    # Back face in looking direction (green)
+    cv2.line(image, _pt(b0), _pt(b1), green, 2)
+    cv2.line(image, _pt(b1), _pt(b2), green, 2)
+    cv2.line(image, _pt(b2), _pt(b3), green, 2)
+    cv2.line(image, _pt(b3), _pt(b0), green, 2)
+
+    # Side edges (blue)
+    cv2.line(image, _pt(f0), _pt(b0), blue, 2)
+    cv2.line(image, _pt(f1), _pt(b1), blue, 2)
+    cv2.line(image, _pt(f2), _pt(b2), blue, 2)
+    cv2.line(image, _pt(f3), _pt(b3), blue, 2)
+
+
+def draw_head_pose_axis(
+    image: np.ndarray,
+    yaw: float,
+    pitch: float,
+    roll: float,
+    bbox: list[int] | np.ndarray,
+    size_ratio: float = 0.5,
+) -> None:
+    """Draw 3D coordinate axes representing head orientation on an image.
+
+    Draws X (red), Y (green), and Z (blue) axes from the center of the
+    bounding box, rotated according to yaw, pitch, and roll.
+
+    Modifies the image in-place.
+
+    Args:
+        image: Input image to draw on (modified in-place).
+        yaw: Yaw angle in degrees.
+        pitch: Pitch angle in degrees.
+        roll: Roll angle in degrees.
+        bbox: Bounding box as ``[x_min, y_min, x_max, y_max]``.
+        size_ratio: Axis length as a fraction of bbox size. Defaults to 0.5.
+
+    Example:
+        >>> from uniface.draw import draw_head_pose_axis
+        >>> draw_head_pose_axis(image, yaw=10.0, pitch=-5.0, roll=2.0, bbox=[100, 100, 250, 280])
+    """
+    x_min, y_min, x_max, y_max = map(int, bbox[:4])
+    yaw_r, pitch_r, roll_r = np.radians([-yaw, pitch, roll])
+
+    tdx = int(x_min + (x_max - x_min) * 0.5)
+    tdy = int(y_min + (y_max - y_min) * 0.5)
+
+    bbox_size = min(x_max - x_min, y_max - y_min)
+    size = bbox_size * size_ratio
+
+    cos_yaw, sin_yaw = np.cos(yaw_r), np.sin(yaw_r)
+    cos_pitch, sin_pitch = np.cos(pitch_r), np.sin(pitch_r)
+    cos_roll, sin_roll = np.cos(roll_r), np.sin(roll_r)
+
+    # X-Axis (red)
+    x1 = int(size * (cos_yaw * cos_roll) + tdx)
+    y1 = int(size * (cos_pitch * sin_roll + cos_roll * sin_pitch * sin_yaw) + tdy)
+
+    # Y-Axis (green)
+    x2 = int(size * (-cos_yaw * sin_roll) + tdx)
+    y2 = int(size * (cos_pitch * cos_roll - sin_pitch * sin_yaw * sin_roll) + tdy)
+
+    # Z-Axis (blue)
+    x3 = int(size * sin_yaw + tdx)
+    y3 = int(size * (-cos_yaw * sin_pitch) + tdy)
+
+    cv2.line(image, (tdx, tdy), (x1, y1), (0, 0, 255), 2)
+    cv2.line(image, (tdx, tdy), (x2, y2), (0, 255, 0), 2)
+    cv2.line(image, (tdx, tdy), (x3, y3), (255, 0, 0), 2)
+
+
+def draw_head_pose(
+    image: np.ndarray,
+    bbox: np.ndarray | list[int],
+    pitch: float,
+    yaw: float,
+    roll: float,
+    *,
+    draw_type: str = 'cube',
+    draw_bbox: bool = False,
+    corner_bbox: bool = True,
+    draw_angles: bool = True,
+) -> None:
+    """Draw head pose visualization with optional bounding box on an image.
+
+    High-level convenience function that combines bounding box drawing with
+    a 3D shape visualization of head orientation.
+
+    Modifies the image in-place.
+
+    Args:
+        image: Input image to draw on (modified in-place).
+        bbox: Face bounding box in xyxy format ``[x1, y1, x2, y2]``.
+        pitch: Pitch angle in degrees (rotation around X-axis).
+        yaw: Yaw angle in degrees (rotation around Y-axis).
+        roll: Roll angle in degrees (rotation around Z-axis).
+        draw_type: Visualization type, ``'cube'`` or ``'axis'``.
+            Defaults to ``'cube'``.
+        draw_bbox: Whether to draw the bounding box. Defaults to False.
+        corner_bbox: Use corner-style bounding box. Defaults to True.
+        draw_angles: Whether to display angle values as text. Defaults to True.
+
+    Example:
+        >>> from uniface.headpose import HeadPose
+        >>> from uniface.draw import draw_head_pose
+        >>> estimator = HeadPose()
+        >>> result = estimator.estimate(face_crop)
+        >>> draw_head_pose(image, bbox, result.pitch, result.yaw, result.roll)
+    """
+    x_min, y_min, x_max, y_max = map(int, bbox[:4])
+
+    line_thickness = max(round(sum(image.shape[:2]) / 2 * 0.003), 2)
+
+    if draw_bbox:
+        if corner_bbox:
+            draw_corner_bbox(image, np.array(bbox), color=(0, 255, 0), thickness=line_thickness)
+        else:
+            cv2.rectangle(image, (x_min, y_min), (x_max, y_max), (0, 255, 0), line_thickness)
+
+    bbox_list = [x_min, y_min, x_max, y_max]
+    if draw_type == 'axis':
+        draw_head_pose_axis(image, yaw, pitch, roll, bbox_list)
+    else:
+        draw_head_pose_cube(image, yaw, pitch, roll, bbox_list)
+
+    if draw_angles:
+        font_scale = max(0.4, min(0.7, (y_max - y_min) / 200))
+        draw_text_label(
+            image,
+            f'P:{pitch:.0f} Y:{yaw:.0f} R:{roll:.0f}',
+            x_min,
+            y_min,
+            bg_color=(0, 0, 255),
+            text_color=(255, 255, 255),
+            font_scale=font_scale,
+        )
+
+
 def draw_tracks(
     *,
     image: np.ndarray,

uniface/face_utils.py

@@ -71,8 +71,7 @@ def estimate_norm(
     alignment[:, 0] += diff_x
 
     # Compute the transformation matrix
-    transform = SimilarityTransform()
-    transform.estimate(landmark, alignment)
+    transform = SimilarityTransform.from_estimate(landmark, alignment)
 
     matrix = transform.params[0:2, :]
     inverse_matrix = np.linalg.inv(transform.params)[0:2, :]

uniface/headpose/__init__.py

@@ -0,0 +1,53 @@
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+from uniface.types import HeadPoseResult
+
+from .base import BaseHeadPoseEstimator
+from .models import HeadPose
+
+
+def create_head_pose_estimator(method: str = 'headpose', **kwargs) -> BaseHeadPoseEstimator:
+    """
+    Factory function to create head pose estimators.
+
+    This function initializes and returns a head pose estimator instance based on the
+    specified method. It acts as a high-level interface to the underlying model classes.
+
+    Args:
+        method (str): The head pose estimation method to use.
+            Options: 'headpose' (default).
+        **kwargs: Model-specific parameters passed to the estimator's constructor.
+            For example, `model_name` can be used to select a specific
+            backbone from `HeadPoseWeights` enum (RESNET18, RESNET34, RESNET50,
+            MOBILENET_V2, MOBILENET_V3_SMALL, MOBILENET_V3_LARGE).
+
+    Returns:
+        BaseHeadPoseEstimator: An initialized head pose estimator instance ready for use.
+
+    Raises:
+        ValueError: If the specified `method` is not supported.
+
+    Examples:
+        >>> # Create the default head pose estimator (ResNet18 backbone)
+        >>> estimator = create_head_pose_estimator()
+
+        >>> # Create with MobileNetV2 backbone
+        >>> from uniface.constants import HeadPoseWeights
+        >>> estimator = create_head_pose_estimator('headpose', model_name=HeadPoseWeights.MOBILENET_V2)
+
+        >>> # Use the estimator
+        >>> result = estimator.estimate(face_crop)
+        >>> print(f'Pitch: {result.pitch:.1f}°, Yaw: {result.yaw:.1f}°, Roll: {result.roll:.1f}°')
+    """
+    method = method.lower()
+
+    if method in ('headpose', 'head_pose', '6drepnet'):
+        return HeadPose(**kwargs)
+    else:
+        available = ['headpose']
+        raise ValueError(f"Unsupported head pose estimation method: '{method}'. Available: {available}")
+
+
+__all__ = ['BaseHeadPoseEstimator', 'HeadPose', 'HeadPoseResult', 'create_head_pose_estimator']

uniface/headpose/base.py

@@ -0,0 +1,115 @@
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+import numpy as np
+
+from uniface.types import HeadPoseResult
+
+__all__ = ['BaseHeadPoseEstimator', 'HeadPoseResult']
+
+
+class BaseHeadPoseEstimator(ABC):
+    """
+    Abstract base class for all head pose estimation models.
+
+    This class defines the common interface that all head pose estimators must implement,
+    ensuring consistency across different head pose estimation methods. Head pose estimation
+    predicts the orientation of a person's head based on their face image.
+
+    The head orientation is represented as Euler angles in degrees:
+    - Pitch: Rotation around X-axis (positive = looking down, negative = looking up)
+    - Yaw: Rotation around Y-axis (positive = looking right, negative = looking left)
+    - Roll: Rotation around Z-axis (positive = tilting clockwise, negative = tilting counter-clockwise)
+    """
+
+    @abstractmethod
+    def _initialize_model(self) -> None:
+        """
+        Initialize the underlying model for inference.
+
+        This method should handle loading model weights, creating the
+        inference session (e.g., ONNX Runtime), and any necessary
+        setup procedures to prepare the model for prediction.
+
+        Raises:
+            RuntimeError: If the model fails to load or initialize.
+        """
+        raise NotImplementedError('Subclasses must implement the _initialize_model method.')
+
+    @abstractmethod
+    def preprocess(self, face_image: np.ndarray) -> np.ndarray:
+        """
+        Preprocess the input face image for model inference.
+
+        This method should take a raw face crop and convert it into the format
+        expected by the model's inference engine (e.g., normalized tensor).
+
+        Args:
+            face_image (np.ndarray): A cropped face image in BGR format with
+                                     shape (H, W, C).
+
+        Returns:
+            np.ndarray: The preprocessed image tensor ready for inference,
+                        typically with shape (1, C, H, W).
+        """
+        raise NotImplementedError('Subclasses must implement the preprocess method.')
+
+    @abstractmethod
+    def postprocess(self, rotation_matrix: np.ndarray) -> HeadPoseResult:
+        """
+        Postprocess a rotation matrix into Euler angles.
+
+        This method takes the raw rotation matrix output from the model's
+        inference and converts it into pitch, yaw, and roll angles in degrees.
+
+        Args:
+            rotation_matrix: Rotation matrix with shape (B, 3, 3) from the
+                             model inference.
+
+        Returns:
+            HeadPoseResult: Result containing pitch, yaw, and roll in degrees.
+        """
+        raise NotImplementedError('Subclasses must implement the postprocess method.')
+
+    @abstractmethod
+    def estimate(self, face_image: np.ndarray) -> HeadPoseResult:
+        """
+        Perform end-to-end head pose estimation on a face image.
+
+        This method orchestrates the full pipeline: preprocessing the input,
+        running inference, and postprocessing to return the head orientation.
+
+        Args:
+            face_image (np.ndarray): A cropped face image in BGR format.
+                                     The face should be roughly centered and
+                                     well-framed within the image.
+
+        Returns:
+            HeadPoseResult: Result containing Euler angles in degrees:
+                - pitch: Rotation around X-axis (positive = down)
+                - yaw: Rotation around Y-axis (positive = right)
+                - roll: Rotation around Z-axis (positive = clockwise)
+
+        Example:
+            >>> estimator = create_head_pose_estimator()
+            >>> result = estimator.estimate(face_crop)
+            >>> print(f'Pose: pitch={result.pitch:.1f}°, yaw={result.yaw:.1f}°, roll={result.roll:.1f}°')
+        """
+        raise NotImplementedError('Subclasses must implement the estimate method.')
+
+    def __call__(self, face_image: np.ndarray) -> HeadPoseResult:
+        """
+        Provides a convenient, callable shortcut for the `estimate` method.
+
+        Args:
+            face_image (np.ndarray): A cropped face image in BGR format.
+
+        Returns:
+            HeadPoseResult: Result containing pitch, yaw, and roll in degrees.
+        """
+        return self.estimate(face_image)

uniface/headpose/models.py

@@ -0,0 +1,178 @@
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+import cv2
+import numpy as np
+
+from uniface.constants import HeadPoseWeights
+from uniface.log import Logger
+from uniface.model_store import verify_model_weights
+from uniface.onnx_utils import create_onnx_session
+from uniface.types import HeadPoseResult
+
+from .base import BaseHeadPoseEstimator
+
+__all__ = ['HeadPose']
+
+
+class HeadPose(BaseHeadPoseEstimator):
+    """
+    Head Pose Estimation with ONNX Runtime using 6D Rotation Representation.
+
+    This model estimates head orientation from a single face image by predicting
+    a 3x3 rotation matrix (via continuous 6D representation) and converting it to
+    Euler angles (pitch, yaw, roll) in degrees.
+
+    Supports multiple backbone architectures: ResNet-18/34/50, MobileNetV2,
+    and MobileNetV3 (small/large).
+
+    Reference:
+        https://github.com/yakhyo/head-pose-estimation
+
+    Args:
+        model_name (HeadPoseWeights): The enum specifying the head pose model to load.
+            Options: RESNET18, RESNET34, RESNET50, MOBILENET_V2, MOBILENET_V3_SMALL,
+            MOBILENET_V3_LARGE. Defaults to `HeadPoseWeights.RESNET18`.
+        input_size (tuple[int, int]): The resolution (width, height) for the model's
+            input. Defaults to (224, 224).
+        providers (list[str] | None): ONNX Runtime execution providers. If None, auto-detects
+            the best available provider. Example: ['CPUExecutionProvider'] to force CPU.
+
+    Attributes:
+        input_size (tuple[int, int]): Model input dimensions.
+        input_mean (np.ndarray): Per-channel mean values for normalization (ImageNet).
+        input_std (np.ndarray): Per-channel std values for normalization (ImageNet).
+
+    Example:
+        >>> from uniface.headpose import HeadPose
+        >>> from uniface import RetinaFace
+        >>>
+        >>> detector = RetinaFace()
+        >>> head_pose = HeadPose()
+        >>>
+        >>> faces = detector.detect(image)
+        >>> for face in faces:
+        ...     bbox = face.bbox
+        ...     x1, y1, x2, y2 = map(int, bbox[:4])
+        ...     face_crop = image[y1:y2, x1:x2]
+        ...     result = head_pose.estimate(face_crop)
+        ...     print(f'Pose: pitch={result.pitch:.1f}°, yaw={result.yaw:.1f}°, roll={result.roll:.1f}°')
+    """
+
+    def __init__(
+        self,
+        model_name: HeadPoseWeights = HeadPoseWeights.RESNET18,
+        input_size: tuple[int, int] = (224, 224),
+        providers: list[str] | None = None,
+    ) -> None:
+        Logger.info(f'Initializing HeadPose with model={model_name}, input_size={input_size}')
+
+        self.input_size = input_size
+        self.input_mean = np.array([0.485, 0.456, 0.406], dtype=np.float32)
+        self.input_std = np.array([0.229, 0.224, 0.225], dtype=np.float32)
+        self.providers = providers
+
+        self.model_path = verify_model_weights(model_name)
+        self._initialize_model()
+
+    def _initialize_model(self) -> None:
+        """
+        Initialize the ONNX model from the stored model path.
+
+        Raises:
+            RuntimeError: If the model fails to load or initialize.
+        """
+        try:
+            self.session = create_onnx_session(self.model_path, providers=self.providers)
+
+            input_cfg = self.session.get_inputs()[0]
+            input_shape = input_cfg.shape
+            self.input_name = input_cfg.name
+            self.input_size = tuple(input_shape[2:4][::-1])
+
+            outputs = self.session.get_outputs()
+            self.output_names = [output.name for output in outputs]
+
+            if len(self.output_names) != 1:
+                raise ValueError(f'Expected 1 output node (rotation_matrix), got {len(self.output_names)}')
+
+            Logger.info(f'HeadPose initialized with input size {self.input_size}')
+
+        except Exception as e:
+            Logger.error(f"Failed to load head pose model from '{self.model_path}'", exc_info=True)
+            raise RuntimeError(f'Failed to initialize head pose model: {e}') from e
+
+    def preprocess(self, face_image: np.ndarray) -> np.ndarray:
+        """
+        Preprocess a face crop for head pose estimation.
+
+        Args:
+            face_image (np.ndarray): A cropped face image in BGR format.
+
+        Returns:
+            np.ndarray: Preprocessed image tensor with shape (1, 3, H, W).
+        """
+        image = cv2.cvtColor(face_image, cv2.COLOR_BGR2RGB)
+        image = cv2.resize(image, self.input_size)
+        image = image.astype(np.float32) / 255.0
+        image = (image - self.input_mean) / self.input_std
+
+        # HWC -> CHW -> NCHW
+        image = np.transpose(image, (2, 0, 1))
+        image = np.expand_dims(image, axis=0).astype(np.float32)
+
+        return image
+
+    @staticmethod
+    def rotation_matrix_to_euler(rotation_matrix: np.ndarray) -> np.ndarray:
+        """Convert (B, 3, 3) rotation matrices to Euler angles in degrees.
+
+        Uses the ZYX convention to decompose rotation matrices into
+        pitch (X), yaw (Y), and roll (Z) angles.
+
+        Args:
+            rotation_matrix: Batch of rotation matrices with shape (B, 3, 3).
+
+        Returns:
+            np.ndarray: Euler angles with shape (B, 3) as [pitch, yaw, roll] in degrees.
+        """
+        R = rotation_matrix
+        sy = np.sqrt(R[:, 0, 0] ** 2 + R[:, 1, 0] ** 2)
+        singular = sy < 1e-6
+
+        x = np.where(singular, np.arctan2(-R[:, 1, 2], R[:, 1, 1]), np.arctan2(R[:, 2, 1], R[:, 2, 2]))
+        y = np.arctan2(-R[:, 2, 0], sy)
+        z = np.where(singular, np.zeros_like(sy), np.arctan2(R[:, 1, 0], R[:, 0, 0]))
+
+        return np.degrees(np.stack([x, y, z], axis=1))
+
+    def postprocess(self, rotation_matrix: np.ndarray) -> HeadPoseResult:
+        """
+        Convert a rotation matrix into Euler angles.
+
+        Args:
+            rotation_matrix: Rotation matrix with shape (B, 3, 3).
+
+        Returns:
+            HeadPoseResult: Result containing pitch, yaw, and roll in degrees.
+        """
+        euler = self.rotation_matrix_to_euler(rotation_matrix)
+        return HeadPoseResult(
+            pitch=float(euler[0, 0]),
+            yaw=float(euler[0, 1]),
+            roll=float(euler[0, 2]),
+        )
+
+    def estimate(self, face_image: np.ndarray) -> HeadPoseResult:
+        """
+        Perform end-to-end head pose estimation on a face image.
+
+        This method orchestrates the full pipeline: preprocessing the input,
+        running inference, and postprocessing to return the head orientation.
+        """
+        input_tensor = self.preprocess(face_image)
+        outputs = self.session.run(self.output_names, {self.input_name: input_tensor})
+        rotation_matrix = outputs[0]  # (1, 3, 3)
+
+        return self.postprocess(rotation_matrix)

uniface/indexing/__init__.py

@@ -0,0 +1,9 @@
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""Vector indexing backends for fast similarity search."""
+
+from uniface.indexing.faiss import FAISS
+
+__all__ = ['FAISS']

uniface/indexing/faiss.py

@@ -0,0 +1,197 @@
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+import numpy as np
+
+from uniface.log import Logger
+
+__all__ = ['FAISS']
+
+Metadata = dict[str, Any]
+
+
+def _import_faiss():
+    """Lazily import faiss, raising a clear error if not installed."""
+    # Prevent OpenMP abort on macOS when multiple libraries (e.g. scipy,
+    # torch) each bundle their own libomp.
+    os.environ.setdefault('KMP_DUPLICATE_LIB_OK', 'TRUE')
+
+    try:
+        import faiss
+    except ImportError as exc:
+        raise ImportError(
+            'faiss is required for FAISS vector store. '
+            'Install it with:  pip install faiss-cpu  (CPU) '
+            'or:  pip install faiss-gpu  (CUDA)'
+        ) from exc
+    return faiss
+
+
+class FAISS:
+    """FAISS vector store using IndexFlatIP (inner product).
+
+    Vectors must be L2-normalised **before** being added so that inner
+    product equals cosine similarity.  The store does not normalise
+    internally -- that is the caller's responsibility.
+
+    Each vector is paired with a metadata dict that can carry any
+    JSON-serialisable payload (person ID, name, source image, etc.).
+
+    Args:
+        embedding_size: Dimension of embedding vectors.
+        db_path: Directory for persisting the index and metadata.
+
+    Example:
+        >>> from uniface.indexing import FAISS
+        >>> store = FAISS(embedding_size=512, db_path='./my_index')
+        >>> store.add(embedding, {'person_id': '001', 'name': 'Alice'})
+        >>> result, score = store.search(query_embedding)
+        >>> result['name']
+        'Alice'
+    """
+
+    def __init__(
+        self,
+        embedding_size: int = 512,
+        db_path: str = './vector_index',
+    ) -> None:
+        faiss = _import_faiss()
+
+        self.embedding_size = embedding_size
+        self.db_path = db_path
+        self._index_file = os.path.join(db_path, 'faiss_index.bin')
+        self._meta_file = os.path.join(db_path, 'metadata.json')
+
+        os.makedirs(db_path, exist_ok=True)
+
+        self.index = faiss.IndexFlatIP(embedding_size)
+        self.metadata: list[Metadata] = []
+
+    def add(self, embedding: np.ndarray, metadata: Metadata) -> None:
+        """Add a single embedding with associated metadata.
+
+        Args:
+            embedding: Embedding vector (must be L2-normalised).
+            metadata: Arbitrary dict of JSON-serialisable key-value pairs.
+        """
+        vec = self._prepare(embedding).reshape(1, -1)
+        self.index.add(vec)
+        self.metadata.append(metadata)
+
+    def search(
+        self,
+        embedding: np.ndarray,
+        threshold: float = 0.4,
+    ) -> tuple[Metadata | None, float]:
+        """Find the closest match for a query embedding.
+
+        Args:
+            embedding: Query embedding vector (must be L2-normalised).
+            threshold: Minimum cosine similarity to accept a match.
+
+        Returns:
+            ``(metadata, similarity)`` for the best match, or
+            ``(None, similarity)`` when below *threshold* or the
+            index is empty.
+        """
+        if self.index.ntotal == 0:
+            return None, 0.0
+
+        vec = self._prepare(embedding).reshape(1, -1)
+        similarities, indices = self.index.search(vec, 1)
+
+        similarity = float(similarities[0][0])
+        idx = int(indices[0][0])
+
+        if similarity > threshold and 0 <= idx < len(self.metadata):
+            return self.metadata[idx], similarity
+        return None, similarity
+
+    def remove(self, key: str, value: Any) -> int:
+        """Remove all entries where ``metadata[key] == value`` and rebuild.
+
+        Args:
+            key: Metadata key to match against.
+            value: Value to match.
+
+        Returns:
+            Number of entries removed.
+        """
+        faiss = _import_faiss()
+
+        keep = [i for i, m in enumerate(self.metadata) if m.get(key) != value]
+        removed = len(self.metadata) - len(keep)
+        if removed == 0:
+            return 0
+
+        if keep:
+            vectors = np.empty((len(keep), self.embedding_size), dtype=np.float32)
+            for dst, src in enumerate(keep):
+                self.index.reconstruct(src, vectors[dst])
+            new_index = faiss.IndexFlatIP(self.embedding_size)
+            new_index.add(vectors)
+        else:
+            new_index = faiss.IndexFlatIP(self.embedding_size)
+
+        self.index = new_index
+        self.metadata = [self.metadata[i] for i in keep]
+        Logger.info('Removed %d entries where %s=%s (%d remaining)', removed, key, value, self.index.ntotal)
+        return removed
+
+    def save(self) -> None:
+        """Persist the FAISS index and metadata to disk."""
+        faiss = _import_faiss()
+
+        faiss.write_index(self.index, self._index_file)
+        with open(self._meta_file, 'w', encoding='utf-8') as fh:
+            json.dump(self.metadata, fh, ensure_ascii=False, indent=2)
+        Logger.info('Saved FAISS index with %d vectors to %s', self.index.ntotal, self.db_path)
+
+    def load(self) -> bool:
+        """Load a previously saved index and metadata from disk.
+
+        Returns:
+            ``True`` if loaded successfully, ``False`` if files are missing.
+
+        Raises:
+            RuntimeError: If files exist but cannot be read.
+        """
+        if not (os.path.exists(self._index_file) and os.path.exists(self._meta_file)):
+            return False
+
+        faiss = _import_faiss()
+
+        try:
+            loaded_index = faiss.read_index(self._index_file)
+            with open(self._meta_file, encoding='utf-8') as fh:
+                loaded_metadata: list[Metadata] = json.load(fh)
+        except Exception as exc:
+            raise RuntimeError(f'Failed to load FAISS index from {self.db_path}') from exc
+
+        self.index = loaded_index
+        self.metadata = loaded_metadata
+        Logger.info('Loaded FAISS index with %d vectors from %s', self.index.ntotal, self.db_path)
+        return True
+
+    @property
+    def size(self) -> int:
+        """Number of vectors currently in the index."""
+        return self.index.ntotal
+
+    @staticmethod
+    def _prepare(vec: np.ndarray) -> np.ndarray:
+        """Cast to contiguous float32 for FAISS compatibility."""
+        return np.ascontiguousarray(vec.ravel(), dtype=np.float32)
+
+    def __len__(self) -> int:
+        return self.index.ntotal
+
+    def __repr__(self) -> str:
+        return f'FAISS(embedding_size={self.embedding_size}, vectors={self.index.ntotal})'

uniface/model_store.py

@@ -14,6 +14,7 @@ from concurrent.futures import ThreadPoolExecutor, as_completed
 from enum import Enum
 import hashlib
 import os
+import time
 
 import requests
 from tqdm import tqdm
@@ -64,7 +65,12 @@ def set_cache_dir(path: str) -> None:
     Logger.info(f'Cache directory set to: {path}')
 
 
-def verify_model_weights(model_name: Enum, root: str | None = None) -> str:
+def verify_model_weights(
+    model_name: Enum,
+    root: str | None = None,
+    timeout: int = 60,
+    max_retries: int = 3,
+) -> str:
     """Ensure model weights are present, downloading and verifying them if necessary.
 
     Given a model identifier from an Enum class (e.g., `RetinaFaceWeights.MNET_V2`),
@@ -76,6 +82,8 @@ def verify_model_weights(model_name: Enum, root: str | None = None) -> str:
         model_name: Model weight identifier enum (e.g., `RetinaFaceWeights.MNET_V2`).
         root: Directory to store or locate the model weights.
             If None, uses the cache directory from :func:`get_cache_dir`.
+        timeout: Connection timeout in seconds. Defaults to 60.
+        max_retries: Maximum number of download attempts. Defaults to 3.
 
     Returns:
         Absolute path to the verified model weights file.
@@ -95,59 +103,75 @@ def verify_model_weights(model_name: Enum, root: str | None = None) -> str:
     root = os.path.expanduser(root) if root is not None else get_cache_dir()
     os.makedirs(root, exist_ok=True)
 
-    # Keep model_name as enum for dictionary lookup
-    url = const.MODEL_URLS.get(model_name)
-    if not url:
-        Logger.error(f"No URL found for model '{model_name}'")
-        raise ValueError(f"No URL found for model '{model_name}'")
+    # Lookup model info from registry
+    model_info = const.MODEL_REGISTRY.get(model_name)
+    if not model_info:
+        Logger.error(f"No entry found in MODEL_REGISTRY for model '{model_name}'")
+        raise ValueError(f"Unknown model identifier: '{model_name}'")
+
+    url = model_info.url
+    expected_hash = model_info.sha256
 
     file_ext = os.path.splitext(url)[1]
     model_path = os.path.normpath(os.path.join(root, f'{model_name.value}{file_ext}'))
 
     if not os.path.exists(model_path):
-        Logger.info(f"Downloading model '{model_name}' from {url}")
+        Logger.info(f"Downloading model '{model_name.value}' from {url}")
         try:
-            download_file(url, model_path)
-            Logger.info(f"Successfully downloaded '{model_name}' to {model_path}")
+            download_file(url, model_path, timeout=timeout, max_retries=max_retries)
+            Logger.info(f"Successfully downloaded '{model_name.value}' to {model_path}")
         except Exception as e:
-            Logger.error(f"Failed to download model '{model_name}': {e}")
-            raise ConnectionError(f"Download failed for '{model_name}'") from e
+            Logger.error(f"Failed to download model '{model_name.value}': {e}")
+            raise ConnectionError(f"Download failed for '{model_name.value}' after {max_retries} attempts") from e
 
-    expected_hash = const.MODEL_SHA256.get(model_name)
     if expected_hash and not verify_file_hash(model_path, expected_hash):
         os.remove(model_path)  # Remove corrupted file
-        Logger.warning('Corrupted weight detected. Removing...')
-        raise ValueError(f"Hash mismatch for '{model_name}'. The file may be corrupted; please try downloading again.")
+        Logger.warning(f"Corrupted weights detected for '{model_name.value}'. Removing...")
+        raise ValueError(f"Hash mismatch for '{model_name.value}'. The file may be corrupted; please try again.")
 
     return model_path
 
 
-def download_file(url: str, dest_path: str, timeout: int = 30) -> None:
-    """Download a file from a URL in chunks and save it to the destination path.
+def download_file(url: str, dest_path: str, timeout: int = 60, max_retries: int = 3) -> None:
+    """Download a file from a URL with retry logic.
 
     Args:
         url: URL to download from.
         dest_path: Local file path to save to.
-        timeout: Connection timeout in seconds. Defaults to 30.
+        timeout: Connection timeout in seconds. Defaults to 60.
+        max_retries: Maximum number of attempts. Defaults to 3.
     """
-    try:
-        response = requests.get(url, stream=True, timeout=timeout)
-        response.raise_for_status()
-        with (
-            open(dest_path, 'wb') as file,
-            tqdm(
-                desc=f'Downloading {dest_path}',
-                unit='B',
-                unit_scale=True,
-                unit_divisor=1024,
-            ) as progress,
-        ):
-            for chunk in response.iter_content(chunk_size=const.CHUNK_SIZE):
-                if chunk:
-                    file.write(chunk)
-                    progress.update(len(chunk))
-    except requests.RequestException as e:
-        raise ConnectionError(f'Failed to download file from {url}. Error: {e}') from e
+    last_error = None
+    for attempt in range(max_retries):
+        try:
+            response = requests.get(url, stream=True, timeout=timeout)
+            response.raise_for_status()
+
+            total_size = int(response.headers.get('content-length', 0))
+
+            with (
+                open(dest_path, 'wb') as file,
+                tqdm(
+                    total=total_size,
+                    desc=f'Attempt {attempt + 1}/{max_retries}',
+                    unit='B',
+                    unit_scale=True,
+                    unit_divisor=1024,
+                ) as progress,
+            ):
+                for chunk in response.iter_content(chunk_size=const.CHUNK_SIZE):
+                    if chunk:
+                        file.write(chunk)
+                        progress.update(len(chunk))
+            return  # Success
+        except (OSError, requests.RequestException) as e:
+            last_error = e
+            Logger.warning(f'Download attempt {attempt + 1} failed: {e}. Retrying...')
+            if os.path.exists(dest_path):
+                os.remove(dest_path)
+            time.sleep(2**attempt)  # Exponential backoff
+
+    raise ConnectionError(f'Failed to download file from {url}. Error: {last_error}')
 
 
 def verify_file_hash(file_path: str, expected_hash: str) -> bool:
@@ -162,7 +186,9 @@ def verify_file_hash(file_path: str, expected_hash: str) -> bool:
     return actual_hash == expected_hash
 
 
-def download_models(model_names: list[Enum], max_workers: int = 4) -> dict[Enum, str]:
+def download_models(
+    model_names: list[Enum], max_workers: int = 4, timeout: int = 60, max_retries: int = 3
+) -> dict[Enum, str]:
     """Download and verify multiple models concurrently.
 
     Uses a thread pool to download models in parallel, which is significantly
@@ -171,6 +197,8 @@ def download_models(model_names: list[Enum], max_workers: int = 4) -> dict[Enum,
     Args:
         model_names: List of model weight enum identifiers to download.
         max_workers: Maximum number of concurrent download threads. Defaults to 4.
+        timeout: Connection timeout in seconds. Defaults to 60.
+        max_retries: Maximum number of attempts per model. Defaults to 3.
 
     Returns:
         Mapping of each model enum to its local file path.
@@ -187,7 +215,10 @@ def download_models(model_names: list[Enum], max_workers: int = 4) -> dict[Enum,
     errors: list[str] = []
 
     with ThreadPoolExecutor(max_workers=max_workers) as executor:
-        future_to_model = {executor.submit(verify_model_weights, name): name for name in model_names}
+        future_to_model = {
+            executor.submit(verify_model_weights, name, timeout=timeout, max_retries=max_retries): name
+            for name in model_names
+        }
 
         for future in as_completed(future_to_model):
             model = future_to_model[future]
@@ -204,8 +235,3 @@ def download_models(model_names: list[Enum], max_workers: int = 4) -> dict[Enum,
 
     Logger.info(f'All {len(results)} model(s) downloaded and verified')
     return results
-
-
-if __name__ == '__main__':
-    for model in const.RetinaFaceWeights:
-        model_path = verify_model_weights(model)

uniface/onnx_utils.py

@@ -10,6 +10,8 @@ inference sessions with automatic hardware acceleration detection.
 
 from __future__ import annotations
 
+import functools
+
 import onnxruntime as ort
 
 from uniface.log import Logger
@@ -17,6 +19,7 @@ from uniface.log import Logger
 __all__ = ['create_onnx_session', 'get_available_providers']
 
 
+@functools.lru_cache(maxsize=1)
 def get_available_providers() -> list[str]:
     """Get list of available ONNX Runtime execution providers.
 
@@ -30,7 +33,7 @@ def get_available_providers() -> list[str]:
 
     Example:
         >>> providers = get_available_providers()
-        >>> # On M4 Mac: ['CoreMLExecutionProvider', 'CPUExecutionProvider']
+        >>> # On macOS: ['CoreMLExecutionProvider', 'CPUExecutionProvider']
         >>> # On Linux with CUDA: ['CUDAExecutionProvider', 'CPUExecutionProvider']
     """
     available = ort.get_available_providers()
@@ -98,7 +101,7 @@ def create_onnx_session(
             'CPUExecutionProvider': 'CPU',
         }
         provider_display = provider_names.get(active_provider, active_provider)
-        Logger.info(f'✓ Model loaded ({provider_display})')
+        Logger.debug(f'Model loaded from {model_path} ({provider_display})')
 
         return session
     except Exception as e:

uniface/parsing/base.py

@@ -10,17 +10,23 @@ import numpy as np
 
 
 class BaseFaceParser(ABC):
-    """
-    Abstract base class for all face parsing models.
+    """Abstract base class for all face parsing models.
 
     This class defines the common interface that all face parsing models must implement,
     ensuring consistency across different parsing methods. Face parsing segments a face
     image into semantic regions such as skin, eyes, nose, mouth, hair, etc.
 
-    The output is a segmentation mask where each pixel is assigned a class label
-    representing a facial component.
+    Subclasses must define a ``mask_type`` class attribute to indicate output format:
+
+    - ``"class_ids"``: uint8 mask with discrete class labels (e.g. BiSeNet: 0-18)
+    - ``"probability"``: float32 mask with continuous values in [0, 1] (e.g. XSeg)
+
+    Attributes:
+        mask_type (str): Output format identifier. Must be set by subclasses.
     """
 
+    mask_type: str
+
     @abstractmethod
     def _initialize_model(self) -> None:
         """
@@ -86,13 +92,17 @@ class BaseFaceParser(ABC):
                 Ignored by parsers that do not need landmarks (e.g., BiSeNet).
 
         Returns:
-            np.ndarray: Segmentation mask with the same size as input image,
-                       where each pixel value represents a facial component class.
+            np.ndarray: Segmentation mask with the same size as input image.
+                Format depends on ``mask_type``:
+
+                - ``"class_ids"``: uint8 with discrete class labels
+                - ``"probability"``: float32 with values in [0, 1]
 
         Example:
             >>> parser = create_face_parser()
             >>> mask = parser.parse(face_crop)
-            >>> print(f'Mask shape: {mask.shape}, unique classes: {np.unique(mask)}')
+            >>> print(f'Mask type: {parser.mask_type}')
+            >>> print(f'Mask shape: {mask.shape}, dtype: {mask.dtype}')
         """
         raise NotImplementedError('Subclasses must implement the parse method.')
 

uniface/parsing/bisenet.py

@@ -18,8 +18,7 @@ __all__ = ['BiSeNet']
 
 
 class BiSeNet(BaseFaceParser):
-    """
-    BiSeNet: Bilateral Segmentation Network for Face Parsing with ONNX Runtime.
+    """BiSeNet: Bilateral Segmentation Network for Face Parsing with ONNX Runtime.
 
     BiSeNet is a semantic segmentation model that segments a face image into
     different facial components such as skin, eyes, nose, mouth, hair, etc. The model
@@ -45,6 +44,7 @@ class BiSeNet(BaseFaceParser):
         input_size (Tuple[int, int]): Model input dimensions.
         input_mean (np.ndarray): Per-channel mean values for normalization (ImageNet).
         input_std (np.ndarray): Per-channel std values for normalization (ImageNet).
+        mask_type (str): Output type identifier - "class_ids" for BiSeNet.
 
     Example:
         >>> from uniface.parsing import BiSeNet
@@ -61,8 +61,11 @@ class BiSeNet(BaseFaceParser):
         ...     face_crop = image[y1:y2, x1:x2]
         ...     mask = parser.parse(face_crop)
         ...     print(f'Mask shape: {mask.shape}, unique classes: {np.unique(mask)}')
+        ...     print(f'Output type: {parser.mask_type}')  # "class_ids"
     """
 
+    mask_type = 'class_ids'
+
     def __init__(
         self,
         model_name: ParsingWeights = ParsingWeights.RESNET18,

uniface/parsing/xseg.py

@@ -19,10 +19,9 @@ __all__ = ['XSeg']
 
 
 class XSeg(BaseFaceParser):
-    """
-    XSeg: Face Segmentation Model from DeepFaceLab with ONNX Runtime.
+    """XSeg: Face Segmentation Model from DeepFaceLab with ONNX Runtime.
 
-    XSeg outputs a mask for face regions. Unlike BiSeNet which works
+    XSeg outputs a soft probability mask for face regions. Unlike BiSeNet which works
     on bbox crops, XSeg requires 5-point landmarks for face alignment. The model
     uses NHWC input format and outputs values in [0, 1] range.
 
@@ -43,6 +42,7 @@ class XSeg(BaseFaceParser):
         align_size (int): Face alignment output size.
         blur_sigma (float): Blur sigma for post-processing.
         input_size (tuple[int, int]): Model input dimensions (width, height).
+        mask_type (str): Output type identifier - "probability" for XSeg.
 
     Example:
         >>> from uniface.parsing import XSeg
@@ -56,8 +56,11 @@ class XSeg(BaseFaceParser):
         ...     if face.landmarks is not None:
         ...         mask = parser.parse(image, landmarks=face.landmarks)
         ...         print(f'Mask shape: {mask.shape}')
+        ...         print(f'Output type: {parser.mask_type}')  # "probability"
     """
 
+    mask_type = 'probability'
+
     def __init__(
         self,
         model_name: XSegWeights = XSegWeights.DEFAULT,

uniface/privacy/blur.py

@@ -4,14 +4,11 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, ClassVar
+from typing import ClassVar
 
 import cv2
 import numpy as np
 
-if TYPE_CHECKING:
-    pass
-
 __all__ = ['BlurFace', 'EllipticalBlur']
 
 

uniface/recognition/base.py

@@ -141,7 +141,7 @@ class BaseRecognizer(ABC):
                 image is already aligned.
 
         Returns:
-            Face embedding vector (typically 512-dimensional).
+            Face embedding with shape (1, 512) — raw ONNX output with batch dimension.
         """
         # If landmarks are provided, align the face first
         if landmarks is not None:
@@ -164,9 +164,9 @@ class BaseRecognizer(ABC):
             landmarks: Facial landmarks (5 points for alignment).
 
         Returns:
-            L2-normalized face embedding vector (typically 512-dimensional).
+            L2-normalized face embedding as a 1D vector with shape (512,).
         """
-        embedding = self.get_embedding(image, landmarks)
+        embedding = self.get_embedding(image, landmarks).ravel()
         norm = np.linalg.norm(embedding)
         return embedding / norm if norm > 0 else embedding
 
@@ -178,6 +178,6 @@ class BaseRecognizer(ABC):
             landmarks: Facial landmarks (5 points for alignment).
 
         Returns:
-            L2-normalized face embedding vector (typically 512-dimensional).
+            L2-normalized face embedding as a 1D vector with shape (512,).
         """
         return self.get_normalized_embedding(image, landmarks)

uniface/types.py

@@ -28,6 +28,7 @@ __all__ = [
     'EmotionResult',
     'Face',
     'GazeResult',
+    'HeadPoseResult',
     'SpoofingResult',
 ]
 
@@ -48,6 +49,24 @@ class GazeResult:
         return f'GazeResult(pitch={self.pitch:.4f}, yaw={self.yaw:.4f})'
 
 
+@dataclass(slots=True, frozen=True)
+class HeadPoseResult:
+    """Result of head pose estimation.
+
+    Attributes:
+        pitch: Rotation around X-axis in degrees (positive = looking down).
+        yaw: Rotation around Y-axis in degrees (positive = looking right).
+        roll: Rotation around Z-axis in degrees (positive = tilting clockwise).
+    """
+
+    pitch: float
+    yaw: float
+    roll: float
+
+    def __repr__(self) -> str:
+        return f'HeadPoseResult(pitch={self.pitch:.1f}, yaw={self.yaw:.1f}, roll={self.roll:.1f})'
+
+
 @dataclass(slots=True, frozen=True)
 class SpoofingResult:
     """Result of face anti-spoofing detection.
@@ -245,5 +264,5 @@ class Face:
         if self.emotion is not None:
             parts.append(f'emotion={self.emotion}')
         if self.embedding is not None:
-            parts.append(f'embedding_dim={self.embedding.shape[0]}')
+            parts.append(f'embedding_dim={self.embedding.shape[-1]}')
         return ', '.join(parts) + ')'