release: Update release version and docs (#79 )

docs: Update UniFace library documentation and README.md (#78 )
* docs: Update wrong/missing references * docs: Update README.md
2026-05-14 20:35:28 +00:00 · 2026-02-05 21:45:28 +09:00 · 2026-02-04 20:45:02 +09:00 · 2026-01-25 17:07:40 +09:00 · 2026-01-24 22:25:09 +09:00 · 2026-01-22 22:33:31 +09:00
100 changed files with 2638 additions and 433 deletions
--- a/.github/logos/new/uniface_enhanced.webp
+++ b/.github/logos/new/uniface_enhanced.webp
--- a/.github/logos/new/uniface_high_res_original.png
+++ b/.github/logos/new/uniface_high_res_original.png
--- a/.github/logos/new/uniface_rounded.png
+++ b/.github/logos/new/uniface_rounded.png
--- a/.github/logos/new/uniface_rounded_150px.png
+++ b/.github/logos/new/uniface_rounded_150px.png
--- a/.github/logos/new/uniface_rounded_q80.png
+++ b/.github/logos/new/uniface_rounded_q80.png
--- a/.github/logos/new/uniface_rounded_q80.webp
+++ b/.github/logos/new/uniface_rounded_q80.webp
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,14 +1,12 @@
-name: CI
+name: Build

 on:
  push:
    branches:
      - main
-      - develop
  pull_request:
    branches:
      - main
-      - develop

 concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
@@ -22,7 +20,7 @@ jobs:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
-          python-version: '3.11'
+          python-version: "3.10"
      - uses: pre-commit/action@v3.0.1

  test:
@@ -33,8 +31,16 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ["3.11", "3.13"]
+        include:
+          # Full Python range on Linux (fastest runner)
+          - os: ubuntu-latest
+            python-version: "3.10"
+          - os: ubuntu-latest
+            python-version: "3.13"
+          - os: macos-latest
+            python-version: "3.13"
+          - os: windows-latest
+            python-version: "3.13"

    steps:
      - name: Checkout code
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -24,7 +24,7 @@ jobs:
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
-          python-version: "3.11"
+          python-version: "3.11"  # Needs 3.11+ for tomllib

      - name: Get version from tag and pyproject.toml
        id: get_version
@@ -54,7 +54,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        python-version: ["3.11", "3.13"]
+        python-version: ["3.10", "3.13"]

    steps:
      - name: Checkout code
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,5 @@
 tmp_*
+.vscode/

 # Byte-compiled / optimized / DLL files
 __pycache__/
--- a/CONTRIBUTING.md
+++ b/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.11+ (use modern syntax)
+- **Python version:** 3.10+ (use modern syntax)
 - **Quote style:** Single quotes for strings, double quotes for docstrings

 #### Type Hints

-Use modern Python 3.11+ type hints (PEP 585 and PEP 604):
+Use modern Python 3.10+ type hints (PEP 585 and PEP 604):

 ```python
 # Preferred (modern)
--- a/README.md
+++ b/README.md
@@ -1,32 +1,33 @@
-# UniFace: All-in-One Face Analysis Library
+<h1 align="center">UniFace: All-in-One Face Analysis Library</h1>

 <div align="center">

-[![PyPI](https://img.shields.io/pypi/v/uniface.svg)](https://pypi.org/project/uniface/)
-[![Python](https://img.shields.io/badge/Python-3.11%2B-blue)](https://www.python.org/)
+[![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/)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![CI](https://github.com/yakhyo/uniface/actions/workflows/ci.yml/badge.svg)](https://github.com/yakhyo/uniface/actions)
-[![Downloads](https://static.pepy.tech/badge/uniface)](https://pepy.tech/project/uniface)
-[![Docs](https://img.shields.io/badge/Docs-UniFace-blue.svg)](https://yakhyo.github.io/uniface/)
+[![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)
+[![UniFace Documentation](https://img.shields.io/badge/Docs-UniFace-blue.svg)](https://yakhyo.github.io/uniface/)
+[![Kaggle Badge](https://img.shields.io/badge/Notebooks-Kaggle?label=Kaggle&color=blue)](https://www.kaggle.com/yakhyokhuja/code)

 </div>

 <div align="center">
-    <img src=".github/logos/logo_web.webp" width=80%>
+    <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">
 </div>

+---
+
 **UniFace** is a lightweight, production-ready face analysis library built on ONNX Runtime. It provides high-performance face detection, recognition, landmark detection, face parsing, gaze estimation, and attribute analysis with hardware acceleration support across platforms.

-> 💬 **Have questions?** [Chat with this codebase on DeepWiki](https://deepwiki.com/yakhyo/uniface) - AI-powered docs that let you ask anything about UniFace.
-
 ---

 ## Features

- **Face Detection** — RetinaFace, SCRFD, and YOLOv5-Face with 5-point landmarks
+- **Face Detection** — RetinaFace, SCRFD, YOLOv5-Face, and YOLOv8-Face with 5-point landmarks
 - **Face Recognition** — ArcFace, MobileFace, and SphereFace embeddings
- **Facial Landmarks** — 106-point landmark localization
- **Face Parsing** — BiSeNet semantic segmentation (19 classes)
+- **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
 - **Attribute Analysis** — Age, gender, race (FairFace), and emotion
 - **Anti-Spoofing** — Face liveness detection with MiniFASNet
@@ -37,31 +38,55 @@

 ## Installation

+**Standard installation**
+
 ```bash
-# Standard installation
 pip install uniface
+```

-# GPU support (CUDA)
+**GPU support (CUDA)**
+
+```bash
 pip install uniface[gpu]
+```

-# From source
+**From source (latest version)**
+
+```bash
 git clone https://github.com/yakhyo/uniface.git
 cd uniface && pip install -e .
 ```

+**Optional dependencies**
+- Emotion model uses TorchScript and requires `torch`:
+  `pip install torch` (choose the correct build for your OS/CUDA)
+- YOLOv5-Face and YOLOv8-Face support faster NMS with `torchvision`:
+  `pip install torch torchvision` then use `nms_mode='torchvision'`
+
 ---

-## Quick Example
+## Model Downloads and Cache
+
+Models are downloaded automatically on first use and verified via SHA-256.
+
+Default cache location: `~/.uniface/models`
+
+You can override it with `UNIFACE_CACHE_DIR=/your/cache/path`
+
+---
+
+## Quick Example (Detection)

 ```python
 import cv2
 from uniface import RetinaFace

-# Initialize detector (models auto-download on first use)
 detector = RetinaFace()

-# Detect faces
 image = cv2.imread("photo.jpg")
+if image is None:
+    raise ValueError("Failed to load image. Check the path to 'photo.jpg'.")
+
 faces = detector.detect(image)

 for face in faces:
@@ -71,14 +96,52 @@ for face in faces:
 ```

 <div align="center">
-    <img src="assets/test_result.png">
+    <img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/test_result.png" width="90%">
+    <p>Face Detection Model Output</p>
 </div>

 ---

+## Example (Face Analyzer)
+
+```python
+import cv2
+from uniface import RetinaFace, ArcFace, FaceAnalyzer
+
+detector = RetinaFace()
+recognizer = ArcFace()
+
+analyzer = FaceAnalyzer(detector, recognizer=recognizer)
+
+image = cv2.imread("photo.jpg")
+if image is None:
+    raise ValueError("Failed to load image. Check the path to 'photo.jpg'.")
+
+faces = analyzer.analyze(image)
+
+for face in faces:
+    print(face.bbox, face.embedding.shape if face.embedding is not None else None)
+```
+
+---
+
+## Execution Providers (ONNX Runtime)
+
+```python
+from uniface import RetinaFace
+
+# Force CPU-only inference
+detector = RetinaFace(providers=["CPUExecutionProvider"])
+```
+
+See more in the docs:
+https://yakhyo.github.io/uniface/concepts/execution-providers/
+
+---
+
 ## Documentation

-📚 **Full documentation**: [yakhyo.github.io/uniface](https://yakhyo.github.io/uniface/)
+Full documentation: https://yakhyo.github.io/uniface/

 | Resource | Description |
 |----------|-------------|
@@ -88,7 +151,9 @@ for face in faces:
 | [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 |

-### Jupyter Notebooks
+---
+
+## Jupyter Notebooks

 | Example | Colab | Description |
 |---------|:-----:|-------------|
@@ -100,25 +165,52 @@ for face in faces:
 | [06_face_parsing.ipynb](examples/06_face_parsing.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/06_face_parsing.ipynb) | Semantic face segmentation |
 | [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 |
+
+---
+
+## Licensing and Model Usage
+
+UniFace is MIT-licensed, but several pretrained models carry their own licenses.
+Review: https://yakhyo.github.io/uniface/license-attribution/
+
+Notable examples:
+- YOLOv5-Face and YOLOv8-Face weights are GPL-3.0
+- FairFace weights are CC BY 4.0
+
+If you plan commercial use, verify model license compatibility.

 ---

 ## References

- [yakhyo/retinaface-pytorch](https://github.com/yakhyo/retinaface-pytorch) — RetinaFace training
- [yakhyo/yolov5-face-onnx-inference](https://github.com/yakhyo/yolov5-face-onnx-inference) — YOLOv5-Face ONNX
- [yakhyo/face-recognition](https://github.com/yakhyo/face-recognition) — ArcFace, MobileFace, SphereFace
- [yakhyo/face-parsing](https://github.com/yakhyo/face-parsing) — BiSeNet face parsing
- [yakhyo/gaze-estimation](https://github.com/yakhyo/gaze-estimation) — MobileGaze training
- [yakhyo/face-anti-spoofing](https://github.com/yakhyo/face-anti-spoofing) — MiniFASNet inference
- [yakhyo/fairface-onnx](https://github.com/yakhyo/fairface-onnx) — FairFace attributes
- [deepinsight/insightface](https://github.com/deepinsight/insightface) — Model architectures
+| Feature | Repository | Training | Description |
+|---------|------------|:--------:|-------------|
+| Detection | [retinaface-pytorch](https://github.com/yakhyo/retinaface-pytorch) | ✓ | RetinaFace PyTorch Training & Export |
+| Detection | [yolov5-face-onnx-inference](https://github.com/yakhyo/yolov5-face-onnx-inference) | - | YOLOv5-Face ONNX Inference |
+| Detection | [yolov8-face-onnx-inference](https://github.com/yakhyo/yolov8-face-onnx-inference) | - | YOLOv8-Face ONNX Inference |
+| Recognition | [face-recognition](https://github.com/yakhyo/face-recognition) | ✓ | MobileFace, SphereFace Training |
+| 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 |
+| 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 |
+
+*SCRFD and ArcFace models are from [InsightFace](https://github.com/deepinsight/insightface).

 ---

 ## Contributing

-Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Contributions are welcome. Please see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Support
+
+If you find this project useful, consider giving it a ⭐ on GitHub — it helps others discover it!
+
+Questions or feedback:
+- GitHub Issues: https://github.com/yakhyo/uniface/issues
+- DeepWiki Q&A: https://deepwiki.com/yakhyo/uniface

 ## License

--- a/docs/concepts/execution-providers.md
+++ b/docs/concepts/execution-providers.md
@@ -17,12 +17,39 @@ detector = RetinaFace()

 **Priority order:**

-1. **CUDAExecutionProvider** - NVIDIA GPU
-2. **CoreMLExecutionProvider** - Apple Silicon
+1. **CoreMLExecutionProvider** - Apple Silicon
+2. **CUDAExecutionProvider** - NVIDIA GPU
 3. **CPUExecutionProvider** - Fallback

 ---

+## Explicit Provider Selection
+
+You can specify which execution provider to use by passing the `providers` parameter:
+
+```python
+from uniface import RetinaFace, ArcFace
+
+# Force CPU execution (even if GPU is available)
+detector = RetinaFace(providers=['CPUExecutionProvider'])
+recognizer = ArcFace(providers=['CPUExecutionProvider'])
+
+# Use CUDA with CPU fallback
+detector = RetinaFace(providers=['CUDAExecutionProvider', 'CPUExecutionProvider'])
+```
+
+All model classes accept the `providers` parameter:
+
+- Detection: `RetinaFace`, `SCRFD`, `YOLOv5Face`, `YOLOv8Face`
+- Recognition: `ArcFace`, `AdaFace`, `MobileFace`, `SphereFace`
+- Landmarks: `Landmark106`
+- Gaze: `MobileGaze`
+- Parsing: `BiSeNet`
+- Attributes: `AgeGender`, `FairFace`
+- Anti-Spoofing: `MiniFASNet`
+
+---
+
 ## Check Available Providers

 ```python
--- a/docs/concepts/inputs-outputs.md
+++ b/docs/concepts/inputs-outputs.md
@@ -199,16 +199,16 @@ print(f"Classes: {np.unique(mask)}")  # [0, 1, 2, ...]

 | ID | Class | ID | Class |
 |----|-------|----|-------|
-| 0 | Background | 10 | Ear Ring |
-| 1 | Skin | 11 | Nose |
-| 2 | Left Eyebrow | 12 | Mouth |
-| 3 | Right Eyebrow | 13 | Upper Lip |
-| 4 | Left Eye | 14 | Lower Lip |
-| 5 | Right Eye | 15 | Neck |
-| 6 | Eye Glasses | 16 | Neck Lace |
-| 7 | Left Ear | 17 | Cloth |
-| 8 | Right Ear | 18 | Hair |
-| 9 | Hat | | |
+| 0 | Background | 10 | Nose |
+| 1 | Skin | 11 | Mouth |
+| 2 | Left Eyebrow | 12 | Upper Lip |
+| 3 | Right Eyebrow | 13 | Lower Lip |
+| 4 | Left Eye | 14 | Neck |
+| 5 | Right Eye | 15 | Necklace |
+| 6 | Eyeglasses | 16 | Cloth |
+| 7 | Left Ear | 17 | Hair |
+| 8 | Right Ear | 18 | Hat |
+| 9 | Earring | | |

 ---

--- a/docs/concepts/model-cache-offline.md
+++ b/docs/concepts/model-cache-offline.md
@@ -32,9 +32,9 @@ Default cache directory:

 ```
 ~/.uniface/models/
-├── retinaface_mv2.onnx
-├── w600k_mbf.onnx
-├── 2d106det.onnx
+├── retinaface_mnet_v2.onnx
+├── arcface_mnet.onnx
+├── 2d_106.onnx
 ├── gaze_resnet34.onnx
 ├── parsing_resnet18.onnx
 └── ...
@@ -155,6 +155,8 @@ If a model fails verification, it's re-downloaded automatically.
 | YOLOv5n-Face | 11 MB | ✅ |
 | YOLOv5s-Face | 28 MB | ✅ |
 | YOLOv5m-Face | 82 MB | ✅ |
+| YOLOv8-Lite-S | 7.4 MB | ✅ |
+| YOLOv8n-Face | 12 MB | ✅ |

 ### Recognition Models

--- a/docs/concepts/overview.md
+++ b/docs/concepts/overview.md
@@ -15,7 +15,7 @@ graph TB
    end

    subgraph Detection
-        DET[RetinaFace / SCRFD / YOLOv5Face]
+        DET[RetinaFace / SCRFD / YOLOv5Face / YOLOv8Face]
    end

    subgraph Analysis
@@ -97,8 +97,8 @@ def detect(self, image: np.ndarray) -> list[Face]:

 ```
 uniface/
-├── detection/      # Face detection (RetinaFace, SCRFD, YOLOv5Face)
-├── recognition/    # Face recognition (ArcFace, MobileFace, SphereFace)
+├── detection/      # Face detection (RetinaFace, SCRFD, YOLOv5Face, YOLOv8Face)
+├── recognition/    # Face recognition (AdaFace, ArcFace, MobileFace, SphereFace)
 ├── landmark/       # 106-point landmarks
 ├── attribute/      # Age, gender, emotion, race
 ├── parsing/        # Face semantic segmentation
@@ -151,12 +151,18 @@ for face in faces:
 For convenience, `FaceAnalyzer` combines multiple modules:

 ```python
-from uniface import FaceAnalyzer
+from uniface import FaceAnalyzer, RetinaFace, ArcFace, AgeGender, FairFace
+
+detector = RetinaFace()
+recognizer = ArcFace()
+age_gender = AgeGender()
+fairface = FairFace()

 analyzer = FaceAnalyzer(
-    detect=True,
-    recognize=True,
-    attributes=True
+    detector,
+    recognizer=recognizer,
+    age_gender=age_gender,
+    fairface=fairface,
 )

 faces = analyzer.analyze(image)
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -32,7 +32,7 @@ ruff check . --fix
 **Guidelines:**

 - Line length: 120
- Python 3.11+ type hints
+- Python 3.10+ type hints
 - Google-style docstrings

 ---
--- a/docs/index.md
+++ b/docs/index.md
@@ -10,12 +10,16 @@ template: home.html

 # UniFace { .hero-title }

-<p class="hero-subtitle">A lightweight, production-ready face analysis library built on ONNX Runtime</p>
+<p class="hero-subtitle">All-in-One Open-Source Face Analysis Library</p>

-[![PyPI](https://img.shields.io/pypi/v/uniface.svg)](https://pypi.org/project/uniface/)
-[![Python](https://img.shields.io/badge/Python-3.11%2B-blue)](https://www.python.org/)
+[![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/)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Downloads](https://static.pepy.tech/badge/uniface)](https://pepy.tech/project/uniface)
+[![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)
+
+<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: 90%; margin: 1rem 0;">

 [Get Started](quickstart.md){ .md-button .md-button--primary }
 [View on GitHub](https://github.com/yakhyo/uniface){ .md-button }
@@ -26,12 +30,12 @@ template: home.html

 <div class="feature-card" markdown>
 ### :material-face-recognition: Face Detection
-ONNX-optimized RetinaFace, SCRFD, and YOLOv5-Face models with 5-point landmarks.
+ONNX-optimized detectors (RetinaFace, SCRFD, YOLO) with 5-point landmarks.
 </div>

 <div class="feature-card" markdown>
 ### :material-account-check: Face Recognition
-ArcFace, MobileFace, and SphereFace embeddings for identity verification.
+AdaFace, ArcFace, MobileFace, and SphereFace embeddings for identity verification.
 </div>

 <div class="feature-card" markdown>
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -6,7 +6,7 @@ This guide covers all installation options for UniFace.

 ## Requirements

- **Python**: 3.11 or higher
+- **Python**: 3.10 or higher
 - **Operating Systems**: macOS, Linux, Windows

 ---
@@ -107,7 +107,9 @@ 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 |

@@ -137,11 +139,11 @@ print("Installation successful!")

 ### Import Errors

-If you encounter import errors, ensure you're using Python 3.11+:
+If you encounter import errors, ensure you're using Python 3.10+:

 ```bash
 python --version
-# Should show: Python 3.11.x or higher
+# Should show: Python 3.10.x or higher
 ```

 ### Model Download Issues
--- a/docs/license-attribution.md
+++ b/docs/license-attribution.md
@@ -13,6 +13,8 @@ UniFace is released under the [MIT License](https://opensource.org/licenses/MIT)
 | RetinaFace | [yakhyo/retinaface-pytorch](https://github.com/yakhyo/retinaface-pytorch) | MIT |
 | SCRFD | [InsightFace](https://github.com/deepinsight/insightface) | MIT |
 | YOLOv5-Face | [yakhyo/yolov5-face-onnx-inference](https://github.com/yakhyo/yolov5-face-onnx-inference) | GPL-3.0 |
+| YOLOv8-Face | [yakhyo/yolov8-face-onnx-inference](https://github.com/yakhyo/yolov8-face-onnx-inference) | GPL-3.0 |
+| AdaFace | [yakhyo/adaface-onnx](https://github.com/yakhyo/adaface-onnx) | MIT |
 | ArcFace | [InsightFace](https://github.com/deepinsight/insightface) | MIT |
 | MobileFace | [yakhyo/face-recognition](https://github.com/yakhyo/face-recognition) | MIT |
 | SphereFace | [yakhyo/face-recognition](https://github.com/yakhyo/face-recognition) | MIT |
--- a/docs/models.md
+++ b/docs/models.md
@@ -1,6 +1,6 @@
 # Model Zoo

-Complete guide to all available models, their performance characteristics, and selection criteria.
+Complete guide to all available models and their performance characteristics.

 ---

@@ -8,107 +8,143 @@ Complete guide to all available models, their performance characteristics, and s

 ### RetinaFace Family

-RetinaFace models are trained on the WIDER FACE dataset and provide excellent accuracy-speed tradeoffs.
+RetinaFace models are trained on the WIDER FACE dataset.

-| Model Name     | Params | Size  | Easy   | Medium | Hard   | Use Case                      |
-| -------------- | ------ | ----- | ------ | ------ | ------ | ----------------------------- |
-| `MNET_025`   | 0.4M   | 1.7MB | 88.48% | 87.02% | 80.61% | Mobile/Edge devices           |
-| `MNET_050`   | 1.0M   | 2.6MB | 89.42% | 87.97% | 82.40% | Mobile/Edge devices           |
-| `MNET_V1`    | 3.5M   | 3.8MB | 90.59% | 89.14% | 84.13% | Balanced mobile               |
-| `MNET_V2` :material-check-circle: | 3.2M   | 3.5MB | 91.70% | 91.03% | 86.60% | **Default** |
-| `RESNET18`   | 11.7M  | 27MB  | 92.50% | 91.02% | 86.63% | Server/High accuracy          |
-| `RESNET34`   | 24.8M  | 56MB  | 94.16% | 93.12% | 88.90% | Maximum accuracy              |
+| Model Name     | Params | Size  | Easy   | Medium | Hard   |
+| -------------- | ------ | ----- | ------ | ------ | ------ |
+| `MNET_025`   | 0.4M   | 1.7MB | 88.48% | 87.02% | 80.61% |
+| `MNET_050`   | 1.0M   | 2.6MB | 89.42% | 87.97% | 82.40% |
+| `MNET_V1`    | 3.5M   | 3.8MB | 90.59% | 89.14% | 84.13% |
+| `MNET_V2` :material-check-circle: | 3.2M   | 3.5MB | 91.70% | 91.03% | 86.60% |
+| `RESNET18`   | 11.7M  | 27MB  | 92.50% | 91.02% | 86.63% |
+| `RESNET34`   | 24.8M  | 56MB  | 94.16% | 93.12% | 88.90% |

 !!! info "Accuracy & Benchmarks"
    **Accuracy**: WIDER FACE validation set (Easy/Medium/Hard subsets) - from [RetinaFace paper](https://arxiv.org/abs/1905.00641)

-    **Speed**: Benchmark on your own hardware using `python tools/detection.py --source <image> --iterations 100`
+    **Speed**: Benchmark on your own hardware using `python tools/detection.py --source <image>`

 ---

 ### SCRFD Family

-SCRFD (Sample and Computation Redistribution for Efficient Face Detection) models offer state-of-the-art speed-accuracy tradeoffs.
+SCRFD (Sample and Computation Redistribution for Efficient Face Detection) models trained on WIDER FACE dataset.

-| Model Name       | Params | Size  | Easy   | Medium | Hard   | Use Case                        |
-| ---------------- | ------ | ----- | ------ | ------ | ------ | ------------------------------- |
-| `SCRFD_500M`   | 0.6M   | 2.5MB | 90.57% | 88.12% | 68.51% | Real-time applications          |
-| `SCRFD_10G` :material-check-circle: | 4.2M   | 17MB  | 95.16% | 93.87% | 83.05% | **High accuracy + speed** |
+| Model Name       | Params | Size  | Easy   | Medium | Hard   |
+| ---------------- | ------ | ----- | ------ | ------ | ------ |
+| `SCRFD_500M_KPS`   | 0.6M   | 2.5MB | 90.57% | 88.12% | 68.51% |
+| `SCRFD_10G_KPS` :material-check-circle: | 4.2M   | 17MB  | 95.16% | 93.87% | 83.05% |

 !!! info "Accuracy & Benchmarks"
    **Accuracy**: WIDER FACE validation set - from [SCRFD paper](https://arxiv.org/abs/2105.04714)

-    **Speed**: Benchmark on your own hardware using `python tools/detection.py --source <image> --iterations 100`
+    **Speed**: Benchmark on your own hardware using `python tools/detection.py --source <image>`

 ---

 ### YOLOv5-Face Family

-YOLOv5-Face models provide excellent detection accuracy with 5-point facial landmarks, optimized for real-time applications.
+YOLOv5-Face models provide detection with 5-point facial landmarks, trained on WIDER FACE dataset.

-| Model Name     | Size | Easy   | Medium | Hard   | Use Case                       |
-| -------------- | ---- | ------ | ------ | ------ | ------------------------------ |
-| `YOLOV5N`    | 11MB | 93.61% | 91.52% | 80.53% | Lightweight/Mobile             |
-| `YOLOV5S` :material-check-circle: | 28MB | 94.33% | 92.61% | 83.15% | **Real-time + accuracy** |
-| `YOLOV5M`    | 82MB | 95.30% | 93.76% | 85.28% | High accuracy                  |
+| Model Name     | Size | Easy   | Medium | Hard   |
+| -------------- | ---- | ------ | ------ | ------ |
+| `YOLOV5N`    | 11MB | 93.61% | 91.52% | 80.53% |
+| `YOLOV5S` :material-check-circle: | 28MB | 94.33% | 92.61% | 83.15% |
+| `YOLOV5M`    | 82MB | 95.30% | 93.76% | 85.28% |

 !!! info "Accuracy & Benchmarks"
    **Accuracy**: WIDER FACE validation set - from [YOLOv5-Face paper](https://arxiv.org/abs/2105.12931)

-    **Speed**: Benchmark on your own hardware using `python tools/detection.py --source <image> --iterations 100`
+    **Speed**: Benchmark on your own hardware using `python tools/detection.py --source <image>`

 !!! note "Fixed Input Size"
-    All YOLOv5-Face models use a fixed input size of 640×640. Models exported to ONNX from [deepcam-cn/yolov5-face](https://github.com/deepcam-cn/yolov5-face).
+    All YOLOv5-Face models use a fixed input size of 640×640.
+
+---
+
+### YOLOv8-Face Family
+
+YOLOv8-Face models use anchor-free design with DFL (Distribution Focal Loss) for bbox regression. Provides detection with 5-point facial landmarks.
+
+| Model Name       | Size   | Easy   | Medium | Hard   |
+| ---------------- | ------ | ------ | ------ | ------ |
+| `YOLOV8_LITE_S`| 7.4MB  | 93.4%  | 91.2%  | 78.6%  |
+| `YOLOV8N` :material-check-circle: | 12MB   | 94.6%  | 92.3%  | 79.6%  |
+
+!!! info "Accuracy & Benchmarks"
+    **Accuracy**: WIDER FACE validation set (Easy/Medium/Hard subsets)
+
+    **Speed**: Benchmark on your own hardware using `python tools/detection.py --source <image> --method yolov8face`
+
+!!! note "Fixed Input Size"
+    All YOLOv8-Face models use a fixed input size of 640×640.

 ---

 ## Face Recognition Models

+### AdaFace
+
+Face recognition using adaptive margin based on image quality.
+
+| Model Name  | Backbone | Dataset     | Size   | IJB-B TAR | IJB-C TAR |
+| ----------- | -------- | ----------- | ------ | --------- | --------- |
+| `IR_18` :material-check-circle: | IR-18    | WebFace4M   | 92 MB  | 93.03%    | 94.99%    |
+| `IR_101`  | IR-101   | WebFace12M  | 249 MB | -         | 97.66%    |
+
+!!! info "Training Data & Accuracy"
+    **Dataset**: WebFace4M (4M images) / WebFace12M (12M images)
+
+    **Accuracy**: IJB-B and IJB-C benchmarks, TAR@FAR=0.01%
+
+!!! tip "Key Innovation"
+    AdaFace introduces adaptive margin that adjusts based on image quality, providing better performance on low-quality images compared to fixed-margin approaches.
+
+
+---
+
 ### ArcFace

-State-of-the-art face recognition using additive angular margin loss.
+Face recognition using additive angular margin loss.

-| Model Name  | Backbone  | Params | Size  | Use Case                         |
-| ----------- | --------- | ------ | ----- | -------------------------------- |
-| `MNET` :material-check-circle: | MobileNet | 2.0M   | 8MB   | **Balanced (recommended)** |
-| `RESNET`  | ResNet50  | 43.6M  | 166MB | Maximum accuracy                 |
+| Model Name  | Backbone  | Params | Size  | LFW    | CFP-FP | AgeDB-30 | IJB-C |
+| ----------- | --------- | ------ | ----- | ------ | ------ | -------- | ----- |
+| `MNET` :material-check-circle: | MobileNet | 2.0M   | 8MB   | 99.70% | 98.00% | 96.58%   | 95.02% |
+| `RESNET`  | ResNet50  | 43.6M  | 166MB | 99.83% | 99.33% | 98.23%   | 97.25% |

 !!! info "Training Data"
-    **Dataset**: Trained on MS1M-V2 (5.8M images, 85K identities)
+    **Dataset**: Trained on WebFace600K (600K images)

-    **Accuracy**: Benchmark on your own dataset or use standard face verification benchmarks
+    **Accuracy**: IJB-C accuracy reported as TAR@FAR=1e-4

 ---

 ### MobileFace

-Lightweight face recognition optimized for mobile devices.
+Lightweight face recognition models with MobileNet backbones.

-| Model Name        | Backbone         | Params | Size | LFW    | CALFW  | CPLFW  | AgeDB-30 | Use Case              |
-| ----------------- | ---------------- | ------ | ---- | ------ | ------ | ------ | -------- | --------------------- |
-| `MNET_025`      | MobileNetV1 0.25 | 0.36M  | 1MB  | 98.76% | 92.02% | 82.37% | 90.02%   | Ultra-lightweight     |
-| `MNET_V2` :material-check-circle:    | MobileNetV2      | 2.29M  | 4MB  | 99.55% | 94.87% | 86.89% | 95.16%   | **Mobile/Edge** |
-| `MNET_V3_SMALL` | MobileNetV3-S    | 1.25M  | 3MB  | 99.30% | 93.77% | 85.29% | 92.79%   | Mobile optimized      |
-| `MNET_V3_LARGE` | MobileNetV3-L    | 3.52M  | 10MB | 99.53% | 94.56% | 86.79% | 95.13%   | Balanced mobile       |
+| Model Name        | Backbone         | Params | Size | LFW    | CALFW  | CPLFW  | AgeDB-30 |
+| ----------------- | ---------------- | ------ | ---- | ------ | ------ | ------ | -------- |
+| `MNET_025`      | MobileNetV1 0.25 | 0.36M  | 1MB  | 98.76% | 92.02% | 82.37% | 90.02%   |
+| `MNET_V2` :material-check-circle:    | MobileNetV2      | 2.29M  | 4MB  | 99.55% | 94.87% | 86.89% | 95.16%   |
+| `MNET_V3_SMALL` | MobileNetV3-S    | 1.25M  | 3MB  | 99.30% | 93.77% | 85.29% | 92.79%   |
+| `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)

    **Accuracy**: Evaluated on LFW, CALFW, CPLFW, and AgeDB-30 benchmarks

-!!! tip "Use Case"
-    These models are lightweight alternatives to ArcFace for resource-constrained environments.
-
 ---

 ### SphereFace

 Face recognition using angular softmax loss.

-| Model Name   | Backbone | Params | Size | LFW    | CALFW  | CPLFW  | AgeDB-30 | Use Case            |
-| ------------ | -------- | ------ | ---- | ------ | ------ | ------ | -------- | ------------------- |
-| `SPHERE20` | Sphere20 | 24.5M  | 50MB | 99.67% | 95.61% | 88.75% | 96.58%   | Research/Comparison |
-| `SPHERE36` | Sphere36 | 34.6M  | 92MB | 99.72% | 95.64% | 89.92% | 96.83%   | Research/Comparison |
+| Model Name   | Backbone | Params | Size | LFW    | CALFW  | CPLFW  | AgeDB-30 |
+| ------------ | -------- | ------ | ---- | ------ | ------ | ------ | -------- |
+| `SPHERE20` | Sphere20 | 24.5M  | 50MB | 99.67% | 95.61% | 88.75% | 96.58%   |
+| `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)
@@ -124,11 +160,11 @@ Face recognition using angular softmax loss.

 ### 106-Point Landmark Detection

-High-precision facial landmark localization.
+Facial landmark localization model.

-| Model Name | Points | Params | Size | Use Case                 |
-| ---------- | ------ | ------ | ---- | ------------------------ |
-| `2D106`  | 106    | 3.7M   | 14MB | Face alignment, analysis |
+| Model Name | Points | Params | Size |
+| ---------- | ------ | ------ | ---- |
+| `2D106`  | 106    | 3.7M   | 14MB |

 **Landmark Groups:**

@@ -146,9 +182,9 @@ High-precision facial landmark localization.

 ### Age & Gender Detection

-| Model Name  | Attributes  | Params | Size | Use Case        |
-| ----------- | ----------- | ------ | ---- | --------------- |
-| `AgeGender` | Age, Gender | 2.1M   | 8MB  | General purpose |
+| Model Name  | Attributes  | Params | Size |
+| ----------- | ----------- | ------ | ---- |
+| `AgeGender` | Age, Gender | 2.1M   | 8MB  |

 !!! info "Training Data"
    **Dataset**: Trained on CelebA
@@ -160,9 +196,9 @@ High-precision facial landmark localization.

 ### FairFace Attributes

-| Model Name  | Attributes            | Params | Size  | Use Case                    |
-| ----------- | --------------------- | ------ | ----- | --------------------------- |
-| `FairFace` | Race, Gender, Age Group | -      | 44MB  | Balanced demographic prediction |
+| Model Name  | Attributes            | Params | Size  |
+| ----------- | --------------------- | ------ | ----- |
+| `FairFace` | Race, Gender, Age Group | -      | 44MB  |

 !!! info "Training Data"
    **Dataset**: Trained on FairFace dataset with balanced demographics
@@ -178,10 +214,10 @@ High-precision facial landmark localization.

 ### Emotion Detection

-| Model Name    | Classes | Params | Size | Use Case        |
-| ------------- | ------- | ------ | ---- | --------------- |
-| `AFFECNET7` | 7       | 0.5M   | 2MB  | 7-class emotion |
-| `AFFECNET8` | 8       | 0.5M   | 2MB  | 8-class emotion |
+| Model Name    | Classes | Params | Size |
+| ------------- | ------- | ------ | ---- |
+| `AFFECNET7` | 7       | 0.5M   | 2MB  |
+| `AFFECNET8` | 8       | 0.5M   | 2MB  |

 **Classes (7)**: Neutral, Happy, Sad, Surprise, Fear, Disgust, Anger

@@ -199,15 +235,15 @@ High-precision facial landmark localization.

 ### MobileGaze Family

-Real-time gaze direction prediction models trained on Gaze360 dataset. Returns pitch (vertical) and yaw (horizontal) angles in radians.
+Gaze direction prediction models trained on Gaze360 dataset. Returns pitch (vertical) and yaw (horizontal) angles in radians.

-| Model Name     | Params | Size    | MAE*  | Use Case                      |
-| -------------- | ------ | ------- | ----- | ----------------------------- |
-| `RESNET18`   | 11.7M  | 43 MB   | 12.84 | Balanced accuracy/speed       |
-| `RESNET34` :material-check-circle: | 24.8M  | 81.6 MB | 11.33 | **Default** |
-| `RESNET50`   | 25.6M  | 91.3 MB | 11.34 | High accuracy                 |
-| `MOBILENET_V2` | 3.5M   | 9.59 MB | 13.07 | Mobile/Edge devices           |
-| `MOBILEONE_S0` | 2.1M   | 4.8 MB  | 12.58 | Lightweight/Real-time         |
+| Model Name     | Params | Size    | MAE*  |
+| -------------- | ------ | ------- | ----- |
+| `RESNET18`   | 11.7M  | 43 MB   | 12.84 |
+| `RESNET34` :material-check-circle: | 24.8M  | 81.6 MB | 11.33 |
+| `RESNET50`   | 25.6M  | 91.3 MB | 11.34 |
+| `MOBILENET_V2` | 3.5M   | 9.59 MB | 13.07 |
+| `MOBILEONE_S0` | 2.1M   | 4.8 MB  | 12.58 |

 *MAE (Mean Absolute Error) in degrees on Gaze360 test set - lower is better

@@ -227,10 +263,10 @@ Real-time gaze direction prediction models trained on Gaze360 dataset. Returns p

 BiSeNet (Bilateral Segmentation Network) models for semantic face parsing. Segments face images into 19 facial component classes.

-| Model Name     | Params | Size    | Classes | Use Case                      |
-| -------------- | ------ | ------- | ------- | ----------------------------- |
-| `RESNET18` :material-check-circle: | 13.3M  | 50.7 MB | 19      | **Default** |
-| `RESNET34`   | 24.1M  | 89.2 MB | 19      | Higher accuracy               |
+| Model Name     | Params | Size    | Classes |
+| -------------- | ------ | ------- | ------- |
+| `RESNET18` :material-check-circle: | 13.3M  | 50.7 MB | 19      |
+| `RESNET34`   | 24.1M  | 89.2 MB | 19      |

 !!! info "Training Data"
    **Dataset**: Trained on CelebAMask-HQ
@@ -264,22 +300,48 @@ BiSeNet (Bilateral Segmentation Network) models for semantic face parsing. Segme

 ---

+### XSeg
+
+XSeg from DeepFaceLab outputs masks for face regions. Requires 5-point landmarks for face alignment.
+
+| Model Name | Size   | Output |
+|------------|--------|--------|
+| `DEFAULT`  | 67 MB  | Mask [0, 1] |
+
+!!! info "Model Details"
+    **Origin**: DeepFaceLab
+
+    **Input**: NHWC format, normalized to [0, 1]
+
+    **Alignment**: Requires 5-point landmarks (not bbox crops)
+
+**Applications:**
+
+- Face region extraction
+- Face swapping pipelines
+- Occlusion handling
+
+!!! note "Input Requirements"
+    Requires 5-point facial landmarks. Use a face detector like RetinaFace to obtain landmarks first.
+
+---
+
 ## Anti-Spoofing Models

 ### MiniFASNet Family

-Lightweight face anti-spoofing models for liveness detection. Detect if a face is real (live) or fake (photo, video replay, mask).
+Face anti-spoofing models for liveness detection. Detect if a face is real (live) or fake (photo, video replay, mask).

-| Model Name | Size   | Scale | Use Case                      |
-| ---------- | ------ | ----- | ----------------------------- |
-| `V1SE`   | 1.2 MB | 4.0   | Squeeze-and-excitation variant |
-| `V2` :material-check-circle:  | 1.2 MB | 2.7   | **Default**       |
+| Model Name | Size   | Scale |
+| ---------- | ------ | ----- |
+| `V1SE`   | 1.2 MB | 4.0   |
+| `V2` :material-check-circle:  | 1.2 MB | 2.7   |

 !!! info "Output Format"
    **Output**: Returns `SpoofingResult(is_real, confidence)` where is_real: True=Real, False=Fake

 !!! note "Input Requirements"
-    Requires face bounding box from a detector. Use with RetinaFace, SCRFD, or YOLOv5Face.
+    Requires face bounding box from a detector.

 ---

@@ -300,9 +362,14 @@ Models are automatically downloaded and cached on first use.
 - **RetinaFace Training**: [yakhyo/retinaface-pytorch](https://github.com/yakhyo/retinaface-pytorch) - PyTorch implementation and training code
 - **YOLOv5-Face Original**: [deepcam-cn/yolov5-face](https://github.com/deepcam-cn/yolov5-face) - Original PyTorch implementation
 - **YOLOv5-Face ONNX**: [yakhyo/yolov5-face-onnx-inference](https://github.com/yakhyo/yolov5-face-onnx-inference) - ONNX inference implementation
+- **YOLOv8-Face Original**: [derronqi/yolov8-face](https://github.com/derronqi/yolov8-face) - Original PyTorch implementation
+- **YOLOv8-Face ONNX**: [yakhyo/yolov8-face-onnx-inference](https://github.com/yakhyo/yolov8-face-onnx-inference) - ONNX inference implementation
+- **AdaFace Original**: [mk-minchul/AdaFace](https://github.com/mk-minchul/AdaFace) - Original PyTorch implementation
+- **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
 - **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))
 - **FairFace**: [yakhyo/fairface-onnx](https://github.com/yakhyo/fairface-onnx) - FairFace ONNX inference for race, gender, age prediction
 - **InsightFace**: [deepinsight/insightface](https://github.com/deepinsight/insightface) - Model architectures and pretrained weights
@@ -312,6 +379,7 @@ Models are automatically downloaded and cached on first use.
 - **RetinaFace**: [Single-Shot Multi-Level Face Localisation in the Wild](https://arxiv.org/abs/1905.00641)
 - **SCRFD**: [Sample and Computation Redistribution for Efficient Face Detection](https://arxiv.org/abs/2105.04714)
 - **YOLOv5-Face**: [YOLO5Face: Why Reinventing a Face Detector](https://arxiv.org/abs/2105.12931)
+- **AdaFace**: [AdaFace: Quality Adaptive Margin for Face Recognition](https://arxiv.org/abs/2204.00964)
 - **ArcFace**: [Additive Angular Margin Loss for Deep Face Recognition](https://arxiv.org/abs/1801.07698)
 - **SphereFace**: [Deep Hypersphere Embedding for Face Recognition](https://arxiv.org/abs/1704.08063)
 - **BiSeNet**: [Bilateral Segmentation Network for Real-time Semantic Segmentation](https://arxiv.org/abs/1808.00897)
--- a/docs/modules/attributes.md
+++ b/docs/modules/attributes.md
@@ -125,7 +125,7 @@ from uniface.attribute import Emotion
 from uniface.constants import DDAMFNWeights

 detector = RetinaFace()
-emotion = Emotion(model_name=DDAMFNWeights.AFFECNET7)
+emotion = Emotion(model_weights=DDAMFNWeights.AFFECNET7)

 faces = detector.detect(image)

@@ -169,10 +169,10 @@ from uniface.attribute import Emotion
 from uniface.constants import DDAMFNWeights

 # 7-class emotion
-emotion = Emotion(model_name=DDAMFNWeights.AFFECNET7)
+emotion = Emotion(model_weights=DDAMFNWeights.AFFECNET7)

 # 8-class emotion
-emotion = Emotion(model_name=DDAMFNWeights.AFFECNET8)
+emotion = Emotion(model_weights=DDAMFNWeights.AFFECNET8)
 ```

 ---
@@ -206,12 +206,11 @@ for face in faces:
 ### Using FaceAnalyzer

 ```python
-from uniface import FaceAnalyzer
+from uniface import FaceAnalyzer, RetinaFace, AgeGender

 analyzer = FaceAnalyzer(
-    detect=True,
-    recognize=False,
-    attributes=True  # Uses AgeGender
+    RetinaFace(),
+    age_gender=AgeGender(),
 )

 faces = analyzer.analyze(image)
--- a/docs/modules/detection.md
+++ b/docs/modules/detection.md
@@ -1,22 +1,25 @@
 # Detection

-Face detection is the first step in any face analysis pipeline. UniFace provides three detection models.
+Face detection is the first step in any face analysis pipeline. UniFace provides four detection models.

 ---

 ## Available Models

-| Model | Backbone | Size | WIDER FACE (Easy/Medium/Hard) | Best For |
-|-------|----------|------|-------------------------------|----------|
-| **RetinaFace** | MobileNet V2 | 3.5 MB | 91.7% / 91.0% / 86.6% | Balanced (recommended) |
-| **SCRFD** | SCRFD-10G | 17 MB | 95.2% / 93.9% / 83.1% | High accuracy |
-| **YOLOv5-Face** | YOLOv5s | 28 MB | 94.3% / 92.6% / 83.2% | Real-time |
+| Model | Backbone | Size | Easy | Medium | Hard | Landmarks |
+|-------|----------|------|------|--------|------|:---------:|
+| **RetinaFace** | MobileNet V2 | 3.5 MB | 91.7% | 91.0% | 86.6% | :material-check: |
+| **SCRFD** | SCRFD-10G | 17 MB | 95.2% | 93.9% | 83.1% | :material-check: |
+| **YOLOv5-Face** | YOLOv5s | 28 MB | 94.3% | 92.6% | 83.2% | :material-check: |
+| **YOLOv8-Face** | YOLOv8n | 12 MB | 94.6% | 92.3% | 79.6% | :material-check: |

+!!! note "Dataset"
+    All models trained on WIDERFACE dataset.
 ---

 ## RetinaFace

-The recommended detector for most use cases.
+Single-shot face detector with multi-scale feature pyramid.

 ### Basic Usage

@@ -65,7 +68,8 @@ detector = RetinaFace(
    confidence_threshold=0.5,  # Min confidence
    nms_threshold=0.4,         # NMS IoU threshold
    input_size=(640, 640),     # Input resolution
-    dynamic_size=False         # Enable dynamic input size
+    dynamic_size=False,        # Enable dynamic input size
+    providers=None,            # Auto-detect, or ['CPUExecutionProvider']
 )
 ```

@@ -109,7 +113,8 @@ detector = SCRFD(
    model_name=SCRFDWeights.SCRFD_10G_KPS,
    confidence_threshold=0.5,
    nms_threshold=0.4,
-    input_size=(640, 640)
+    input_size=(640, 640),
+    providers=None,  # Auto-detect, or ['CPUExecutionProvider']
 )
 ```

@@ -159,7 +164,57 @@ detector = YOLOv5Face(model_name=YOLOv5FaceWeights.YOLOV5M)
 detector = YOLOv5Face(
    model_name=YOLOv5FaceWeights.YOLOV5S,
    confidence_threshold=0.6,
-    nms_threshold=0.5
+    nms_threshold=0.5,
+    nms_mode='numpy',  # or 'torchvision' for faster NMS
+    providers=None,    # Auto-detect, or ['CPUExecutionProvider']
+)
+```
+
+---
+
+## YOLOv8-Face
+
+Anchor-free detection with DFL (Distribution Focal Loss) for accurate bbox regression.
+
+### Basic Usage
+
+```python
+from uniface import YOLOv8Face
+
+detector = YOLOv8Face()
+faces = detector.detect(image)
+```
+
+### Model Variants
+
+```python
+from uniface import YOLOv8Face
+from uniface.constants import YOLOv8FaceWeights
+
+# Lightweight
+detector = YOLOv8Face(model_name=YOLOv8FaceWeights.YOLOV8_LITE_S)
+
+# Recommended (default)
+detector = YOLOv8Face(model_name=YOLOv8FaceWeights.YOLOV8N)
+```
+
+| Variant | Size | Easy | Medium | Hard |
+|---------|------|------|--------|------|
+| YOLOV8_LITE_S | 7.4 MB | 93.4% | 91.2% | 78.6% |
+| **YOLOV8N** :material-check-circle: | 12 MB | 94.6% | 92.3% | 79.6% |
+
+!!! note "Fixed Input Size"
+    YOLOv8-Face uses a fixed input size of 640×640.
+
+### Configuration
+
+```python
+detector = YOLOv8Face(
+    model_name=YOLOv8FaceWeights.YOLOV8N,
+    confidence_threshold=0.5,
+    nms_threshold=0.45,
+    nms_mode='numpy',  # or 'torchvision' for faster NMS
+    providers=None,    # Auto-detect, or ['CPUExecutionProvider']
 )
 ```

@@ -177,6 +232,8 @@ detector = create_detector('retinaface')
 detector = create_detector('scrfd')
 # or
 detector = create_detector('yolov5face')
+# or
+detector = create_detector('yolov8face')
 ```

 ---
@@ -188,11 +245,11 @@ One-line detection:
 ```python
 from uniface import detect_faces

-faces = detect_faces(
-    image,
-    method='retinaface',
-    confidence_threshold=0.5
-)
+# Using RetinaFace (default)
+faces = detect_faces(image, method='retinaface', confidence_threshold=0.5)
+
+# Using YOLOv8-Face
+faces = detect_faces(image, method='yolov8face', confidence_threshold=0.5)
 ```

 ---
@@ -239,7 +296,7 @@ cv2.imwrite("result.jpg", image)
 Benchmark on your hardware:

 ```bash
-python tools/detection.py --source image.jpg --iterations 100
+python tools/detection.py --source image.jpg
 ```

 ---
--- a/docs/modules/gaze.md
+++ b/docs/modules/gaze.md
@@ -6,13 +6,13 @@ Gaze estimation predicts where a person is looking (pitch and yaw angles).

 ## Available Models

-| Model | Backbone | Size | MAE* | Best For |
-|-------|----------|------|------|----------|
-| ResNet18 | ResNet18 | 43 MB | 12.84° | Balanced |
-| **ResNet34** :material-check-circle: | ResNet34 | 82 MB | 11.33° | Recommended |
-| ResNet50 | ResNet50 | 91 MB | 11.34° | High accuracy |
-| MobileNetV2 | MobileNetV2 | 9.6 MB | 13.07° | Mobile |
-| MobileOne-S0 | MobileOne | 4.8 MB | 12.58° | Lightweight |
+| Model | Backbone | Size | MAE* |
+|-------|----------|------|------|
+| ResNet18 | ResNet18 | 43 MB | 12.84° |
+| **ResNet34** :material-check-circle: | ResNet34 | 82 MB | 11.33° |
+| ResNet50 | ResNet50 | 91 MB | 11.34° |
+| MobileNetV2 | MobileNetV2 | 9.6 MB | 13.07° |
+| MobileOne-S0 | MobileOne | 4.8 MB | 12.58° |

 *MAE = Mean Absolute Error on Gaze360 test set (lower is better)

--- a/docs/modules/landmarks.md
+++ b/docs/modules/landmarks.md
@@ -6,12 +6,12 @@ Facial landmark detection provides precise localization of facial features.

 ## Available Models

-| Model | Points | Size | Use Case |
-|-------|--------|------|----------|
-| **Landmark106** | 106 | 14 MB | Detailed face analysis |
+| Model | Points | Size |
+|-------|--------|------|
+| **Landmark106** | 106 | 14 MB |

 !!! info "5-Point Landmarks"
-    Basic 5-point landmarks are included with all detection models (RetinaFace, SCRFD, YOLOv5-Face).
+    Basic 5-point landmarks are included with all detection models (RetinaFace, SCRFD, YOLOv5-Face, YOLOv8-Face).

 ---

--- a/docs/modules/parsing.md
+++ b/docs/modules/parsing.md
@@ -1,15 +1,16 @@
 # Parsing

-Face parsing segments faces into semantic components (skin, eyes, nose, mouth, hair, etc.).
+Face parsing segments faces into semantic components or face regions.

 ---

 ## Available Models

-| Model | Backbone | Size | Classes | Best For |
-|-------|----------|------|---------|----------|
-| **BiSeNet ResNet18** :material-check-circle: | ResNet18 | 51 MB | 19 | Balanced (recommended) |
-| **BiSeNet ResNet34** | ResNet34 | 89 MB | 19 | Higher accuracy |
+| Model | Backbone | Size | Output |
+|-------|----------|------|--------|
+| **BiSeNet ResNet18** :material-check-circle: | ResNet18 | 51 MB | 19 classes |
+| BiSeNet ResNet34 | ResNet34 | 89 MB | 19 classes |
+| XSeg | - | 67 MB | Mask |

 ---

@@ -45,16 +46,16 @@ cv2.imwrite("parsed.jpg", vis_bgr)

 | ID | Class | ID | Class |
 |----|-------|----|-------|
-| 0 | Background | 10 | Ear Ring |
-| 1 | Skin | 11 | Nose |
-| 2 | Left Eyebrow | 12 | Mouth |
-| 3 | Right Eyebrow | 13 | Upper Lip |
-| 4 | Left Eye | 14 | Lower Lip |
-| 5 | Right Eye | 15 | Neck |
-| 6 | Eye Glasses | 16 | Neck Lace |
-| 7 | Left Ear | 17 | Cloth |
-| 8 | Right Ear | 18 | Hair |
-| 9 | Hat | | |
+| 0 | Background | 10 | Nose |
+| 1 | Skin | 11 | Mouth |
+| 2 | Left Eyebrow | 12 | Upper Lip |
+| 3 | Right Eyebrow | 13 | Lower Lip |
+| 4 | Left Eye | 14 | Neck |
+| 5 | Right Eye | 15 | Necklace |
+| 6 | Eyeglasses | 16 | Cloth |
+| 7 | Left Ear | 17 | Hair |
+| 8 | Right Ear | 18 | Hat |
+| 9 | Earring | | |

 ---

@@ -71,10 +72,10 @@ parser = BiSeNet()
 parser = BiSeNet(model_name=ParsingWeights.RESNET34)
 ```

-| Variant | Params | Size | Notes |
-|---------|--------|------|-------|
-| **RESNET18** :material-check-circle: | 13.3M | 51 MB | Recommended |
-| RESNET34 | 24.1M | 89 MB | Higher accuracy |
+| Variant | Params | Size |
+|---------|--------|------|
+| **RESNET18** :material-check-circle: | 13.3M | 51 MB |
+| RESNET34 | 24.1M | 89 MB |

 ---

@@ -125,7 +126,7 @@ mask = parser.parse(face_image)

 # Extract specific component
 SKIN = 1
-HAIR = 18
+HAIR = 17
 LEFT_EYE = 4
 RIGHT_EYE = 5

@@ -148,10 +149,10 @@ mask = parser.parse(face_image)

 component_names = {
    0: 'Background', 1: 'Skin', 2: 'L-Eyebrow', 3: 'R-Eyebrow',
-    4: 'L-Eye', 5: 'R-Eye', 6: 'Glasses', 7: 'L-Ear', 8: 'R-Ear',
-    9: 'Hat', 10: 'Earring', 11: 'Nose', 12: 'Mouth',
-    13: 'U-Lip', 14: 'L-Lip', 15: 'Neck', 16: 'Necklace',
-    17: 'Cloth', 18: 'Hair'
+    4: 'L-Eye', 5: 'R-Eye', 6: 'Eyeglasses', 7: 'L-Ear', 8: 'R-Ear',
+    9: 'Earring', 10: 'Nose', 11: 'Mouth',
+    12: 'U-Lip', 13: 'L-Lip', 14: 'Neck', 15: 'Necklace',
+    16: 'Cloth', 17: 'Hair', 18: 'Hat'
 }

 for class_id in np.unique(mask):
@@ -218,7 +219,7 @@ def replace_background(image, mask, background):
 ```python
 def get_hair_mask(mask):
    """Extract clean hair mask."""
-    hair_mask = (mask == 18).astype(np.uint8) * 255
+    hair_mask = (mask == 17).astype(np.uint8) * 255

    # Clean up with morphological operations
    kernel = np.ones((5, 5), np.uint8)
@@ -248,12 +249,83 @@ vis_result = vis_parsing_maps(

 ---

+## XSeg
+
+XSeg outputs a mask for face regions. Unlike BiSeNet which works on bbox crops, XSeg requires 5-point landmarks for face alignment.
+
+### Basic Usage
+
+```python
+import cv2
+from uniface import RetinaFace
+from uniface.parsing import XSeg
+
+detector = RetinaFace()
+parser = XSeg()
+
+image = cv2.imread("photo.jpg")
+faces = detector.detect(image)
+
+for face in faces:
+    if face.landmarks is not None:
+        mask = parser.parse(image, face.landmarks)
+        print(f"Mask shape: {mask.shape}")  # (H, W), values in [0, 1]
+```
+
+### Parameters
+
+```python
+from uniface.parsing import XSeg
+
+# Default settings
+parser = XSeg()
+
+# Custom settings
+parser = XSeg(
+    align_size=256,   # Face alignment size
+    blur_sigma=5,     # Gaussian blur for smoothing (0 = raw)
+)
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `align_size` | 256 | Face alignment output size |
+| `blur_sigma` | 0 | Mask smoothing (0 = no blur) |
+
+### Methods
+
+```python
+# Full pipeline: align -> segment -> warp back to original space
+mask = parser.parse(image, landmarks)
+
+# For pre-aligned face crops
+mask = parser.parse_aligned(face_crop)
+
+# Get mask + crop + inverse matrix for custom warping
+mask, face_crop, inverse_matrix = parser.parse_with_inverse(image, landmarks)
+```
+
+### BiSeNet vs XSeg
+
+| Feature | BiSeNet | XSeg |
+|---------|---------|------|
+| Output | 19 class labels | Mask [0, 1] |
+| Input | Bbox crop | Requires landmarks |
+| Use case | Facial components | Face region extraction |
+
+---
+
 ## Factory Function

 ```python
 from uniface import create_face_parser
+from uniface.constants import ParsingWeights, XSegWeights

-parser = create_face_parser()  # Returns BiSeNet
+# BiSeNet (default)
+parser = create_face_parser()
+
+# XSeg
+parser = create_face_parser(XSegWeights.DEFAULT)
 ```

 ---
--- a/docs/modules/privacy.md
+++ b/docs/modules/privacy.md
@@ -6,13 +6,13 @@ Face anonymization protects privacy by blurring or obscuring faces in images and

 ## Available Methods

-| Method | Description | Use Case |
-|--------|-------------|----------|
-| **pixelate** | Blocky pixelation | News media standard |
-| **gaussian** | Smooth blur | Natural appearance |
-| **blackout** | Solid color fill | Maximum privacy |
-| **elliptical** | Oval-shaped blur | Natural face shape |
-| **median** | Edge-preserving blur | Artistic effect |
+| Method | Description |
+|--------|-------------|
+| **pixelate** | Blocky pixelation |
+| **gaussian** | Smooth blur |
+| **blackout** | Solid color fill |
+| **elliptical** | Oval-shaped blur |
+| **median** | Edge-preserving blur |

 ---

@@ -64,7 +64,7 @@ blurrer = BlurFace(method='pixelate', pixel_blocks=10)

 | Parameter | Default | Description |
 |-----------|---------|-------------|
-| `pixel_blocks` | 10 | Number of blocks (lower = more pixelated) |
+| `pixel_blocks` | 15 | Number of blocks (lower = more pixelated) |

 ### Gaussian

--- a/docs/modules/recognition.md
+++ b/docs/modules/recognition.md
@@ -6,17 +6,65 @@ Face recognition extracts embeddings for identity verification and face search.

 ## Available Models

-| Model | Backbone | Size | Embedding Dim | Best For |
-|-------|----------|------|---------------|----------|
-| **ArcFace** | MobileNet/ResNet | 8-166 MB | 512 | General use (recommended) |
-| **MobileFace** | MobileNet V2/V3 | 1-10 MB | 512 | Mobile/Edge |
-| **SphereFace** | Sphere20/36 | 50-92 MB | 512 | Research |
+| Model | Backbone | Size | Embedding Dim |
+|-------|----------|------|---------------|
+| **AdaFace** | IR-18/IR-101 | 92-249 MB | 512 |
+| **ArcFace** | MobileNet/ResNet | 8-166 MB | 512 |
+| **MobileFace** | MobileNet V2/V3 | 1-10 MB | 512 |
+| **SphereFace** | Sphere20/36 | 50-92 MB | 512 |
+
+---
+
+## AdaFace
+
+Face recognition using adaptive margin based on image quality.
+
+### Basic Usage
+
+```python
+from uniface import RetinaFace, AdaFace
+
+detector = RetinaFace()
+recognizer = AdaFace()
+
+# Detect face
+faces = detector.detect(image)
+
+# Extract embedding
+if faces:
+    embedding = recognizer.get_normalized_embedding(image, faces[0].landmarks)
+    print(f"Embedding shape: {embedding.shape}")  # (1, 512)
+```
+
+### Model Variants
+
+```python
+from uniface import AdaFace
+from uniface.constants import AdaFaceWeights
+
+# Lightweight (default)
+recognizer = AdaFace(model_name=AdaFaceWeights.IR_18)
+
+# High accuracy
+recognizer = AdaFace(model_name=AdaFaceWeights.IR_101)
+
+# Force CPU execution
+recognizer = AdaFace(providers=['CPUExecutionProvider'])
+```
+
+| Variant | Dataset | Size | IJB-B | IJB-C |
+|---------|---------|------|-------|-------|
+| **IR_18** :material-check-circle: | WebFace4M | 92 MB | 93.03% | 94.99% |
+| IR_101 | WebFace12M | 249 MB | - | 97.66% |
+
+!!! info "Benchmark Metrics"
+    IJB-B and IJB-C accuracy reported as TAR@FAR=0.01%

 ---

 ## ArcFace

-State-of-the-art recognition using additive angular margin loss.
+Face recognition using additive angular margin loss.

 ### Basic Usage

@@ -46,18 +94,26 @@ recognizer = ArcFace(model_name=ArcFaceWeights.MNET)

 # High accuracy
 recognizer = ArcFace(model_name=ArcFaceWeights.RESNET)
+
+# Force CPU execution
+recognizer = ArcFace(providers=['CPUExecutionProvider'])
 ```

-| Variant | Backbone | Size | Use Case |
-|---------|----------|------|----------|
-| **MNET** :material-check-circle: | MobileNet | 8 MB | Balanced (recommended) |
-| RESNET | ResNet50 | 166 MB | Maximum accuracy |
+| Variant | Backbone | Size | LFW | CFP-FP | AgeDB-30 | IJB-C |
+|---------|----------|------|-----|--------|----------|-------|
+| **MNET** :material-check-circle: | MobileNet | 8 MB | 99.70% | 98.00% | 96.58% | 95.02% |
+| RESNET | ResNet50 | 166 MB | 99.83% | 99.33% | 98.23% | 97.25% |
+
+!!! info "Training Data & Metrics"
+    **Dataset**: Trained on WebFace600K (600K images)
+
+    **Accuracy**: IJB-C reported as TAR@FAR=1e-4

 ---

 ## MobileFace

-Lightweight recognition for resource-constrained environments.
+Lightweight face recognition models with MobileNet backbones.

 ### Basic Usage

@@ -84,18 +140,18 @@ recognizer = MobileFace(model_name=MobileFaceWeights.MNET_V2)
 recognizer = MobileFace(model_name=MobileFaceWeights.MNET_V3_LARGE)
 ```

-| Variant | Params | Size | LFW | Use Case |
-|---------|--------|------|-----|----------|
-| MNET_025 | 0.36M | 1 MB | 98.8% | Ultra-lightweight |
-| **MNET_V2** :material-check-circle: | 2.29M | 4 MB | 99.6% | Mobile/Edge |
-| MNET_V3_SMALL | 1.25M | 3 MB | 99.3% | Mobile optimized |
-| MNET_V3_LARGE | 3.52M | 10 MB | 99.5% | Balanced mobile |
+| Variant | Params | Size | LFW | CALFW | CPLFW | AgeDB-30 |
+|---------|--------|------|-----|-------|-------|----------|
+| MNET_025 | 0.36M | 1 MB | 98.76% | 92.02% | 82.37% | 90.02% |
+| **MNET_V2** :material-check-circle: | 2.29M | 4 MB | 99.55% | 94.87% | 86.89% | 95.16% |
+| MNET_V3_SMALL | 1.25M | 3 MB | 99.30% | 93.77% | 85.29% | 92.79% |
+| MNET_V3_LARGE | 3.52M | 10 MB | 99.53% | 94.56% | 86.79% | 95.13% |

 ---

 ## SphereFace

-Recognition using angular softmax loss (A-Softmax).
+Face recognition using angular softmax loss (A-Softmax).

 ### Basic Usage

@@ -107,10 +163,10 @@ recognizer = SphereFace(model_name=SphereFaceWeights.SPHERE20)
 embedding = recognizer.get_normalized_embedding(image, landmarks)
 ```

-| Variant | Params | Size | LFW | Use Case |
-|---------|--------|------|-----|----------|
-| SPHERE20 | 24.5M | 50 MB | 99.7% | Research |
-| SPHERE36 | 34.6M | 92 MB | 99.7% | Research |
+| Variant | Params | Size | LFW | CALFW | CPLFW | AgeDB-30 |
+|---------|--------|------|-----|-------|-------|----------|
+| SPHERE20 | 24.5M | 50 MB | 99.67% | 95.61% | 88.75% | 96.58% |
+| SPHERE36 | 34.6M | 92 MB | 99.72% | 95.64% | 89.92% | 96.83% |

 ---

@@ -228,7 +284,9 @@ else:
 ```python
 from uniface import create_recognizer

+# Available methods: 'arcface', 'adaface', 'mobileface', 'sphereface'
 recognizer = create_recognizer('arcface')
+recognizer = create_recognizer('adaface')
 ```

 ---
--- a/docs/modules/spoofing.md
+++ b/docs/modules/spoofing.md
@@ -6,10 +6,10 @@ Face anti-spoofing detects whether a face is real (live) or fake (photo, video r

 ## Available Models

-| Model | Size | Notes |
-|-------|------|-------|
-| MiniFASNet V1SE | 1.2 MB | Squeeze-and-Excitation variant |
-| **MiniFASNet V2** :material-check-circle: | 1.2 MB | Improved version (recommended) |
+| Model | Size |
+|-------|------|
+| MiniFASNet V1SE | 1.2 MB |
+| **MiniFASNet V2** :material-check-circle: | 1.2 MB |

 ---

@@ -69,20 +69,21 @@ spoofer = MiniFASNet(model_name=MiniFASNetWeights.V1SE)

 ## Confidence Thresholds

-The default threshold is 0.5. Adjust for your use case:
+`result.is_real` is based on the model's top predicted class (argmax). If you want stricter behavior,
+apply your own confidence threshold:

 ```python
 result = spoofer.predict(image, face.bbox)

 # High security (fewer false accepts)
 HIGH_THRESHOLD = 0.7
-if result.confidence > HIGH_THRESHOLD:
+if result.is_real and result.confidence > HIGH_THRESHOLD:
    print("Real (high confidence)")
 else:
    print("Suspicious")

-# Balanced
-if result.is_real:  # Uses default 0.5 threshold
+# Balanced (argmax decision)
+if result.is_real:
    print("Real")
 else:
    print("Fake")
--- a/docs/notebooks.md
+++ b/docs/notebooks.md
@@ -16,6 +16,7 @@ Run UniFace examples directly in your browser with Google Colab, or download and
 | [Face Parsing](https://github.com/yakhyo/uniface/blob/main/examples/06_face_parsing.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/06_face_parsing.ipynb) | Semantic face segmentation |
 | [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 |

 ---

--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -357,18 +357,18 @@ cv2.destroyAllWindows()

 ## Model Selection

-For detailed model comparisons, benchmarks, and selection guidance, see the [Model Zoo](models.md).
+For detailed model comparisons and benchmarks, see the [Model Zoo](models.md).

-**Quick recommendations:**
+**Available models by task:**

-| Task | Recommended Model | Alternative |
-|------|-------------------|-------------|
-| Detection (balanced) | `RetinaFace` (MNET_V2) | `YOLOv5Face` (YOLOV5S) |
-| Detection (speed) | `RetinaFace` (MNET_025) | `SCRFD` (SCRFD_500M) |
-| Detection (accuracy) | `SCRFD` (SCRFD_10G) | `RetinaFace` (RESNET34) |
-| Recognition | `ArcFace` (MNET) | `MobileFace` (MNET_V2) |
-| Gaze | `MobileGaze` (RESNET34) | `MobileGaze` (MOBILEONE_S0) |
-| Parsing | `BiSeNet` (RESNET18) | `BiSeNet` (RESNET34) |
+| Task | Available Models |
+|------|------------------|
+| Detection | `RetinaFace`, `SCRFD`, `YOLOv5Face`, `YOLOv8Face` |
+| Recognition | `ArcFace`, `AdaFace`, `MobileFace`, `SphereFace` |
+| Gaze | `MobileGaze` (ResNet18/34/50, MobileNetV2, MobileOneS0) |
+| Parsing | `BiSeNet` (ResNet18/34) |
+| Attributes | `AgeGender`, `FairFace`, `Emotion` |
+| Anti-Spoofing | `MiniFASNet` (V1SE, V2) |

 ---

--- a/docs/recipes/custom-models.md
+++ b/docs/recipes/custom-models.md
@@ -27,29 +27,29 @@ import numpy as np

 class MyDetector(BaseDetector):
    def __init__(self, model_path: str, confidence_threshold: float = 0.5):
+        super().__init__(confidence_threshold=confidence_threshold)
        self.session = create_onnx_session(model_path)
        self.threshold = confidence_threshold

+    def preprocess(self, image: np.ndarray) -> np.ndarray:
+        # Your preprocessing logic
+        # e.g., resize, normalize, transpose
+        raise NotImplementedError
+
+    def postprocess(self, outputs, shape) -> list[Face]:
+        # Your postprocessing logic
+        # e.g., decode boxes, apply NMS, create Face objects
+        raise NotImplementedError
+
    def detect(self, image: np.ndarray) -> list[Face]:
        # 1. Preprocess image
-        input_tensor = self._preprocess(image)
+        input_tensor = self.preprocess(image)

        # 2. Run inference
        outputs = self.session.run(None, {'input': input_tensor})

        # 3. Postprocess outputs to Face objects
-        faces = self._postprocess(outputs, image.shape)
-        return faces
-
-    def _preprocess(self, image):
-        # Your preprocessing logic
-        # e.g., resize, normalize, transpose
-        pass
-
-    def _postprocess(self, outputs, shape):
-        # Your postprocessing logic
-        # e.g., decode boxes, apply NMS, create Face objects
-        pass
+        return self.postprocess(outputs, image.shape)
 ```

 ---
@@ -57,36 +57,14 @@ class MyDetector(BaseDetector):
 ## Add Custom Recognition Model

 ```python
-from uniface.recognition.base import BaseRecognizer
-from uniface.onnx_utils import create_onnx_session
-from uniface import face_alignment
-import numpy as np
+from uniface.recognition.base import BaseRecognizer, PreprocessConfig

 class MyRecognizer(BaseRecognizer):
-    def __init__(self, model_path: str):
-        self.session = create_onnx_session(model_path)
+    def __init__(self, model_path: str, providers=None):
+        preprocessing = PreprocessConfig(input_mean=127.5, input_std=127.5, input_size=(112, 112))
+        super().__init__(model_path, preprocessing, providers=providers)

-    def get_normalized_embedding(
-        self,
-        image: np.ndarray,
-        landmarks: np.ndarray
-    ) -> np.ndarray:
-        # 1. Align face
-        aligned = face_alignment(image, landmarks)
-
-        # 2. Preprocess
-        input_tensor = self._preprocess(aligned)
-
-        # 3. Run inference
-        embedding = self.session.run(None, {'input': input_tensor})[0]
-
-        # 4. Normalize
-        embedding = embedding / np.linalg.norm(embedding)
-        return embedding
-
-    def _preprocess(self, image):
-        # Your preprocessing logic
-        pass
+    # Optional: override preprocess() if your model expects custom normalization.
 ```

 ---
--- a/docs/recipes/image-pipeline.md
+++ b/docs/recipes/image-pipeline.md
@@ -67,14 +67,18 @@ cv2.imwrite("result.jpg", result_image)
 For convenience, use the built-in `FaceAnalyzer`:

 ```python
-from uniface import FaceAnalyzer
+from uniface import FaceAnalyzer, RetinaFace, ArcFace, AgeGender
 import cv2

 # Initialize with desired modules
+detector = RetinaFace()
+recognizer = ArcFace()
+age_gender = AgeGender()
+
 analyzer = FaceAnalyzer(
-    detect=True,
-    recognize=True,
-    attributes=True
+    detector,
+    recognizer=recognizer,
+    age_gender=age_gender,
 )

 # Process image
--- a/examples/09_face_segmentation.ipynb
+++ b/examples/09_face_segmentation.ipynb
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -77,7 +77,7 @@ extra:
      link: https://x.com/y_valikhujaev
  analytics:
    provider: google
-    property: G-XXXXXXXXXX
+    property: G-FGEHR2K5ZE

 extra_css:
  - stylesheets/extra.css
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "uniface"
-version = "2.0.2"
+version = "2.3.0"
 description = "UniFace: A Comprehensive Library for Face Detection, Recognition, 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.11,<3.14"
+requires-python = ">=3.10,<3.14"
 keywords = [
    "face-detection",
    "face-recognition",
@@ -33,6 +33,7 @@ classifiers = [
    "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",
@@ -71,7 +72,7 @@ uniface = ["py.typed"]

 [tool.ruff]
 line-length = 120
-target-version = "py311"
+target-version = "py310"
 exclude = [
    ".git",
    ".ruff_cache",
@@ -127,15 +128,6 @@ section-order = [
 [tool.ruff.lint.pydocstyle]
 convention = "google"

-[tool.mypy]
-python_version = "3.11"
-warn_return_any = false
-warn_unused_ignores = true
-ignore_missing_imports = true
-exclude = ["tests/", "scripts/", "examples/"]
-# Disable strict return type checking for numpy operations
-disable_error_code = ["no-any-return"]
-
 [tool.bandit]
 exclude_dirs = ["tests", "scripts", "examples"]
 skips = ["B101", "B614"]  # B101: assert, B614: torch.jit.load (models are SHA256 verified)
--- a/tests/test_age_gender.py
+++ b/tests/test_age_gender.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tests/test_factory.py
+++ b/tests/test_factory.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tests/test_landmark.py
+++ b/tests/test_landmark.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tests/test_parsing.py
+++ b/tests/test_parsing.py
@@ -1,16 +1,16 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

-"""Tests for BiSeNet face parsing model."""
+"""Tests for face parsing models (BiSeNet and XSeg)."""

 from __future__ import annotations

 import numpy as np
 import pytest

-from uniface.constants import ParsingWeights
-from uniface.parsing import BiSeNet, create_face_parser
+from uniface.constants import ParsingWeights, XSegWeights
+from uniface.parsing import BiSeNet, XSeg, create_face_parser


 def test_bisenet_initialization():
@@ -120,3 +120,151 @@ def test_bisenet_different_input_sizes():

        assert mask.shape == (h, w), f'Failed for size {h}x{w}'
        assert mask.dtype == np.uint8
+
+
+# XSeg Tests
+
+
+def test_xseg_initialization():
+    """Test XSeg initialization."""
+    parser = XSeg()
+    assert parser is not None
+    assert parser.input_size == (256, 256)
+    assert parser.align_size == 256
+    assert parser.blur_sigma == 0
+
+
+def test_xseg_with_custom_params():
+    """Test XSeg with custom parameters."""
+    parser = XSeg(align_size=512, blur_sigma=5)
+    assert parser.align_size == 512
+    assert parser.blur_sigma == 5
+
+
+def test_xseg_preprocess():
+    """Test XSeg preprocessing."""
+    parser = XSeg()
+
+    # Create a dummy aligned face crop
+    face_crop = np.random.randint(0, 255, (256, 256, 3), dtype=np.uint8)
+
+    # Preprocess
+    preprocessed = parser.preprocess(face_crop)
+
+    assert preprocessed.shape == (1, 256, 256, 3)  # NHWC format
+    assert preprocessed.dtype == np.float32
+    assert preprocessed.min() >= 0
+    assert preprocessed.max() <= 1
+
+
+def test_xseg_postprocess():
+    """Test XSeg postprocessing."""
+    parser = XSeg()
+
+    # Create dummy model output (NHWC format)
+    dummy_output = np.random.rand(1, 256, 256, 1).astype(np.float32)
+
+    # Postprocess
+    mask = parser.postprocess(dummy_output, crop_size=(256, 256))
+
+    assert mask.shape == (256, 256)
+    assert mask.dtype == np.float32
+    assert mask.min() >= 0
+    assert mask.max() <= 1
+
+
+def test_xseg_parse_aligned():
+    """Test XSeg parse_aligned method."""
+    parser = XSeg()
+
+    # Create a dummy aligned face crop
+    face_crop = np.random.randint(0, 255, (256, 256, 3), dtype=np.uint8)
+
+    # Parse
+    mask = parser.parse_aligned(face_crop)
+
+    assert mask.shape == (256, 256)
+    assert mask.dtype == np.float32
+    assert mask.min() >= 0
+    assert mask.max() <= 1
+
+
+def test_xseg_parse_with_landmarks():
+    """Test XSeg parse method with landmarks."""
+    parser = XSeg()
+
+    # Create a dummy image
+    image = np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8)
+
+    # Create dummy 5-point landmarks
+    landmarks = np.array(
+        [
+            [250, 200],  # left eye
+            [390, 200],  # right eye
+            [320, 280],  # nose
+            [260, 350],  # left mouth
+            [380, 350],  # right mouth
+        ],
+        dtype=np.float32,
+    )
+
+    # Parse
+    mask = parser.parse(image, landmarks)
+
+    assert mask.shape == (480, 640)
+    assert mask.dtype == np.float32
+    assert mask.min() >= 0
+    assert mask.max() <= 1
+
+
+def test_xseg_parse_invalid_landmarks():
+    """Test XSeg parse with invalid landmarks shape."""
+    parser = XSeg()
+    image = np.random.randint(0, 255, (256, 256, 3), dtype=np.uint8)
+
+    # Wrong shape
+    invalid_landmarks = np.array([[0, 0], [1, 1], [2, 2]])
+
+    with pytest.raises(ValueError, match='Landmarks must have shape'):
+        parser.parse(image, invalid_landmarks)
+
+
+def test_xseg_parse_with_inverse():
+    """Test XSeg parse_with_inverse method."""
+    parser = XSeg()
+
+    # Create a dummy image
+    image = np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8)
+
+    # Create dummy 5-point landmarks
+    landmarks = np.array(
+        [
+            [250, 200],
+            [390, 200],
+            [320, 280],
+            [260, 350],
+            [380, 350],
+        ],
+        dtype=np.float32,
+    )
+
+    # Parse with inverse
+    mask, face_crop, inverse_matrix = parser.parse_with_inverse(image, landmarks)
+
+    assert mask.shape == (256, 256)
+    assert face_crop.shape == (256, 256, 3)
+    assert inverse_matrix.shape == (2, 3)
+
+
+def test_create_face_parser_xseg_enum():
+    """Test factory function with XSeg enum."""
+    parser = create_face_parser(XSegWeights.DEFAULT)
+    assert parser is not None
+    assert isinstance(parser, XSeg)
+
+
+def test_create_face_parser_xseg_string():
+    """Test factory function with XSeg string."""
+    parser = create_face_parser('xseg')
+    assert parser is not None
+    assert isinstance(parser, XSeg)
--- a/tests/test_recognition.py
+++ b/tests/test_recognition.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tests/test_retinaface.py
+++ b/tests/test_retinaface.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tests/test_scrfd.py
+++ b/tests/test_scrfd.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tests/test_types.py
+++ b/tests/test_types.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tests/test_utils.py
+++ b/tests/test_utils.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tools/README.md
+++ b/tools/README.md
@@ -17,7 +17,8 @@ CLI utilities for testing and running UniFace features.
 | `face_search.py` | Real-time face matching against reference |
 | `fairface.py` | FairFace attribute prediction (race, gender, age) |
 | `spoofing.py` | Face anti-spoofing detection |
-| `face_parsing.py` | Face semantic segmentation |
+| `face_parsing.py` | Face semantic segmentation (BiSeNet) |
+| `xseg.py` | Face segmentation (XSeg) |
 | `video_detection.py` | Face detection on video files with progress bar |
 | `batch_process.py` | Batch process folder of images |
 | `download_model.py` | Download model weights |
@@ -63,10 +64,14 @@ python tools/landmarks.py --source 0
 python tools/fairface.py --source assets/test.jpg
 python tools/fairface.py --source 0

-# Face parsing
+# Face parsing (BiSeNet)
 python tools/face_parsing.py --source assets/test.jpg
 python tools/face_parsing.py --source 0

+# Face segmentation (XSeg)
+python tools/xseg.py --source assets/test.jpg
+python tools/xseg.py --source 0
+
 # Face anti-spoofing
 python tools/spoofing.py --source assets/test.jpg
 python tools/spoofing.py --source 0
--- a/tools/age_gender.py
+++ b/tools/age_gender.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tools/batch_process.py
+++ b/tools/batch_process.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tools/detection.py
+++ b/tools/detection.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

@@ -18,7 +18,7 @@ from pathlib import Path

 import cv2

-from uniface.detection import SCRFD, RetinaFace, YOLOv5Face
+from uniface.detection import SCRFD, RetinaFace, YOLOv5Face, YOLOv8Face
 from uniface.visualization import draw_detections

 IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.webp', '.tiff'}
@@ -157,7 +157,9 @@ def run_camera(detector, camera_id: int = 0, threshold: float = 0.6):
 def main():
    parser = argparse.ArgumentParser(description='Run face detection')
    parser.add_argument('--source', type=str, required=True, help='Image/video path or camera ID (0, 1, ...)')
-    parser.add_argument('--method', type=str, default='retinaface', choices=['retinaface', 'scrfd', 'yolov5face'])
+    parser.add_argument(
+        '--method', type=str, default='retinaface', choices=['retinaface', 'scrfd', 'yolov5face', 'yolov8face']
+    )
    parser.add_argument('--threshold', type=float, default=0.25, help='Visualization threshold')
    parser.add_argument('--save-dir', type=str, default='outputs', help='Output directory')
    args = parser.parse_args()
@@ -167,10 +169,14 @@ def main():
        detector = RetinaFace()
    elif args.method == 'scrfd':
        detector = SCRFD()
-    else:
+    elif args.method == 'yolov5face':
        from uniface.constants import YOLOv5FaceWeights

        detector = YOLOv5Face(model_name=YOLOv5FaceWeights.YOLOV5M)
+    else:  # yolov8face
+        from uniface.constants import YOLOv8FaceWeights
+
+        detector = YOLOv8Face(model_name=YOLOv8FaceWeights.YOLOV8N)

    # Determine source type and process
    source_type = get_source_type(args.source)
--- a/tools/face_analyzer.py
+++ b/tools/face_analyzer.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tools/face_anonymize.py
+++ b/tools/face_anonymize.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tools/face_emotion.py
+++ b/tools/face_emotion.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tools/face_parsing.py
+++ b/tools/face_parsing.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tools/face_search.py
+++ b/tools/face_search.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tools/fairface.py
+++ b/tools/fairface.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tools/gaze_estimation.py
+++ b/tools/gaze_estimation.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tools/landmarks.py
+++ b/tools/landmarks.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tools/recognition.py
+++ b/tools/recognition.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tools/spoofing.py
+++ b/tools/spoofing.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tools/video_detection.py
+++ b/tools/video_detection.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/tools/xseg.py
+++ b/tools/xseg.py
@@ -0,0 +1,250 @@
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""XSeg face segmentation on detected faces.
+
+Usage:
+    python tools/xseg.py --source path/to/image.jpg
+    python tools/xseg.py --source path/to/video.mp4
+    python tools/xseg.py --source 0  # webcam
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+from uniface import RetinaFace, XSeg
+
+IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.webp', '.tiff'}
+VIDEO_EXTENSIONS = {'.mp4', '.avi', '.mov', '.mkv', '.webm', '.flv'}
+
+
+def get_source_type(source: str) -> str:
+    """Determine if source is image, video, or camera."""
+    if source.isdigit():
+        return 'camera'
+    path = Path(source)
+    suffix = path.suffix.lower()
+    if suffix in IMAGE_EXTENSIONS:
+        return 'image'
+    elif suffix in VIDEO_EXTENSIONS:
+        return 'video'
+    else:
+        return 'unknown'
+
+
+def apply_mask_visualization(image: np.ndarray, mask: np.ndarray, alpha: float = 0.5) -> np.ndarray:
+    """Apply colored mask overlay for visualization."""
+    overlay = image.copy().astype(np.float32)
+    mask_3ch = np.stack([mask * 0.3, mask * 0.7, mask * 0.3], axis=-1)
+    overlay = overlay * (1 - mask[..., None] * alpha) + mask_3ch * 255 * alpha
+
+    return overlay.clip(0, 255).astype(np.uint8)
+
+
+def process_image(
+    detector: RetinaFace,
+    parser: XSeg,
+    image_path: str,
+    save_dir: str = 'outputs',
+) -> None:
+    """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)')
+
+    if len(faces) == 0:
+        print('No faces detected.')
+        return
+
+    # Accumulate masks from all faces
+    full_mask = np.zeros((image.shape[0], image.shape[1]), dtype=np.float32)
+    for i, face in enumerate(faces):
+        if face.landmarks is None:
+            print(f'  Face {i + 1}: skipped (no landmarks)')
+            continue
+
+        mask = parser.parse(image, face.landmarks)
+        full_mask = np.maximum(full_mask, mask)
+        print(f'  Face {i + 1}: done')
+
+    # Apply visualization
+    result_image = apply_mask_visualization(image, full_mask)
+
+    # Draw bounding boxes
+    for face in faces:
+        x1, y1, x2, y2 = map(int, face.bbox[:4])
+        cv2.rectangle(result_image, (x1, y1), (x2, y2), (0, 255, 0), 2)
+
+    # Save results
+    os.makedirs(save_dir, exist_ok=True)
+    output_path = os.path.join(save_dir, f'{Path(image_path).stem}_xseg.jpg')
+    cv2.imwrite(output_path, result_image)
+    print(f'Output saved: {output_path}')
+
+    mask_path = os.path.join(save_dir, f'{Path(image_path).stem}_xseg_mask.png')
+    mask_uint8 = (full_mask * 255).astype(np.uint8)
+    cv2.imwrite(mask_path, mask_uint8)
+    print(f'Mask saved: {mask_path}')
+
+
+def process_video(
+    detector: RetinaFace,
+    parser: XSeg,
+    video_path: str,
+    save_dir: str = 'outputs',
+) -> None:
+    """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}_xseg.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)
+
+        # Accumulate masks from all faces
+        full_mask = np.zeros((frame.shape[0], frame.shape[1]), dtype=np.float32)
+        for face in faces:
+            if face.landmarks is None:
+                continue
+            mask = parser.parse(frame, face.landmarks)
+            full_mask = np.maximum(full_mask, mask)
+
+        # Apply visualization
+        result_frame = apply_mask_visualization(frame, full_mask)
+
+        # Draw bounding boxes
+        for face in faces:
+            x1, y1, x2, y2 = map(int, face.bbox[:4])
+            cv2.rectangle(result_frame, (x1, y1), (x2, y2), (0, 255, 0), 2)
+
+        cv2.putText(result_frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+        out.write(result_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: RetinaFace,
+    parser: XSeg,
+    camera_id: int = 0,
+) -> None:
+    """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)
+
+        # Accumulate masks from all faces
+        full_mask = np.zeros((frame.shape[0], frame.shape[1]), dtype=np.float32)
+        for face in faces:
+            if face.landmarks is None:
+                continue
+            mask = parser.parse(frame, face.landmarks)
+            full_mask = np.maximum(full_mask, mask)
+
+        # Apply visualization
+        result_frame = apply_mask_visualization(frame, full_mask)
+
+        # Draw bounding boxes
+        for face in faces:
+            x1, y1, x2, y2 = map(int, face.bbox[:4])
+            cv2.rectangle(result_frame, (x1, y1), (x2, y2), (0, 255, 0), 2)
+
+        cv2.putText(result_frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+        cv2.imshow('XSeg Face Segmentation', result_frame)
+
+        if cv2.waitKey(1) & 0xFF == ord('q'):
+            break
+
+    cap.release()
+    cv2.destroyAllWindows()
+
+
+def main() -> None:
+    arg_parser = argparse.ArgumentParser(description='XSeg face segmentation')
+    arg_parser.add_argument('--source', type=str, required=True, help='Image/video path or camera ID (0, 1, ...)')
+    arg_parser.add_argument('--save-dir', type=str, default='outputs', help='Output directory')
+    arg_parser.add_argument(
+        '--blur',
+        type=float,
+        default=0,
+        help='Gaussian blur sigma for mask smoothing (default: 0 = raw)',
+    )
+    arg_parser.add_argument(
+        '--align-size',
+        type=int,
+        default=256,
+        help='Face alignment size (default: 256)',
+    )
+    args = arg_parser.parse_args()
+
+    # Initialize models
+    detector = RetinaFace()
+    parser = XSeg(blur_sigma=args.blur, align_size=args.align_size)
+
+    source_type = get_source_type(args.source)
+
+    if source_type == 'camera':
+        run_camera(detector, parser, int(args.source))
+    elif source_type == 'image':
+        if not os.path.exists(args.source):
+            print(f'Error: Image not found: {args.source}')
+            return
+        process_image(detector, parser, args.source, args.save_dir)
+    elif source_type == 'video':
+        if not os.path.exists(args.source):
+            print(f'Error: Video not found: {args.source}')
+            return
+        process_video(detector, parser, args.source, args.save_dir)
+    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()
--- a/uniface/init.py
+++ b/uniface/init.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 #
 # Licensed under the MIT License.
 # You may obtain a copy of the License at
@@ -14,8 +14,8 @@
 """UniFace: A comprehensive library for face analysis.

 This library provides unified APIs for:
- Face detection (RetinaFace, SCRFD, YOLOv5Face)
- Face recognition (ArcFace, MobileFace, SphereFace)
+- Face detection (RetinaFace, SCRFD, YOLOv5Face, YOLOv8Face)
+- Face recognition (AdaFace, ArcFace, MobileFace, SphereFace)
 - Facial landmarks (106-point detection)
 - Face parsing (semantic segmentation)
 - Gaze estimation
@@ -28,7 +28,7 @@ from __future__ import annotations

 __license__ = 'MIT'
 __author__ = 'Yakhyokhuja Valikhujaev'
-__version__ = '2.0.2'
+__version__ = '2.3.0'

 from uniface.face_utils import compute_similarity, face_alignment
 from uniface.log import Logger, enable_logging
@@ -41,15 +41,16 @@ from .detection import (
    SCRFD,
    RetinaFace,
    YOLOv5Face,
+    YOLOv8Face,
    create_detector,
    detect_faces,
    list_available_detectors,
 )
 from .gaze import MobileGaze, create_gaze_estimator
 from .landmark import Landmark106, create_landmarker
-from .parsing import BiSeNet, create_face_parser
+from .parsing import BiSeNet, XSeg, create_face_parser
 from .privacy import BlurFace, anonymize_faces
-from .recognition import ArcFace, MobileFace, SphereFace, create_recognizer
+from .recognition import AdaFace, ArcFace, MobileFace, SphereFace, create_recognizer
 from .spoofing import MiniFASNet, create_spoofer
 from .types import AttributeResult, EmotionResult, Face, GazeResult, SpoofingResult

@@ -81,7 +82,9 @@ __all__ = [
    'RetinaFace',
    'SCRFD',
    'YOLOv5Face',
+    'YOLOv8Face',
    # Recognition models
+    'AdaFace',
    'ArcFace',
    'MobileFace',
    'SphereFace',
@@ -92,6 +95,7 @@ __all__ = [
    'MobileGaze',
    # Parsing models
    'BiSeNet',
+    'XSeg',
    # Attribute models
    'AgeGender',
    'AttributeResult',
--- a/uniface/analyzer.py
+++ b/uniface/analyzer.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/attribute/init.py
+++ b/uniface/attribute/init.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/attribute/age_gender.py
+++ b/uniface/attribute/age_gender.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

@@ -30,12 +30,15 @@ class AgeGender(Attribute):
            Defaults to `AgeGenderWeights.DEFAULT`.
        input_size (Optional[Tuple[int, int]]): Input size (height, width).
            If None, automatically detected from model metadata. Defaults to None.
+        providers (list[str] | None): ONNX Runtime execution providers. If None, auto-detects
+            the best available provider. Example: ['CPUExecutionProvider'] to force CPU.
    """

    def __init__(
        self,
        model_name: AgeGenderWeights = AgeGenderWeights.DEFAULT,
        input_size: tuple[int, int] | None = None,
+        providers: list[str] | None = None,
    ) -> None:
        """
        Initializes the AgeGender prediction model.
@@ -44,10 +47,13 @@ class AgeGender(Attribute):
            model_name (AgeGenderWeights): The enum specifying the model weights to load.
            input_size (Optional[Tuple[int, int]]): Input size (height, width).
                If None, automatically detected from model metadata. Defaults to None.
+            providers (list[str] | None): ONNX Runtime execution providers. If None, auto-detects
+                the best available provider. Example: ['CPUExecutionProvider'] to force CPU.
        """
        Logger.info(f'Initializing AgeGender with model={model_name.name}')
        self.model_path = verify_model_weights(model_name)
        self._user_input_size = input_size  # Store user preference
+        self.providers = providers
        self._initialize_model()

    def _initialize_model(self) -> None:
@@ -55,7 +61,7 @@ class AgeGender(Attribute):
        Initializes the ONNX model and creates an inference session.
        """
        try:
-            self.session = create_onnx_session(self.model_path)
+            self.session = create_onnx_session(self.model_path, providers=self.providers)
            # Get model input details from the loaded model
            input_meta = self.session.get_inputs()[0]
            self.input_name = input_meta.name
--- a/uniface/attribute/base.py
+++ b/uniface/attribute/base.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/attribute/emotion.py
+++ b/uniface/attribute/emotion.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/attribute/fairface.py
+++ b/uniface/attribute/fairface.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

@@ -44,12 +44,15 @@ class FairFace(Attribute):
            Defaults to `FairFaceWeights.DEFAULT`.
        input_size (Optional[Tuple[int, int]]): Input size (height, width).
            If None, defaults to (224, 224). Defaults to None.
+        providers (list[str] | None): ONNX Runtime execution providers. If None, auto-detects
+            the best available provider. Example: ['CPUExecutionProvider'] to force CPU.
    """

    def __init__(
        self,
        model_name: FairFaceWeights = FairFaceWeights.DEFAULT,
        input_size: tuple[int, int] | None = None,
+        providers: list[str] | None = None,
    ) -> None:
        """
        Initializes the FairFace prediction model.
@@ -58,10 +61,13 @@ class FairFace(Attribute):
            model_name (FairFaceWeights): The enum specifying the model weights to load.
            input_size (Optional[Tuple[int, int]]): Input size (height, width).
                If None, 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.
        """
        Logger.info(f'Initializing FairFace with model={model_name.name}')
        self.model_path = verify_model_weights(model_name)
        self.input_size = input_size if input_size is not None else (224, 224)
+        self.providers = providers
        self._initialize_model()

    def _initialize_model(self) -> None:
@@ -69,7 +75,7 @@ class FairFace(Attribute):
        Initializes the ONNX model and creates an inference session.
        """
        try:
-            self.session = create_onnx_session(self.model_path)
+            self.session = create_onnx_session(self.model_path, providers=self.providers)
            # Get model input details from the loaded model
            input_meta = self.session.get_inputs()[0]
            self.input_name = input_meta.name
--- a/uniface/common.py
+++ b/uniface/common.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/constants.py
+++ b/uniface/constants.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

@@ -32,6 +32,15 @@ class ArcFaceWeights(str, Enum):
    MNET   = "arcface_mnet"
    RESNET = "arcface_resnet"

+
+class AdaFaceWeights(str, Enum):
+    """
+    AdaFace model weights trained on WebFace datasets.
+    https://github.com/yakhyo/adaface-onnx
+    """
+    IR_18  = "adaface_ir_18"
+    IR_101 = "adaface_ir_101"
+
 class RetinaFaceWeights(str, Enum):
    """
    Trained on WIDER FACE dataset.
@@ -70,6 +79,20 @@ class YOLOv5FaceWeights(str, Enum):
    YOLOV5M = "yolov5m"


+class YOLOv8FaceWeights(str, Enum):
+    """
+    YOLOv8-Face models trained on WIDER FACE dataset.
+    Uses anchor-free design with DFL (Distribution Focal Loss) for bbox regression.
+    Exported to ONNX from: https://github.com/yakhyo/yolov8-face-onnx-inference
+
+    Model Performance (WIDER FACE):
+    - YOLOV8_LITE_S: 7.4MB, 93.4% Easy / 91.2% Medium / 78.6% Hard (lightweight)
+    - YOLOV8N: 12MB, 94.6% Easy / 92.3% Medium / 79.6% Hard (recommended)
+    """
+    YOLOV8_LITE_S = "yolov8_lite_s"
+    YOLOV8N       = "yolov8n_face"
+
+
 class DDAMFNWeights(str, Enum):
    """
    Trained on AffectNet dataset.
@@ -127,6 +150,15 @@ class ParsingWeights(str, Enum):
    RESNET34 = "parsing_resnet34"


+class XSegWeights(str, Enum):
+    """
+    XSeg face segmentation model from DeepFaceLab.
+    Outputs mask for face region.
+    https://github.com/iperov/DeepFaceLab
+    """
+    DEFAULT = "xseg"
+
+
 class MiniFASNetWeights(str, Enum):
    """
    MiniFASNet: Lightweight Face Anti-Spoofing models.
@@ -160,6 +192,9 @@ MODEL_URLS: dict[Enum, str] = {
    # 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',
+    # 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',
    # 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',
@@ -167,6 +202,9 @@ MODEL_URLS: dict[Enum, str] = {
    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',
+    # 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',
    # 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',
@@ -188,6 +226,8 @@ MODEL_URLS: dict[Enum, str] = {
    # 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',
+    # XSeg
+    XSegWeights.DEFAULT:             'https://github.com/yakhyo/face-segmentation/releases/download/weights/xseg.onnx',
 }

 MODEL_SHA256: dict[Enum, str] = {
@@ -209,6 +249,9 @@ MODEL_SHA256: dict[Enum, str] = {
    # 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',
@@ -216,6 +259,9 @@ MODEL_SHA256: dict[Enum, str] = {
    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',
@@ -237,6 +283,8 @@ MODEL_SHA256: dict[Enum, str] = {
    # Anti-Spoofing (MiniFASNet)
    MiniFASNetWeights.V1SE:          'ebab7f90c7833fbccd46d3a555410e78d969db5438e169b6524be444862b3676',
    MiniFASNetWeights.V2:            'b32929adc2d9c34b9486f8c4c7bc97c1b69bc0ea9befefc380e4faae4e463907',
+    # XSeg
+    XSegWeights.DEFAULT:             '0b57328efcb839d85973164b617ceee9dfe6cfcb2c82e8a033bba9f4f09b27e5',
 }

 CHUNK_SIZE = 8192
--- a/uniface/detection/init.py
+++ b/uniface/detection/init.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

@@ -14,6 +14,7 @@ from .base import BaseDetector
 from .retinaface import RetinaFace
 from .scrfd import SCRFD
 from .yolov5 import YOLOv5Face
+from .yolov8 import YOLOv8Face

 # Global cache for detector instances (keyed by method name + config hash)
 _detector_cache: dict[str, BaseDetector] = {}
@@ -27,7 +28,7 @@ def detect_faces(image: np.ndarray, method: str = 'retinaface', **kwargs: Any) -

    Args:
        image: Input image as numpy array with shape (H, W, C) in BGR format.
-        method: Detection method to use. Options: 'retinaface', 'scrfd', 'yolov5face'.
+        method: Detection method to use. Options: 'retinaface', 'scrfd', 'yolov5face', 'yolov8face'.
        **kwargs: Additional arguments passed to the detector.

    Returns:
@@ -66,6 +67,7 @@ def create_detector(method: str = 'retinaface', **kwargs: Any) -> BaseDetector:
            - 'retinaface': RetinaFace detector (default)
            - 'scrfd': SCRFD detector (fast and accurate)
            - 'yolov5face': YOLOv5-Face detector (accurate with landmarks)
+            - 'yolov8face': YOLOv8-Face detector (anchor-free, accurate)
        **kwargs: Detector-specific parameters.

    Returns:
@@ -84,11 +86,9 @@ def create_detector(method: str = 'retinaface', **kwargs: Any) -> BaseDetector:
        ...     'scrfd', model_name=SCRFDWeights.SCRFD_10G_KPS, confidence_threshold=0.8, input_size=(640, 640)
        ... )

-        >>> # RetinaFace detector
-        >>> from uniface.constants import RetinaFaceWeights
-        >>> detector = create_detector(
-        ...     'retinaface', model_name=RetinaFaceWeights.MNET_V2, confidence_threshold=0.8, nms_threshold=0.4
-        ... )
+        >>> # YOLOv8-Face detector
+        >>> from uniface.constants import YOLOv8FaceWeights
+        >>> detector = create_detector('yolov8face', model_name=YOLOv8FaceWeights.YOLOV8N, confidence_threshold=0.5)
    """
    method = method.lower()

@@ -101,8 +101,11 @@ def create_detector(method: str = 'retinaface', **kwargs: Any) -> BaseDetector:
    elif method == 'yolov5face':
        return YOLOv5Face(**kwargs)

+    elif method == 'yolov8face':
+        return YOLOv8Face(**kwargs)
+
    else:
-        available_methods = ['retinaface', 'scrfd', 'yolov5face']
+        available_methods = ['retinaface', 'scrfd', 'yolov5face', 'yolov8face']
        raise ValueError(f"Unsupported detection method: '{method}'. Available methods: {available_methods}")


@@ -147,6 +150,17 @@ def list_available_detectors() -> dict[str, dict[str, Any]]:
                'input_size': 640,
            },
        },
+        'yolov8face': {
+            'description': 'YOLOv8-Face detector - anchor-free design with DFL for accurate detection',
+            'supports_landmarks': True,
+            'paper': 'https://github.com/derronqi/yolov8-face',
+            'default_params': {
+                'model_name': 'yolov8n_face',
+                'confidence_threshold': 0.5,
+                'nms_threshold': 0.45,
+                'input_size': 640,
+            },
+        },
    }


@@ -155,6 +169,7 @@ __all__ = [
    'BaseDetector',
    'RetinaFace',
    'YOLOv5Face',
+    'YOLOv8Face',
    'create_detector',
    'detect_faces',
    'list_available_detectors',
--- a/uniface/detection/base.py
+++ b/uniface/detection/base.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/detection/retinaface.py
+++ b/uniface/detection/retinaface.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

@@ -39,6 +39,8 @@ class RetinaFace(BaseDetector):
        input_size (Tuple[int, int]): Fixed input size (width, height) if `dynamic_size=False`.
            Defaults to (640, 640).
            Note: Non-default sizes may cause slower inference and CoreML compatibility issues.
+        providers (list[str] | None): ONNX Runtime execution providers. If None, auto-detects
+            the best available provider. Example: ['CPUExecutionProvider'] to force CPU.
        **kwargs: Advanced options:
            pre_nms_topk (int): Number of top-scoring boxes considered before NMS. Defaults to 5000.
            post_nms_topk (int): Max number of detections kept after NMS. Defaults to 750.
@@ -68,6 +70,7 @@ class RetinaFace(BaseDetector):
        confidence_threshold: float = 0.5,
        nms_threshold: float = 0.4,
        input_size: tuple[int, int] = (640, 640),
+        providers: list[str] | None = None,
        **kwargs: Any,
    ) -> None:
        super().__init__(
@@ -75,6 +78,7 @@ class RetinaFace(BaseDetector):
            confidence_threshold=confidence_threshold,
            nms_threshold=nms_threshold,
            input_size=input_size,
+            providers=providers,
            **kwargs,
        )
        self._supports_landmarks = True  # RetinaFace supports landmarks
@@ -83,6 +87,7 @@ class RetinaFace(BaseDetector):
        self.confidence_threshold = confidence_threshold
        self.nms_threshold = nms_threshold
        self.input_size = input_size
+        self.providers = providers

        # Advanced options from kwargs
        self.pre_nms_topk = kwargs.get('pre_nms_topk', 5000)
@@ -116,7 +121,7 @@ class RetinaFace(BaseDetector):
            RuntimeError: If the model fails to load.
        """
        try:
-            self.session = create_onnx_session(model_path)
+            self.session = create_onnx_session(model_path, providers=self.providers)
            self.input_names = self.session.get_inputs()[0].name
            self.output_names = [x.name for x in self.session.get_outputs()]
            Logger.info(f'Successfully initialized the model from {model_path}')
--- a/uniface/detection/scrfd.py
+++ b/uniface/detection/scrfd.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

@@ -36,6 +36,8 @@ class SCRFD(BaseDetector):
        input_size (Tuple[int, int]): Input image size (width, height).
            Defaults to (640, 640).
            Note: Non-default sizes may cause slower inference and CoreML compatibility issues.
+        providers (list[str] | None): ONNX Runtime execution providers. If None, auto-detects
+            the best available provider. Example: ['CPUExecutionProvider'] to force CPU.
        **kwargs: Reserved for future advanced options.

    Attributes:
@@ -61,6 +63,7 @@ class SCRFD(BaseDetector):
        confidence_threshold: float = 0.5,
        nms_threshold: float = 0.4,
        input_size: tuple[int, int] = (640, 640),
+        providers: list[str] | None = None,
        **kwargs: Any,
    ) -> None:
        super().__init__(
@@ -68,6 +71,7 @@ class SCRFD(BaseDetector):
            confidence_threshold=confidence_threshold,
            nms_threshold=nms_threshold,
            input_size=input_size,
+            providers=providers,
            **kwargs,
        )
        self._supports_landmarks = True  # SCRFD supports landmarks
@@ -76,6 +80,7 @@ class SCRFD(BaseDetector):
        self.confidence_threshold = confidence_threshold
        self.nms_threshold = nms_threshold
        self.input_size = input_size
+        self.providers = providers

        # ------- SCRFD model params ------
        self._num_feature_maps = 3
@@ -106,7 +111,7 @@ class SCRFD(BaseDetector):
            RuntimeError: If the model fails to load.
        """
        try:
-            self.session = create_onnx_session(model_path)
+            self.session = create_onnx_session(model_path, providers=self.providers)
            self.input_names = self.session.get_inputs()[0].name
            self.output_names = [x.name for x in self.session.get_outputs()]
            Logger.info(f'Successfully initialized the model from {model_path}')
--- a/uniface/detection/yolov5.py
+++ b/uniface/detection/yolov5.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

@@ -16,6 +16,15 @@ from uniface.types import Face

 from .base import BaseDetector

+# Optional torchvision import for faster NMS
+try:
+    import torch
+    import torchvision
+
+    TORCHVISION_AVAILABLE = True
+except ImportError:
+    TORCHVISION_AVAILABLE = False
+
 __all__ = ['YOLOv5Face']


@@ -34,6 +43,10 @@ class YOLOv5Face(BaseDetector):
        nms_threshold (float): Non-Maximum Suppression threshold. Defaults to 0.5.
        input_size (int): Input image size. Defaults to 640.
            Note: ONNX model is fixed at 640. Changing this will cause inference errors.
+        nms_mode (str): NMS calculation method. Options: 'torchvision' (faster, requires torch)
+            or 'numpy' (no dependencies). Defaults to 'numpy'.
+        providers (list[str] | None): ONNX Runtime execution providers. If None, auto-detects
+            the best available provider. Example: ['CPUExecutionProvider'] to force CPU.
        **kwargs: Advanced options:
            max_det (int): Maximum number of detections to return. Defaults to 750.

@@ -42,6 +55,7 @@ class YOLOv5Face(BaseDetector):
        confidence_threshold (float): Threshold used to filter low-confidence detections.
        nms_threshold (float): Threshold used during NMS to suppress overlapping boxes.
        input_size (int): Image size to which inputs are resized before inference.
+        nms_mode (str): NMS calculation method being used.
        max_det (int): Maximum number of detections to return.
        _model_path (str): Absolute path to the downloaded/verified model weights.

@@ -57,6 +71,8 @@ class YOLOv5Face(BaseDetector):
        confidence_threshold: float = 0.6,
        nms_threshold: float = 0.5,
        input_size: int = 640,
+        nms_mode: Literal['torchvision', 'numpy'] = 'numpy',
+        providers: list[str] | None = None,
        **kwargs: Any,
    ) -> None:
        super().__init__(
@@ -64,6 +80,8 @@ class YOLOv5Face(BaseDetector):
            confidence_threshold=confidence_threshold,
            nms_threshold=nms_threshold,
            input_size=input_size,
+            nms_mode=nms_mode,
+            providers=providers,
            **kwargs,
        )
        self._supports_landmarks = True  # YOLOv5-Face supports landmarks
@@ -78,13 +96,21 @@ class YOLOv5Face(BaseDetector):
        self.confidence_threshold = confidence_threshold
        self.nms_threshold = nms_threshold
        self.input_size = input_size
+        self.providers = providers
+
+        # Set NMS mode with automatic fallback
+        if nms_mode == 'torchvision' and not TORCHVISION_AVAILABLE:
+            Logger.warning('torchvision not available, falling back to numpy NMS')
+            self.nms_mode = 'numpy'
+        else:
+            self.nms_mode = nms_mode

        # Advanced options from kwargs
        self.max_det = kwargs.get('max_det', 750)

        Logger.info(
            f'Initializing YOLOv5Face with model={self.model_name}, confidence_threshold={self.confidence_threshold}, '
-            f'nms_threshold={self.nms_threshold}, input_size={self.input_size}'
+            f'nms_threshold={self.nms_threshold}, input_size={self.input_size}, nms_mode={self.nms_mode}'
        )

        # Get path to model weights
@@ -105,7 +131,7 @@ class YOLOv5Face(BaseDetector):
            RuntimeError: If the model fails to load, logs an error and raises an exception.
        """
        try:
-            self.session = create_onnx_session(model_path)
+            self.session = create_onnx_session(model_path, providers=self.providers)
            self.input_names = self.session.get_inputs()[0].name
            self.output_names = [x.name for x in self.session.get_outputs()]
            Logger.info(f'Successfully initialized the model from {model_path}')
@@ -205,9 +231,16 @@ class YOLOv5Face(BaseDetector):
        # Get landmarks (5 points, 10 coordinates)
        landmarks = predictions[:, 5:15].copy()

-        # Apply NMS
-        detections_for_nms = np.hstack((boxes, scores[:, None])).astype(np.float32, copy=False)
-        keep = non_max_suppression(detections_for_nms, self.nms_threshold)
+        # Apply NMS based on selected mode
+        if self.nms_mode == 'torchvision':
+            keep = torchvision.ops.nms(
+                torch.tensor(boxes, dtype=torch.float32),
+                torch.tensor(scores, dtype=torch.float32),
+                self.nms_threshold,
+            ).numpy()
+        else:
+            detections = np.hstack((boxes, scores[:, None])).astype(np.float32, copy=False)
+            keep = non_max_suppression(detections, self.nms_threshold)

        if len(keep) == 0:
            return np.array([]), np.array([])
--- a/uniface/detection/yolov8.py
+++ b/uniface/detection/yolov8.py
@@ -0,0 +1,424 @@
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""
+YOLOv8-Face detector implementation.
+
+Uses anchor-free design with DFL (Distribution Focal Loss) for bbox regression.
+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.constants import YOLOv8FaceWeights
+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 Face
+
+from .base import BaseDetector
+
+# Optional torchvision import for faster NMS
+try:
+    import torch
+    import torchvision
+
+    TORCHVISION_AVAILABLE = True
+except ImportError:
+    TORCHVISION_AVAILABLE = False
+
+__all__ = ['YOLOv8Face']
+
+
+class YOLOv8Face(BaseDetector):
+    """
+    Face detector based on the YOLOv8-Face architecture.
+
+    Uses anchor-free design with DFL (Distribution Focal Loss) for bbox regression.
+    Outputs 3 feature maps at different scales for multi-scale detection.
+
+    Reference: https://github.com/yakhyo/yolov8-face-onnx-inference
+
+    Args:
+        model_name (YOLOv8FaceWeights): Predefined model enum (e.g., `YOLOV8N`).
+            Specifies the YOLOv8-Face variant to load. Defaults to YOLOV8N.
+        confidence_threshold (float): Confidence threshold for filtering detections. Defaults to 0.5.
+        nms_threshold (float): Non-Maximum Suppression threshold. Defaults to 0.45.
+        input_size (int): Input image size. Defaults to 640.
+            Note: ONNX model is fixed at 640. Changing this will cause inference errors.
+        nms_mode (str): NMS calculation method. Options: 'torchvision' (faster, requires torch)
+            or 'numpy' (no dependencies). Defaults to 'numpy'.
+        providers (list[str] | None): ONNX Runtime execution providers. If None, auto-detects
+            the best available provider. Example: ['CPUExecutionProvider'] to force CPU.
+        **kwargs: Advanced options:
+            max_det (int): Maximum number of detections to return. Defaults to 750.
+
+    Attributes:
+        model_name (YOLOv8FaceWeights): Selected model variant.
+        confidence_threshold (float): Threshold used to filter low-confidence detections.
+        nms_threshold (float): Threshold used during NMS to suppress overlapping boxes.
+        input_size (int): Image size to which inputs are resized before inference.
+        nms_mode (str): NMS calculation method being used.
+        max_det (int): Maximum number of detections to return.
+        _model_path (str): Absolute path to the downloaded/verified model weights.
+
+    Raises:
+        ValueError: If the model weights are invalid or not found.
+        RuntimeError: If the ONNX model fails to load or initialize.
+    """
+
+    def __init__(
+        self,
+        *,
+        model_name: YOLOv8FaceWeights = YOLOv8FaceWeights.YOLOV8N,
+        confidence_threshold: float = 0.5,
+        nms_threshold: float = 0.45,
+        input_size: int = 640,
+        nms_mode: Literal['torchvision', 'numpy'] = 'numpy',
+        providers: list[str] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            model_name=model_name,
+            confidence_threshold=confidence_threshold,
+            nms_threshold=nms_threshold,
+            input_size=input_size,
+            nms_mode=nms_mode,
+            providers=providers,
+            **kwargs,
+        )
+        self._supports_landmarks = True  # YOLOv8-Face supports landmarks
+
+        # Validate input size
+        if input_size != 640:
+            raise ValueError(
+                f'YOLOv8Face only supports input_size=640 (got {input_size}). The ONNX model has a fixed input shape.'
+            )
+
+        self.model_name = model_name
+        self.confidence_threshold = confidence_threshold
+        self.nms_threshold = nms_threshold
+        self.input_size = input_size
+        self.providers = providers
+
+        # Set NMS mode with automatic fallback
+        if nms_mode == 'torchvision' and not TORCHVISION_AVAILABLE:
+            Logger.warning('torchvision not available, falling back to numpy NMS')
+            self.nms_mode = 'numpy'
+        else:
+            self.nms_mode = nms_mode
+
+        # Advanced options from kwargs
+        self.max_det = kwargs.get('max_det', 750)
+
+        # YOLOv8 strides for 640x640 input (3 feature maps: 80x80, 40x40, 20x20)
+        self.strides = [8, 16, 32]
+
+        Logger.info(
+            f'Initializing YOLOv8Face with model={self.model_name}, confidence_threshold={self.confidence_threshold}, '
+            f'nms_threshold={self.nms_threshold}, input_size={self.input_size}, nms_mode={self.nms_mode}'
+        )
+
+        # Get path to model weights
+        self._model_path = verify_model_weights(self.model_name)
+        Logger.info(f'Verified model weights located at: {self._model_path}')
+
+        # Initialize model
+        self._initialize_model(self._model_path)
+
+    def _initialize_model(self, model_path: str) -> None:
+        """
+        Initializes an ONNX model session from the given path.
+
+        Args:
+            model_path (str): The file path to the ONNX model.
+
+        Raises:
+            RuntimeError: If the model fails to load, logs an error and raises an exception.
+        """
+        try:
+            self.session = create_onnx_session(model_path, providers=self.providers)
+            self.input_names = self.session.get_inputs()[0].name
+            self.output_names = [x.name for x in self.session.get_outputs()]
+            Logger.info(f'Successfully initialized the model from {model_path}')
+        except Exception as e:
+            Logger.error(f"Failed to load model from '{model_path}': {e}", exc_info=True)
+            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).
+
+        Args:
+            image (np.ndarray): Input image (BGR format)
+
+        Returns:
+            Tuple[np.ndarray, float, Tuple[int, int]]: Preprocessed image, scale ratio, and padding (pad_w, pad_h)
+        """
+        # 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)
+
+    def inference(self, input_tensor: np.ndarray) -> list[np.ndarray]:
+        """Perform model inference on the preprocessed image tensor.
+
+        Args:
+            input_tensor (np.ndarray): Preprocessed input tensor.
+
+        Returns:
+            List[np.ndarray]: Raw model outputs (3 feature maps).
+        """
+        return self.session.run(self.output_names, {self.input_names: input_tensor})
+
+    @staticmethod
+    def _softmax(x: np.ndarray, axis: int = -1) -> np.ndarray:
+        """Compute softmax values for array x along specified axis."""
+        exp_x = np.exp(x - np.max(x, axis=axis, keepdims=True))
+        return exp_x / np.sum(exp_x, axis=axis, keepdims=True)
+
+    def postprocess(
+        self,
+        predictions: list[np.ndarray],
+        scale: float,
+        padding: tuple[int, int],
+        original_shape: tuple[int, int],
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """
+        Postprocess model predictions with DFL decoding and coordinate scaling.
+
+        Args:
+            predictions (List[np.ndarray]): Raw model outputs (3 feature maps)
+            scale (float): Scale ratio used in preprocessing
+            padding (Tuple[int, int]): Padding (pad_w, pad_h) used in preprocessing
+            original_shape (Tuple[int, int]): Original image shape (height, width)
+
+        Returns:
+            Tuple[np.ndarray, np.ndarray]: Filtered detections and landmarks
+                - detections: [N, 5] as [x1, y1, x2, y2, conf]
+                - landmarks: [N, 5, 2] for each detection
+        """
+        # YOLOv8-Face outputs 3 feature maps with Pose head
+        # Each output: (1, 80, H, W) where 80 = 64 (bbox DFL) + 1 (class) + 15 (5 keypoints * 3)
+
+        boxes_list = []
+        scores_list = []
+        landmarks_list = []
+
+        for pred, stride in zip(predictions, self.strides, strict=False):
+            # pred shape: (1, 80, H, W)
+            batch_size, channels, height, width = pred.shape
+
+            # Reshape: (1, 80, H, W) -> (1, 80, H*W) -> (1, H*W, 80) -> (H*W, 80)
+            pred = pred.reshape(batch_size, channels, -1).transpose(0, 2, 1)[0]
+
+            # Create grid with 0.5 offset (matching PyTorch's make_anchors)
+            grid_y, grid_x = np.meshgrid(np.arange(height) + 0.5, np.arange(width) + 0.5, indexing='ij')
+            grid_x = grid_x.flatten()
+            grid_y = grid_y.flatten()
+
+            # Extract components
+            bbox_pred = pred[:, :64]  # DFL bbox prediction (64 channels = 4 * 16)
+            cls_conf = pred[:, 64]  # Class confidence (1 channel)
+            kpt_pred = pred[:, 65:]  # Keypoints (15 channels = 5 points * 3: x, y, visibility)
+
+            # Decode bounding boxes from DFL
+            bbox_pred = bbox_pred.reshape(-1, 4, 16)
+            bbox_dist = self._softmax(bbox_pred, axis=-1) @ np.arange(16)
+
+            # Convert distances to xyxy format
+            x1 = (grid_x - bbox_dist[:, 0]) * stride
+            y1 = (grid_y - bbox_dist[:, 1]) * stride
+            x2 = (grid_x + bbox_dist[:, 2]) * stride
+            y2 = (grid_y + bbox_dist[:, 3]) * stride
+            boxes = np.stack([x1, y1, x2, y2], axis=-1)
+
+            # Decode keypoints: kpt = (kpt * 2.0 + grid) * stride
+            kpt_grid_y, kpt_grid_x = np.meshgrid(np.arange(height), np.arange(width), indexing='ij')
+            kpt_grid_x = kpt_grid_x.flatten()
+            kpt_grid_y = kpt_grid_y.flatten()
+
+            kpt_pred = kpt_pred.reshape(-1, 5, 3)  # 5 points * (x, y, visibility)
+            kpt_x = (kpt_pred[:, :, 0] * 2.0 + kpt_grid_x[:, None]) * stride
+            kpt_y = (kpt_pred[:, :, 1] * 2.0 + kpt_grid_y[:, None]) * stride
+            # Ignore visibility (kpt_pred[:, :, 2]) for uniface compatibility
+            landmarks = np.stack([kpt_x, kpt_y], axis=-1).reshape(-1, 10)
+
+            # Apply sigmoid to class confidence
+            scores = 1 / (1 + np.exp(-cls_conf))
+
+            boxes_list.append(boxes)
+            scores_list.append(scores)
+            landmarks_list.append(landmarks)
+
+        # Concatenate all predictions from all feature maps
+        boxes = np.concatenate(boxes_list, axis=0)
+        scores = np.concatenate(scores_list, axis=0)
+        landmarks = np.concatenate(landmarks_list, axis=0)
+
+        # Filter by confidence threshold
+        mask = scores >= self.confidence_threshold
+        boxes = boxes[mask]
+        scores = scores[mask]
+        landmarks = landmarks[mask]
+
+        if len(boxes) == 0:
+            return np.array([]), np.array([])
+
+        # Apply NMS based on selected mode
+        if self.nms_mode == 'torchvision':
+            keep = torchvision.ops.nms(
+                torch.tensor(boxes, dtype=torch.float32),
+                torch.tensor(scores, dtype=torch.float32),
+                self.nms_threshold,
+            ).numpy()
+        else:
+            detections_for_nms = np.hstack((boxes, scores[:, None])).astype(np.float32, copy=False)
+            keep = non_max_suppression(detections_for_nms, self.nms_threshold)
+
+        if len(keep) == 0:
+            return np.array([]), np.array([])
+
+        # Limit to max_det
+        keep = keep[: self.max_det]
+        boxes = boxes[keep]
+        scores = scores[keep]
+        landmarks = landmarks[keep]
+
+        # === SCALE TO ORIGINAL IMAGE COORDINATES ===
+        pad_w, pad_h = padding
+
+        # Scale boxes back to original image coordinates
+        boxes[:, [0, 2]] = (boxes[:, [0, 2]] - pad_w) / scale
+        boxes[:, [1, 3]] = (boxes[:, [1, 3]] - pad_h) / scale
+
+        # Clip boxes to image boundaries
+        boxes[:, [0, 2]] = np.clip(boxes[:, [0, 2]], 0, original_shape[1])
+        boxes[:, [1, 3]] = np.clip(boxes[:, [1, 3]], 0, original_shape[0])
+
+        # Scale landmarks back to original image coordinates
+        landmarks[:, 0::2] = (landmarks[:, 0::2] - pad_w) / scale  # x coordinates
+        landmarks[:, 1::2] = (landmarks[:, 1::2] - pad_h) / scale  # y coordinates
+
+        # Reshape landmarks to (N, 5, 2)
+        landmarks = landmarks.reshape(-1, 5, 2)
+
+        # Combine box and score
+        detections = np.concatenate([boxes, scores[:, None]], axis=1)
+
+        return detections, landmarks
+
+    def detect(
+        self,
+        image: np.ndarray,
+        *,
+        max_num: int = 0,
+        metric: Literal['default', 'max'] = 'max',
+        center_weight: float = 2.0,
+    ) -> list[Face]:
+        """
+        Perform face detection on an input image and return bounding boxes and facial landmarks.
+
+        Args:
+            image (np.ndarray): Input image as a NumPy array of shape (H, W, C) in BGR format.
+            max_num (int): Maximum number of detections to return. Use 0 to return all detections. Defaults to 0.
+            metric (Literal["default", "max"]): Metric for ranking detections when `max_num` is limited.
+                - "default": Prioritize detections closer to the image center.
+                - "max": Prioritize detections with larger bounding box areas.
+            center_weight (float): Weight for penalizing detections farther from the image center
+                when using the "default" metric. Defaults to 2.0.
+
+        Returns:
+            List[Face]: List of Face objects, each containing:
+                - bbox (np.ndarray): Bounding box coordinates with shape (4,) as [x1, y1, x2, y2]
+                - confidence (float): Detection confidence score (0.0 to 1.0)
+                - landmarks (np.ndarray): 5-point facial landmarks with shape (5, 2)
+
+        Example:
+            >>> faces = detector.detect(image)
+            >>> for face in faces:
+            ...     bbox = face.bbox  # np.ndarray with shape (4,)
+            ...     confidence = face.confidence  # float
+            ...     landmarks = face.landmarks  # np.ndarray with shape (5, 2)
+        """
+        original_height, original_width = image.shape[:2]
+
+        # Preprocess
+        image_tensor, scale, padding = self.preprocess(image)
+
+        # ONNXRuntime inference
+        outputs = self.inference(image_tensor)
+
+        # Postprocess with original image shape for clipping
+        detections, landmarks = self.postprocess(outputs, scale, padding, (original_height, original_width))
+
+        # Handle case when no faces are detected
+        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])
+
+            # 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
--- a/uniface/face_utils.py
+++ b/uniface/face_utils.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/gaze/init.py
+++ b/uniface/gaze/init.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/gaze/base.py
+++ b/uniface/gaze/base.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/gaze/models.py
+++ b/uniface/gaze/models.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

@@ -38,6 +38,8 @@ class MobileGaze(BaseGazeEstimator):
            Defaults to `GazeWeights.RESNET18`.
        input_size (Tuple[int, int]): The resolution (width, height) for the model's
            input. Defaults to (448, 448).
+        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.
@@ -65,12 +67,14 @@ class MobileGaze(BaseGazeEstimator):
        self,
        model_name: GazeWeights = GazeWeights.RESNET34,
        input_size: tuple[int, int] = (448, 448),
+        providers: list[str] | None = None,
    ) -> None:
        Logger.info(f'Initializing MobileGaze with model={model_name}, input_size={input_size}')

        self.input_size = input_size
        self.input_mean = [0.485, 0.456, 0.406]
        self.input_std = [0.229, 0.224, 0.225]
