|
Download README.md from Microguy1/HairDeck-DUPLI: direct link, hf CLI and curl.
- Browser
- Download file 7.25 kB
-
https://huggingface.co/Microguy1/HairDeck-DUPLI/resolve/main/README.md
- Command line
-
hf download hf://Microguy1/HairDeck-DUPLI/README.md
-
curl -L -o README.md https://huggingface.co/Microguy1/HairDeck-DUPLI/resolve/main/README.md
7.25 kB
| license: apache-2.0 | |
| library_name: pytorch | |
| pipeline_tag: image-to-3d | |
| tags: | |
| - 3d | |
| - anime | |
| - hair | |
| - hair-cards | |
| - vrm | |
| - diffusion | |
| - arxiv:2610.40599 | |
| <h1 align="center">HairDeck: Animation-Ready Stylized Hair Cards<br>from a Single Image</h1> | |
| <p align="center" style="font-size: 14px; line-height: 1.6;"><a href="https://hyzcluster.github.io/">Yuze He</a><sup>1,*</sup> Yixiang Wei<sup>1,*</sup> <a href="https://thuzhaowang.github.io/">Wang Zhao</a><sup>1</sup> <a href="https://czzzzh.github.io/">Chuhao Chen</a><sup>2</sup> <a href="https://amandaynzhou.github.io/">Yanning Zhou</a><sup>3,†</sup> <a href="https://yongjinliu.github.io/">Yong-Jin Liu</a><sup>1,†</sup></p> | |
| <p align="center" style="font-size: 13px; line-height: 1.6;"><sup>1</sup>Tsinghua University <sup>2</sup>Carnegie Mellon University <sup>3</sup>The Chinese University of Hong Kong</p> | |
| <p align="center" style="font-size: 12px; line-height: 1.6;"><sup>*</sup>Equal contribution. <sup>†</sup>Corresponding authors.</p> | |
| <p align="center"> | |
| <a href="https://huggingface.co/spaces/hyz317/HairDeck"><img src="https://img.shields.io/badge/%F0%9F%A4%97%20Demo-Try%20it-ffd21e" alt="Try the online demo"></a> | |
| <a href="https://github.com/hyz317/HairDeck"><img src="https://img.shields.io/badge/Code-GitHub-181717?logo=github" alt="Code on GitHub"></a> | |
| <a href="https://hyzcluster.github.io/HairDeck"><img src="https://img.shields.io/badge/Project-Page-426b92" alt="Project page"></a> | |
| <a href="https://arxiv.org/abs/2610.40599"><img src="https://img.shields.io/badge/arXiv-2610.40599-b31b1b" alt="arXiv: 2610.40599"></a> | |
| </p> | |
| **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. | |
| <video controls playsinline preload="metadata" src="https://huggingface.co/hyz317/HairDeck/resolve/main/assets/hairdeck-demo.mp4" poster="https://huggingface.co/hyz317/HairDeck/resolve/main/assets/video-poster.jpg" style="width: 100%; height: auto;"></video> | |
| ## 🚀 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. | |
| <details> | |
| <summary>Detailed file layout and checkpoint format</summary> | |
| | 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. | |
| </details> | |
| ## 📊 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. | |