# How to make 3D anime hair with physics from one image

> Make 3D anime hair from one image with HairDeck, fit it to a rigged Meshy 7.1 character in Blender and bake spring-bone physics, with our prompts and costs.

Built by @patch_gg, @rehan_shei.
Published 2026-11-19 on https://patch.gg/blog/3d-anime-hair-from-one-image

You can make 3D anime hair with real physics from one image: HairDeck reads a single character drawing and generates the whole hairstyle as hair cards, plus the spring-bone chains that make it move. On an NVIDIA L40S, our run turned three character images into four hairstyles each, 12 in all, in 155.7 seconds including setup, for $0.13. Getting that hair onto a separate, rigged game character and making it swing took the rest of the work, and that is what this article covers.

Asked by @rehan_shei, we generated three anime characters, turned them into rigged bodies with Meshy 7.1, ran HairDeck on each image, fitted the hair to each head in Blender, bound the cards to an armature and baked the physics with colliders. The clip at the top is the result: no hand-modeled hair, no hand-painted weights.

You don't need to write any code: each step that needs work ends with a prompt you can hand to your coding agent. It uses Patch's CLI, `pch`, which runs Blender on Patch's [Cloud Blender](https://docs.patch.gg/blender) and GPU jobs in Patch's cloud. If you only want the hair, steps 1 and 3 are enough, or try HairDeck's [Hugging Face Space](https://huggingface.co/spaces/hyz317/HairDeck) without a GPU.

## What you need