+        self.providers = providers

        # Model specific parameters for bin-based classification (Gaze360 config)
        self._bins = 90
@@ -89,7 +93,7 @@ class MobileGaze(BaseGazeEstimator):
            RuntimeError: If the model fails to load or initialize.
        """
        try:
-            self.session = create_onnx_session(self.model_path)
+            self.session = create_onnx_session(self.model_path, providers=self.providers)

            # Get input configuration
            input_cfg = self.session.get_inputs()[0]
--- a/uniface/landmark/init.py
+++ b/uniface/landmark/init.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/landmark/base.py
+++ b/uniface/landmark/base.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/landmark/models.py
+++ b/uniface/landmark/models.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

@@ -31,6 +31,8 @@ class Landmark106(BaseLandmarker):
            Defaults to `LandmarkWeights.DEFAULT`.
        input_size (Tuple[int, int]): The resolution (width, height) for the model's
            input. Defaults to (192, 192).
+        providers (list[str] | None): ONNX Runtime execution providers. If None, auto-detects
+            the best available provider. Example: ['CPUExecutionProvider'] to force CPU.

    Example:
        >>> # Assume 'image' is a loaded image and 'bbox' is a face bounding box
@@ -46,11 +48,13 @@ class Landmark106(BaseLandmarker):
        self,
        model_name: LandmarkWeights = LandmarkWeights.DEFAULT,
        input_size: tuple[int, int] = (192, 192),
+        providers: list[str] | None = None,
    ) -> None:
        Logger.info(f'Initializing Facial Landmark with model={model_name}, input_size={input_size}')
        self.input_size = input_size
        self.input_std = 1.0
        self.input_mean = 0.0
+        self.providers = providers
        self.model_path = verify_model_weights(model_name)
        self._initialize_model()

@@ -62,7 +66,7 @@ class Landmark106(BaseLandmarker):
            RuntimeError: If the model fails to load or initialize.
        """
        try:
