emilianavt/OpenSeeFace

OpenSeeFace – 用于虚拟角色动画的实时面部特征点追踪器

它是什么 – OpenSeeFace 是一个轻量级、跨平台的库，可从网络摄像头或视频流中检测 66 个面部特征点（以及视线和眨眼信息）。核心模型是基于 MobileNetV3 的神经网络，并导出为 ONNX，因此可以使用 onnxruntime 在 CPU 上快速执行（单核心上可达 30-60 fps）。它不是一个完整的虚拟角色操纵应用程序；相反，它通过 UDP 流传输追踪数据，以便其他程序（例如 Unity、Godot、VSeeFace、VTube Studio）可以驱动 3D/2D 虚拟角色。

为什么它很重要 – 实时虚拟角色操纵需要稳定、低延迟的面部特征点，且能在噪声照明、低分辨率和各种头部姿势下运作。OpenSeeFace 以些许的精确度换取了稳健性和速度，使其适用于直播、VTubing 以及其他 CPU 资源有限的交互式媒体。

主要功能

功能	详细信息
面部特征点模型	66 个点（类似 iBUG-68）加上准 3D 轮廓点；包含眼睛开/闭、视线和眨眼提示。
模型变体	五种预训练模型（-1 … 3），从超快/低准确度到较慢/高准确度（在一个 CPU 核心上约 213 fps → 44 fps）。
ONNX Runtime 推理	无需 GPU 即可在 Windows、Linux、macOS 上执行；提供 Windows 预编译的 facetracker.exe。
UDP 输出	以二进制包发送每帧的特征点数据；可在独立机器上接收，以保持采集电脑隔离。
Unity 集成	OpenSee、OpenSeeShowPoints、OpenSeeLauncher、OpenSeeIKTarget 和 OpenSeeExpression 组件处理包接收、可视化、IK 驱动和用户表情训练。
跨语言支持	追踪器是一个 Python 3 脚本 (facetracker.py)，可直接执行或通过编译后的可执行文件执行；依赖项极少 (onnxruntime, OpenCV, Pillow, NumPy)。
表情分类器	可选的基于 SVM 的表情检测器，可针对每个用户进行校准并保存/加载。
稳健性	适用于部分遮挡、眼镜、低光和广泛的头部姿势范围；人脸检测使用自定义热图回归模型或 RetinaFace。

---

典型工作流程

1. 启动追踪器 – 执行 facetracker.exe (Windows) 或 python facetracker.py (任何操作系统)。选择摄像头或视频文件，选择模型 (--model 0-3)，并可选择启用 --visualize 以在本地查看特征点。
2. 流数据 – 脚本会发送包含特征点坐标（以及可选的视线/眨眼标记）的 UDP 包。
3. 在 Unity 中使用 – 将 OpenSee 组件添加到 GameObject；它会在后台线程中接收包，并通过 trackingData 公开。使用 OpenSeeShowPoints 来可视化这些点，或将数据馈送至 VRM/Live2D 虚拟角色控制器。
4. 可选的表情训练 – 添加 OpenSeeExpression，为每个表情记录几个示例，训练 SVM，然后在您的虚拟角色逻辑中查询 IsExpressionActive("smile")。

---

优势

• 仅使用 CPU 的实时性能 – 无需 GPU；适用于低端笔记本电脑或流媒体设备。
• 在恶劣条件下表现稳健 – 对于虚拟角色使用案例，在低光、噪声和部分遮挡下的表现优于许多同类解决方案（例如 MediaPipe）。
• 模块化设计 – UDP 流让您可以将采集与渲染分开，减少延迟尖峰并保护摄像头隐私。
• 多种模型尺寸 – 您可以为多人脸选择更快的模型，或为单人流选择更高质量的模型。
• 开源与宽松授权 – BSD-2-clause，易于嵌入商业项目。

---

限制

• 眼部区域准确度 – 眼部周围的特征点位置不如某些专用眼动追踪器精确；眨眼检测有效，但细致的视线追踪可能会抖动。
• CPU 负载 – 以 30 fps 追踪单一人脸可能会占用近一个完整的 CPU 核心；更高的帧率或多个人脸会成比例增加使用量。
• 无内置虚拟角色渲染器 – 您必须提供自己的 Unity/Unreal/Godot 集成（提供示例项目，但不是完整的终端用户应用程序）。
• Linux onnxruntime 加载问题 – 部分用户需要调整可执行文件堆栈 (execstack -c …) 才能加载库。

---

快速入门

# 安装依赖项 (建议通过 uv)
uv sync --locked          # 创建虚拟环境
uv run facetracker.py --visualize 3 -c 0   # 网络摄像头, 模型 3, 显示特征点

在 Unity 中：

1. 创建一个空的 GameObject。
2. 添加 OpenSee 和 OpenSeeShowPoints 组件。
3. 按下 Play – 追踪器将启动（或使用 OpenSeeLauncher 手动启动）。

---

授权

代码和预训练模型采用 BSD 2-clause 授权发布。第三方库授权包含在发布二进制文件的 Licenses 文件夹中。

更多信息

• Unity 示例项目 – https://github.com/emilianavt/OpenSeeFaceSample
• 演示视频 – https://www.youtube.com/watch?v=AaNap_ud_3I
• 相关虚拟角色操纵应用程序 – VSeeFace (https://www.vseeface.icu/)，它会消耗 OpenSeeFace 数据。