{"id":34086587,"url":"https://github.com/yakhyo/uniface","last_synced_at":"2026-02-14T16:26:39.621Z","repository":{"id":263550454,"uuid":"888286802","full_name":"yakhyo/uniface","owner":"yakhyo","description":"UniFace: An All-in-One Open-Source Face Analysis Library - Face Detection, Face Recognition, Landmark Localization, Face Parsing, Gaze Estimation, and Attribute Estimation (Age, Gender, Race)","archived":false,"fork":false,"pushed_at":"2026-02-11T15:20:57.000Z","size":62901,"stargazers_count":545,"open_issues_count":7,"forks_count":69,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-02-11T23:59:11.421Z","etag":null,"topics":["age-gender-estimation","arcface","face-alignment","face-analysis","face-detection","face-emotion-detection","face-landmark-detection","face-mask","face-parsing","face-recognition","face-segmentation","gaze-estimation","headpose-estimation","onnxruntime","retinaface","scrfd","sphereface","yoloface"],"latest_commit_sha":null,"homepage":"https://yakhyo.github.io/uniface/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yakhyo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-14T06:12:34.000Z","updated_at":"2026-02-11T15:20:28.000Z","dependencies_parsed_at":"2025-01-09T06:34:51.740Z","dependency_job_id":"ee6c9c9c-4fc0-4d25-89bc-2f78c0fdf65f","html_url":"https://github.com/yakhyo/uniface","commit_stats":null,"previous_names":["yakhyo/retinaface","yakhyo/retinafacex","yakhyo/uniface"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/yakhyo/uniface","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yakhyo%2Funiface","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yakhyo%2Funiface/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yakhyo%2Funiface/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yakhyo%2Funiface/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yakhyo","download_url":"https://codeload.github.com/yakhyo/uniface/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yakhyo%2Funiface/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29449369,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T15:52:44.973Z","status":"ssl_error","status_checked_at":"2026-02-14T15:52:11.208Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["age-gender-estimation","arcface","face-alignment","face-analysis","face-detection","face-emotion-detection","face-landmark-detection","face-mask","face-parsing","face-recognition","face-segmentation","gaze-estimation","headpose-estimation","onnxruntime","retinaface","scrfd","sphereface","yoloface"],"created_at":"2025-12-14T13:30:32.925Z","updated_at":"2026-02-14T16:26:39.616Z","avatar_url":"https://github.com/yakhyo.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eUniFace: All-in-One Face Analysis Library\u003c/h1\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![PyPI Version](https://img.shields.io/pypi/v/uniface.svg?label=Version)](https://pypi.org/project/uniface/)\n[![Python Version](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Github Build Status](https://github.com/yakhyo/uniface/actions/workflows/ci.yml/badge.svg)](https://github.com/yakhyo/uniface/actions)\n[![PyPI Downloads](https://static.pepy.tech/personalized-badge/uniface?period=total\u0026units=INTERNATIONAL_SYSTEM\u0026left_color=GRAY\u0026right_color=BLUE\u0026left_text=Downloads)](https://pepy.tech/projects/uniface)\n[![UniFace Documentation](https://img.shields.io/badge/Docs-UniFace-blue.svg)](https://yakhyo.github.io/uniface/)\n[![Kaggle Badge](https://img.shields.io/badge/Notebooks-Kaggle?label=Kaggle\u0026color=blue)](https://www.kaggle.com/yakhyokhuja/code)\n[![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?logo=discord\u0026logoColor=white)](https://discord.gg/wdzrjr7R5j)\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg 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\"\u003e\n\u003c/div\u003e\n\n---\n\n**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.\n\n---\n\n## Features\n\n- **Face Detection** — RetinaFace, SCRFD, YOLOv5-Face, and YOLOv8-Face with 5-point landmarks\n- **Face Recognition** — ArcFace, MobileFace, and SphereFace embeddings\n- **Face Tracking** — Multi-object tracking with [BYTETracker](https://github.com/yakhyo/bytetrack-tracker) for persistent IDs across video frames\n- **Facial Landmarks** — 106-point landmark localization module (separate from 5-point detector landmarks)\n- **Face Parsing** — BiSeNet semantic segmentation (19 classes), XSeg face masking\n- **Gaze Estimation** — Real-time gaze direction with MobileGaze\n- **Attribute Analysis** — Age, gender, race (FairFace), and emotion\n- **Anti-Spoofing** — Face liveness detection with MiniFASNet\n- **Face Anonymization** — 5 blur methods for privacy protection\n- **Hardware Acceleration** — ARM64 (Apple Silicon), CUDA (NVIDIA), CPU\n\n---\n\n## Installation\n\n**Standard installation**\n\n```bash\npip install uniface\n```\n\n**GPU support (CUDA)**\n\n```bash\npip install uniface[gpu]\n```\n\n**From source (latest version)**\n\n```bash\ngit clone https://github.com/yakhyo/uniface.git\ncd uniface \u0026\u0026 pip install -e .\n```\n\n**Optional dependencies**\n- Emotion model uses TorchScript and requires `torch`:\n  `pip install torch` (choose the correct build for your OS/CUDA)\n- YOLOv5-Face and YOLOv8-Face support faster NMS with `torchvision`:\n  `pip install torch torchvision` then use `nms_mode='torchvision'`\n\n---\n\n## Model Downloads and Cache\n\nModels are downloaded automatically on first use and verified via SHA-256.\n\nDefault cache location: `~/.uniface/models`\n\nOverride with the programmatic API or environment variable:\n\n```python\nfrom uniface.model_store import get_cache_dir, set_cache_dir\n\nset_cache_dir('/data/models')\nprint(get_cache_dir())  # /data/models\n```\n\n```bash\nexport UNIFACE_CACHE_DIR=/data/models\n```\n\n---\n\n## Quick Example (Detection)\n\n```python\nimport cv2\nfrom uniface.detection import RetinaFace\n\ndetector = RetinaFace()\n\nimage = cv2.imread(\"photo.jpg\")\nif image is None:\n    raise ValueError(\"Failed to load image. Check the path to 'photo.jpg'.\")\n\nfaces = detector.detect(image)\n\nfor face in faces:\n    print(f\"Confidence: {face.confidence:.2f}\")\n    print(f\"BBox: {face.bbox}\")\n    print(f\"Landmarks: {face.landmarks.shape}\")\n```\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/yakhyo/uniface/main/assets/test_result.png\" width=\"90%\"\u003e\n    \u003cp\u003eFace Detection Model Output\u003c/p\u003e\n\u003c/div\u003e\n\n---\n\n## Example (Face Analyzer)\n\n```python\nimport cv2\nfrom uniface.analyzer import FaceAnalyzer\nfrom uniface.detection import RetinaFace\nfrom uniface.recognition import ArcFace\n\ndetector = RetinaFace()\nrecognizer = ArcFace()\n\nanalyzer = FaceAnalyzer(detector, recognizer=recognizer)\n\nimage = cv2.imread(\"photo.jpg\")\nif image is None:\n    raise ValueError(\"Failed to load image. Check the path to 'photo.jpg'.\")\n\nfaces = analyzer.analyze(image)\n\nfor face in faces:\n    print(face.bbox, face.embedding.shape if face.embedding is not None else None)\n```\n\n---\n\n## Execution Providers (ONNX Runtime)\n\n```python\nfrom uniface.detection import RetinaFace\n\n# Force CPU-only inference\ndetector = RetinaFace(providers=[\"CPUExecutionProvider\"])\n```\n\nSee more in the docs:\nhttps://yakhyo.github.io/uniface/concepts/execution-providers/\n\n---\n\n## Documentation\n\nFull documentation: https://yakhyo.github.io/uniface/\n\n| Resource | Description |\n|----------|-------------|\n| [Quickstart](https://yakhyo.github.io/uniface/quickstart/) | Get up and running in 5 minutes |\n| [Model Zoo](https://yakhyo.github.io/uniface/models/) | All models, benchmarks, and selection guide |\n| [API Reference](https://yakhyo.github.io/uniface/modules/detection/) | Detailed module documentation |\n| [Tutorials](https://yakhyo.github.io/uniface/recipes/image-pipeline/) | Step-by-step workflow examples |\n| [Guides](https://yakhyo.github.io/uniface/concepts/overview/) | Architecture and design principles |\n\n---\n\n## Jupyter Notebooks\n\n| Example | Colab | Description |\n|---------|:-----:|-------------|\n| [01_face_detection.ipynb](examples/01_face_detection.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/01_face_detection.ipynb) | Face detection and landmarks |\n| [02_face_alignment.ipynb](examples/02_face_alignment.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/02_face_alignment.ipynb) | Face alignment for recognition |\n| [03_face_verification.ipynb](examples/03_face_verification.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/03_face_verification.ipynb) | Compare faces for identity |\n| [04_face_search.ipynb](examples/04_face_search.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/04_face_search.ipynb) | Find a person in group photos |\n| [05_face_analyzer.ipynb](examples/05_face_analyzer.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/05_face_analyzer.ipynb) | All-in-one analysis |\n| [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 |\n| [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 |\n| [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 |\n| [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 |\n\n---\n\n## Licensing and Model Usage\n\nUniFace is MIT-licensed, but several pretrained models carry their own licenses.\nReview: https://yakhyo.github.io/uniface/license-attribution/\n\nNotable examples:\n- YOLOv5-Face and YOLOv8-Face weights are GPL-3.0\n- FairFace weights are CC BY 4.0\n\nIf you plan commercial use, verify model license compatibility.\n\n---\n\n## References\n\n| Feature | Repository | Training | Description |\n|---------|------------|:--------:|-------------|\n| Detection | [retinaface-pytorch](https://github.com/yakhyo/retinaface-pytorch) | ✓ | RetinaFace PyTorch Training \u0026 Export |\n| Detection | [yolov5-face-onnx-inference](https://github.com/yakhyo/yolov5-face-onnx-inference) | - | YOLOv5-Face ONNX Inference |\n| Detection | [yolov8-face-onnx-inference](https://github.com/yakhyo/yolov8-face-onnx-inference) | - | YOLOv8-Face ONNX Inference |\n| Tracking | [bytetrack-tracker](https://github.com/yakhyo/bytetrack-tracker) | - | BYTETracker Multi-Object Tracking |\n| Recognition | [face-recognition](https://github.com/yakhyo/face-recognition) | ✓ | MobileFace, SphereFace Training |\n| Parsing | [face-parsing](https://github.com/yakhyo/face-parsing) | ✓ | BiSeNet Face Parsing |\n| Parsing | [face-segmentation](https://github.com/yakhyo/face-segmentation) | - | XSeg Face Segmentation |\n| Gaze | [gaze-estimation](https://github.com/yakhyo/gaze-estimation) | ✓ | MobileGaze Training |\n| Anti-Spoofing | [face-anti-spoofing](https://github.com/yakhyo/face-anti-spoofing) | - | MiniFASNet Inference |\n| Attributes | [fairface-onnx](https://github.com/yakhyo/fairface-onnx) | - | FairFace ONNX Inference |\n\n*SCRFD and ArcFace models are from [InsightFace](https://github.com/deepinsight/insightface).\n\n---\n\n## Contributing\n\nContributions are welcome. Please see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Support\n\nIf you find this project useful, consider giving it a ⭐ on GitHub — it helps others discover it!\n\nQuestions or feedback:\n- Discord: https://discord.gg/wdzrjr7R5j\n- GitHub Issues: https://github.com/yakhyo/uniface/issues\n- DeepWiki Q\u0026A: https://deepwiki.com/yakhyo/uniface\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyakhyo%2Funiface","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyakhyo%2Funiface","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyakhyo%2Funiface/lists"}