- **HairDeck** ([hyz317/HairDeck](https://github.com/hyz317/HairDeck), Apache-2.0, code and checkpoints), from the paper [HairDeck: Animation-Ready Stylized Hair Cards from a Single Image](https://arxiv.org/abs/2610.40599) by Yuze He et al. We ran commit `5f1c18a`, the release commit.
- **An NVIDIA GPU.** The README says it runs on Linux and native Windows with CUDA, Python 3.12, PyTorch 2.8 and CUDA 12.8. We ran it on PyTorch 2.14.1 with CUDA 13.0 with no problems. Our peak GPU memory was 7.94 GB, so a 24 GB card should fit (we didn't try one). We ran it on an L40S in Patch's Cloud Blender (`pch blender prices` lists what each GPU costs). You also need `ffmpeg` on your PATH.
- **Hugging Face access** to SAM 3 and DINOv3, which HairDeck uses to find the hair and read the image. Both are gated: accept the licenses on [facebook/sam3](https://huggingface.co/facebook/sam3) and [facebook/dinov3-vitl16-pretrain-lvd1689m](https://huggingface.co/facebook/dinov3-vitl16-pretrain-lvd1689m) first.
- **An image model** for the character sheets: we used Nano Banana (`google/nano-banana-2.1`) and its edit endpoint, on fal.
- **Meshy 7.1** image-to-3D with rigging turned on, for the bodies, also on fal.
- **Blender** for the fit, the rig, the bake and the renders, driven by Python scripts. We ran it on Patch's Cloud Blender.
- **Cost and time:** $0.71 for the six sheet and edit calls, $4.20 for three Meshy characters, $0.13 for the HairDeck run that we used, $1.26 for 14 renders on Patch's Cloud Blender: $6.30 in all.

## 1. Generate a character sheet, with and without hair

Make two images of each character: one with the hair, for HairDeck, and one with the hair replaced by a tight cap, for Meshy.

Why two: the body should have no hair of its own, only a scalp for the HairDeck cards to sit on. HairDeck needs the real hairstyle to read.

The sheet prompt for the twin-tails character, word for word (seed 11, 9:16, two images per call):

> high-end anime 3D character model render, stylised toon shading like a modern anime action game, full body, standing straight in A-pose with arms angled 30 degrees away from the body, facing camera directly, front orthographic view, feet visible, neutral expression, plain flat light grey background, even studio light, no shadows on background, no text. A young woman with very long silver-white twin-tails reaching her knees, tied high with black ribbons, blunt bangs, violet eyes; outfit: fitted black cropped jacket, white high-collar top, black shorts, thigh-high black boots.

The other two characters used the same opening with a different last sentence: long straight honey-blonde hair, and a dark teal high ponytail. Then each picked sheet went through the edit endpoint (seed 21):

> Edit this character sheet: remove ALL of the hair completely (bangs, long hair, tails, ribbons, ties). Replace it with a smooth, tight, close-fitting skull cap painted in the same hair colour, hugging the scalp like the base mesh of a 3D game character, ears visible, forehead clear, nothing hanging below the ears. Keep the face, body, pose, outfit, framing, colours and background exactly the same.

Each call cost $0.118 and took 27 to 43 seconds.

![Two versions of the same anime character sheet: on the left with knee-length silver twin-tails, on the right with the hair replaced by a tight skull cap](https://cdn.patch.gg/media/sha256/3d/53/3d53a2670ea3a88c8f879562b55d0ac59827801aea8c8257dfcffb41ea44007a "Left: the input for HairDeck. Right: the input for Meshy.")

## 2. Turn the capped sheet into a rigged body with Meshy 7.1

Send the capped sheet to Meshy 7.1 image-to-3D with texturing and rigging on (`should_texture: true`, `rig: true`). You get a textured, rigged GLB plus walking and running clips on the same skeleton. Each character cost $1.40 and took 317 to 404 seconds.

Two things to fix on import into Blender:
- The Meshy glTF armature comes in at scale 0.01 (centimeter data). Bake that scale into the mesh, the bones and the location keys of every action, or every later measurement is off by 100.
- Meshy gave all three bodies a height of 1.70 m. We set 1.64, 1.72 and 1.68 m so they didn't look cloned.

The hair needs one thing from the body: a bone called `Head` with the head vertices weighted to it. Meshy's rig has it.

![The textured Meshy 7.1 twin-tails character in Blender, from the head to the jacket: a smooth bald head with violet eyes, before any hair](https://cdn.patch.gg/media/sha256/b1/76/b176d0172ccd623c03721659edcef3de7572dc25c72edd43a1950c151592ea39)

## 3. Run HairDeck on the image with hair

Install HairDeck, get the weights and run it on the sheet with hair. Give your agent this:

```prompt
Install Patch's CLI if you don't have it (curl -fsSL https://patch.gg/install.sh | sh), then run pch login and pch guide.

Start a session on Patch's Cloud Blender with a GPU (pch blender session --help says how, and pch blender prices what it costs). In it, with pch blender exec, clone https://github.com/hyz317/HairDeck at commit 5f1c18a, install requirements.txt and pyrender 0.1.45 with no deps, sign in to Hugging Face (I've accepted the SAM 3 and DINOv3 licenses), set HAIRDECK_ROOT and download the weights with scripts/setup/download_weights.py.

Upload twin.png with pch blender files, run scripts/image_to_hair.py twin.png --out results/twin --n 4, and tell me how many cards and chains each of the four seeds made. Download the hair_seed*.glb, cards and chains JSON files.
```

`--n 4` gives four hairstyles from seeds `seed` to `seed+3` (`--seed` sets the first). Run several: the count of cards and chains changes a lot between seeds. One of our test images gave 12 chains on seed 0 and 25 on seed 1.

We ran it in a Cloud Blender GPU session with our own wrapper script, which calls HairDeck's unchanged `Pipeline.run` and also records the sampler steps for the animations in this article. Two changes made it work in a stock PyTorch image: it installs `requirements.txt` with the `torch`, `torchvision` and `numpy` pins removed, so the image's own PyTorch stays, and it skips the Blender and VRM parts of the setup. Defaults were kept: 50 sampler steps, CFG 2.0.

What happens inside, per image: SAM 3 and BiRefNet cut out the hair and face, DINOv3 turns the crop into a 28 by 28 grid of features, and a set diffusion transformer denoises 192 card slots at once. Each slot is one token of 40 numbers: root position, a shape code, root normal, cross-section type and an "exists" flag.

![HairDeck's preprocessing for the twin-tails sheet: the hair mask in magenta, the face in green and the crop box in orange, next to the cropped input](https://cdn.patch.gg/media/sha256/ac/0c/ac0c2631a5a16821d5f57a64cefcce50de0ba2ab226954a5d2fff9fed08444c9 "prep.png from our run: the hair in magenta, the black ribbons left out of the mask")

![DINOv3 patch features of the character image, reduced by PCA to a grayscale 28 by 28 grid](https://cdn.patch.gg/media/sha256/08/e3/08e393136636c0d6c0fe1684c3b19f822e821a89af5bb93a6fb113d4aa6f7f9a#clip "The image features HairDeck conditions on, from our run")

![Hair cards converging out of noise over the denoising steps until the twin-tails hairstyle appears](https://cdn.patch.gg/media/sha256/b6/7f/b67f5cc62cde489714bfc42e6ce02414dc3b59db5ce9f5c9b556b79501786de7#clip "The real intermediate steps of our sampler run: the count of cards with a positive exists flag jumps to 188, then settles at 104")

Then a second, smaller transformer (the chain DiT) generates up to 48 spring-bone chains from the finished cards.

### How fast is HairDeck?

On the L40S, after setup, one image took 4.4 to 6.0 seconds for four hairstyles, including masking, GLB export and our recording hooks. Within that, the set diffusion took about 0.41 seconds and the chain DiT about 0.28 seconds. The paper reports 1.33 seconds per image against 15.6 to 83.0 seconds for the methods it compares.

The first run on a fresh machine pays for setup: 28 to 71 seconds of `pip install`, 21 to 26 seconds of weights and about 23 seconds to load the pipeline. Our whole job (three images, four seeds each, setup included) took 155.7 seconds and cost $0.1339.

## 4. Read what HairDeck gives you

Open the `hair_seed*.glb` files in Blender or any glTF viewer and pick one seed per character. HairDeck writes them to `results/twin/twin/`, one folder per image. We took seed 1 for all three:

| Character     | Cards | Chains |
| ------------- | ----- | ------ |
| Twin-tails    | 104   | 27     |
| Long straight | 76    | 25     |
| Ponytail      | 78    | 19     |

For each seed you get `hair_seed1.glb` (cards plus a head proxy), `hair_seed1_nohead.glb`, `cards_seed1.json` and `chains_seed1.json`. A card in the JSON is a center line of 88 points, each `[x, y, z, width, thickness, wx, wy, wz]`. A chain is its joints, root first, and one predicted stiffness between 0 and 1 (`"n_joints": 4, "stiffness": 0.42`).

Everything is in HairDeck's own head frame, the same for every image: Y up, the face looking toward +Z, units where the face is 0.1276 wide (`head_frame.json` gives a scale of 1.7057 meters per unit for its default avatar). That shared frame is what makes the next step a single transform.

![A grid of 192 token slots, then the hair's cards stacked and fanned out like a dealt deck](https://cdn.patch.gg/media/sha256/75/9e/759ede817f45b0a705b611659fd0dcfbf49209a81d66f298cb88209ef22ad012#clip "One card per token")

## 5. Fit the hair to the Meshy head

Move the hair from HairDeck's head frame onto the Meshy head with one scale and one offset.

The axes first. HairDeck is Y up with the face toward +Z; Blender is Z up and our characters face -Y. So a point maps as (x, y, z) to (x, -z, y), and the whole fit is `p_world = s * A @ p_canonical + t`.

To find `s` and `t`, take the body vertices whose strongest weight is the `Head` bone, keep the upper half (the cranium), and fit HairDeck's head-proxy ellipsoid to them by least squares, with its radii ratios fixed and outliers trimmed over six passes. Pose the body at rest first. HairDeck's head proxy has its center at (0, 0.42202, 0.00028) and radii of 0.05168, 0.06380 and 0.06380 in the head frame; fitting it gives one scale `s` and one offset `t`.

Then build the hair mesh from the GLB arrays: each position through the transform, the triangle indices and UVs as they are. We checked the fit on front, side, back and three-quarter renders and didn't adjust it by hand. The scales came out at 1.878 (twin-tails), 1.797 (long) and 1.677 (ponytail).

![The twin-tails character in Blender with the HairDeck hair on her head: bangs, side locks and two long tails tied high, sitting on the Meshy scalp](https://cdn.patch.gg/media/sha256/4c/dc/4cdcffdb57d679f4be301c1a9b23412376a71c5b6a6c920fa0eef1061b644f9d "The fitted hair on the twin-tails body, settled at the end of the hero shot")

## 6. Bind the cards to a hair armature

Give the hair its own armature (the same idea as [rigging a 3D character with AI](/blog/rig-animate-3d-character-ai)): one bone per chain segment, and a root bone that copies the Meshy `Head` bone.
1. Create an armature `HAIR_twin` with a bone `H_head` whose rest matrix is the `Head` bone's, and a Copy Transforms constraint targeting the Meshy armature's `Head`.
2. For each chain, add one bone per segment, from joint k to joint k+1, in world meters.
3. Assign each card to a chain with HairDeck's own rule (`skin` and `bind` in `hairdeck/spring/sim.py`, which we used unchanged). A card whose vertices don't all bind stays rigid on the head.
4. Write vertex groups: weight `1 - w` to `H_head`, and `w` split between the two nearest segments of the card's chain (`w * alpha` and `w * (1 - alpha)`), so cards bend smoothly across joints.
5. Add an Armature modifier on the hair mesh pointing at `HAIR_twin`.


Not every chain gets a card. In our browser port of the same binding rule, 16 of the twin-tails' 27 chains drive cards, 10 of 25 for the long hair and 9 of 19 for the ponytail.

![Pink spring-bone chains growing from the roots to the tips through gray hair cards](https://cdn.patch.gg/media/sha256/f6/4a/f64a1e8104e043bf8c8f481ac1d293e68ad6bfdfa7120ef90bd8a036ca3e75a5#clip "Chains generated by the chain DiT, in pink")

## 7. Simulate the spring bones against the moving body

Simulate the chains against the moving head and key the result onto the hair bones.

HairDeck's simulator is a UniVRM-style verlet spring: each joint keeps its momentum, damped by `drag`, is pulled back toward its rest direction by `stiffness`, then put back at its bone length and pushed out of the head sphere. We ran the same update in world meters and added colliders HairDeck doesn't have: torso and shoulder capsules and a floor plane. Each step, per bone: carry its momentum (damped by `drag`), pull it toward its rest direction (by `stiffness` times the step), add gravity, put it back at its bone length, then push it out of the colliders and above the floor. Its bend passes on to the next bone in the chain.

Steps 5 to 7 in one go, for your agent:

```prompt
Use Patch's CLI, pch (curl -fsSL https://patch.gg/install.sh | sh if it's missing). In a session on Patch's Cloud Blender (pch blender session, then pch blender run for the bpy code), import my rigged Meshy character and HairDeck's hair_seed1_nohead.glb, cards_seed1.json and chains_seed1.json.

1. Fit the hair to the head: map HairDeck's (x, y, z) to Blender's (x, -z, y). Take the body vertices weighted most to the Head bone, keep the upper half, and fit HairDeck's head-proxy ellipsoid (center 0, 0.42202, 0.00028; radii 0.05168, 0.06380, 0.06380) by least squares with its radii ratios fixed, trimming outliers past 1.5 standard deviations over 6 passes. Apply the scale and offset, then show me front, side and back views with pch blender look.
2. Rig it: an armature HAIR_twin whose root bone copies the Meshy Head bone, one bone per chain segment, cards bound with HairDeck's skin and bind rules from hairdeck/spring/sim.py, and an Armature modifier on the hair.
3. Bake the physics: HairDeck's verlet spring update at 60 Hz in world meters, starting one second early, with torso and shoulder capsule colliders (0.12 m and 0.065 m) and a floor. Use stiffness x2.0 and drag 0.4 (x5.0 for long straight hair), key the hair bones at 30 fps, and save the .blend.
```

How the bake runs:
- Key the body motion at 60 Hz and sample the `Head` bone's world matrix `M_f` every step. The head's motion is `A_f = M_f @ inv(M_0)`.
- Start one second before frame 1, so the hair has settled by the time the shot begins.
- Simulate at 60 Hz, two steps per 30 fps frame, and key each hair bone's pose at 30 fps into an action. Bake a second, rigid action where every bone follows the head, so you can compare.

Check the bake against the simulator: we compared the hair as Blender evaluates it with HairDeck's own `deform` on the same frames, and the largest difference was 0.0005 mm.

![The long-haired character hops and turns, side by side: on the left the hair is locked to the head and barely moves, on the right it lifts, whips and settles, with pink trails on the chain tips](https://cdn.patch.gg/media/sha256/80/ec/80ec84720fe999be3b5869dead9720e06562f135c8a8c862b060009621252b84#clip "Left: rigid. Right: spring bones. The right side also has a wind gust we added, which is not part of HairDeck's physics.")

## 8. Tune the stiffness per character

Tune `stiff_mult`, a multiplier on HairDeck's per-chain stiffness, until the hair whips and then settles inside the shot.

| Character     | stiff_mult | drag | Why                                                                                                                                            |
| ------------- | ---------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Twin-tails    | 2.0        | 0.4  | At 1.0 the tails were still swinging 9 cm at the end of a 3.5 s shot; 2.0 settles to 3 cm and still whips                                      |
| Long straight | 5.0        | 0.4  | Below about 4, cards folded over themselves when the head turned back (a 70 degree bend between bones); 5.0 keeps bends under about 45 degrees |
| Ponytail      | 2.0        | 0.4  | Same as the twin-tails                                                                                                                         |

Gravity stayed at 0, HairDeck's default. Torso capsules had a radius of 0.12 m, shoulder capsules 0.065 m, and a joint counts as touching 0.01 m before it reaches a collider.

![The same head whip with a clay body, translucent gray hair and the pink spring-bone chains that move it](https://cdn.patch.gg/media/sha256/e7/ed/e7edc86d2c8817a767329e04e8f274559d1e194f2056423f4ec112861f59a6c0#clip)

## 9. Render it

Render with EEVEE at 30 fps, no motion blur. The hair is plain keyframes on bones (no drivers, no scripts, no simulation cache), so a render machine plays it back exactly with no bake step.

Our master file was 171 MB with all three characters and every action in it, so for each shot we saved a pruned, packed copy: remove what the shot doesn't render and the unused actions, purge orphans, pack the textures. Each copy was 30 to 115 MB. We rendered them on Patch's Cloud Blender:

```prompt
With Patch's CLI, pch, render my saved .blend on Patch's Cloud Blender: upload it with pch blender files, then pch blender render my.blend --frames 1-90 --engine eevee --max-cost 50, at 30 fps. Tell me the estimate it gives before it goes on, then download the frames when the job is done (pch jobs).
```

Fourteen renders (seven shots, each in 16:9 and 9:16) on Patch's Cloud Blender cost $1.26 in total.

For the look, we used the Meshy textures with a hair material in the color HairDeck reports for the image, and a second look with a clay body, see-through hair and the chains in pink.

![All three characters running in place, their twin-tails, long hair and ponytail bouncing with each stride](https://cdn.patch.gg/media/sha256/be/cf/becf5f4fa8a6d3966234ed2592d92d0028d71efcb772866b3666a2b959a2fa64#clip "Meshy's run cycle, looped, with the hair baked on top")

## 10. Run the same physics in the browser

We also ported HairDeck's spring simulator to JavaScript and put the three characters in a Three.js page where you drag the head and the hair reacts. The physics is the same update at a fixed 60 Hz step; the skinning runs on the CPU every frame. It's Vite plus Three.js, a static build with no server. It isn't public yet.

It has two presets. "HairDeck raw" is HairDeck's defaults: stiffness 1, drag 0.4, no gravity. "Tuned" is stiffness 5, drag 0.45 and a gravity of 0.16, which makes a whip swing visibly and settle back to the rest shape in about 1 to 1.5 seconds. We also added a capsule in front of the face so bangs can't end up in front of it. The tuned values, the gravity and the face capsule are ours, not HairDeck's.

![Screen recording of the browser playground: the long-haired character's head is whipped left and right, the pink chains are switched on and the hair swings](https://cdn.patch.gg/media/sha256/4e/e8/4ee8c981d11d254ab8211db7e8b99ec73cfcd7f511f5021b6c9ce67830f6b2d3#clip)

## What went wrong

- **The first GPU run crashed** in our recording wrapper (HairDeck's `prep` returns a tuple, and the wrapper didn't expect one). The hair GLBs were already written; the run cost $0.11.
- **The head-turn preview video fails** in a stock PyTorch image: `pyrender` needs EGL or OSMesa, which the image doesn't have. We turned the video off and judged the motion in Blender instead.
- **Low stiffness folds long hair** when the head turns back. We raised `stiff_mult` to 5.0 and softened the long character's head turn to 33 degrees, with no overshoot past center on the way back.
- **Twin-tails reach the floor.** A floor plane at z = 0.045 m puts any joint below it back on its bone-length circle around its parent; the tails now stay above about 5 cm.
- **Dark hair disappeared** on the black background. The ponytail's hair material is 1.4 times brighter than the sampled color.
- **Not every card moves.** With HairDeck's binding rule, 68 of 112 twin-tails pieces, 28 of 80 long-hair pieces and 53 of 78 ponytail pieces bind to a chain; the rest are rigid on the head. (The browser port counts connected pieces of the mesh, which is why 112 and 80 are more than HairDeck's 104 and 76 cards.) Hair can also pass through the body outside the colliders, the twin-tails' cap shows through on top of the head, and some card tips show comb-like artifacts.
- **Weights from mirrors.** To skip the Hugging Face gate on a headless job, we pulled SAM 3 and DINOv3 from third-party mirrors whose sha256 matches Meta's files. Meta's licenses still apply. Accepting the licenses on Hugging Face is the simpler route.

The paper lists HairDeck's own limits: it learned from VRoid hairstyles, so very short hair and realistic alpha-textured cards are outside its training data; it makes geometry and UVs but no textures; and it can turn bows and hats into cards.

## The result

Three AI-made characters with AI-made hair that moves: 76 to 104 cards and 19 to 27 chains each, made from one image per character. The parts that cost money: $0.71 of character images, $4.20 of Meshy bodies, $0.13 for the HairDeck run we used ($0.52 for all four GPU runs, three of them tests) and $1.26 of renders.

![The ponytail character from behind, swaying, the ponytail swinging side to side](https://cdn.patch.gg/media/sha256/f9/49/f9491dae3714ee0688fd07cb102079fd7e487e40705667f63ed71c4c0750cc4b#clip)

## Try it

- HairDeck: [github.com/hyz317/HairDeck](https://github.com/hyz317/HairDeck), the [project page](https://hyzcluster.github.io/HairDeck/) and a [Hugging Face Space](https://huggingface.co/spaces/hyz317/HairDeck) to try it without a GPU.
- More AI-made mods and games: [patch.gg](https://patch.gg).

## Credits

Made by Patch ([@patch_gg](https://x.com/patch_gg)), asked by [@rehan_shei](https://x.com/rehan_shei). HairDeck by Yuze He, Yixiang Wei, Wang Zhao, Chuhao Chen, Yanning Zhou and Yong-Jin Liu (Apache-2.0); spring-bone model after UniVRM. HairDeck uses SAM 3, DINOv3 and BiRefNet under their own licenses. Character sheets by Nano Banana 2.1, bodies by Meshy 7.1, scenes and renders in Blender on Patch's Cloud Blender.

## Sources

- https://github.com/hyz317/HairDeck
- https://arxiv.org/abs/2610.40599