-            self.session = create_onnx_session(self.model_path)
+            self.session = create_onnx_session(self.model_path, providers=self.providers)

            # Get input configuration
            input_metadata = self.session.get_inputs()[0]
--- a/uniface/log.py
+++ b/uniface/log.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/model_store.py
+++ b/uniface/model_store.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

@@ -51,6 +51,7 @@ def verify_model_weights(model_name: Enum, root: str = '~/.uniface/models') -> s
        '/home/user/.uniface/models/retinaface_mnet_v2.onnx'
    """

+    root = os.getenv('UNIFACE_CACHE_DIR', root)
    root = os.path.expanduser(root)
    os.makedirs(root, exist_ok=True)

--- a/uniface/onnx_utils.py
+++ b/uniface/onnx_utils.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/parsing/init.py
+++ b/uniface/parsing/init.py
@@ -1,30 +1,28 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

 from __future__ import annotations

-from uniface.constants import ParsingWeights
+from uniface.constants import ParsingWeights, XSegWeights

 from .base import BaseFaceParser
 from .bisenet import BiSeNet
+from .xseg import XSeg

-__all__ = ['BaseFaceParser', 'BiSeNet', 'create_face_parser']
+__all__ = ['BaseFaceParser', 'BiSeNet', 'XSeg', 'create_face_parser']


 def create_face_parser(
-    model_name: str | ParsingWeights = ParsingWeights.RESNET18,
+    model_name: str | ParsingWeights | XSegWeights = ParsingWeights.RESNET18,
+    **kwargs,
 ) -> BaseFaceParser:
-    """Factory function to create a face parsing model instance.
-
-    This function provides a convenient way to instantiate face parsing models
-    without directly importing the specific model classes.
+    """Factory function to create a face parsing model.

    Args:
-        model_name: The face parsing model to create. Can be either a string
-            or a ParsingWeights enum value. Available options:
-            - 'parsing_resnet18' or ParsingWeights.RESNET18 (default)
-            - 'parsing_resnet34' or ParsingWeights.RESNET34
+        model_name: Model to create. Options: ParsingWeights.RESNET18/RESNET34 (BiSeNet),
+            XSegWeights.DEFAULT (XSeg, requires landmarks).
+        **kwargs: Additional arguments passed to the model constructor.

    Returns:
        An instance of the requested face parsing model.
@@ -33,20 +31,32 @@ def create_face_parser(
        ValueError: If the model_name is not recognized.

    Example:
-        >>> from uniface.parsing import create_face_parser
-        >>> from uniface.constants import ParsingWeights
        >>> parser = create_face_parser(ParsingWeights.RESNET18)
        >>> mask = parser.parse(face_crop)
    """
