Skip to content

UniFace: A Unified Face Analysis Library for Python | Detection, alignment, landmarks, face-mesh, recognition, parsing, gaze, attributes and anti-spoofing under one API.

feat: Add adaface resnet50 version trained on WebFace4M (#146)

Yakhyokhuja Valikhujaev4512ce0dc53a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c95e3b5..53826c2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,21 @@
Notable changes to UniFace are documented here. Earlier releases are covered by
the autogenerated notes on the [GitHub releases page](https://github.com/yakhyo/uniface/releases).
+## Unreleased
+
+### Added
+
+- AdaFace `IR_50` weights (WebFace4M, 166 MB): 95.44% IJB-B, 96.98% IJB-C.
+ More accurate than `IR_18` at 1.8x the size. `IR_18` remains the default.
+
+### Fixed
+
+- Model licence table no longer implies the MIT licence covers pretrained
+ weights: code and weights licences are now separate columns. InsightFace
+ weights (SCRFD, ArcFace, AgeGender, Landmark106) are non-commercial upstream,
+ EdgeFace is BSD-3-Clause rather than MIT, and AgeGender, Landmark106 and
+ EdgeFace were missing from the table entirely.
+
## 4.0.0 - 2026-08-03
### Breaking changes
diff --git a/docs/datasets.md b/docs/datasets.md
index 45c43d3..2eefc58 100644
--- a/docs/datasets.md
+++ b/docs/datasets.md
@@ -89,7 +89,7 @@ Large-scale face recognition datasets from the WebFace260M collection. Used for
| Property | WebFace4M | WebFace12M |
| -------- | ------------- | -------------- |
| Images | ~4M | ~12M |
-| Used by | AdaFace IR_18 | AdaFace IR_101 |
+| Used by | AdaFace IR_18, IR_50 | AdaFace IR_101 |
!!! info "Source"
**Paper**: [AdaFace: Quality Adaptive Margin for Face Recognition](https://arxiv.org/abs/2204.00964)
diff --git a/docs/license-attribution.md b/docs/license-attribution.md
index 24e3bc4..d57ba48 100644
--- a/docs/license-attribution.md
+++ b/docs/license-attribution.md
@@ -4,27 +4,71 @@
UniFace is released under the [MIT License](https://opensource.org/licenses/MIT).
+That licence covers UniFace's own source code. It does not cover the pretrained
+weights, which are third-party artifacts downloaded on first use and governed by
+their upstream terms. Several of them prohibit commercial use — check the
+**Weights** column below before shipping.
+
---
## Model Credits
-| Model | Source | License |
-|-------|--------|---------|
-| RetinaFace | [yakhyo/retinaface-pytorch](https://github.com/yakhyo/retinaface-pytorch) | MIT |
-| SCRFD | [InsightFace](https://github.com/deepinsight/insightface) | MIT |
-| CenterFace | [Star-Clouds/CenterFace](https://github.com/Star-Clouds/CenterFace) | MIT |
-| BlazeFace | [yakhyo/mediapipe-face-mesh-onnx](https://github.com/yakhyo/mediapipe-face-mesh-onnx) — architecture & weights from Google [MediaPipe](https://github.com/google-ai-edge/mediapipe) | Apache-2.0 |
-| 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 |
-| BiSeNet | [yakhyo/face-parsing](https://github.com/yakhyo/face-parsing) | MIT |
-| MobileGaze | [yakhyo/gaze-estimation](https://github.com/yakhyo/gaze-estimation) | MIT |
-| MODNet | [yakhyo/modnet](https://github.com/yakhyo/modnet) | Apache-2.0 |
-| MiniFASNet | [yakhyo/face-anti-spoofing](https://github.com/yakhyo/face-anti-spoofing) | Apache-2.0 |
-| FairFace | [yakhyo/fairface-onnx](https://github.com/yakhyo/fairface-onnx) | CC BY 4.0 |
-| FaceAttribNet | [yakhyo/face-attribute](https://github.com/yakhyo/face-attribute) — architecture & weights © Qualcomm Technologies, Inc. ([qualcomm/ai-hub-models](https://github.com/qualcomm/ai-hub-models)) | BSD-3-Clause |
-| PIPNet | [yakhyo/pipnet-onnx](https://github.com/yakhyo/pipnet-onnx) — meanface tables vendored from [jhb86253817/PIPNet](https://github.com/jhb86253817/PIPNet) | MIT |
-| Face Mesh | [yakhyo/mediapipe-face-mesh-onnx](https://github.com/yakhyo/mediapipe-face-mesh-onnx) — topology & weights from Google [MediaPipe](https://github.com/google-ai-edge/mediapipe), sourced via [PINTO0309's ONNX conversion](https://github.com/PINTO0309/facemesh_onnx_tensorrt); tessellation tables vendored from the same source | Apache-2.0 |
+| Model | Source | Code | Weights |
+|-------|--------|------|---------|
+| RetinaFace | [yakhyo/retinaface-pytorch](https://github.com/yakhyo/retinaface-pytorch) | MIT | Follows source |
+| SCRFD | [InsightFace](https://github.com/deepinsight/insightface) | MIT | **Non-commercial**[^insightface] |
+| CenterFace | [Star-Clouds/CenterFace](https://github.com/Star-Clouds/CenterFace) | MIT | Follows source |
+| BlazeFace | [yakhyo/mediapipe-face-mesh-onnx](https://github.com/yakhyo/mediapipe-face-mesh-onnx) — architecture & weights from Google [MediaPipe](https://github.com/google-ai-edge/mediapipe) | Apache-2.0 | Apache-2.0 |
+| YOLOv5-Face | [yakhyo/yolov5-face-onnx-inference](https://github.com/yakhyo/yolov5-face-onnx-inference) | GPL-3.0 | Follows source |
+| YOLOv8-Face | [yakhyo/yolov8-face-onnx-inference](https://github.com/yakhyo/yolov8-face-onnx-inference) | GPL-3.0 | Follows source |
+| AdaFace | [yakhyo/adaface-onnx](https://github.com/yakhyo/adaface-onnx) — architecture & weights from [mk-minchul/AdaFace](https://github.com/mk-minchul/AdaFace) | MIT | MIT |
+| ArcFace | [InsightFace](https://github.com/deepinsight/insightface) | MIT | **Non-commercial**[^insightface] |
+| EdgeFace | [yakhyo/edgeface-onnx](https://github.com/yakhyo/edgeface-onnx) — architecture & weights from [otroshi/edgeface](https://github.com/otroshi/edgeface), Idiap Research Institute | BSD-3-Clause | BSD-3-Clause |
+| MobileFace | [yakhyo/face-recognition](https://github.com/yakhyo/face-recognition) | MIT | Follows source |
+| SphereFace | [yakhyo/face-recognition](https://github.com/yakhyo/face-recognition) | MIT | Follows source |
+| BiSeNet | [yakhyo/face-parsing](https://github.com/yakhyo/face-parsing) | MIT | Follows source |
+| MobileGaze | [yakhyo/gaze-estimation](https://github.com/yakhyo/gaze-estimation) | MIT | Follows source |
+| MODNet | [yakhyo/modnet](https://github.com/yakhyo/modnet) | Apache-2.0 | Apache-2.0 |
+| MiniFASNet | [yakhyo/face-anti-spoofing](https://github.com/yakhyo/face-anti-spoofing) | Apache-2.0 | Apache-2.0 |
+| FairFace | [yakhyo/fairface-onnx](https://github.com/yakhyo/fairface-onnx) | CC BY 4.0 | CC BY 4.0 |
+| AgeGender | [InsightFace](https://github.com/deepinsight/insightface) — `genderage` from the buffalo packs | MIT | **Non-commercial**[^insightface] |
+| FaceAttribNet | [yakhyo/face-attribute](https://github.com/yakhyo/face-attribute) — architecture & weights © Qualcomm Technologies, Inc. ([qualcomm/ai-hub-models](https://github.com/qualcomm/ai-hub-models)) | BSD-3-Clause | BSD-3-Clause |
+| PIPNet | [yakhyo/pipnet-onnx](https://github.com/yakhyo/pipnet-onnx) — meanface tables vendored from [jhb86253817/PIPNet](https://github.com/jhb86253817/PIPNet) | MIT | Follows source |
+| Landmark106 | [InsightFace](https://github.com/deepinsight/insightface/tree/master/alignment/coordinate_reg) — `2d106det` | MIT | **Non-commercial**[^insightface] |
+| Face Mesh | [yakhyo/mediapipe-face-mesh-onnx](https://github.com/yakhyo/mediapipe-face-mesh-onnx) — topology & weights from Google [MediaPipe](https://github.com/google-ai-edge/mediapipe), sourced via [PINTO0309's ONNX conversion](https://github.com/PINTO0309/facemesh_onnx_tensorrt); tessellation tables vendored from the same source | Apache-2.0 | Apache-2.0 |
+
+!!! note "Rows marked *Follows source*"
+ We have not identified weights terms separate from the source project's
+ licence, so the source project's terms apply.
+
+!!! warning "Training-data provenance"
+ Separately from the licences above, many face models are trained on datasets
+ whose own terms restrict use to non-commercial research — WebFace260M
+ (AdaFace, EdgeFace), WIDER FACE (most detectors), MS-Celeb-1M. The upstream
+ authors released these weights under the permissive licences listed here and
+ state no further restriction, and this page does not attempt to judge
+ whether a dataset's terms reach you as a downstream recipient of the
+ weights. If you are deploying commercially, do your own diligence.
+
+---
+
+## Non-commercial weights
+
+These weights cannot be used commercially under their upstream terms, even
+though UniFace itself is MIT and the upstream **code** is permissive.
+
+### InsightFace — SCRFD, ArcFace, AgeGender, Landmark106 { #insightface }
+
+> The code of InsightFace is released under the MIT License. There is no
+> limitation for both academic and commercial usage.
+>
+> The training data containing the annotation (and the models trained with these
+> data) are available for non-commercial research purposes only.
+
+— [deepinsight/insightface](https://github.com/deepinsight/insightface)
+
+ArcFace's `w600k_r50` is the `buffalo_l` recognition model. InsightFace directs
+commercial licensing enquiries for it to `[email protected]`.
+
+[^insightface]: InsightFace's code is MIT, but models trained on their data are
+ for non-commercial research only. See [Non-commercial weights](#insightface).
diff --git a/docs/models.md b/docs/models.md
index 333845c..8fbae31 100644
--- a/docs/models.md
+++ b/docs/models.md
@@ -146,6 +146,7 @@ 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_50` | IR-50 | WebFace4M | 166 MB | 95.44% | 96.98% |
| `IR_101` | IR-101 | WebFace12M | 249 MB | - | 97.66% |
!!! info "Training Data & Accuracy"
diff --git a/docs/modules/recognition.md b/docs/modules/recognition.md
index 913f0c2..cc2c21c 100644
--- a/docs/modules/recognition.md
+++ b/docs/modules/recognition.md
@@ -13,7 +13,7 @@ Face recognition extracts embeddings for identity verification and face search.
| Model | Backbone | Size | Embedding Dim |
|-------|----------|------|---------------|
-| **AdaFace** | IR-18/IR-101 | 92-249 MB | 512 |
+| **AdaFace** | IR-18/IR-50/IR-101 | 92-249 MB | 512 |
| **ArcFace** | MobileNet/ResNet | 8-166 MB | 512 |
| **EdgeFace** | EdgeNeXt/LoRA | 5-70 MB | 512 |
| **MobileFace** | MobileNet V2/V3 | 1-10 MB | 512 |
@@ -62,6 +62,7 @@ recognizer = AdaFace(providers=['CPUExecutionProvider'])
| Variant | Dataset | Size | IJB-B | IJB-C |
|---------|---------|------|-------|-------|
| **IR_18** :material-check-circle: | WebFace4M | 92 MB | 93.03% | 94.99% |
+| IR_50 | WebFace4M | 166 MB | 95.44% | 96.98% |
| IR_101 | WebFace12M | 249 MB | - | 97.66% |
!!! info "Benchmark Metrics"
diff --git a/tests/test_model_store.py b/tests/test_model_store.py
index 369dde9..1e249a0 100644
--- a/tests/test_model_store.py
+++ b/tests/test_model_store.py
@@ -27,8 +27,7 @@ class TestMirrorUrl:
def test_mirror_url_shape(self, model):
"""Assert the literal URL, so a wrong repo id or revision fails the test."""
assert _mirror_url(model, const.MODEL_REGISTRY[model].url) == (
- 'https://huggingface.co/yakhyo/uniface-weights/resolve/'
- '4c7ed723a20deb7ff154b1ba7d6e73747d954016/blazeface.onnx'
+ 'https://huggingface.co/yakhyo/uniface-weights/resolve/main/blazeface.onnx'
)
def test_extension_follows_primary_url(self, model):
diff --git a/uniface/constants.py b/uniface/constants.py
index 37f14da..4d6fcb6 100644
--- a/uniface/constants.py
+++ b/uniface/constants.py
@@ -24,10 +24,11 @@ class ModelInfo:
DOWNLOAD_CHUNK_SIZE = 256 * 1024 # 256 KiB
HASH_CHUNK_SIZE = 1024 * 1024 # 1 MiB
-# Fallback source when a primary (GitHub Releases) URL is unreachable. Pinned to a
-# commit SHA so the fallback serves immutable bytes, matching the SHA-256 guarantee
-# of the primary path. Bump the SHA whenever new weights land in the mirror repo.
-HF_MIRROR_URL = 'https://huggingface.co/yakhyo/uniface-weights/resolve/4c7ed723a20deb7ff154b1ba7d6e73747d954016'
+# Fallback source when a primary (GitHub Releases) URL is unreachable. Tracks the
+# mirror's main branch: every download is checked against the SHA-256 in this
+# registry regardless of source, so a mutable ref cannot serve the wrong bytes --
+# it can only fail. Tracking main also means new weights need no change here.
+HF_MIRROR_URL = 'https://huggingface.co/yakhyo/uniface-weights/resolve/main'
# fmt: off
@@ -64,6 +65,7 @@ class AdaFaceWeights(str, Enum):
https://github.com/yakhyo/adaface-onnx
"""
IR_18 = "adaface_ir_18"
+ IR_50 = "adaface_ir_50"
IR_101 = "adaface_ir_101"
class EdgeFaceWeights(str, Enum):
@@ -407,6 +409,10 @@ MODEL_REGISTRY: dict[Enum, ModelInfo] = {
url='https://github.com/yakhyo/adaface-onnx/releases/download/weights/adaface_ir_18.onnx',
sha256='6b6a35772fb636cdd4fa86520c1a259d0c41472a76f70f802b351837a00d9870'
),
+ AdaFaceWeights.IR_50: ModelInfo(
+ url='https://github.com/yakhyo/adaface-onnx/releases/download/weights/adaface_ir_50.onnx',
+ sha256='9c0ae385d7362323c92d218de598d32e52a9130b78faac6a8a924091aca62c0b'
+ ),
AdaFaceWeights.IR_101: ModelInfo(
url='https://github.com/yakhyo/adaface-onnx/releases/download/weights/adaface_ir_101.onnx',
sha256='f2eb07d03de0af560a82e1214df799fec5e09375d43521e2868f9dc387e5a43e'
diff --git a/uniface/recognition/adaface.py b/uniface/recognition/adaface.py
index 70a94fb..7ef6a81 100644
--- a/uniface/recognition/adaface.py
+++ b/uniface/recognition/adaface.py
@@ -27,6 +27,7 @@ class AdaFace(BaseRecognizer):
Args:
model_name (AdaFaceWeights): The specific AdaFace model variant to use.
- IR_18: Smaller model trained on WebFace4M (92 MB)
+ - IR_50: Mid-size model trained on WebFace4M (166 MB)
- IR_101: Larger model trained on WebFace12M (249 MB)
Defaults to `AdaFaceWeights.IR_18`.
preprocessing (PreprocessConfig | None): An optional custom preprocessing