HairDeck README

项目的 README,来自 github.com/hyz317/HairDeck。合并为一个 markdown 文件:README.md。

HairDeck: Animation-Ready Stylized Hair Cards
from a Single Image

Yuze He1,*   Yixiang Wei1,*   Wang Zhao1   Chuhao Chen2   Yanning Zhou3,†   Yong-Jin Liu1,†

1Tsinghua University   2Carnegie Mellon University   3The Chinese University of Hong Kong

*Equal contribution.   †Corresponding authors.

Project page arXiv: 2610.40599 Model weights on Hugging Face Try the online demo Watch the demonstration

English · 简体中文 · 日本語

🔥 Updates

Video

https://github.com/user-attachments/assets/3eec4de5-ed21-4b75-b7d7-4bd599cbfeb2

Overview

HairDeck generates stylized hair cards and the spring-bone chains that animate them from a single image. Each hair card is represented by one token, and a set diffusion transformer generates the cards jointly. The generated hairstyle can be exported as a GLB mesh or attached to an avatar and exported as VRM.

HairDeck pipeline: hair-card tokens, image- or point-cloud-conditioned set diffusion, and generated cards with spring-bone chains.

Getting started

🛠️ Installation · 🤗 Model weights · 🚀 Quick start · 🖼️ Local demo · 📦 Outputs · 📊 Evaluation · 🏋️ Training · 📝 Citation

🛠️ Installation

HairDeck runs on Linux and native Windows with an NVIDIA CUDA GPU, Python 3.12, PyTorch 2.8 and CUDA 12.8. Apple silicon Macs run it on MPS (see macOS below).

Windows: Follow Windows setup to install the environment and launch Gradio.

macOS (Apple silicon): Follow macOS setup: the same pipeline runs on Apple MPS, without CUDA or Triton.

AMD ROCm (Linux): See ROCm setup for the tested Radeon 8060S / Strix Halo container, including HIP-enabled torchvision and headless rendering.

Linux: Install the dependencies below and make ffmpeg available on your PATH.

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  # without its old PyOpenGL pin

Run the commands below from the repository root, in the same Python environment.

🤗 Model weights

Our checkpoints and supporting assets are hosted at hyz317/HairDeck. SAM 3 and DINOv3 are gated: first accept their licences on facebook/sam3 and facebook/dinov3-vitl16-pretrain-lvd1689m, then log in:

hf auth login
export HAIRDECK_ROOT=/path/to/workspace  # checkpoints, data, third-party weights and outputs
python scripts/setup/download_weights.py

Chinese users can refer to the Chinese README for download instructions.

The downloader sets up the HairDeck checkpoints, preprocessing and image-encoder weights, supporting data, and Blender 4.2 LTS with the VRM Add-on. The downloader selects the Blender build for your operating system. To use an existing Blender 4.2 LTS installation with the VRM Add-on enabled, set HAIRDECK_BLENDER to its command.

The default workspace layout is:

$HAIRDECK_ROOT/
├── ckpt/                       # HairDeck checkpoints and latent statistics
├── data/                       # Normalization statistics, avatar and demo examples
└── third_party/
    ├── weights/
    │   ├── dinov3/             # facebook/dinov3-vitl16-pretrain-lvd1689m
    │   ├── sam3/               # facebook/sam3
    │   └── birefnet_matting/    # ZhengPeng7/BiRefNet-matting
    ├── dinov3_src/             # DINOv3 source
    ├── sam3_src/               # SAM 3 source
    └── blender/                # Blender and the VRM Add-on

Individual locations can be configured through environment variables or a JSON file; see configs/paths.example.json and hairdeck/paths.py.

🚀 Quick start

Generate four variations from a character image, then export variation 0 as a VRM avatar and a head-turn video:

python scripts/image_to_hair.py character.png --out results/my_character --n 4
python -m hairdeck.vrm.export results/my_character/character 0

Results are written to OUT/<image name>/, here results/my_character/character/. --n accepts 1–4 variations; --seed sets the first seed. Use --no-chains to generate cards only, and --no-colors for one hair color. For custom models, pass --ckpt and a matching --chain_ckpt trained with the same card VAE. Set HAIRDECK_FAST=1 to sample with the fast sampler (2-3x faster sampling at small batch sizes, measured on NVIDIA and AMD; on by default with ROCm).

🖼️ Local demo

python -m pip install -r requirements-demo.txt
python demo/app.py --port 7860

Open http://127.0.0.1:7860 to generate hair, inspect variations, and export a VRM or animation preview. You can also try the hosted demo.

📦 Outputs

The main files for seed 0 are:

