--- license: apache-2.0 library_name: pytorch pipeline_tag: image-to-3d tags: - 3d - anime - hair - hair-cards - vrm - diffusion - arxiv:2610.40599 ---

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.

Try the online demo Code on GitHub Project page arXiv: 2610.40599

**HairDeck turns a single character image into stylized hair cards with per-card UVs and colors, 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](https://huggingface.co/spaces/hyz317/HairDeck), or run the models locally with the [HairDeck code](https://github.com/hyz317/HairDeck). For local use, follow the [installation instructions](https://github.com/hyz317/HairDeck#installation) for Linux, Python 3.12 and a CUDA GPU. Accept the SAM 3 and DINOv3 licences and log in as described in [model setup](https://github.com/hyz317/HairDeck#model-weights). Then, from the code repository root: ```bash 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](https://github.com/hyz317/HairDeck#outputs) 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` | | **Color DiT** | Predicts the colors along each card, conditioned on the card tokens and the image. | `ckpt/color_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 + Color DiT + 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: ```bash python scripts/setup/download_weights.py --only test_data charm_test_pc dora ``` Follow the [evaluation guide](https://github.com/hyz317/HairDeck#test-set-evaluation) 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](https://github.com/hyz317/HairDeck#training). ## 📝 Citation ```bibtex @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.