+    # Handle XSegWeights
+    if isinstance(model_name, XSegWeights):
+        return XSeg(model_name=model_name, **kwargs)
+
    # Convert string to enum if necessary
    if isinstance(model_name, str):
+        # Try XSegWeights first
+        try:
+            xseg_model = XSegWeights(model_name)
+            return XSeg(model_name=xseg_model, **kwargs)
+        except ValueError:
+            pass
+
+        # Try ParsingWeights
        try:
            model_name = ParsingWeights(model_name)
        except ValueError as e:
-            valid_models = [e.value for e in ParsingWeights]
+            valid_parsing = [m.value for m in ParsingWeights]
+            valid_xseg = [m.value for m in XSegWeights]
+            valid_models = valid_parsing + valid_xseg
            raise ValueError(
                f"Unknown face parsing model: '{model_name}'. Valid options are: {', '.join(valid_models)}"
            ) from e

-    # All parsing models use the same BiSeNet class
-    return BiSeNet(model_name=model_name)
+    # BiSeNet models
+    return BiSeNet(model_name=model_name, **kwargs)
--- a/uniface/parsing/base.py
+++ b/uniface/parsing/base.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/parsing/bisenet.py
+++ b/uniface/parsing/bisenet.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

@@ -37,6 +37,8 @@ class BiSeNet(BaseFaceParser):
            Defaults to `ParsingWeights.RESNET18`.
        input_size (Tuple[int, int]): The resolution (width, height) for the model's
            input. Defaults to (512, 512).
