hyz317/HairDeck

HairDeck is a research release that converts a single character image into stylized 3D hair cards, plus the spring-bone chains used to animate them. It is aimed at technical artists and researchers working on game-ready or VRM avatars rather than at general image editing.

What it produces

Given an input image, the pipeline writes hair-card geometry as JSON, a hair_*.glb mesh with a head proxy and per-card UVs, and generated bone chains; the README also documents VRM export onto an avatar and a head-turn preview video. Each card is encoded as a token, and a conditional set diffusion transformer generates the whole hairstyle at once rather than card by card. A second chain diffusion model produces bones, with skinning and VRM export handled through Blender. See the project page and paper.

How it is used

There are three paths:

• Command line: an image-to-hair script generates 1–4 seeded variations, then a separate export command builds a VRM avatar.
• Local web demo: a Gradio app lets you generate hair, compare variations and export a VRM or animation preview in the browser.
• Hosted demo: a Hugging Face Space lets you try generation without local setup, though VRM export and downstream use still depend on the outputs you can download.

The README also documents test-set evaluation and a training recipe, so the repository is useful as a research reference, not only as an end-user tool.

Requirements and limits

Local use needs Linux x86-64, Python 3.12 and an NVIDIA CUDA GPU; the release was tested with PyTorch 2.8 and CUDA 12.8, and the video preview needs ffmpeg on the path. The weights downloader also fetches Blender 4.2 LTS and the VRM Add-on by default, with an option to point at an existing installation. SAM 3 and DINOv3 are gated, so you must accept their licences and log in before downloading. These conditions apply only to the local paths; the hosted demo does not require them.

The current image-training recipe uses synthetic appearance augmentation, but the restyled-render pool behind the released image model is not included, so the released model cannot be fully reproduced from the provided training script. HairDeck's code and checkpoints are Apache-2.0, while third-party models, code and datasets keep their own licences. See the README for setup details.