3DFaceViewer

简体中文 | English

3DFaceViewer 是一个本地运行的实时 3D 人头查看与控制工具。Electron 负责桌面窗口，Three.js 负责 PBR 渲染，Python/NumPy 后端负责运行 Google GNM Head 模型。

本项目是独立开源项目，与 Google 没有隶属关系，也不代表 Google 的官方产品或背书。

功能

• 实时生成 GNM v3 Head：253 维 Identity、383 维 Expression。
• 按性别、人群条件和 seed 随机生成可复现的人脸 Identity。
• 20 类 GNM 语义表情，支持表情强度、单维参数和完整向量控制。
• 独立控制颈部、头部、左右眼球和瞳孔变化。
• 程序生成的默认虹膜，可上传 JPEG/PNG/WebP 虹膜照片并调节尺寸、旋转。
• 可调肤色、背景、曝光、环境反射、主光位置、补光和阴影。
• 通过系统保存对话框导出当前 3D 视口 PNG。
• 内置本地 WebSocket 接口，可从 Python、Node.js、C++ 或其他进程控制表情、头部和眼球。
• 网格请求合并与最高 30 Hz 更新，避免连续控制使 Python 后端排队。

系统要求

• macOS、Linux 或 Windows；当前已在 macOS Apple Silicon 实测。
• Node.js >=22.12.0 和 npm >=10。
• Python >=3.11（当前已在 Python 3.13 实测）。
• Git，用于安装锁定版本的 GNM Python 包。
• 首次安装需要网络；运行时不需要上传照片或模型数据。

快速开始

# 克隆或下载仓库后进入项目目录
cd 3DFaceViewer
npm run setup
npm start

npm run setup 会创建 .venv、安装锁定 GNM commit 的 Python 依赖、执行 npm ci 并运行 JavaScript 检查。GNM 包含模型数据和 TensorFlow 语义采样依赖，第一次安装会花费一些时间。

macOS 完成安装后也可直接双击 start.command。

手动安装

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
npm ci
npm run check
FACEVIEWER_PYTHON="$PWD/.venv/bin/python" npm start

Windows 请将 Python 路径替换为 .venv\Scripts\python.exe。

环境变量

变量	说明	默认值
FACEVIEWER_SETUP_PYTHON	一键安装时指定 Python 解释器	自动查找 Python 3
FACEVIEWER_GNM_SOURCE	从已有 GNM/gnm/shape 源码安装，适合离线开发	未设置时下载锁定 commit
FACEVIEWER_PYTHON	指定用于后端的 Python 解释器	优先使用项目 .venv
FACEVIEWER_WS_PORT	WebSocket 端口	8766
FACEVIEWER_WS_URL	示例客户端的连接地址	ws://127.0.0.1:8766/3dfaceviewer

GNM_PYTHON 和 GNM_WS_PORT 仍作为旧版环境变量的兼容回退。

WebSocket 控制

• 地址：ws://127.0.0.1:8766/3dfaceviewer
• 必须子协议：3dfaceviewer-control-v1
• 仅监听本机 loopback，单消息最大 64 KiB。
• 最多 8 个客户端，每客户端最多 120 条/秒。

请求格式：

{"v":1,"id":"pose-1","op":"pose.set","payload":{"head":{"yawDeg":15},"transitionMs":180}}

常用操作：

操作	作用
identity.randomize / identity.set	随机生成或直接设置 253 维 Identity
expression.preset / expression.set	语义表情或完整 383 维 Expression
expression.patch	一次修改 1–64 个表情维度
eyes.set	设置左/右眼球局部旋转
pose.set	原子更新 Head/Neck 局部姿态
state.get / state.reset	获取或复位状态
meta.get / ping	获取协议元数据或检查连接

控制命令返回 ok: true 只表示已接收。需要确认新网格已显示时，等待 state.changed 事件的 appliedRevision 大于或等于该命令响应的 revision。

应用启动后可运行内置示例：

npm run demo:ws

所有 payload、参数范围、事件与错误码见完整 WebSocket API 文档。

项目结构

3DFaceViewer/
├── electron/              # 主进程、preload、协议和 renderer 源码
├── backend/               # 本地 GNM NumPy HTTP 后端与静态页面
├── docs/                  # 中英文 WebSocket API 文档
├── examples/              # WebSocket 客户端示例
├── scripts/               # 构建和环境安装脚本
├── test/                  # Node.js 协议测试
├── tests/                 # Python 后端测试
├── LICENSE                # 3DFaceViewer 自有代码的 MIT 许可证
└── THIRD_PARTY_NOTICES.md # GNM 及其他依赖声明

Renderer 从 electron/renderer/renderer.js 构建到 backend/static/renderer.bundle.js；生成的 bundle 和 node_modules 均不应提交到 Git。

开发与测试

npm run check
npm run test:python
npm run screenshot:docs

npm run check 会重建 renderer 并运行 WebSocket 协议测试。Python 测试会实际加载 GNM v3 Head，并验证零参数网格生成。npm run screenshot:docs 会在 GNM 首帧渲染完成后更新 README 使用的真实运行图。

性能、隐私与安全

• 模型计算、虹膜烘焙和渲染均在本机进行。
• 上传的虹膜图只存在于 Electron renderer 内存，关闭程序后释放；限制为 20 MB、8192×8192。
• Python HTTP 后端使用随机本地端口，WebSocket 只监听 127.0.0.1。
• Electron 开启 contextIsolation 和 sandbox，禁止 Node integration、新窗口和网页权限。
• 截图由主进程验证来源后使用系统保存对话框写入，renderer 不获得任意文件写入能力。

当前限制

• 当前是源码运行工程，还没有提供 .dmg、.exe 或 Linux 安装包。
• 皮肤使用自然肤色 PBR 材质，并非从个人人脸照片生成的皮肤贴图。
• 默认虹膜为程序生成；实际使用时可上传居中裁剪的虹膜照片。
• 第一次随机 Identity 或语义表情会按需加载 TensorFlow 解码器；冷启动可能需要 1–2 分钟，后续采样通常很快。

许可证

3DFaceViewer 原创应用代码使用 MIT License。GNM Head 作为锁定版本的外部依赖安装，其源码、模型数据和权重仍受 Apache License 2.0 及上游第三方声明约束。详见 THIRD_PARTY_NOTICES.md。

GNM 论文：GNM Head: A Generative aNthropometric Model of the human head, Ploumpis et al., 2026, arXiv:2607.23687.