+        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.
@@ -64,12 +66,14 @@ class BiSeNet(BaseFaceParser):
        self,
        model_name: ParsingWeights = ParsingWeights.RESNET18,
        input_size: tuple[int, int] = (512, 512),
+        providers: list[str] | None = None,
    ) -> None:
        Logger.info(f'Initializing BiSeNet 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()
@@ -82,7 +86,7 @@ class BiSeNet(BaseFaceParser):
            RuntimeError: If the model fails to load or initialize.
        """
        try:
-            self.session = create_onnx_session(self.model_path)
+            self.session = create_onnx_session(self.model_path, providers=self.providers)

            # Get input configuration
            input_cfg = self.session.get_inputs()[0]
--- a/uniface/parsing/xseg.py
+++ b/uniface/parsing/xseg.py
@@ -0,0 +1,242 @@
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+from uniface.constants import XSegWeights
+from uniface.face_utils import face_alignment
+from uniface.log import Logger
+from uniface.model_store import verify_model_weights
+from uniface.onnx_utils import create_onnx_session
+
+from .base import BaseFaceParser
+
+__all__ = ['XSeg']
+
+
+class XSeg(BaseFaceParser):
+    """
+    XSeg: Face Segmentation Model from DeepFaceLab with ONNX Runtime.
+
+    XSeg outputs a 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.
+
+    Reference:
+        https://github.com/iperov/DeepFaceLab
+
+    Args:
+        model_name (XSegWeights): The enum specifying the XSeg model to load.
+            Defaults to `XSegWeights.DEFAULT`.
+        align_size (int): Face alignment output size. Must be multiple of 112 or 128.
+            Defaults to 256.
+        blur_sigma (float): Gaussian blur sigma for mask smoothing.
+            0 = raw output (no blur). Defaults to 0.
+        providers (list[str] | None): ONNX Runtime execution providers. If None,
+            auto-detects the best available provider.
+
+    Attributes:
+        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).
+
+    Example:
+        >>> from uniface.parsing import XSeg
+        >>> from uniface import RetinaFace
+        >>>
+        >>> detector = RetinaFace()
+        >>> parser = XSeg()
+        >>>
+        >>> faces = detector.detect(image)
+        >>> for face in faces:
+        ...     if face.landmarks is not None:
+        ...         mask = parser.parse(image, face.landmarks)
+        ...         print(f'Mask shape: {mask.shape}')
+    """
+
+    def __init__(
+        self,
+        model_name: XSegWeights = XSegWeights.DEFAULT,
+        align_size: int = 256,
+        blur_sigma: float = 0,
+        providers: list[str] | None = None,
+    ) -> None:
+        Logger.info(f'Initializing XSeg with model={model_name}, align_size={align_size}, blur_sigma={blur_sigma}')
+
+        self.align_size = align_size
+        self.blur_sigma = blur_sigma
+        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)
+
+            # Get input configuration
+            input_cfg = self.session.get_inputs()[0]
+            input_shape = input_cfg.shape
+            self.input_name = input_cfg.name
+
+            # NHWC format: (N, H, W, C)
+            if isinstance(input_shape[1], int) and isinstance(input_shape[2], int):
+                self.input_size = (input_shape[2], input_shape[1])
+            else:
+                self.input_size = (256, 256)
+                Logger.info(f'Dynamic input shape detected, using default: {self.input_size}')
+
+            # Get output configuration
+            outputs = self.session.get_outputs()
+            self.output_names = [output.name for output in outputs]
+
+            Logger.info(f'XSeg initialized with input size {self.input_size}')
+
+        except Exception as e:
+            Logger.error(f"Failed to load XSeg model from '{self.model_path}'", exc_info=True)
+            raise RuntimeError(f'Failed to initialize XSeg model: {e}') from e
+
+    def preprocess(self, face_crop: np.ndarray) -> np.ndarray:
+        """
+        Preprocess an aligned face crop for inference.
+
+        Args:
+            face_crop (np.ndarray): An aligned face crop in BGR format.
+
+        Returns:
+            np.ndarray: Preprocessed image tensor with shape (1, H, W, 3).
+        """
+        # Resize to model input size
+        image = cv2.resize(face_crop, self.input_size, interpolation=cv2.INTER_LINEAR)
+
+        # Normalize to [0, 1]
+        image = image.astype(np.float32) / 255.0
+
+        # Add batch dimension (NHWC format)
+        image = np.expand_dims(image, axis=0)
+
+        return image
+
+    def postprocess(self, outputs: np.ndarray, crop_size: tuple[int, int]) -> np.ndarray:
+        """
+        Postprocess model output to segmentation mask.
+
+        Args:
+            outputs (np.ndarray): Raw model output.
+            crop_size (tuple[int, int]): Size to resize mask to (width, height).
+
+        Returns:
+            np.ndarray: Segmentation mask as float32 in range [0, 1].
+        """
+        # Squeeze and clip to valid range
+        mask = outputs.squeeze().clip(0, 1).astype(np.float32)
+
+        # Resize back to crop size
+        mask = cv2.resize(mask, crop_size, interpolation=cv2.INTER_LINEAR)
+
+        # Apply optional blur and threshold
+        if self.blur_sigma > 0:
+            mask = cv2.GaussianBlur(mask, (0, 0), self.blur_sigma)
+            mask = (mask.clip(0.5, 1) - 0.5) * 2
+
+        return mask
+
+    def parse(self, image: np.ndarray, landmarks: np.ndarray) -> np.ndarray:
+        """
+        Perform face segmentation using 5-point landmarks.
+
+        Args:
+            image (np.ndarray): Input image in BGR format.
+            landmarks (np.ndarray): 5-point facial landmarks with shape (5, 2).
+
+        Returns:
+            np.ndarray: Segmentation mask in original image space, values in [0, 1].
+
+        Raises:
+            ValueError: If landmarks shape is not (5, 2).
+        """
+        if landmarks.shape != (5, 2):
+            raise ValueError(f'Landmarks must have shape (5, 2), got {landmarks.shape}')
+
+        # Align face using landmarks
+        face_crop, inverse_matrix = face_alignment(image, landmarks, image_size=self.align_size)
+
+        # Run inference
+        crop_size = (face_crop.shape[1], face_crop.shape[0])
+        input_tensor = self.preprocess(face_crop)
+        outputs = self.session.run(self.output_names, {self.input_name: input_tensor})
+
+        # Postprocess mask
+        mask = self.postprocess(outputs[0], crop_size)
+
+        # Warp mask back to original image space
+        h, w = image.shape[:2]
+        warped_mask = cv2.warpAffine(
+            mask,
+            inverse_matrix,
+            (w, h),
+            flags=cv2.INTER_LINEAR,
+            borderMode=cv2.BORDER_CONSTANT,
+            borderValue=0,
+        )
+
+        return warped_mask
+
+    def parse_aligned(self, face_crop: np.ndarray) -> np.ndarray:
+        """
+        Perform segmentation on an already aligned face crop.
+
+        Args:
+            face_crop (np.ndarray): An aligned face crop in BGR format.
+
+        Returns:
+            np.ndarray: Segmentation mask with same size as input, values in [0, 1].
+        """
+        crop_size = (face_crop.shape[1], face_crop.shape[0])
+
+        # Run inference
+        input_tensor = self.preprocess(face_crop)
+        outputs = self.session.run(self.output_names, {self.input_name: input_tensor})
+
+        return self.postprocess(outputs[0], crop_size)
+
+    def parse_with_inverse(
+        self,
+        image: np.ndarray,
+        landmarks: np.ndarray,
+    ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """
+        Parse face and return mask with inverse matrix for custom warping.
+
+        Args:
+            image (np.ndarray): Input image in BGR format.
+            landmarks (np.ndarray): 5-point facial landmarks with shape (5, 2).
+
+        Returns:
+            Tuple of (mask, face_crop, inverse_matrix).
+        """
+        if landmarks.shape != (5, 2):
+            raise ValueError(f'Landmarks must have shape (5, 2), got {landmarks.shape}')
+
+        # Align face using landmarks
+        face_crop, inverse_matrix = face_alignment(image, landmarks, image_size=self.align_size)
+
+        # Run inference
+        crop_size = (face_crop.shape[1], face_crop.shape[0])
+        input_tensor = self.preprocess(face_crop)
+        outputs = self.session.run(self.output_names, {self.input_name: input_tensor})
+
+        # Postprocess mask (in crop space)
+        mask = self.postprocess(outputs[0], crop_size)
+
+        return mask, face_crop, inverse_matrix
--- a/uniface/privacy/init.py
+++ b/uniface/privacy/init.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/privacy/blur.py
+++ b/uniface/privacy/blur.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/recognition/init.py
+++ b/uniface/recognition/init.py
@@ -1,8 +1,9 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo


+from .adaface import AdaFace
 from .base import BaseRecognizer
 from .models import ArcFace, MobileFace, SphereFace

@@ -13,11 +14,11 @@ def create_recognizer(method: str = 'arcface', **kwargs) -> BaseRecognizer:

    This function initializes and returns a face recognizer instance based on the
    specified method. It acts as a high-level interface to the underlying
-    model classes like ArcFace, MobileFace, etc.
+    model classes like ArcFace, AdaFace, MobileFace, etc.

    Args:
        method (str): The recognition method to use.
-            Options: 'arcface' (default), 'mobileface', 'sphereface'.
+            Options: 'arcface' (default), 'adaface', 'mobileface', 'sphereface'.
        **kwargs: Model-specific parameters passed to the recognizer's constructor.
            For example, `model_name` can be used to select a specific
            pre-trained weight from the available enums (e.g., `ArcFaceWeights.MNET`).
@@ -32,6 +33,10 @@ def create_recognizer(method: str = 'arcface', **kwargs) -> BaseRecognizer:
        >>> # Create the default ArcFace recognizer
        >>> recognizer = create_recognizer()

+        >>> # Create an AdaFace recognizer
+        >>> from uniface.constants import AdaFaceWeights
+        >>> recognizer = create_recognizer('adaface', model_name=AdaFaceWeights.IR_101)
+
        >>> # Create a specific MobileFace recognizer
        >>> from uniface.constants import MobileFaceWeights
        >>> recognizer = create_recognizer('mobileface', model_name=MobileFaceWeights.MNET_V2)
@@ -43,13 +48,15 @@ def create_recognizer(method: str = 'arcface', **kwargs) -> BaseRecognizer:

    if method == 'arcface':
        return ArcFace(**kwargs)
+    elif method == 'adaface':
+        return AdaFace(**kwargs)
    elif method == 'mobileface':
        return MobileFace(**kwargs)
    elif method == 'sphereface':
        return SphereFace(**kwargs)
    else:
-        available = ['arcface', 'mobileface', 'sphereface']
+        available = ['arcface', 'adaface', 'mobileface', 'sphereface']
        raise ValueError(f"Unsupported method: '{method}'. Available: {available}")


-__all__ = ['ArcFace', 'BaseRecognizer', 'MobileFace', 'SphereFace', 'create_recognizer']
+__all__ = ['AdaFace', 'ArcFace', 'BaseRecognizer', 'MobileFace', 'SphereFace', 'create_recognizer']
--- a/uniface/recognition/adaface.py
+++ b/uniface/recognition/adaface.py
@@ -0,0 +1,90 @@
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+from uniface.constants import AdaFaceWeights
+from uniface.model_store import verify_model_weights
+
+from .base import BaseRecognizer, PreprocessConfig
+
+__all__ = ['AdaFace']
+
+
+class AdaFace(BaseRecognizer):
+    """AdaFace model for high-quality face recognition.
+
+    AdaFace introduces adaptive margin based on image quality, achieving
+    state-of-the-art results on challenging benchmarks like IJB-B and IJB-C.
+
+    Key difference from other recognizers: AdaFace uses BGR color space
+    (no RGB conversion) during preprocessing.
+
+    Args:
+        model_name (AdaFaceWeights): The specific AdaFace model variant to use.
+            - IR_18: Smaller model trained on WebFace4M (92 MB)
+            - IR_101: Larger model trained on WebFace12M (249 MB)
+            Defaults to `AdaFaceWeights.IR_18`.
+        preprocessing (Optional[PreprocessConfig]): An optional custom preprocessing
+            configuration. If None, a default config for AdaFace is used.
+        providers (list[str] | None): ONNX Runtime execution providers. If None, auto-detects
+            the best available provider. Example: ['CPUExecutionProvider'] to force CPU.
+
+    Example:
+        >>> from uniface.recognition import AdaFace
+        >>> recognizer = AdaFace()
+        >>> # embedding = recognizer.get_normalized_embedding(image, landmarks)
+
+    Reference:
+        https://github.com/mk-minchul/AdaFace
+        https://github.com/yakhyo/adaface-onnx
+    """
+
+    def __init__(
+        self,
+        model_name: AdaFaceWeights = AdaFaceWeights.IR_18,
+        preprocessing: PreprocessConfig | None = None,
+        providers: list[str] | None = None,
+    ) -> None:
+        if preprocessing is None:
+            preprocessing = PreprocessConfig(input_mean=127.5, input_std=127.5, input_size=(112, 112))
+        model_path = verify_model_weights(model_name)
+        super().__init__(model_path=model_path, preprocessing=preprocessing, providers=providers)
+
+    def preprocess(self, face_img: np.ndarray) -> np.ndarray:
+        """Preprocess the image: resize, normalize, and convert to blob.
+
+        AdaFace uses BGR color space (no RGB conversion).
+
+        Args:
+            face_img: Input image in BGR format.
+
+        Returns:
+            Preprocessed image as a NumPy array ready for inference.
+        """
+        resized_img = cv2.resize(face_img, self.input_size)
+
+        if isinstance(self.input_std, list | tuple):
+            # Per-channel normalization (keep BGR)
+            mean_array = np.array(self.input_mean, dtype=np.float32)
+            std_array = np.array(self.input_std, dtype=np.float32)
+            normalized_img = (resized_img.astype(np.float32) - mean_array) / std_array
+
+            # Change to NCHW format (batch, channels, height, width)
+            blob = np.transpose(normalized_img, (2, 0, 1))  # CHW
+            blob = np.expand_dims(blob, axis=0)  # NCHW
+        else:
+            # Single-value normalization using cv2.dnn (keep BGR, swapRB=False)
+            blob = cv2.dnn.blobFromImage(
+                resized_img,
+                scalefactor=1.0 / self.input_std,
+                size=self.input_size,
+                mean=(self.input_mean, self.input_mean, self.input_mean),
+                swapRB=False,  # Keep BGR for AdaFace
+            )
+
+        return blob
--- a/uniface/recognition/base.py
+++ b/uniface/recognition/base.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

@@ -39,19 +39,27 @@ class BaseRecognizer(ABC):
    """

    @abstractmethod
