face-hub 1.0.1__tar.gz

face_hub-1.0.1/LICENSE

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

face_hub-1.0.1/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: face-hub
+Version: 1.0.1
+Summary: Real-time face recognition library: detection, embedding, tracking and matching.
+Author: AllenDeng
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/allen902/face_hub
+Project-URL: Documentation, https://allen902.github.io/face_hub
+Project-URL: Repository, https://github.com/allen902/face_hub
+Project-URL: Issues, https://github.com/allen902/face_hub/issues
+Keywords: face-recognition,insightface,retinaface,arcface,computer-vision
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opencv-python>=4.8.0
+Requires-Dist: insightface>=0.7.3
+Requires-Dist: onnxruntime>=1.18.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: Pillow>=10.0.0
+Provides-Extra: gpu-win
+Requires-Dist: onnxruntime-directml>=1.24.0; extra == "gpu-win"
+Provides-Extra: gpu-linux
+Requires-Dist: onnxruntime-gpu>=1.18.0; extra == "gpu-linux"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build>=0.10; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: license-file
+
+# FaceHub
+
+> Real-time face recognition library — detection, embedding, tracking, and matching.
+
+[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Tests](https://github.com/allen902/face_hub/actions/workflows/publish.yml/badge.svg)](https://github.com/allen902/face_hub/actions/workflows/publish.yml)
+
+## Features
+
+- **Detection**: insightface RetinaFace with GPU auto-detection (CUDA / DirectML) and CPU fallback.
+- **Embedding**: ArcFace 512-dim L2-normalized features.
+- **Recognition**: 1:N cosine-similarity matching with a versioned encoding cache.
+- **Tracking**: IoU-based multi-face tracker with majority-vote identity smoothing.
+- **Camera**: cross-platform capture thread (Windows DShow, macOS AVFoundation, Linux V4L2).
+- **Protocol**: `DetectorProtocol` lets you plug in your own detector (YOLO, MediaPipe, etc.).
+
+## Installation
+
+```bash
+pip install face-hub
+```
+
+Optional GPU backends:
+
+```bash
+# Windows DirectML
+pip uninstall -y onnxruntime
+pip install face-hub[gpu-win]
+
+# Linux NVIDIA CUDA
+pip uninstall -y onnxruntime
+pip install face-hub[gpu-linux]
+```
+
+## Quick Start
+
+```python
+from face_hub import (
+    FaceHubPipeline, FaceDetector, FaceRecognizer,
+    FaceTracker, FaceDatabase, CameraThread,
+)
+
+# 1. Initialize components
+db = FaceDatabase(db_path="face_db.json")
+detector = FaceDetector(device="auto", det_size=640)
+recognizer = FaceRecognizer(tolerance=0.45)
+tracker = FaceTracker(smooth_frames=5)
+camera = CameraThread(camera_id=0, width=640, height=360)
+
+# 2. Assemble the pipeline
+pipeline = FaceHubPipeline(camera, detector, recognizer, tracker, db)
+pipeline.start()
+
+# 3. Loop
+try:
+    while True:
+        result = pipeline.process_frame()
+        if result is None:
+            continue
+        for face in result.known_faces:
+            print(f"{face.name} ({face.confidence:.0%})")
+finally:
+    pipeline.stop()
+```
+
+## Custom Detector
+
+Any object satisfying `DetectorProtocol` can be plugged into the pipeline:
+
+```python
+from face_hub import DetectorProtocol, DetectionWithEmbedding, BBox
+
+class MyYoloDetector:
+    def detect_with_embeddings(self, frame):
+        boxes = self.yolo_model(frame)
+        return [
+            DetectionWithEmbedding(
+                bbox=BBox(x1=b.x1, y1=b.y1, x2=b.x2, y2=b.y2),
+                confidence=b.conf,
+                embedding=self.embedder(frame[b.y1:b.y2, b.x1:b.x2]),
+                quality_pass=True,
+            )
+            for b in boxes
+        ]
+
+pipeline = FaceHubPipeline(camera, MyYoloDetector(), recognizer, tracker, db)
+```
+
+## Documentation
+
+Full API docs (English / 中文) are in the `docs/` directory and can be served with:
+
+```bash
+pip install mkdocs mkdocs-material
+cd docs && mkdocs serve
+```
+
+## License
+
+The FaceHub **code** is released under the [MIT License](LICENSE).
+
+> ⚠️ The pre-trained `buffalo_l` model downloaded automatically by insightface is subject to insightface's own model license and is for non-commercial research use unless separate authorization is obtained. See the documentation for details.
+
+---
+
+# FaceHub（中文）
+
+> 实时人脸识别库 — 检测、特征提取、追踪、匹配。
+
+## 特性
+
+- **检测**：insightface RetinaFace，自动检测 CUDA / DirectML GPU 并回退 CPU。
+- **特征**：ArcFace 512 维 L2 归一化特征向量。
+- **识别**：1:N 余弦相似度匹配，带版本号缓存。
+- **追踪**：基于 IoU 的多目标追踪 + 多数投票身份平滑。
+- **摄像头**：跨平台采集线程（Windows DShow、macOS AVFoundation、Linux V4L2）。
+- **协议**：`DetectorProtocol` 允许接入自定义检测器（YOLO、MediaPipe 等）。
+
+## 安装
+
+```bash
+pip install face-hub
+```
+
+可选 GPU 后端：
+
+```bash
+# Windows DirectML
+pip uninstall -y onnxruntime
+pip install face-hub[gpu-win]
+
+# Linux NVIDIA CUDA
+pip uninstall -y onnxruntime
+pip install face-hub[gpu-linux]
+```
+
+## 快速开始
+
+```python
+from face_hub import (
+    FaceHubPipeline, FaceDetector, FaceRecognizer,
+    FaceTracker, FaceDatabase, CameraThread,
+)
+
+# 1. 初始化组件
+db = FaceDatabase(db_path="face_db.json")
+detector = FaceDetector(device="auto", det_size=640)
+recognizer = FaceRecognizer(tolerance=0.45)
+tracker = FaceTracker(smooth_frames=5)
+camera = CameraThread(camera_id=0, width=640, height=360)
+
+# 2. 组装流水线
+pipeline = FaceHubPipeline(camera, detector, recognizer, tracker, db)
+pipeline.start()
+
+# 3. 循环处理
+try:
+    while True:
+        result = pipeline.process_frame()
+        if result is None:
+            continue
+        for face in result.known_faces:
+            print(f"{face.name} ({face.confidence:.0%})")
+finally:
+    pipeline.stop()
+```
+
+## 自定义检测器
+
+任何满足 `DetectorProtocol` 的对象都可以接入流水线，示例见上文英文部分。
+
+## 文档
+
+完整中英 API 文档位于 `docs/` 目录，可通过 MkDocs 本地预览。
+
+## 许可
+
+FaceHub **代码** 采用 [MIT License](LICENSE)。
+
+> ⚠️ insightface 自动下载的 `buffalo_l` 预训练模型受其模型许可约束，默认仅供非商用研究使用；商业使用需单独获取授权。详见文档。

face_hub-1.0.1/README.md

@@ -0,0 +1,181 @@
+# FaceHub
+
+> Real-time face recognition library — detection, embedding, tracking, and matching.
+
+[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Tests](https://github.com/allen902/face_hub/actions/workflows/publish.yml/badge.svg)](https://github.com/allen902/face_hub/actions/workflows/publish.yml)
+
+## Features
+
+- **Detection**: insightface RetinaFace with GPU auto-detection (CUDA / DirectML) and CPU fallback.
+- **Embedding**: ArcFace 512-dim L2-normalized features.
+- **Recognition**: 1:N cosine-similarity matching with a versioned encoding cache.
+- **Tracking**: IoU-based multi-face tracker with majority-vote identity smoothing.
+- **Camera**: cross-platform capture thread (Windows DShow, macOS AVFoundation, Linux V4L2).
+- **Protocol**: `DetectorProtocol` lets you plug in your own detector (YOLO, MediaPipe, etc.).
+
+## Installation
+
+```bash
+pip install face-hub
+```
+
+Optional GPU backends:
+
+```bash
+# Windows DirectML
+pip uninstall -y onnxruntime
+pip install face-hub[gpu-win]
+
+# Linux NVIDIA CUDA
+pip uninstall -y onnxruntime
+pip install face-hub[gpu-linux]
+```
+
+## Quick Start
+
+```python
+from face_hub import (
+    FaceHubPipeline, FaceDetector, FaceRecognizer,
+    FaceTracker, FaceDatabase, CameraThread,
+)
+
+# 1. Initialize components
+db = FaceDatabase(db_path="face_db.json")
+detector = FaceDetector(device="auto", det_size=640)
+recognizer = FaceRecognizer(tolerance=0.45)
+tracker = FaceTracker(smooth_frames=5)
+camera = CameraThread(camera_id=0, width=640, height=360)
+
+# 2. Assemble the pipeline
+pipeline = FaceHubPipeline(camera, detector, recognizer, tracker, db)
+pipeline.start()
+
+# 3. Loop
+try:
+    while True:
+        result = pipeline.process_frame()
+        if result is None:
+            continue
+        for face in result.known_faces:
+            print(f"{face.name} ({face.confidence:.0%})")
+finally:
+    pipeline.stop()
+```
+
+## Custom Detector
+
+Any object satisfying `DetectorProtocol` can be plugged into the pipeline:
+
+```python
+from face_hub import DetectorProtocol, DetectionWithEmbedding, BBox
+
+class MyYoloDetector:
+    def detect_with_embeddings(self, frame):
+        boxes = self.yolo_model(frame)
+        return [
+            DetectionWithEmbedding(
+                bbox=BBox(x1=b.x1, y1=b.y1, x2=b.x2, y2=b.y2),
+                confidence=b.conf,
+                embedding=self.embedder(frame[b.y1:b.y2, b.x1:b.x2]),
+                quality_pass=True,
+            )
+            for b in boxes
+        ]
+
+pipeline = FaceHubPipeline(camera, MyYoloDetector(), recognizer, tracker, db)
+```
+
+## Documentation
+
+Full API docs (English / 中文) are in the `docs/` directory and can be served with:
+
+```bash
+pip install mkdocs mkdocs-material
+cd docs && mkdocs serve
+```
+
+## License
+
+The FaceHub **code** is released under the [MIT License](LICENSE).
+
+> ⚠️ The pre-trained `buffalo_l` model downloaded automatically by insightface is subject to insightface's own model license and is for non-commercial research use unless separate authorization is obtained. See the documentation for details.
+
+---
+
+# FaceHub（中文）
+
+> 实时人脸识别库 — 检测、特征提取、追踪、匹配。
+
+## 特性
+
+- **检测**：insightface RetinaFace，自动检测 CUDA / DirectML GPU 并回退 CPU。
+- **特征**：ArcFace 512 维 L2 归一化特征向量。
+- **识别**：1:N 余弦相似度匹配，带版本号缓存。
+- **追踪**：基于 IoU 的多目标追踪 + 多数投票身份平滑。
+- **摄像头**：跨平台采集线程（Windows DShow、macOS AVFoundation、Linux V4L2）。
+- **协议**：`DetectorProtocol` 允许接入自定义检测器（YOLO、MediaPipe 等）。
+
+## 安装
+
+```bash
+pip install face-hub
+```
+
+可选 GPU 后端：
+
+```bash
+# Windows DirectML
+pip uninstall -y onnxruntime
+pip install face-hub[gpu-win]
+
+# Linux NVIDIA CUDA
+pip uninstall -y onnxruntime
+pip install face-hub[gpu-linux]
+```
+
+## 快速开始
+
+```python
+from face_hub import (
+    FaceHubPipeline, FaceDetector, FaceRecognizer,
+    FaceTracker, FaceDatabase, CameraThread,
+)
+
+# 1. 初始化组件
+db = FaceDatabase(db_path="face_db.json")
+detector = FaceDetector(device="auto", det_size=640)
+recognizer = FaceRecognizer(tolerance=0.45)
+tracker = FaceTracker(smooth_frames=5)
+camera = CameraThread(camera_id=0, width=640, height=360)
+
+# 2. 组装流水线
+pipeline = FaceHubPipeline(camera, detector, recognizer, tracker, db)
+pipeline.start()
+
+# 3. 循环处理
+try:
+    while True:
+        result = pipeline.process_frame()
+        if result is None:
+            continue
+        for face in result.known_faces:
+            print(f"{face.name} ({face.confidence:.0%})")
+finally:
+    pipeline.stop()
+```
+
+## 自定义检测器
+
+任何满足 `DetectorProtocol` 的对象都可以接入流水线，示例见上文英文部分。
+
+## 文档
+
+完整中英 API 文档位于 `docs/` 目录，可通过 MkDocs 本地预览。
+
+## 许可
+
+FaceHub **代码** 采用 [MIT License](LICENSE)。
+
+> ⚠️ insightface 自动下载的 `buffalo_l` 预训练模型受其模型许可约束，默认仅供非商用研究使用；商业使用需单独获取授权。详见文档。

face_hub-1.0.1/face_hub/__init__.py

@@ -0,0 +1,84 @@
+"""
+FaceHub — Real-time Face Recognition Library
+
+Usage:
+    from face_hub import (
+        FaceHubPipeline, FaceDetector, FaceRecognizer,
+        CameraThread, FaceTracker, FaceDatabase,
+    )
+    from face_hub.types import UNKNOWN_SENTINEL, PipelineResult, TrackedFace
+"""
+
+__version__ = "1.0.1"
+__author__ = "AllenDeng"
+
+# When installed as a package, prefer the metadata version (pyproject.toml).
+# Falls back to the hardcoded value above during local development.
+try:
+    from importlib.metadata import version as _pkg_version
+
+    __version__ = _pkg_version("face-hub")
+except Exception:
+    pass
+
+# ── Core components (from engine subpackage) ─────────────────
+from face_hub.engine.camera import CameraThread
+from face_hub.engine.face_detector import FaceDetector
+from face_hub.engine.face_recognizer import FaceRecognizer
+from face_hub.engine.face_tracker import FaceTracker
+from face_hub.engine.face_database import FaceDatabase
+
+# ── Pipeline (from face_hub/ main package) ─────────────────────
+from face_hub.pipeline import FaceHubPipeline
+from face_hub.detector_protocol import DetectorProtocol
+
+# ── Types ──────────────────────────────────────────────────────
+from face_hub.types import (
+    UNKNOWN_SENTINEL,
+    BBox,
+    DetectionResult,
+    DetectionWithEmbedding,
+    TrackedFace,
+    PipelineResult,
+)
+
+# ── Exceptions ─────────────────────────────────────────────────
+from face_hub.exceptions import (
+    FaceHubError,
+    ModelLoadError,
+    InferenceError,
+    CameraError,
+    DatabaseError,
+    RecognitionError,
+)
+
+# ── Config ─────────────────────────────────────────────────────
+from face_hub.engine.config import DEFAULT_SETTINGS, get_default_settings
+
+__all__ = [
+    # Core
+    "CameraThread",
+    "FaceDetector",
+    "FaceRecognizer",
+    "FaceTracker",
+    "FaceDatabase",
+    "FaceHubPipeline",
+    "DetectorProtocol",
+    # Types
+    "UNKNOWN_SENTINEL",
+    "BBox",
+    "DetectionResult",
+    "DetectionWithEmbedding",
+    "TrackedFace",
+    "PipelineResult",
+    # Exceptions
+    "FaceHubError",
+    "ModelLoadError",
+    "InferenceError",
+    "CameraError",
+    "DatabaseError",
+    "RecognitionError",
+    # Config
+    "DEFAULT_SETTINGS",
+    "get_default_settings",
+]

face_hub-1.0.1/face_hub/detector_protocol.py

@@ -0,0 +1,67 @@
+"""
+Detector protocol — abstract interface for face detection + embedding.
+
+Built-in implementation: face_hub.engine.face_detector.FaceDetector (insightface).
+Users can implement this protocol to plug in custom models (YOLO, MediaPipe,
+commercial SDK, etc.) without modifying the rest of the pipeline.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, List, runtime_checkable
+import numpy as np
+
+from face_hub.types import DetectionResult, DetectionWithEmbedding
+
+
+@runtime_checkable
+class DetectorProtocol(Protocol):
+    """
+    Protocol for face detection and embedding extraction.
+
+    Any object implementing these three methods can be passed to
+    FaceHubPipeline as the detector.
+
+    Minimal implementation: just implement detect_with_embeddings().
+    detect() and reload_model() have default no-op fallbacks.
+    """
+
+    def detect(self, frame: np.ndarray) -> List[DetectionResult]:
+        """
+        Detect all faces in a BGR frame.
+
+        Args:
+            frame: BGR image as (H, W, 3) numpy array.
+
+        Returns:
+            List of DetectionResult, sorted by confidence descending.
+        """
+        ...
+
+    def detect_with_embeddings(
+        self, frame: np.ndarray
+    ) -> List[DetectionWithEmbedding]:
+        """
+        Detect faces and extract feature embeddings in one pass.
+
+        This is the primary method called by the pipeline. Implementations
+        should return embeddings that are L2-normalized 512-dim float32 vectors
+        (or set the confidence threshold in FaceRecognizer accordingly).
+
+        Args:
+            frame: BGR image as (H, W, 3) numpy array.
+
+        Returns:
+            List of DetectionWithEmbedding, sorted by confidence descending.
+        """
+        ...
+
+    def reload_model(self, det_size: int = None) -> None:
+        """
+        Reload the underlying model with new parameters (optional).
+
+        Called when the user changes detection resolution at runtime.
+        Default no-op is acceptable if the implementation doesn't support
+        hot-reload.
+        """
+        pass

face_hub-1.0.1/face_hub/engine/__init__.py

@@ -0,0 +1 @@
+"""face_hub engine — core algorithms for detection, recognition, tracking."""