fast-face-python 0.1.1__tar.gz

fast_face_python-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xMaulana
+
+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.

fast_face_python-0.1.1/MANIFEST.in

@@ -0,0 +1,6 @@
+global-exclude *.onnx
+
+prune .uv_cache
+prune .ruff_cache
+prune .pytest_cache
+prune .venv

fast_face_python-0.1.1/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: fast-face-python
+Version: 0.1.1
+Summary: Fast and easy face detection using ONNX runtime.
+Author: xMaulana
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: Pillow
+Requires-Dist: opencv-python
+Requires-Dist: pydantic-settings>=2.15.0
+Provides-Extra: cpu
+Requires-Dist: onnxruntime>=1.24.3; extra == "cpu"
+Provides-Extra: gpu
+Requires-Dist: onnxruntime-gpu<=1.26.1,>=1.24.3; extra == "gpu"
+Requires-Dist: nvidia-cudnn-cu12; extra == "gpu"
+Requires-Dist: nvidia-cublas-cu12; extra == "gpu"
+Requires-Dist: nvidia-cuda-runtime-cu12; extra == "gpu"
+Provides-Extra: openvino
+Requires-Dist: onnxruntime-openvino>=1.24.1; extra == "openvino"
+Provides-Extra: rocm
+Requires-Dist: onnxruntime-rocm>=1.22.1; extra == "rocm"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# fast-face-python
+
+Fast and easy face detection using ONNX runtime.
+
+## Overview
+
+fast-face-python provides a unified interface for running face detection and recognition models using ONNX Runtime. It handles model downloading, preprocessing, inference, and post-processing, including non-maximum suppression for detection and alignment for recognition. 
+
+The library supports batched inference and configurable execution providers such as CPU, CUDA, ROCm (AMD GPU), and OpenVINO.
+
+## Features
+
+* Face Detection: YuNet, RetinaFace (MobileNet, ResNet50)
+* Face Recognition: AdaFace (IR18, IR50, IR101)
+* Hardware Acceleration: CPU, CUDA, ROCm (AMD GPU), and OpenVINO support via ONNX Runtime
+* Batched Inference: Process multiple images simultaneously
+* Automatic Model Management: Downloads required ONNX model weights on first use
+
+## Requirements
+
+* Python >= 3.11
+* OpenCV
+* NumPy
+* Pillow
+* ONNX Runtime
+
+## Installation
+
+Install the package using pip:
+
+```bash
+pip install fast-face-python
+```
+
+For NVIDIA GPU support via CUDA 12:
+
+```bash
+pip install "fast-face-python[gpu]"
+```
+
+For AMD GPU support via ROCm:
+
+```bash
+pip install "fast-face-python[rocm]"
+```
+
+For OpenVINO support:
+
+```bash
+pip install "fast-face-python[openvino]"
+```
+
+## Usage
+
+### Face Detection
+
+Instantiate a detection model using `FaceModelFactory` and call the `detect` method. The method accepts an image path, a NumPy array in RGB format, or a list of either.
+
+```python
+from fast_face import FaceModelFactory
+
+# Initialize the model (weights are downloaded automatically if missing)
+model = FaceModelFactory.get_model("YUNET", top_k=500, conf_threshold=0.6)
+
+# Run detection on a local image file
+results = model.detect("image.jpg", return_dict=True)
+
+# Process the detections for the first image
+for det in results[0]:
+    bbox = det["bbox"]
+    confidence = det["score"]
+    landmarks = det["landmarks"]
+    print(f"Face detected at {bbox} with confidence {confidence}")
+```
+
+To run inference on an existing OpenCV image, convert it to RGB first:
+
+```python
+import cv2
+
+img = cv2.imread("image.jpg")
+img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+
+results = model.detect(img_rgb, return_dict=True)
+```
+
+### Face Recognition
+
+Recognition models extract L2-normalized embeddings from aligned face images.
+
+```python
+import numpy as np
+from fast_face import FaceModelFactory
+
+model = FaceModelFactory.get_model("ADAFACE_IR50")
+
+# Provide pre-aligned 112x112 RGB face crops
+face_crop1 = np.random.randint(0, 255, (112, 112, 3), dtype=np.uint8)
+face_crop2 = np.random.randint(0, 255, (112, 112, 3), dtype=np.uint8)
+
+# Extract embeddings for the batch
+embeddings = model.extract([face_crop1, face_crop2])
+
+print(f"Extracted {embeddings.shape[0]} embeddings of dimension {embeddings.shape[1]}")
+```
+
+If you have unaligned images and face landmarks from a detection model, you can pass the landmarks to automatically align the faces before extraction:
+
+```python
+landmarks = np.array([
+    [200.0, 200.0], [280.0, 200.0], [240.0, 250.0], 
+    [210.0, 300.0], [270.0, 300.0]
+], dtype=np.float32)
+
+embeddings = model.extract([img_rgb], landmarks=[landmarks])
+```
+
+### Execution Providers (Hardware Acceleration)
+
+By default, all models run using CPU (`["CPUExecutionProvider"]`). You can enable hardware acceleration (CUDA, ROCm, OpenVINO, CoreML, etc.) by passing the `providers` argument to `FaceModelFactory.get_model()`:
+
+#### NVIDIA GPU (CUDA)
+
+```python
+model = FaceModelFactory.get_model(
+    "RETINAFACE_RESNET50",
+    providers=["CUDAExecutionProvider", "CPUExecutionProvider"],
+)
+```
+
+#### AMD GPU (ROCm)
+
+```python
+model = FaceModelFactory.get_model(
+    "ADAFACE_IR101",
+    providers=["ROCMExecutionProvider", "CPUExecutionProvider"],
+)
+```
+
+#### Intel OpenVINO
+
+```python
+model = FaceModelFactory.get_model(
+    "YUNET",
+    providers=["OpenVINOExecutionProvider", "CPUExecutionProvider"],
+)
+```
+
+#### Custom Provider Options
+
+You can also pass tuple configurations with custom options (such as device ID or memory limits):
+
+```python
+cuda_provider = (
+    "CUDAExecutionProvider",
+    {
+        "device_id": 0,
+        "arena_extend_strategy": "kNextPowerOfTwo",
+        "gpu_mem_limit": 2 * 1024 * 1024 * 1024,  # 2 GB
+    },
+)
+
+model = FaceModelFactory.get_model(
+    "RETINAFACE_RESNET50",
+    providers=[cuda_provider, "CPUExecutionProvider"],
+)
+```
+
+### Supported Models
+
+The following model identifiers are supported by `FaceModelFactory`:
+
+* `YUNET`
+* `RETINAFACE_MOBILENET`
+* `RETINAFACE_RESNET50`
+* `ADAFACE_IR18`
+* `ADAFACE_IR50`
+* `ADAFACE_IR101`
+
+## Development
+
+To set up the repository for development, install the `dev` dependencies:
+
+```bash
+pip install -e ".[dev,cpu]"
+```
+
+### Testing
+
+The project uses `pytest` for testing. Run the test suite:
+
+```bash
+pytest tests/
+```
+
+### Formatting and Linting
+
+The project uses `ruff` for code formatting and linting:
+
+```bash
+ruff check .
+ruff format .
+```
+
+## License
+
+This project is licensed under the terms found in the `LICENSE` file.