-    def __init__(self, model_path: str, preprocessing: PreprocessConfig) -> None:
+    def __init__(
+        self,
+        model_path: str,
+        preprocessing: PreprocessConfig,
+        providers: list[str] | None = None,
+    ) -> None:
        """
        Initializes the model. Subclasses must call this.

        Args:
            model_path (str): The direct path to the verified ONNX model.
            preprocessing (PreprocessConfig): The configuration for preprocessing.
+            providers (list[str] | None): ONNX Runtime execution providers. If None, auto-detects
+                the best available provider. Example: ['CPUExecutionProvider'] to force CPU.
        """
        self.input_mean = preprocessing.input_mean
        self.input_std = preprocessing.input_std
        self.input_size = preprocessing.input_size

        self.model_path = model_path
+        self.providers = providers
        self._initialize_model()

    def _initialize_model(self) -> None:
@@ -63,7 +71,7 @@ class BaseRecognizer(ABC):
        """
        try:
            # Initialize model session with available providers
-            self.session = create_onnx_session(self.model_path)
+            self.session = create_onnx_session(self.model_path, providers=self.providers)

            # Extract input configuration
            input_cfg = self.session.get_inputs()[0]
--- a/uniface/recognition/models.py
+++ b/uniface/recognition/models.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

@@ -24,6 +24,8 @@ class ArcFace(BaseRecognizer):
            Defaults to `ArcFaceWeights.MNET`.
        preprocessing (Optional[PreprocessConfig]): An optional custom preprocessing
            configuration. If None, a default config for ArcFace is used.
+        providers (list[str] | None): ONNX Runtime execution providers. If None, auto-detects
+            the best available provider. Example: ['CPUExecutionProvider'] to force CPU.

    Example:
        >>> from uniface.recognition import ArcFace
@@ -35,11 +37,12 @@ class ArcFace(BaseRecognizer):
        self,
        model_name: ArcFaceWeights = ArcFaceWeights.MNET,
        preprocessing: PreprocessConfig | None = None,
+        providers: list[str] | None = None,
    ) -> None:
        if preprocessing is None:
            preprocessing = PreprocessConfig(input_mean=127.5, input_std=127.5, input_size=(112, 112))
        model_path = verify_model_weights(model_name)
-        super().__init__(model_path=model_path, preprocessing=preprocessing)
+        super().__init__(model_path=model_path, preprocessing=preprocessing, providers=providers)


 class MobileFace(BaseRecognizer):
@@ -54,6 +57,8 @@ class MobileFace(BaseRecognizer):
            Defaults to `MobileFaceWeights.MNET_V2`.
        preprocessing (Optional[PreprocessConfig]): An optional custom preprocessing
            configuration. If None, a default config for MobileFaceNet is used.
+        providers (list[str] | None): ONNX Runtime execution providers. If None, auto-detects
+            the best available provider. Example: ['CPUExecutionProvider'] to force CPU.

    Example:
        >>> from uniface.recognition import MobileFace
@@ -65,11 +70,12 @@ class MobileFace(BaseRecognizer):
        self,
        model_name: MobileFaceWeights = MobileFaceWeights.MNET_V2,
        preprocessing: PreprocessConfig | None = None,
+        providers: list[str] | None = None,
    ) -> None:
        if preprocessing is None:
            preprocessing = PreprocessConfig(input_mean=127.5, input_std=127.5, input_size=(112, 112))
        model_path = verify_model_weights(model_name)
-        super().__init__(model_path=model_path, preprocessing=preprocessing)
+        super().__init__(model_path=model_path, preprocessing=preprocessing, providers=providers)


 class SphereFace(BaseRecognizer):
@@ -84,6 +90,8 @@ class SphereFace(BaseRecognizer):
            Defaults to `SphereFaceWeights.SPHERE20`.
        preprocessing (Optional[PreprocessConfig]): An optional custom preprocessing
            configuration. If None, a default config for SphereFace is used.
+        providers (list[str] | None): ONNX Runtime execution providers. If None, auto-detects
+            the best available provider. Example: ['CPUExecutionProvider'] to force CPU.

    Example:
        >>> from uniface.recognition import SphereFace
@@ -95,9 +103,10 @@ class SphereFace(BaseRecognizer):
        self,
        model_name: SphereFaceWeights = SphereFaceWeights.SPHERE20,
        preprocessing: PreprocessConfig | None = None,
+        providers: list[str] | None = None,
    ) -> None:
        if preprocessing is None:
            preprocessing = PreprocessConfig(input_mean=127.5, input_std=127.5, input_size=(112, 112))

        model_path = verify_model_weights(model_name)
-        super().__init__(model_path=model_path, preprocessing=preprocessing)
+        super().__init__(model_path=model_path, preprocessing=preprocessing, providers=providers)
--- a/uniface/spoofing/init.py
+++ b/uniface/spoofing/init.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/spoofing/base.py
+++ b/uniface/spoofing/base.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/spoofing/minifasnet.py
+++ b/uniface/spoofing/minifasnet.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

@@ -44,6 +44,8 @@ class MiniFASNet(BaseSpoofer):
        scale (Optional[float]): Custom crop scale factor for face region.
            If None, uses the default scale for the selected model variant.
            V1SE uses 4.0, V2 uses 2.7.
+        providers (list[str] | None): ONNX Runtime execution providers. If None, auto-detects
+            the best available provider. Example: ['CPUExecutionProvider'] to force CPU.

    Attributes:
        scale (float): Crop scale factor for face region extraction.
@@ -68,11 +70,13 @@ class MiniFASNet(BaseSpoofer):
        self,
        model_name: MiniFASNetWeights = MiniFASNetWeights.V2,
        scale: float | None = None,
+        providers: list[str] | None = None,
    ) -> None:
        Logger.info(f'Initializing MiniFASNet with model={model_name.name}')

        # Use default scale for the model variant if not specified
        self.scale = scale if scale is not None else DEFAULT_SCALES.get(model_name, 2.7)
+        self.providers = providers

        self.model_path = verify_model_weights(model_name)
        self._initialize_model()
@@ -85,7 +89,7 @@ class MiniFASNet(BaseSpoofer):
            RuntimeError: If the model fails to load or initialize.
        """
        try:
