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-волосы, готовые к анимации: он генерирует стилизованные карты волос и цепочки spring-bone, которые их анимируют. Результат можно экспортировать как GLB-меш или как аватар VRM.
Это готовое приложение или исследовательский код, который я запускаю сам?Это релиз исследовательского кода, который вы клонируете и запускаете из командной строки (есть также необязательный локальный демо-интерфейс), а не готовое приложение.
Как это запустить?После установки зависимостей и загрузки чекпоинтов вы запускаете скрипт быстрого старта на изображении персонажа, чтобы получить несколько вариантов причёсок, затем экспортируете один из них как аватар VRM и видео-превью поворота головы. Также есть локальный демо-интерфейс и онлайн-демо.
Что нужно, чтобы это запустить?Нужны Linux x86-64, Python 3.12, одна видеокарта NVIDIA с поддержкой CUDA (проверено с PyTorch 2.8 и CUDA 12.8), ffmpeg в PATH и Blender 4.2 LTS с аддоном VRM Add-on — загрузчик может установить их за вас.
Есть ли подводные камни при установке?Веса SAM 3 и DINOv3, от которых он зависит, закрыты доступом на Hugging Face: нужно принять их лицензии и войти в аккаунт, прежде чем загрузчик сможет их скачать. Кроме того, по умолчанию поставляется только сборка Blender для Linux x86-64.
В какие форматы файлов можно экспортировать созданную причёску?Карты волос можно экспортировать как GLB-меш или прикрепить к аватару и экспортировать результат как файл VRM.
Что здесь именно понимается под «картой волос»?Карта волос — это отдельный текстурированный полигональный фрагмент, который заменяет прядь волос. HairDeck кодирует каждую карту как один токен с помощью card VAE и генерирует всю причёску целиком как набор через диффузию, сохраняя UV-координаты каждой карты.
Можно ли попробовать HairDeck без настройки локального окружения?Да: помимо локального демо, можно попробовать онлайн-демо, не устанавливая ничего.
На каких данных обучена выпущенная модель?Обучение начинается с датасета CHARM и соответствующих файлов VRM персонажей с использованием рецепта синтетической аугментации внешности; пул перерисованных рендеров, использованный для выпущенной модели изображений, в этот релиз не входит.
Какие есть похожие проекты?UniMate, pointdit, idol-sdk, motionbricks, TRELLIS.2, Hunyuan3D-2, CodeVideoModel, wuji-ego-mint
Автор
hyz317
Размер
0.8 MB
Звёзды
1.2K
Обновлён
КоммитNov 13
Возраст
20 д
Коммиты · 90 дней