HairDeck

HairDeck

Turns one character image into stylized 3D hair cards with colors and spring-bone chains for animation, exported as GLB meshes or a VRM avatar. For avatar makers and 3D artists with a CUDA GPU.

Made by hyz317 on Hugging Face. These notes are Mindket's, written from its model page and model card; the model's own files and license are on Hugging Face.

About

What it is: HairDeck is a set of models that turn a single character image into stylized hair for a 3D avatar. The hair comes as cards, which are flat mesh strips that each have their own UV map and colors, plus spring-bone chains that let the hair move when the avatar animates. You get the hair meshes as GLB files, and you can attach them to the avatar body that ships with the project and export a VRM 0.x avatar.

Who it suits: It suits 3D artists and avatar creators who want animation-ready hair from a picture instead of building it by hand.

Industry | Who uses it | How they use it | Example
Games | 3D artists | Make animation-ready hair for a character from one image | Hair for a stylized game character
Virtual avatars | Avatar creators | Build a VRM avatar with moving hair | Export an avatar with spring-bone hair
Animation | Animators | Get hair meshes as GLB files for their tools | Import GLB hair into a 3D scene
AI research | Researchers | Study generative models for hair cards | Compare the image path with the point-cloud path

If you want photoreal strand hair for film, you can skip it, since the output is stylized hair cards.

Where to use it:

• A Linux machine with Python 3.12 and a CUDA GPU
• The online demo that the card offers, as a first try
• 3D tools that read GLB files, and apps that open VRM avatars

Use case | Who | What they get back
Hair from an image | Artists | Hair-card meshes as GLB files
Animated hair | Avatar creators | Spring-bone chains that move the hair
Avatar export | Creators | A VRM avatar with the hair attached, plus a head-turn video

How to set it up: You need these first:

• A Linux computer with a CUDA GPU, running Python 3.12
• The project's code repository on GitHub, which the card links
• Accepted SAM 3 and DINOv3 licences and a Hugging Face login, as the card describes
• ffmpeg, if you want video previews

1. Follow the install instructions in the code repository.
2. Agree to the licences for SAM 3 and DINOv3, then sign in to Hugging Face.
3. From the code repository root, set the workspace folder and run the weights download script.
4. Run the image script on your character picture, then the export command.

pip install -U huggingface_hub
hf download hyz317/HairDeck

How to use it: Run the image script on your character picture and ask for four variations. They land in a results folder. Then run the export command for one variation to get a VRM avatar and a head-turn video.

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

Tool | What it does
download_weights.py | Fetches the model weights and the extra assets
image_to_hair.py | Makes hair cards from a character image
hairdeck.vrm.export | Builds a VRM avatar and a head-turn video for one variation
ffmpeg | Needed for the video previews

Example: You run the image script on a cartoon character picture and get four hair variations. You pick the first one, run the export command, and get a VRM avatar with the hair attached. The card does not show a finished result here, so treat this as an expectation.

For newcomers and experts: Hair cards are flat strips of mesh with the hair color painted on them, a common way to make hair for games. Spring bones are chains that swing so the hair moves. A good first step is the online demo, before you set up the code.

The image path joins four models. The Image DiT makes hair-card tokens from the picture, the Card VAE turns each token into card geometry, the Color DiT paints the cards, and the Chain DiT adds the spring-bone chains. A separate point-cloud model feeds another path.

Give a character image
The Image DiT makes hair-card tokens
The Card VAE builds the card geometry
The Color and Chain models add colors and spring bones

Good to know: The setup pulls in outside models, and each comes with its own terms.

• Access: SAM 3 and DINOv3 need their licences accepted before setup works
• Outside models: Dora-VAE, BiRefNet-matting, SAM 3 and DINOv3 are pulled in from their own repositories
• Evaluation assets: optional, and the default download skips them
• License: Apache 2.0 for this repository, and the outside models carry their own licences
• Cost to run: none named, you supply the GPU
• Data it reaches: the character images you give it, and the extra models fetched from other repositories

On Hugging Face, 13 November 2026

• Task: image to 3d
• Library: pytorch
• Formats: Safetensors
• Downloads in the last 30 days: 3,681
• Likes: 70
• License: apache-2.0
• Tags: pytorch, safetensors, 3d, anime, hair, hair-cards, diffusion, image-to-3d

Links

• Model: https://huggingface.co/hyz317/HairDeck
• Files: https://huggingface.co/hyz317/HairDeck/tree/main

Get the model

Download its files with Hugging Face's command line:

pip install -U huggingface_hub
hf download hyz317/HairDeck

Then follow the usage in its model card. Nothing in this kit runs by itself.