-            self.session = create_onnx_session(self.model_path)
+            self.session = create_onnx_session(self.model_path, providers=self.providers)

            # Get input configuration
            input_cfg = self.session.get_inputs()[0]
--- a/uniface/types.py
+++ b/uniface/types.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo

--- a/uniface/visualization.py
+++ b/uniface/visualization.py
@@ -1,4 +1,4 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
+# Copyright 2025-2026 Yakhyokhuja Valikhujaev
 # Author: Yakhyokhuja Valikhujaev
 # GitHub: https://github.com/yakhyo
Author	SHA1	Message	Date
Yakhyokhuja Valikhujaev	331f46be7c	release: Update release version and docs (#79 )	2026-02-05 21:45:28 +09:00
Yakhyokhuja Valikhujaev	9991fae62a	docs: Update UniFace library documentation and README.md (#78 ) * docs: Update wrong/missing references * docs: Update README.md	2026-02-04 20:45:02 +09:00
Yakhyokhuja Valikhujaev	b74ab95d39	docs: Update UniFace github image (#75 )	2026-01-25 17:07:40 +09:00
Yakhyokhuja Valikhujaev	d2b0303bfe	docs: Add additional badges to README.md (#74 ) * Update badges in README.md * Update ci.yml	2026-01-24 22:25:09 +09:00
Yakhyokhuja Valikhujaev	5f74487eb3	feat: Add XSeg for Face Segmentation (#72 ) * feat: Add XSeg for Face Segmentation DeepFaceLab * docs: Update model inference related reference * chore: Update jupyter notebook example for face segmentation	2026-01-22 22:33:31 +09:00
Yakhyokhuja Valikhujaev	f897482d26	release: Release UniFace v2.2.1 (#69 )	2026-01-18 22:38:15 +09:00
Yakhyokhuja Valikhujaev	f3d81eb201	feat: Add providers for chosing inference backend (#68 ) * feat: Add providers for chosing inference backend * docs: Update Python version	2026-01-18 22:29:15 +09:00
Yakhyokhuja Valikhujaev	ea0b56f7e0	fix: Add cache dir check (#67 )	2026-01-15 18:07:45 +09:00
Yakhyokhuja Valikhujaev	edbab5f7bf	fix: use Python 3.11 in validate job for tomllib support (#65 )	2026-01-07 00:29:48 +09:00
Yakhyokhuja Valikhujaev	cd8077e460	feat: Update release to v2.2.0 (#64 )	2026-01-07 00:16:29 +09:00
Yakhyokhuja Valikhujaev	452b3381a2	Update badge links in README.md (#63 )	2026-01-06 23:32:36 +09:00
Yakhyokhuja Valikhujaev	07c8bd7b24	feat: Add YOLOv8 Face Detection model support (#62 ) * docs: Update UniFace documentation * feat: Add YOLOv8 face detection model	2026-01-03 19:08:41 +09:00
Yakhyokhuja Valikhujaev	68179d1e2d	feat: Add AdaFace: Quality Adaptive Margin for Face Recognition (#61 ) * feat: Add AdaFace model * release: Update release version to v2.1.0	2026-01-02 00:23:24 +09:00
Yakhyokhuja Valikhujaev	99b35dddb4	chore: Add google analytics (#57 )	2025-12-31 19:45:49 +09:00