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

Yuze He^1,*   Yixiang Wei^1,*   Wang Zhao¹   Chuhao Chen²   Yanning Zhou^3,†   Yong-Jin Liu^1,†

¹Tsinghua University   ²Carnegie Mellon University   ³The Chinese University of Hong Kong

^*Equal contribution.   ^†Corresponding authors.

HairDeck turns a single character image into stylized hair cards with per-card UVs and the spring-bone chains that animate them. Generate hair meshes as GLB files, then attach the hair to the provided avatar body and export a VRM 0.x avatar.

🚀 Try HairDeck

Start with the online demo, or run the models locally with the HairDeck code.

For local use, follow the installation instructions for Linux, Python 3.12 and a CUDA GPU. Accept the SAM 3 and DINOv3 licences and log in as described in model setup. Then, from the code repository root:

export HAIRDECK_ROOT=/path/to/workspace
python scripts/setup/download_weights.py
python scripts/image_to_hair.py character.png --out results/my_character --n 4
python -m hairdeck.vrm.export results/my_character/character 0

download_weights.py downloads the model bundle and supporting assets. Inference writes four variations under results/my_character/character/; the export command creates a VRM and head-turn video for seed 0. Video previews require ffmpeg. See the output guide for the generated files.

🧩 Released models

Model	Role	Weights
Image DiT	Generates hair-card tokens conditioned on an image.	ckpt/image_model/model.safetensors
Card VAE	Decodes each card token's latent into card geometry.	ckpt/card_vae/model.safetensors
Chain DiT	Generates spring-bone chains conditioned on the card tokens.	ckpt/chain_model/model.safetensors
Point-cloud DiT	Generates hair-card tokens conditioned on a point cloud.	ckpt/pointcloud_model/model.safetensors

The image pipeline combines Image DiT + Card VAE + Chain DiT. The point-cloud model is used by the point-cloud generation and evaluation path. Both paths also need the supplied normalization statistics; use the downloader above to obtain the matching files together.

DINOv3, SAM 3, BiRefNet-matting and Dora-VAE are fetched from their own repositories when needed. Their weights are not bundled here. The image model uses DINOv3 ViT-L/16 features, and the point-cloud model uses Dora-VAE 1.1 features.

📦 Supporting assets

This repository also provides normalization statistics, the canonical head frame, the avatar body used for VRM export, and example images. Evaluation assets are optional and skipped by the default download.

Detailed file layout and checkpoint format

Path	Content
ckpt/card_vae/	Card VAE weights, normalization statistics and latent statistics.
data/token_stats.json, data/token_stats_head.json	Card-token normalization in the dataset and head frames.
data/head_frame_train.npz	Canonical head-frame data.
data/spring/chain_stats_head.json	Chain-token normalization.
data/avatar/	The provided VRoid Studio template avatar, its original hair and head-frame fit.
data/demo_examples/	Example input images for the demo.
data/test_cards_orig/, data/test_cards_orig_dirs.npz	Original hair-card geometry and width directions for the 100 test cases.
data/spring/chains_test.jsonl, data/spring/chains_test_head.npz	Test characters' spring-bone chains and their head-frame tokens.
data/head_params_test.json, data/head_frame_test.npz, data/cards_test.npz	Test head fits, head frames and card features.
ckpt/card_vae/latents_test_head.npy	Head-frame latents of the test cards for chain-model conditioning.
config.json	Released models, supporting files and checkpoint format.
MANIFEST.json	File sizes and SHA-256 hashes for the downloadable model/data bundle.

The DiT checkpoints contain EMA weights; the Card VAE contains its model weights. Training configuration is stored in the safetensors metadata under hairdeck and read by hairdeck.ckpt.load. Use the HairDeck code to load these checkpoints.

📊 Evaluation

To download the additional test assets and point-cloud encoder:

python scripts/setup/download_weights.py --only test_data charm_test_pc dora

Follow the evaluation guide to run the point-cloud and chain benchmarks. The default tests sample seeds 0, 1 and 2 and save per-sample metrics and their means. Training instructions are in the code repository.

📝 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}
}

License

The HairDeck checkpoints are released under Apache-2.0.