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: Update FaceAnalyzer defaults and remove Spanish README (#150)

Yakhyokhuja Valikhujaev8e30484351b0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 53826c2..0b6d623 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,12 @@ the autogenerated notes on the [GitHub releases page](https://github.com/yakhyo/
## Unreleased
+### Changed
+
+- `FaceAnalyzer()` now defaults to RetinaFace `MNET_V2` + EdgeFace `XXS`
+ instead of SCRFD `500M_KPS` + ArcFace `MNET`. Pass the old models explicitly
+ to keep using them.
+
### Added
- AdaFace `IR_50` weights (WebFace4M, 166 MB): 95.44% IJB-B, 96.98% IJB-C.
diff --git a/README.es.md b/README.es.md
deleted file mode 100644
index 15d7ddf..0000000
--- a/README.es.md
+++ /dev/null
@@ -1,190 +0,0 @@
-\[[English](README.md)\] | \[[Chinese](README.zh-CN.md)\] | \[[Korean](README.ko.md)\] | \[[Spanish](README.es.md)\] | \[[Uzbek](README.uz.md)\]
-
-<h1 align="center">UniFace: Una biblioteca unificada de análisis facial para Python</h1>
-
-Esta página es la traducción al español del [README en inglés](README.md). La documentación enlazada está principalmente en inglés. Al actualizar la traducción, mantén el contenido sincronizado con la versión inglesa.
-
-<div align="center">
-
-[![PyPI Version](https://img.shields.io/pypi/v/uniface.svg?label=Version)](https://pypi.org/project/uniface/)
-[![Python Version](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
-[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Github Build Status](https://github.com/yakhyo/uniface/actions/workflows/ci.yml/badge.svg)](https://github.com/yakhyo/uniface/actions)
-[![PyPI Downloads](https://static.pepy.tech/personalized-badge/uniface?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=BLUE&left_text=Downloads)](https://pepy.tech/projects/uniface)
-[![Kaggle Badge](https://img.shields.io/badge/Cuadernos-Kaggle?label=Kaggle&color=blue)](https://www.kaggle.com/yakhyokhuja/code)
-[![Hugging Face Spaces](https://img.shields.io/badge/Demo-%F0%9F%A4%97%20Spaces-blue)](https://huggingface.co/spaces/yakhyo/uniface)
-
-</div>
-
-<div align="center">
- <img src="https://raw.githubusercontent.com/yakhyo/uniface/main/.github/logos/uniface_rounded_q80.webp" width="90%" alt="UniFace — Una biblioteca unificada de análisis facial para Python">
-</div>
-
-<p align="center">
- UniFace es una biblioteca ligera de Python, lista para producción, para detección y reconocimiento facial,<br>
- seguimiento, análisis de puntos de referencia, segmentación de partes del rostro, estimación de la mirada y atributos faciales.
-</p>
-
-<p align="center">
- <a href="https://yakhyo.github.io/uniface/quickstart/"><img src="https://img.shields.io/badge/Primeros%20pasos-1f6feb?style=for-the-badge&logoColor=white" alt="Primeros pasos"></a>
- &nbsp;
- <a href="https://yakhyo.github.io/uniface/models/"><img src="https://img.shields.io/badge/Cat%C3%A1logo%20de%20modelos-30363d?style=for-the-badge&logoColor=white" alt="Catálogo de modelos"></a>
- &nbsp;
- <a href="https://yakhyo.github.io/uniface/notebooks/"><img src="https://img.shields.io/badge/Cuadernos-30363d?style=for-the-badge&logo=jupyter&logoColor=white" alt="Cuadernos"></a>
- &nbsp;
- <a href="https://yakhyo.github.io/uniface/"><img src="https://img.shields.io/badge/Documentaci%C3%B3n%20completa-30363d?style=for-the-badge&logoColor=white" alt="Documentación completa"></a>
-</p>
-
-```bash
-pip install "uniface[cpu]" # CPU y Apple Silicon
-pip install "uniface[gpu]" # NVIDIA CUDA
-pip install --pre "uniface[cpu]" # última versión preliminar
-```
-
-<details>
-<summary><b>Un primer script</b></summary>
-
-<br>
-
-`FaceAnalyzer` ejecuta la detección, la alineación y el reconocimiento en una sola llamada. Los modelos de atributos se añaden de forma explícita.
-
-```python
-import cv2
-from uniface import FaceAnalyzer, FairFace
-
-analyzer = FaceAnalyzer(predictors=[FairFace()])
-
-for face in analyzer.analyze(cv2.imread("photo.jpg")):
- print(face.bbox, face.sex, face.age_group, face.embedding.shape)
-```
-
-`bbox`, `confidence`, `landmarks` y `embedding` siempre tienen un valor. La edad, el sexo, la raza, la emoción, la calidad
-y los estados del rostro permanecen en `None` hasta que se añade el predictor correspondiente.
-
-</details>
-
-<details>
-<summary><b>Las quince tareas y sus modelos</b></summary>
-
-<br>
-
-| Tarea | Modelos |
-| --- | --- |
-| Detección facial | RetinaFace, SCRFD, CenterFace, YOLOv5-Face, YOLOv8-Face, BlazeFace |
-| Reconocimiento facial | AdaFace, ArcFace, EdgeFace, MobileFace, SphereFace |
-| Seguimiento facial | BYTETracker, identificadores persistentes entre fotogramas |
-| Puntos de referencia faciales | 2d106det (106), PIPNet (98 / 68), Face Mesh (468 / 478, 3D) |
-| Segmentación de partes del rostro | BiSeNet (19 clases), máscaras con XSeg |
-| Recorte de retratos | MODNet, sin trimap |
-| Estimación de la mirada | MobileGaze (ResNet-18 / 34 / 50, MobileNetV2) |
-| Pose de la cabeza | representación de rotación 6D, cabeceo / guiñada / alabeo |
-| Atributos demográficos | AgeGender, FairFace (grupo de edad, sexo, raza) |
-| Emoción | AffectNet-7 y AffectNet-8 |
-| Estados del rostro | FaceAttribNet: estado de los ojos, gafas, gafas de sol, mascarilla |
-| Calidad facial | eDifFIQA (T / S / M / L) |
-| Detección de suplantación facial | detección de vida con MiniFASNet |
-| Anonimización | 5 métodos de desenfoque |
-| Almacén de vectores | búsqueda de embeddings con FAISS |
-
-Funciona en CPU, Apple Silicon y CUDA. Los pesos se descargan al usarlos por primera vez y se verifican con SHA-256.
-
-</details>
-
-<br>
-
-### Detectar rostros y medir sus características
-
-**Detección facial** &nbsp;·&nbsp; [documentación](https://yakhyo.github.io/uniface/modules/detection/)
-
-<img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/detection.jpg" width="100%">
-
-**Puntos de referencia faciales** &nbsp;·&nbsp; [documentación](https://yakhyo.github.io/uniface/modules/landmarks/)
-
-<img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/landmarks.jpg" width="100%">
-
-**Malla facial** &nbsp;·&nbsp; [documentación](https://yakhyo.github.io/uniface/modules/landmarks/#face-mesh-468-or-478-points-3d)
-
-<img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/face_mesh.jpg" width="100%">
-
-**Calidad facial** &nbsp;·&nbsp; [documentación](https://yakhyo.github.io/uniface/modules/quality/)
-
-<img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/quality.jpg" width="100%">
-
-### Separar rostros y retratos
-
-**Segmentación de partes del rostro** &nbsp;·&nbsp; [documentación](https://yakhyo.github.io/uniface/modules/parsing/)
-
-<img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/parsing.jpg" width="100%">
-
-**Segmentación facial** &nbsp;·&nbsp; [documentación](https://yakhyo.github.io/uniface/modules/parsing/#xseg)
-
-<img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/segmentation.jpg" width="100%">
-
-<img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/segmentation_occluded.jpg" width="100%">
-
-**Recorte de retratos** &nbsp;·&nbsp; [documentación](https://yakhyo.github.io/uniface/modules/matting/)
-
-<img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/matting.jpg" width="100%">
-
-<img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/matting_alt.jpg" width="100%">
-
-### Estimar la orientación de la cabeza y la mirada
-
-**Pose de la cabeza** &nbsp;·&nbsp; [documentación](https://yakhyo.github.io/uniface/modules/headpose/)
-
-<img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/headpose.jpg" width="100%">
-
-**Estimación de la mirada** &nbsp;·&nbsp; [documentación](https://yakhyo.github.io/uniface/modules/gaze/)
-
-<img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/gaze.jpg" width="100%">
-
-### Analizar atributos faciales
-
-**Edad y sexo** &nbsp;·&nbsp; [documentación](https://yakhyo.github.io/uniface/modules/attributes/)
-
-<img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/demography.jpg" width="100%">
-
-**Emoción** &nbsp;·&nbsp; [documentación](https://yakhyo.github.io/uniface/modules/attributes/#emotion)
-
-<img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/emotion.jpg" width="100%">
-
-**Estados del rostro** &nbsp;·&nbsp; [documentación](https://yakhyo.github.io/uniface/modules/attributes/#faceattribnet)
-
-<img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/face_states.jpg" width="100%">
-
-<img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/face_states_alt.jpg" width="100%">
-
-### Distinguir un rostro real de una reproducción
-
-**Detección de suplantación facial** &nbsp;·&nbsp; [documentación](https://yakhyo.github.io/uniface/modules/spoofing/)
-
-<img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/spoofing.jpg" width="100%">
-
-### Comparar rostros o anonimizarlos
-
-**Reconocimiento facial** &nbsp;·&nbsp; [documentación](https://yakhyo.github.io/uniface/modules/recognition/)
-
-<img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/verification.jpg" width="100%">
-
-**Anonimización facial** &nbsp;·&nbsp; [documentación](https://yakhyo.github.io/uniface/modules/privacy/)
-
-<img src="https://raw.githubusercontent.com/yakhyo/uniface/main/assets/demo/anonymization.jpg" width="100%">
-
-<br>
-
-<div align="center">
-
-**[Primeros pasos](https://yakhyo.github.io/uniface/quickstart/)** &nbsp;·&nbsp;
-[Catálogo de modelos](https://yakhyo.github.io/uniface/models/) &nbsp;·&nbsp;
-[Cuadernos](https://yakhyo.github.io/uniface/notebooks/) &nbsp;·&nbsp;
-[Licencias de los modelos](https://yakhyo.github.io/uniface/license-attribution/) &nbsp;·&nbsp;
-[Contribuir](CONTRIBUTING.md) &nbsp;·&nbsp;
-[Discord](https://discord.gg/wdzrjr7R5j) &nbsp;·&nbsp;
-[Incidencias](https://github.com/yakhyo/uniface/issues)
-
-Funciona en CPU, Apple Silicon y CUDA. Los pesos se descargan al usarlos por primera vez y se verifican con SHA-256.<br>
-UniFace se distribuye bajo la licencia [MIT](LICENSE); algunos pesos preentrenados tienen otras licencias, así que consulta las
-[licencias](https://yakhyo.github.io/uniface/license-attribution/) antes de distribuirlo comercialmente.<br>
-Este proyecto no está afiliado a [Uniface](https://uniface.com/) de Rocket Software.
-
-</div>
diff --git a/README.ko.md b/README.ko.md
index d0e0411..f30bfec 100644
--- a/README.ko.md
+++ b/README.ko.md
@@ -1,4 +1,4 @@
-\[[English](README.md)\] | \[[Chinese](README.zh-CN.md)\] | \[[Korean](README.ko.md)\] | \[[Spanish](README.es.md)\] | \[[Uzbek](README.uz.md)\]
+\[[English](README.md)\] | \[[Chinese](README.zh-CN.md)\] | \[[Korean](README.ko.md)\] | \[[Uzbek](README.uz.md)\]
<h1 align="center">UniFace: Python용 통합 얼굴 분석 라이브러리</h1>
diff --git a/README.md b/README.md
index 435902d..41a52d6 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-\[[English](README.md)\] | \[[Chinese](README.zh-CN.md)\] | \[[Korean](README.ko.md)\] | \[[Spanish](README.es.md)\] | \[[Uzbek](README.uz.md)\]
+\[[English](README.md)\] | \[[Chinese](README.zh-CN.md)\] | \[[Korean](README.ko.md)\] | \[[Uzbek](README.uz.md)\]
<h1 align="center">UniFace: A Unified Face Analysis Library for Python</h1>
diff --git a/README.uz.md b/README.uz.md
index a4479b8..773850c 100644
--- a/README.uz.md
+++ b/README.uz.md
@@ -1,4 +1,4 @@
-\[[English](README.md)\] | \[[Chinese](README.zh-CN.md)\] | \[[Korean](README.ko.md)\] | \[[Spanish](README.es.md)\] | \[[Uzbek](README.uz.md)\]
+\[[English](README.md)\] | \[[Chinese](README.zh-CN.md)\] | \[[Korean](README.ko.md)\] | \[[Uzbek](README.uz.md)\]
<h1 align="center">UniFace: Python uchun yagona yuz tahlili kutubxonasi</h1>
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 0392aff..161af29 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -1,4 +1,4 @@
-\[[English](README.md)\] | \[[Chinese](README.zh-CN.md)\] | \[[Korean](README.ko.md)\] | \[[Spanish](README.es.md)\] | \[[Uzbek](README.uz.md)\]
+\[[English](README.md)\] | \[[Chinese](README.zh-CN.md)\] | \[[Korean](README.ko.md)\] | \[[Uzbek](README.uz.md)\]
<h1 align="center">UniFace:统一的 Python 人脸分析库</h1>
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 4684a78..3f2c173 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -13,7 +13,7 @@ models you hand it. Start here if you want a whole pipeline rather than one mode
import cv2
from uniface import FaceAnalyzer
-analyzer = FaceAnalyzer() # SCRFD + ArcFace by default, no arguments needed
+analyzer = FaceAnalyzer() # RetinaFace + EdgeFace by default, no arguments needed
faces = analyzer.analyze(cv2.imread("photo.jpg"))
for face in faces:
diff --git a/tests/test_analyzer.py b/tests/test_analyzer.py
index fd54e53..f1c8af1 100644
--- a/tests/test_analyzer.py
+++ b/tests/test_analyzer.py
@@ -121,3 +121,14 @@ def test_repr_lists_predictors():
def test_constructor_is_keyword_only():
with pytest.raises(TypeError):
FaceAnalyzer(StubDetector())
+
+
+def test_defaults_use_permissively_licensed_weights():
+ """InsightFace weights (SCRFD, ArcFace) are non-commercial, so they must stay opt-in."""
+ from uniface.detection import RetinaFace
+ from uniface.recognition import EdgeFace
+
+ analyzer = FaceAnalyzer()
+
+ assert isinstance(analyzer.detector, RetinaFace)
+ assert isinstance(analyzer.recognizer, EdgeFace)
diff --git a/tests/test_detector_base.py b/tests/test_detector_base.py
index 8421d74..ae537fc 100644
--- a/tests/test_detector_base.py
+++ b/tests/test_detector_base.py
@@ -42,7 +42,7 @@ def test_capability_flags_are_opt_in():
def test_analyzer_disables_recognition_for_box_only_detector():
- """A boxes-only detector must take the recognition-disabled branch, not load ArcFace."""
+ """A boxes-only detector must take the recognition-disabled branch, not load EdgeFace."""
analyzer = FaceAnalyzer(detector=BoxOnlyDetector())
assert analyzer.recognizer is None
diff --git a/uniface/analyzer.py b/uniface/analyzer.py
index c12c7ad..60122f0 100644
--- a/uniface/analyzer.py
+++ b/uniface/analyzer.py
@@ -9,8 +9,11 @@ from typing import Any
import numpy as np
from uniface.attribute.base import BaseAttribute
+from uniface.constants import EdgeFaceWeights, RetinaFaceWeights
+from uniface.detection import RetinaFace
from uniface.detection.base import BaseDetector
from uniface.log import Logger
+from uniface.recognition import EdgeFace
from uniface.recognition.base import BaseRecognizer
from uniface.types import Face
@@ -31,13 +34,13 @@ class FaceAnalyzer:
via the `predictors` list. Each predictor's `predict(image, face)`
is called once per detected face, enriching the `Face` in-place.
- When called with no arguments, uses SCRFD (500M) for detection and
- ArcFace (MobileNet) for recognition — the smallest and fastest variants.
+ When called with no arguments, uses RetinaFace (MobileNetV2) for detection
+ and EdgeFace (XXS) for recognition.
Args:
- detector: Face detector instance. Defaults to `SCRFD(SCRFD_500M_KPS)`.
+ detector: Face detector instance. Defaults to `RetinaFace(MNET_V2)`.
recognizer: Face recognizer for extracting embeddings.
- Defaults to `ArcFace(MNET)`. Pass `None` to disable recognition.
+ Defaults to `EdgeFace(XXS)`. Pass `None` to disable recognition.
predictors: Optional list of `BaseAttribute` predictors to run on
each detected face (e.g. `[AgeGender()]`).
@@ -59,10 +62,7 @@ class FaceAnalyzer:
predictors: list[BaseAttribute] | None = None,
) -> None:
if detector is None:
- from uniface.constants import SCRFDWeights
- from uniface.detection import SCRFD
-
- detector = SCRFD(model_name=SCRFDWeights.SCRFD_500M_KPS)
+ detector = RetinaFace(model_name=RetinaFaceWeights.MNET_V2)
# Checked before the _UNSET branch below so an unusable recognizer is never loaded.
if not getattr(detector, 'supports_alignment', False):
@@ -75,9 +75,7 @@ class FaceAnalyzer:
recognizer = None
if recognizer is _UNSET:
- from uniface.recognition import ArcFace
-
- recognizer = ArcFace()
+ recognizer = EdgeFace(model_name=EdgeFaceWeights.XXS)
self.detector = detector
self.recognizer = recognizer