results/my_character/character/
├── input.png                   # Input image
├── prep.png                    # Preprocessing masks and crop
├── model_input.png             # Image crop used by the model
├── cards_seed0.json             # Hair-card geometry and colors
├── chains_seed0.json            # Generated spring-bone chains
├── hair_seed0.glb               # Hair with a head proxy, per-card UVs and colors
├── hair_seed0_nohead.glb         # Hair without the head proxy
├── info.json                    # Generation settings and result metadata
├── avatar_seed0.vrm             # Created by the VRM export command
└── turn_seed0.mp4               # Created by the head-turn preview command

Other variations use their corresponding seed in the filename. The chains file is omitted with --no-chains.

📊 Test-set evaluation

On Linux, download the evaluation assets, then run the point-cloud and chain tests. Each test samples seeds 0, 1 and 2, prints the corresponding paper metrics, and saves per-sample results and their means in eval.json.

python scripts/setup/download_weights.py --only test_data charm_test_pc dora
python scripts/test.py pointcloud
python scripts/test.py chains                                # On the artists' cards
python scripts/test.py chains --cards results/pointcloud     # On the point-cloud model's cards

Evaluation paths such as results/pointcloud follow the workspace layout under HAIRDECK_ROOT and its path overrides.

🏋️ Training

On Linux, start from the CHARM dataset and the characters' VRM files:

python scripts/setup/download_weights.py --only dora test_data charm_test_pc
python scripts/data.py DATASET_DIR VRM_DIR
bash scripts/train/launch_vae.sh
bash scripts/train/launch_pc_dit.sh && bash scripts/train/launch_img_dit.sh && bash scripts/train/launch_chain_dit.sh
bash scripts/train/launch_color_dit.sh

The launchers write to ckpt/train_*, separately from the downloaded checkpoints. The image-training recipe includes synthetic appearance augmentation.

🧩 Community

📝 Citation

@misc{hairdeck2026,
  title         = {HairDeck: Animation-Ready Stylized Hair Cards from a Single Image},
  author        = {Yuze He and Yixiang Wei and Wang Zhao and Chuhao Chen and Yanning Zhou and Yong-Jin Liu},
  year          = {2026},
  eprint        = {2610.40599},
  archivePrefix = {arXiv},
  primaryClass  = {cs.CV},
  doi           = {10.48550/arXiv.2610.40599},
  url           = {https://arxiv.org/abs/2610.40599}
}

Acknowledgments

HairDeck uses CHARM, Dora-VAE, DINOv3, SAM 3, BiRefNet, and the VRM Add-on for Blender. We thank their authors for making these resources available.

License

HairDeck code and checkpoints are licensed under Apache-2.0. Third-party models, code and datasets retain their respective licences.

HairDeck (hyz317/HairDeck)

正在搜索数据库…

这是什么?HairDeck 是一个研究流程,只需一张角色图像,就能生成可用于动画的 3D 头发:它会生成风格化的发片(hair cards)以及驱动这些发片摆动的弹簧骨骼链(spring-bone chains),结果可导出为 GLB 网格或 VRM 虚拟形象。
这是打包好的应用,还是需要我自己运行的研究代码?这是一个研究代码发布版,需要你克隆下来并通过命令行运行(可选配本地演示界面),而不是现成的应用程序。
怎么让它跑起来?安装依赖并下载检查点之后,对一张角色图像运行快速启动脚本,即可生成多种发型变体,然后导出其中一款,得到一个 VRM 虚拟形象和一段转头预览视频;另外还提供本地演示界面和在线演示。
运行之前需要准备什么?需要 Linux x86-64、Python 3.12、一块 NVIDIA CUDA GPU(已用 PyTorch 2.8 和 CUDA 12.8 测试)、PATH 中可用的 ffmpeg,以及附带 VRM Add-on 的 Blender 4.2 LTS;下载器可以帮你完成 Blender 的设置。
安装时有哪些需要注意的坑?它依赖的 SAM 3 和 DINOv3 权重在 Hugging Face 上受门控,因此必须先接受其许可协议并登录,下载器才能获取它们;默认情况下,它也只提供 Linux x86-64 版本的 Blender。
我可以把生成的发型导出为哪些文件格式?你可以将发片导出为 GLB 网格,也可以把它们附加到虚拟形象上,并将结果导出为 VRM 文件。
这里的“发片(hair card)”到底指什么?发片是一块带纹理的网格小面片,用来代表一簇头发;HairDeck 使用发片 VAE 将每张发片编码为一个词元(token),再通过扩散模型把整套发型作为一个整体一起生成,并保留每张发片的 UV 坐标。
不配置本地环境,我也能试用 HairDeck 吗?可以,除了本地演示,你还可以在安装任何东西之前,直接在线试用托管的演示版本。
已发布的模型是用什么数据训练的?训练从 CHARM 数据集以及对应角色的 VRM 文件开始,采用合成外观增强方案;用于已发布图像模型的风格化渲染图数据池不包含在本次发布中。
作者
hyz317
大小
0.8 MB
星标
1.2K
更新
提交Nov 13
时长
20天
提交 · 90 天