fast_face_python-0.1.1/README.md

@@ -0,0 +1,207 @@
+# fast-face-python
+
+Fast and easy face detection using ONNX runtime.
+
+## Overview
+
+fast-face-python provides a unified interface for running face detection and recognition models using ONNX Runtime. It handles model downloading, preprocessing, inference, and post-processing, including non-maximum suppression for detection and alignment for recognition. 
+
+The library supports batched inference and configurable execution providers such as CPU, CUDA, ROCm (AMD GPU), and OpenVINO.
+
+## Features
+
+* Face Detection: YuNet, RetinaFace (MobileNet, ResNet50)
+* Face Recognition: AdaFace (IR18, IR50, IR101)
+* Hardware Acceleration: CPU, CUDA, ROCm (AMD GPU), and OpenVINO support via ONNX Runtime
+* Batched Inference: Process multiple images simultaneously
+* Automatic Model Management: Downloads required ONNX model weights on first use
+
+## Requirements
+
+* Python >= 3.11
+* OpenCV
+* NumPy
+* Pillow
+* ONNX Runtime
+
+## Installation
+
+Install the package using pip:
+
+```bash
+pip install fast-face-python
+```
+
+For NVIDIA GPU support via CUDA 12:
+
+```bash
+pip install "fast-face-python[gpu]"
+```
+
+For AMD GPU support via ROCm:
+
+```bash
+pip install "fast-face-python[rocm]"
+```
+
+For OpenVINO support:
+
+```bash
+pip install "fast-face-python[openvino]"
+```
+
+## Usage
+
+### Face Detection
+
+Instantiate a detection model using `FaceModelFactory` and call the `detect` method. The method accepts an image path, a NumPy array in RGB format, or a list of either.
+
+```python
+from fast_face import FaceModelFactory
+
+# Initialize the model (weights are downloaded automatically if missing)
+model = FaceModelFactory.get_model("YUNET", top_k=500, conf_threshold=0.6)
+
+# Run detection on a local image file
+results = model.detect("image.jpg", return_dict=True)
+
+# Process the detections for the first image
+for det in results[0]:
+    bbox = det["bbox"]
+    confidence = det["score"]
+    landmarks = det["landmarks"]
+    print(f"Face detected at {bbox} with confidence {confidence}")
+```
+
+To run inference on an existing OpenCV image, convert it to RGB first:
+
+```python
+import cv2
+
+img = cv2.imread("image.jpg")
+img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+
+results = model.detect(img_rgb, return_dict=True)
+```
+
+### Face Recognition
+
+Recognition models extract L2-normalized embeddings from aligned face images.
+
+```python
+import numpy as np
+from fast_face import FaceModelFactory
+
+model = FaceModelFactory.get_model("ADAFACE_IR50")
+
+# Provide pre-aligned 112x112 RGB face crops
+face_crop1 = np.random.randint(0, 255, (112, 112, 3), dtype=np.uint8)
+face_crop2 = np.random.randint(0, 255, (112, 112, 3), dtype=np.uint8)
+
+# Extract embeddings for the batch
+embeddings = model.extract([face_crop1, face_crop2])
+
+print(f"Extracted {embeddings.shape[0]} embeddings of dimension {embeddings.shape[1]}")
+```
+
+If you have unaligned images and face landmarks from a detection model, you can pass the landmarks to automatically align the faces before extraction:
+
+```python
+landmarks = np.array([
+    [200.0, 200.0], [280.0, 200.0], [240.0, 250.0], 
+    [210.0, 300.0], [270.0, 300.0]
+], dtype=np.float32)
+
+embeddings = model.extract([img_rgb], landmarks=[landmarks])
+```
+
+### Execution Providers (Hardware Acceleration)
+
+By default, all models run using CPU (`["CPUExecutionProvider"]`). You can enable hardware acceleration (CUDA, ROCm, OpenVINO, CoreML, etc.) by passing the `providers` argument to `FaceModelFactory.get_model()`:
+
+#### NVIDIA GPU (CUDA)
+
+```python
+model = FaceModelFactory.get_model(
+    "RETINAFACE_RESNET50",
+    providers=["CUDAExecutionProvider", "CPUExecutionProvider"],
+)
+```
+
+#### AMD GPU (ROCm)
+
+```python
+model = FaceModelFactory.get_model(
+    "ADAFACE_IR101",
+    providers=["ROCMExecutionProvider", "CPUExecutionProvider"],
+)
+```
+
+#### Intel OpenVINO
+
+```python
+model = FaceModelFactory.get_model(
+    "YUNET",
+    providers=["OpenVINOExecutionProvider", "CPUExecutionProvider"],
+)
+```
+
+#### Custom Provider Options
+
+You can also pass tuple configurations with custom options (such as device ID or memory limits):
+
+```python
+cuda_provider = (
+    "CUDAExecutionProvider",
+    {
+        "device_id": 0,
+        "arena_extend_strategy": "kNextPowerOfTwo",
+        "gpu_mem_limit": 2 * 1024 * 1024 * 1024,  # 2 GB
+    },
+)
+
+model = FaceModelFactory.get_model(
+    "RETINAFACE_RESNET50",
+    providers=[cuda_provider, "CPUExecutionProvider"],
+)
+```
+
+### Supported Models
+
+The following model identifiers are supported by `FaceModelFactory`:
+
+* `YUNET`
+* `RETINAFACE_MOBILENET`
+* `RETINAFACE_RESNET50`
+* `ADAFACE_IR18`
+* `ADAFACE_IR50`
+* `ADAFACE_IR101`
+
+## Development
+
+To set up the repository for development, install the `dev` dependencies:
+
+```bash
+pip install -e ".[dev,cpu]"
+```
+
+### Testing
+
+The project uses `pytest` for testing. Run the test suite:
+
+```bash
+pytest tests/
+```
+
+### Formatting and Linting
+
+The project uses `ruff` for code formatting and linting:
+
+```bash
+ruff check .
+ruff format .
+```
+
+## License
+
+This project is licensed under the terms found in the `LICENSE` file.

