uniface 0.1.4__tar.gz

uniface-0.1.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Yakhyokhuja Valikhujaev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

uniface-0.1.4/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.1
+Name: uniface
+Version: 0.1.4
+Summary: UniFace: A Comprehensive Library for Face Detection, Recognition, Landmark Analysis, Age, and Gender Detection
+Home-page: https://github.com/yakhyo/uniface
+Author: Yakhyokhuja Valikhujaev
+Author-email: yakhyo9696@gmail.com
+License: MIT
+Keywords: face detection,face recognition,facial landmark,facial attribute,onnx,opencv,retinaface
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Requires-Dist: onnx
+Requires-Dist: onnxruntime
+Requires-Dist: requests
+Requires-Dist: torch
+Requires-Dist: scikit-image
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# UniFace: All-in-One Face Analysis Library
+
+
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+![Python](https://img.shields.io/badge/Python-3.8%2B-blue)
+[![PyPI Version](https://img.shields.io/pypi/v/uniface.svg)](https://pypi.org/project/uniface/)
+[![Build Status](https://github.com/yakhyo/uniface/actions/workflows/build.yml/badge.svg)](https://github.com/yakhyo/uniface/actions)
+[![Downloads](https://pepy.tech/badge/uniface)](https://pepy.tech/project/uniface)
+[![Code Style: PEP8](https://img.shields.io/badge/code%20style-PEP8-green.svg)](https://www.python.org/dev/peps/pep-0008/)
+[![GitHub Release Downloads](https://img.shields.io/github/downloads/yakhyo/uniface/total.svg?label=Model%20Downloads)](https://github.com/yakhyo/uniface/releases)
+
+
+**uniface** is a lightweight face detection library designed for high-performance face localization, landmark detection and face alignment. The library supports ONNX models and provides utilities for bounding box visualization and landmark plotting. To train RetinaFace model, see https://github.com/yakhyo/retinaface-pytorch.
+
+---
+
+## Features
+
+- [ ] Age and gender detection (Planned).
+- [ ] Face recognition (Planned).
+- [x] Face Alignment (Added: 2024-11-21).
+- [x] High-speed face detection using ONNX models (Added: 2024-11-20).
+- [x] Accurate facial landmark localization (e.g., eyes, nose, and mouth) (Added: 2024-11-20).
+- [x] Easy-to-use API for inference and visualization (Added: 2024-11-20).
+
+---
+
+## Installation
+
+The easiest way to install **UniFace** is via [PyPI](https://pypi.org/project/uniface/). This will automatically install the library along with its prerequisites.
+
+```bash
+pip install uniface
+```
+
+To work with the latest version of **UniFace**, which may not yet be released on PyPI, you can install it directly from the repository:
+
+```bash
+git clone https://github.com/yakhyo/uniface.git
+cd uniface
+pip install .
+```
+
+---
+
+## Quick Start
+
+To get started with face detection using **UniFace**, check out the [example notebook](examples/face_detection.ipynb).
+It demonstrates how to initialize the model, run inference, and visualize the results.
+
+---
+
+## Examples
+
+Explore the following example notebooks to learn how to use **UniFace** effectively:
+
+- [Face Detection](examples/face_detection.ipynb): Demonstrates how to perform face detection, draw bounding boxes, and landmarks on an image.
+- [Face Alignment](examples/face_alignment.ipynb): Shows how to align faces using detected landmarks.
+- [Age and Gender Detection](examples/age_gender.ipynb): Example for detecting age and gender from faces. (underdevelopment)
+
+### Initialize the Model
+
+```python
+from uniface import RetinaFace
+
+# Initialize the RetinaFace model
+uniface_inference = RetinaFace(
+    model="retinaface_mnet_v2",  # Model name
+    conf_thresh=0.5,             # Confidence threshold
+    pre_nms_topk=5000,           # Pre-NMS Top-K detections
+    nms_thresh=0.4,              # NMS IoU threshold
+    post_nms_topk=750            # Post-NMS Top-K detections
+)
+```
+
+### Run Inference
+
+Inference on image:
+
+```python
+import cv2
+from uniface.visualization import draw_detections
+
+# Load an image
+image_path = "assets/test.jpg"
+original_image = cv2.imread(image_path)
+
+# Perform inference
+boxes, landmarks = uniface_inference.detect(original_image)
+
+# Visualize results
+draw_detections(original_image, (boxes, landmarks), vis_threshold=0.6)
+
+# Save the output image
+output_path = "output.jpg"
+cv2.imwrite(output_path, original_image)
+print(f"Saved output image to {output_path}")
+```
+
+Inference on video:
+
+```python
+import cv2
+from uniface.visualization import draw_detections
+
+# Initialize the webcam
+cap = cv2.VideoCapture(0)
+
+if not cap.isOpened():
+    print("Error: Unable to access the webcam.")
+    exit()
+
+while True:
+    # Capture a frame from the webcam
+    ret, frame = cap.read()
+    if not ret:
+        print("Error: Failed to read frame.")
+        break
+
+    # Perform inference
+    boxes, landmarks = uniface_inference.detect(frame)
+
+    # Draw detections on the frame
+    draw_detections(frame, (boxes, landmarks), vis_threshold=0.6)
+
+    # Display the output
+    cv2.imshow("Webcam Inference", frame)
+
+    # Exit if 'q' is pressed
+    if cv2.waitKey(1) & 0xFF == ord('q'):
+        break
+
+# Release the webcam and close all OpenCV windows
+cap.release()
+cv2.destroyAllWindows()
+```
+
+---
+
+### Evaluation results of available models on WiderFace
+
+| RetinaFace Models  | Easy       | Medium     | Hard       |
+| ------------------ | ---------- | ---------- | ---------- |
+| retinaface_mnet025 | 88.48%     | 87.02%     | 80.61%     |
+| retinaface_mnet050 | 89.42%     | 87.97%     | 82.40%     |
+| retinaface_mnet_v1 | 90.59%     | 89.14%     | 84.13%     |
+| retinaface_mnet_v2 | 91.70%     | 91.03%     | 86.60%     |
+| retinaface_r18     | 92.50%     | 91.02%     | 86.63%     |
+| retinaface_r34     | **94.16%** | **93.12%** | **88.90%** |
+
+## API Reference
+
+### `RetinaFace` Class
+
+#### Initialization
+
+```python
+RetinaFace(
+    model: str,
+    conf_thresh: float = 0.5,
+    pre_nms_topk: int = 5000,
+    nms_thresh: float = 0.4,
+    post_nms_topk: int = 750
+)
+```
+
+**Parameters**:
+
+- `model` _(str)_: Name of the model to use. Supported models:
+  - `retinaface_mnet025`, `retinaface_mnet050`, `retinaface_mnet_v1`, `retinaface_mnet_v2`
+  - `retinaface_r18`, `retinaface_r34`
+- `conf_thresh` _(float, default=0.5)_: Minimum confidence score for detections.
+- `pre_nms_topk` _(int, default=5000)_: Max detections to keep before NMS.
+- `nms_thresh` _(float, default=0.4)_: IoU threshold for Non-Maximum Suppression.
+- `post_nms_topk` _(int, default=750)_: Max detections to keep after NMS.
+
+---
+
+### `detect` Method
+
+```python
+detect(
+    image: np.ndarray,
+    max_num: int = 0,
+    metric: str = "default",
+    center_weight: float = 2.0
+) -> Tuple[np.ndarray, np.ndarray]
+```
+
+**Description**:
+Detects faces in the given image and returns bounding boxes and landmarks.
+
+**Parameters**:
+
+- `image` _(np.ndarray)_: Input image in BGR format.
+- `max_num` _(int, default=0)_: Maximum number of faces to return. `0` means return all.
+- `metric` _(str, default="default")_: Metric for prioritizing detections:
+  - `"default"`: Prioritize detections closer to the image center.
+  - `"max"`: Prioritize larger bounding box areas.
+- `center_weight` _(float, default=2.0)_: Weight for prioritizing center-aligned faces.
+
+**Returns**:
+
+- `bounding_boxes` _(np.ndarray)_: Array of detections as `[x_min, y_min, x_max, y_max, confidence]`.
+- `landmarks` _(np.ndarray)_: Array of landmarks as `[(x1, y1), ..., (x5, y5)]`.
+
+---
+
+### Visualization Utilities
+
+#### `draw_detections`
+
+```python
+draw_detections(
+    image: np.ndarray,
+    detections: Tuple[np.ndarray, np.ndarray],
+    vis_threshold: float
+) -> None
+```
+
+**Description**:
+Draws bounding boxes and landmarks on the given image.
+
+**Parameters**:
+
+- `image` _(np.ndarray)_: The input image in BGR format.
+- `detections` _(Tuple[np.ndarray, np.ndarray])_: A tuple of bounding boxes and landmarks.
+- `vis_threshold` _(float)_: Minimum confidence score for visualization.
+
+---
+
+## Contributing
+
+We welcome contributions to enhance the library! Feel free to:
+
+- Submit bug reports or feature requests.
+- Fork the repository and create a pull request.
+
+---
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+---
+
+## Acknowledgments
+
+- Based on the RetinaFace model for face detection ([https://github.com/yakhyo/retinaface-pytorch](https://github.com/yakhyo/retinaface-pytorch)).
+- Inspired by InsightFace and other face detection projects.
+
+---

uniface-0.1.4/README.md

@@ -0,0 +1,252 @@
+# UniFace: All-in-One Face Analysis Library
+
+
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+![Python](https://img.shields.io/badge/Python-3.8%2B-blue)
+[![PyPI Version](https://img.shields.io/pypi/v/uniface.svg)](https://pypi.org/project/uniface/)
+[![Build Status](https://github.com/yakhyo/uniface/actions/workflows/build.yml/badge.svg)](https://github.com/yakhyo/uniface/actions)
+[![Downloads](https://pepy.tech/badge/uniface)](https://pepy.tech/project/uniface)
+[![Code Style: PEP8](https://img.shields.io/badge/code%20style-PEP8-green.svg)](https://www.python.org/dev/peps/pep-0008/)
+[![GitHub Release Downloads](https://img.shields.io/github/downloads/yakhyo/uniface/total.svg?label=Model%20Downloads)](https://github.com/yakhyo/uniface/releases)
+
+
+**uniface** is a lightweight face detection library designed for high-performance face localization, landmark detection and face alignment. The library supports ONNX models and provides utilities for bounding box visualization and landmark plotting. To train RetinaFace model, see https://github.com/yakhyo/retinaface-pytorch.
+
+---
+
+## Features
+
+- [ ] Age and gender detection (Planned).
+- [ ] Face recognition (Planned).
+- [x] Face Alignment (Added: 2024-11-21).
+- [x] High-speed face detection using ONNX models (Added: 2024-11-20).
+- [x] Accurate facial landmark localization (e.g., eyes, nose, and mouth) (Added: 2024-11-20).
+- [x] Easy-to-use API for inference and visualization (Added: 2024-11-20).
+
+---
+
+## Installation
+
+The easiest way to install **UniFace** is via [PyPI](https://pypi.org/project/uniface/). This will automatically install the library along with its prerequisites.
+
+```bash
+pip install uniface
+```
+
+To work with the latest version of **UniFace**, which may not yet be released on PyPI, you can install it directly from the repository:
+
+```bash
+git clone https://github.com/yakhyo/uniface.git
+cd uniface
+pip install .
+```
+
+---
+
+## Quick Start
+
+To get started with face detection using **UniFace**, check out the [example notebook](examples/face_detection.ipynb).
+It demonstrates how to initialize the model, run inference, and visualize the results.
+
+---
+
+## Examples
+
+Explore the following example notebooks to learn how to use **UniFace** effectively:
+
+- [Face Detection](examples/face_detection.ipynb): Demonstrates how to perform face detection, draw bounding boxes, and landmarks on an image.
+- [Face Alignment](examples/face_alignment.ipynb): Shows how to align faces using detected landmarks.
+- [Age and Gender Detection](examples/age_gender.ipynb): Example for detecting age and gender from faces. (underdevelopment)
+
+### Initialize the Model
+
+```python
+from uniface import RetinaFace
+
+# Initialize the RetinaFace model
+uniface_inference = RetinaFace(
+    model="retinaface_mnet_v2",  # Model name
+    conf_thresh=0.5,             # Confidence threshold
+    pre_nms_topk=5000,           # Pre-NMS Top-K detections
+    nms_thresh=0.4,              # NMS IoU threshold
+    post_nms_topk=750            # Post-NMS Top-K detections
+)
+```
+
+### Run Inference
+
+Inference on image:
+
+```python
+import cv2
+from uniface.visualization import draw_detections
+
+# Load an image
+image_path = "assets/test.jpg"
+original_image = cv2.imread(image_path)
+
+# Perform inference
+boxes, landmarks = uniface_inference.detect(original_image)
+
+# Visualize results
+draw_detections(original_image, (boxes, landmarks), vis_threshold=0.6)
+
+# Save the output image
+output_path = "output.jpg"
+cv2.imwrite(output_path, original_image)
+print(f"Saved output image to {output_path}")
+```
+
+Inference on video:
+
+```python
+import cv2
+from uniface.visualization import draw_detections
+
+# Initialize the webcam
+cap = cv2.VideoCapture(0)
+
+if not cap.isOpened():
+    print("Error: Unable to access the webcam.")
+    exit()
+
+while True:
+    # Capture a frame from the webcam
+    ret, frame = cap.read()
+    if not ret:
+        print("Error: Failed to read frame.")
+        break
+
+    # Perform inference
+    boxes, landmarks = uniface_inference.detect(frame)
+
+    # Draw detections on the frame
+    draw_detections(frame, (boxes, landmarks), vis_threshold=0.6)
+
+    # Display the output
+    cv2.imshow("Webcam Inference", frame)
+
+    # Exit if 'q' is pressed
+    if cv2.waitKey(1) & 0xFF == ord('q'):
+        break
+
+# Release the webcam and close all OpenCV windows
+cap.release()
+cv2.destroyAllWindows()
+```
+
+---
+
+### Evaluation results of available models on WiderFace
+
+| RetinaFace Models  | Easy       | Medium     | Hard       |
+| ------------------ | ---------- | ---------- | ---------- |
+| retinaface_mnet025 | 88.48%     | 87.02%     | 80.61%     |
+| retinaface_mnet050 | 89.42%     | 87.97%     | 82.40%     |
+| retinaface_mnet_v1 | 90.59%     | 89.14%     | 84.13%     |
+| retinaface_mnet_v2 | 91.70%     | 91.03%     | 86.60%     |
+| retinaface_r18     | 92.50%     | 91.02%     | 86.63%     |
+| retinaface_r34     | **94.16%** | **93.12%** | **88.90%** |
+
+## API Reference
+
+### `RetinaFace` Class
+
+#### Initialization
+
+```python
+RetinaFace(
+    model: str,
+    conf_thresh: float = 0.5,
+    pre_nms_topk: int = 5000,
+    nms_thresh: float = 0.4,
+    post_nms_topk: int = 750
+)
+```
+
+**Parameters**:
+
+- `model` _(str)_: Name of the model to use. Supported models:
+  - `retinaface_mnet025`, `retinaface_mnet050`, `retinaface_mnet_v1`, `retinaface_mnet_v2`
+  - `retinaface_r18`, `retinaface_r34`
+- `conf_thresh` _(float, default=0.5)_: Minimum confidence score for detections.
+- `pre_nms_topk` _(int, default=5000)_: Max detections to keep before NMS.
+- `nms_thresh` _(float, default=0.4)_: IoU threshold for Non-Maximum Suppression.
+- `post_nms_topk` _(int, default=750)_: Max detections to keep after NMS.
+
+---
+
+### `detect` Method
+
+```python
+detect(
+    image: np.ndarray,
+    max_num: int = 0,
+    metric: str = "default",
+    center_weight: float = 2.0
+) -> Tuple[np.ndarray, np.ndarray]
+```
+
+**Description**:
+Detects faces in the given image and returns bounding boxes and landmarks.
+
+**Parameters**:
+
+- `image` _(np.ndarray)_: Input image in BGR format.
+- `max_num` _(int, default=0)_: Maximum number of faces to return. `0` means return all.
+- `metric` _(str, default="default")_: Metric for prioritizing detections:
+  - `"default"`: Prioritize detections closer to the image center.
+  - `"max"`: Prioritize larger bounding box areas.
+- `center_weight` _(float, default=2.0)_: Weight for prioritizing center-aligned faces.
+
+**Returns**:
+
+- `bounding_boxes` _(np.ndarray)_: Array of detections as `[x_min, y_min, x_max, y_max, confidence]`.
+- `landmarks` _(np.ndarray)_: Array of landmarks as `[(x1, y1), ..., (x5, y5)]`.
+
+---
+
+### Visualization Utilities
+
+#### `draw_detections`
+
+```python
+draw_detections(
+    image: np.ndarray,
+    detections: Tuple[np.ndarray, np.ndarray],
+    vis_threshold: float
+) -> None
+```
+
+**Description**:
+Draws bounding boxes and landmarks on the given image.
+
+**Parameters**:
+
+- `image` _(np.ndarray)_: The input image in BGR format.
+- `detections` _(Tuple[np.ndarray, np.ndarray])_: A tuple of bounding boxes and landmarks.
+- `vis_threshold` _(float)_: Minimum confidence score for visualization.
+
+---
+
+## Contributing
+
+We welcome contributions to enhance the library! Feel free to:
+
+- Submit bug reports or feature requests.
+- Fork the repository and create a pull request.
+
+---
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+---
+
+## Acknowledgments
+
+- Based on the RetinaFace model for face detection ([https://github.com/yakhyo/retinaface-pytorch](https://github.com/yakhyo/retinaface-pytorch)).
+- Inspired by InsightFace and other face detection projects.
+
+---

uniface-0.1.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

uniface-0.1.4/setup.py

@@ -0,0 +1,44 @@
+import os
+from setuptools import setup, find_packages
+
+# Read the README file for the long description
+long_description = ""
+if os.path.exists("README.md"):
+    with open("README.md", "r", encoding="utf-8") as f:
+        long_description = f.read()
+
+setup(
+    name="uniface",
+    version="0.1.4",
+    packages=find_packages(),
+    install_requires=[
+        "numpy",
+        "opencv-python",
+        "onnx",
+        "onnxruntime",
+        "requests",
+        "torch",
+        "scikit-image"
+    ],
+    extras_require={
+        "dev": ["pytest"],
+    },
+    description="UniFace: A Comprehensive Library for Face Detection, Recognition, Landmark Analysis, Age, and Gender Detection",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    author="Yakhyokhuja Valikhujaev",
+    author_email="yakhyo9696@gmail.com",
+    url="https://github.com/yakhyo/uniface",
+    license="MIT",
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+    ],
+    keywords="face detection, face recognition, facial landmark, facial attribute, onnx, opencv, retinaface",
+    python_requires=">=3.8",
+)

uniface-0.1.4/tests/test_retinaface.py

@@ -0,0 +1,78 @@
+import pytest
+import numpy as np
+from uniface import RetinaFace
+
+
+@pytest.fixture
+def retinaface_model():
+    """
+    Fixture to initialize the RetinaFace model for testing.
+    """
+    return RetinaFace(
+        model="retinaface_mnet_v2",
+        conf_thresh=0.5,
+        pre_nms_topk=5000,
+        nms_thresh=0.4,
+        post_nms_topk=750,
+    )
+
+
+def test_model_initialization(retinaface_model):
+    """
+    Test that the RetinaFace model initializes correctly.
+    """
+    assert retinaface_model is not None, "Model initialization failed."
+
+
+def test_inference_on_640x640_image(retinaface_model):
+    """
+    Test inference on a 640x640 BGR image.
+    """
+    # Generate a mock 640x640 BGR image
+    mock_image = np.random.randint(0, 255, (640, 640, 3), dtype=np.uint8)
+
+    # Run inference
+    detections, landmarks = retinaface_model.detect(mock_image)
+
+    # Check output types
+    assert isinstance(detections, np.ndarray), "Detections should be a numpy array."
+    assert isinstance(landmarks, np.ndarray), "Landmarks should be a numpy array."
+
+    # Check that detections have the expected shape
+    if detections.size > 0:  # If faces are detected
+        assert detections.shape[1] == 5, "Each detection should have 5 values (x1, y1, x2, y2, score)."
+
+    # Check landmarks shape
+    if landmarks.size > 0:
+        assert landmarks.shape[1:] == (5, 2), "Landmarks should have shape (N, 5, 2)."
+
+
+def test_confidence_threshold(retinaface_model):
+    """
+    Test that detections respect the confidence threshold.
+    """
+    # Generate a mock 640x640 BGR image
+    mock_image = np.random.randint(0, 255, (640, 640, 3), dtype=np.uint8)
+
+    # Run inference
+    detections, _ = retinaface_model.detect(mock_image)
+
+    # Ensure all detections have confidence scores above the threshold
+    if detections.size > 0:  # If faces are detected
+        confidence_scores = detections[:, 4]
+        assert (confidence_scores >= 0.5).all(), "Some detections have confidence below the threshold."
+
+
+def test_no_faces_detected(retinaface_model):
+    """
+    Test inference on an image without detectable faces.
+    """
+    # Generate an empty (black) 640x640 image
+    empty_image = np.zeros((640, 640, 3), dtype=np.uint8)
+
+    # Run inference
+    detections, landmarks = retinaface_model.detect(empty_image)
+
+    # Ensure no detections or landmarks are found
+    assert detections.size == 0, "Detections should be empty for a blank image."
+    assert landmarks.size == 0, "Landmarks should be empty for a blank image."