HairDeck 是一款专为 3D 角色工作流设计的生成模型，能够将单张 2D 角色图像转化为具备动画就绪能力的 3D 风格化发片系统。由清华大学、卡内基梅隆大学和香港中文大学的研究团队推出。
- 项目主页：https://hyzcluster.github.io/HairDeck
- GitHub：https://github.com/hyz317/HairDeck
- 模型：https://huggingface.co/hyz317/HairDeck
- ComfyUI节点：https://github.com/visualbruno/ComfyUI-HairDeck
- Demo：https://huggingface.co/spaces/hyz317/HairDeck
该工具不仅生成带有独立 UV 坐标和颜色属性的三维头发网格（GLB 格式），还会自动预测并生成驱动头发摆动的弹簧骨骼链（Spring Bone Chains）。生成的发型可直接附加到提供的虚拟化身（Avatar）身体上，并导出为标准的 VRM 0.x 格式，大幅简化了从概念图到可动 3D 资产的转化流程。
技术架构与生成机制
HairDeck 的生成流程通过三个核心模块协同完成，确保了几何结构的合理性与动画驱动的稳定性：
- Card VAE 编码：模型采用 Card VAE 对每片头发进行编码。其核心改进在于，使用单个 Token 即可表示一整片发片的几何与颜色特征，而非传统的逐点或逐面片编码，这显著降低了序列长度并提高了生成效率。
- Set Diffusion Transformer 生成：在编码基础上，模型利用 Set Diffusion Transformer 统筹生成整套发型。这种集合生成方式能够保持发片之间的空间连贯性与整体造型的结构合理性。
- Chain Diffusion Model 骨骼预测：在发片几何生成后，Chain Diffusion Model 会根据发片的形态预测对应的弹簧骨骼链。随后通过蒙皮（Skinning）技术完成绑定，使头发能够根据角色的物理动作产生自然的摆动效果。
此外，内置的颜色模型（Color Model）会根据输入图像，沿发片长度方向预测颜色分布，能够有效还原双色头发及复杂的发饰细节。
环境配置与安装部署
HairDeck 支持 Linux 和原生 Windows 系统，依赖 NVIDIA CUDA GPU。为确保兼容性，必须严格遵循以下环境版本要求：Python 3.12、PyTorch 2.8 和 CUDA 12.8。
1. 基础环境安装
- Windows：请参考项目提供的 Windows 专属指南配置环境并启动 Gradio 界面。
- Linux：在终端中执行以下命令克隆仓库并安装依赖。注意，需单独处理
pyrender的依赖冲突，避免其锁定旧版 PyOpenGL。git clone https://github.com/hyz317/HairDeck.git cd HairDeck python -m pip install -r requirements.txt python -m pip install --no-deps pyrender==0.1.45注：后续所有命令均需在仓库根目录下运行，并确保使用同一个 Python 虚拟环境。同时，请确保
ffmpeg已加入系统 PATH。
2. 模型权重与第三方组件下载
模型运行需要下载 HairDeck 权重、图像预处理模型以及自动化部署的 Blender 环境。下载前，需先在 Hugging Face 的 facebook/sam3 和 facebook/dinov3-vitl16-pretrain-lvd1689m 页面接受许可条款。
- 通过 Hugging Face 下载：
hf auth login export HAIRDECK_ROOT=/path/to/workspace # 指定权重、数据和输出目录 python scripts/setup/download_weights.py - 通过 ModelScope 下载（国内网络推荐）：
python scripts/setup/download_weights.py --gated-source modelscope注：两种下载方式获取的权重文件校验值完全一致。
下载脚本会自动获取以下内容：
- HairDeck 核心模型权重及 Latent 统计量。
- 图像预处理与编码所需模型（DINOv3, SAM 3, BiRefNet-matting）。
- Blender 4.2 LTS 及 VRM Add-on：脚本会根据当前操作系统自动下载对应版本的 Blender。若用户已手动安装 Blender 4.2 LTS 并启用了 VRM 插件，可通过设置环境变量
HAIRDECK_BLENDER指向其启动命令来跳过自动下载。
3. 路径自定义
如需修改模型或数据的默认存储路径，可通过环境变量或 JSON 文件进行配置。具体参数映射关系请参考 configs/paths.example.json 和 hairdeck/paths.py。
快速上手与推理工作流
以下命令展示了从单张角色图像生成 4 个候选发型，并将第 0 号结果导出为 VRM 角色及转头预览视频的完整流程：
# 1. 生成候选发型 (生成 4 个结果)
python scripts/image_to_hair.py character.png --out results/my_character --n 4
# 2. 导出 VRM 角色与转头预览 (选择第 0 个结果)
python -m hairdeck.vrm.export results/my_character/character 0
结果将按输入图片名称保存在 OUT/<image name>/ 目录下（上例对应 results/my_character/character/）。
关键参数说明：
--n：指定生成候选项的数量（范围 1–4）。--seed：指定起始随机种子，用于结果复现。--no-chains：仅生成发片几何与颜色，跳过弹簧骨骼链的预测与生成。--no-colors：禁用颜色预测，整套发型将使用单一基础发色。--ckpt与--chain_ckpt：若使用非默认模型权重，可通过这两个参数分别指定发片模型和骨骼链模型路径。需注意，这两个模型必须基于同一个 Card VAE 训练才能保证兼容性。
本地演示与输出文件结构
1. 本地 Web 演示
项目提供了基于 Gradio 的可视化界面，便于直观调整参数和查看结果：
python -m pip install -r requirements-demo.txt
python demo/app.py --port 7860
启动后，访问 http://127.0.0.1:7860 即可上传图片、预览生成的发型，并直接执行 VRM 导出或动画预览操作。
2. 输出文件结构解析
以随机种子 0 为例，执行完整工作流后，输出目录 results/my_character/character/ 将包含以下文件：
results/my_character/character/
├── input.png # 原始输入图像
├── prep.png # 预处理阶段的掩码与裁剪结果
├── model_input.png # 输入给模型的实际裁剪后图像
├── cards_seed0.json # 发片的几何数据与颜色属性配置
├── chains_seed0.json # 生成的弹簧骨骼链数据
├── hair_seed0.glb # 完整发型网格（包含 head proxy、各发片的 UV 和颜色）
├── hair_seed0_nohead.glb # 纯净发型网格（不包含 head proxy）
├── info.json # 本次生成的参数配置与结果元数据
├── avatar_seed0.vrm # 由 VRM 导出命令生成的最终虚拟化身文件
└── turn_seed0.mp4 # 由转头预览命令生成的角色展示视频
注：若使用了 --no-chains 参数，目录中将不会生成 chains_seed0.json 及相关骨骼绑定文件。其他随机种子的结果文件名将以对应的种子编号作为后缀。
© 版权声明
文章版权归作者所有，未经允许请勿转载。