fast_face_python-0.1.1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fast-face-python"
+version = "0.1.1"
+description = "Fast and easy face detection using ONNX runtime."
+authors = [
+  { name="xMaulana" },
+]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "numpy",
+    "Pillow",
+    "opencv-python",
+    "pydantic-settings>=2.15.0",
+]
+
+[project.optional-dependencies]
+cpu = [
+    "onnxruntime>=1.24.3",
+]
+gpu = [
+    "onnxruntime-gpu>=1.24.3, <=1.26.1",
+    "nvidia-cudnn-cu12",
+    "nvidia-cublas-cu12",
+    "nvidia-cuda-runtime-cu12"
+]
+openvino = [
+    "onnxruntime-openvino>=1.24.1"
+]
+rocm = [
+    "onnxruntime-rocm>=1.22.1"
+]
+dev = [
+    "pytest",
+    "ruff",
+    "build",
+    "twine"
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+packages = ["fast_face", "fast_face.models"]
+
+[tool.uv]
+cache-dir = ".uv_cache"

fast_face_python-0.1.1/setup.cfg

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

fast_face_python-0.1.1/src/fast_face/__init__.py

@@ -0,0 +1,6 @@
+from .models.factory import FaceModelFactory
+from .models.yunet import YuNet
+from .models.retinaface import RetinaFace
+from .models.adaface import AdaFace
+
+__all__ = ["FaceModelFactory", "YuNet", "RetinaFace", "AdaFace"]

fast_face_python-0.1.1/src/fast_face/models/__init__.py

@@ -0,0 +1,11 @@
+from .base import BaseFaceModel
+from .factory import FaceModelFactory
+from .session import ONNXSession
+from .yunet import YuNet
+
+__all__ = [
+    "BaseFaceModel",
+    "FaceModelFactory",
+    "ONNXSession",
+    "YuNet",
+]

fast_face_python-0.1.1/src/fast_face/models/adaface.py

@@ -0,0 +1,91 @@
+from typing import Any
+
+import cv2
+import numpy as np
+
+from ..schema import ProviderType
+from ..tools import align_face
+from .base_recognition import BaseRecognitionModel
+
+
+class AdaFace(BaseRecognitionModel):
+    """AdaFace face recognition model for embedding extraction.
+
+    Supports IR-18, IR-50, and IR-101 backbones.
+    Expects RGB input images; converts to BGR internally as required by AdaFace.
+    """
+
+    def __init__(
+        self,
+        model_path: str,
+        align_size: tuple[int, int] = (112, 112),
+        providers: list[ProviderType] | None = None,
+        **kwargs,
+    ):
+        if providers is None:
+            providers = ["CPUExecutionProvider"]
+        super().__init__(
+            model_path=model_path,
+            providers=providers,
+            sess_options=kwargs.get("sess_options"),
+        )
+        self.align_size = align_size
+
+    def preprocess(self, imgs: list[np.ndarray]) -> np.ndarray:
+        """Preprocess aligned face images: RGB->BGR, normalize to [-1, 1], transpose to NCHW."""
+        processed = []
+        for img in imgs:
+            bgr = cv2.cvtColor(img, cv2.COLOR_RGB2BGR)
+
+            h, w = bgr.shape[:2]
+            if (w, h) != self.align_size:
+                bgr = cv2.resize(bgr, self.align_size)
+
+            processed.append(bgr)
+
+        batch = np.stack(processed, axis=0).astype(np.float32)
+
+        batch = (batch / 255.0 - 0.5) / 0.5
+
+        batch = np.transpose(batch, (0, 3, 1, 2))
+        return batch
+
+    def extract(
+        self,
+        imgs: list[np.ndarray] | np.ndarray,
+        landmarks: list[np.ndarray | dict[str, Any]] | None = None,
+    ) -> np.ndarray:
+        """Extract L2-normalized face embeddings from images.
+
+        Args:
+            imgs: List of face images in RGB, or a single image array.
+                  If landmarks are provided, images should be the full/cropped
+                  frames from which faces will be aligned.
+            landmarks: Optional list of landmarks for face alignment.
+                       Each element can be an np.ndarray of shape (5, 2) or (10,),
+                       or a dictionary with landmark keys.
+
+        Returns:
+            np.ndarray: L2-normalized embeddings of shape (N, embedding_dim).
+        """
+        if isinstance(imgs, np.ndarray) and imgs.ndim == 3:
+            imgs = [imgs]
+
+        if landmarks is not None:
+            aligned_imgs = []
+            for img, lmk in zip(imgs, landmarks):
+                aligned = align_face(img, lmk, align_size=self.align_size)
+                aligned_imgs.append(aligned)
+        else:
+            aligned_imgs = imgs
+
+        batch = self.preprocess(aligned_imgs)
+        outputs = self.session(batch)
+
+        embeddings = outputs[0]
+
+        norms = np.linalg.norm(embeddings, axis=1, keepdims=True)
+        norms = np.maximum(norms, 1e-10)
+        embeddings = embeddings / norms
+
+        return embeddings