Metadata-Version: 2.4
Name: face-hub
Version: 1.1.0
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<5,>=4.8.0
Requires-Dist: insightface<1,>=0.7.3
Requires-Dist: onnxruntime<2,>=1.18.0
Requires-Dist: numpy<3,>=1.24.0
Requires-Dist: Pillow<11,>=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: pytest-timeout>=2.0; extra == "dev"
Requires-Dist: build>=0.10; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: psutil>=5.9.0; extra == "dev"
Dynamic: license-file



# FaceHub
### 🌐 [English](#facehub) | [中文](#facehub中文)



> Real-time face recognition library — detection, embedding, tracking, and matching.

[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/face-hub.svg)](https://pypi.org/project/face-hub/)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://allen902.github.io/face-hub/)
[![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

📖 **[Online Documentation](https://allen902.github.io/face-hub/)** — Full API reference in English & 中文

To preview locally:

```bash
pip install -r docs/requirements.txt
mkdocs serve -f docs/mkdocs.yml
```
## Download Quantity
[![Monthly Downloads](https://static.pepy.tech/badge/face-hub/month)](https://pepy.tech/project/face-hub)

[![Total Downloads](https://static.pepy.tech/badge/face-hub)](https://pepy.tech/project/face-hub)

## Acknowledgements
We would like to express our sincere gratitude to **Leon Jane** for voluntarily providing his facial sample data and fully participating in the verification and testing of all functions of the **Face-hub** library. Many program bugs were successfully identified through his efforts, making a crucial contribution to feature improvement and stability optimization of this project.
## 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（中文）
<div align="right">

### 🌐 [English](#facehub) | [中文](#facehub中文)

</div>


> 实时人脸识别库 — 检测、特征提取、追踪、匹配。

## 特性

- **检测**：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` 的对象都可以接入流水线，示例见上文英文部分。

## 文档

📖 **[在线文档](https://allen902.github.io/face-hub/)** — 完整中英 API 文档

## 下载量
[![Monthly Downloads](https://static.pepy.tech/badge/face-hub/month)](https://pepy.tech/project/face-hub)

[![Total Downloads](https://static.pepy.tech/badge/face-hub)](https://pepy.tech/project/face-hub)

## 致谢
在此特别向 **Leon Jane** 致以诚挚谢意。其无偿提供其人脸样本数据，并完整参与 **Face-hub** 库各项功能的验证测试，有效排查多处程序缺陷，为本项目的功能完善与稳定性优化作出关键贡献。
## 许可

FaceHub **代码** 采用 [MIT License](LICENSE)。

> ⚠️ insightface 自动下载的 `buffalo_l` 预训练模型受其模型许可约束，默认仅供非商用研究使用；商业使用需单独获取授权。详见文档。
