UniFace: A Unified Face Analysis Library for Python | Detection, alignment, landmarks, face-mesh, recognition, parsing, gaze, attributes and anti-spoofing under one API.
Python computer-visiondeep-learningface-alignmentface-analysisface-anonymizationface-anti-spoofingface-attributesface-detectionface-meshface-parsingface-quality-assessmentface-recognitionface-segmentationface-trackingfacial-landmarksgaze-estimationhead-pose-estimationonnxruntimeportrait-mattingpython
feat: Add adaface resnet50 version trained on WebFace4M (#146)
Yakhyokhuja Valikhujaev4512ce0dc53a
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c95e3b5..53826c2 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -3,6 +3,21 @@Notable changes to UniFace are documented here. Earlier releases are covered bythe 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 changesdiff --git a/docs/datasets.md b/docs/datasets.mdindex 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.mdindex 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.mdindex 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.mdindex 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.pyindex 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.pyindex 37f14da..4d6fcb6 100644--- a/uniface/constants.py+++ b/uniface/constants.py@@ -24,10 +24,11 @@ class ModelInfo:DOWNLOAD_CHUNK_SIZE = 256 * 1024 # 256 KiBHASH_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.pyindex 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