Skip to content
Back to search

talking-head

SkillWorks with Claude CodeGitHub

Turn ONE illustrated portrait (a cartoon or drawn head and shoulders, front-facing) into a small 3D head for a web page that follows the pointer, blinks, and moves its jaw with a voice. Makes a GLB of about 1 MB with a "jaw" morph target plus a JSON of where the eyes and mouth sit, and ships a framework-free three.js viewer. Works offline (inflates the outline, or uses a mesh the user already has); can optionally ask the public Hunyuan3D-2 Space for a better shape, which uploads the picture. Use whenever the user wants a talking avatar, a 3D mascot or guide character for a site, a portrait that turns its head or follows the cursor, a head that lip-flaps to audio or text-to-speech, or wants to rebuild, re-mark or shrink a head made this way. Not for photos of real people, face capture, lip-sync to phonemes or deepfakes.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vinvirtual--talking-head/badge.svg)](/listings/vinvirtual--talking-head)

HTML

<a href="/listings/vinvirtual--talking-head"><img src="/api/listings/vinvirtual--talking-head/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 1. the skill itself (for Claude Code; any folder works if you only use the command line)
git clone https://github.com/VinVirtual/talking-head ~/.claude/skills/talking-head
cd ~/.claude/skills/talking-head

# 2. Blender 4.2 or newer, any way you like, for example:
sudo snap install blender --classic

# 3. three.js for the preview and example pages (your own site uses its own copy)
npm install

# 4. only if you want the public generator
python3 -m pip install gradio_client

# 5. check
./head check

Everything is found in default places that you can change with environment variables:

| Variable | Default | What | |---|---|---| | `HEAD_BLENDER` | `blender` on PATH, then `/snap/bin/blender` and other usual places | the Blender program | | `HEAD_CHROME` | `google-chrome`, `chromium` and similar on PATH | browser for the preview sheet | | `HEAD_THREE` | `node_modules/three` in the skill folder, then in the current folder | three.js for the local pages (`preview`, `mark --page`, `serve`, `test --browser`). Nothing is loaded from a CDN: without it those commands stop and say to run `npm install` | | `HEAD_PYTHON` | the Python running `head` | Python that has `gradio_client` |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 83 lines
  1. ---
  2. name: talking-head
  3. description: Turn ONE illustrated portrait (a cartoon or drawn head and shoulders, front-facing) into a small 3D head for a web page that follows the pointer, blinks, and moves its jaw with a voice. Makes a GLB of about 1 MB with a "jaw" morph target plus a JSON of where the eyes and mouth sit, and ships a framework-free three.js viewer. Works offline (inflates the outline, or uses a mesh the user already has); can optionally ask the public Hunyuan3D-2 Space for a better shape, which uploads the picture. Use whenever the user wants a talking avatar, a 3D mascot or guide character for a site, a portrait that turns its head or follows the cursor, a head that lip-flaps to audio or text-to-speech, or wants to rebuild, re-mark or shrink a head made this way. Not for photos of real people, face capture, lip-sync to phonemes or deepfakes.
  4. ---
  5. # talking-head
  6. Pipeline: **shape** (a raw mesh of the figure) → **mark** (eyes, mouth, chin in the picture) → **build** (headless Blender: fit the mesh to the drawing, project the drawing on as the texture, add a `jaw` morph target, export GLB + JSON) → **view** (`viewer/viewer.js`, three.js).
  7. Skill folder: `~/.claude/skills/talking-head/` (written below as `$H`). Every command is `$H/head <command> <project>`. `$H/head help` lists them.
  8. ```
  9. $H/head the command line (check, new, shape, mark, build, preview, verify, serve, test)
  10. $H/pipeline/cli.py the commands
  11. $H/pipeline/headmath.py the pure maths (feature mapping, jaw, validation, size budget), unit tested
  12. $H/pipeline/blender/ the Blender steps (job.py is the entry; build.py, fit.py, inflate.py, imaging.py, mesh.py)
  13. $H/pipeline/generate_space.py the one call to the public generator
  14. $H/viewer/viewer.js, math.js the viewer to copy into the user's site
  15. $H/pages/ preview sheet page and marking page (served by the command line)
  16. $H/examples/ a finished example (Juno, a fictional character) and a demo page
  17. $H/references/formats.md config.json, marks.json, head.json and viewer options
  18. $H/README.md install, licences, limits
  19. ```
  20. ## Before you start: three questions
  21. 1. **Whose picture is it?** If it shows a real person (a photo or a drawn likeness), the user needs that person's consent. Ask. Do not build a head of a public figure or of anyone the user cannot speak for. This tool makes a cartoon puppet, not a likeness capture, and must not be used to impersonate.
  22. 2. **May the picture leave this machine?** `--source space` uploads it to Hugging Face, to a public Space run by Tencent. Never choose that yourself. Offer it and say plainly: it uploads the picture; the model's licence does not apply in the European Union, the United Kingdom or South Korea (do not use it, or show its output, there); it needs a separate licence from Tencent above 1 million monthly active users; and its output must not be used to train or improve other AI models. Use it only when the user says yes, and then pass `--yes-upload` (without it the command refuses when it cannot ask).
  23. 3. **Is the picture suitable?** Front-facing, head and shoulders, illustrated, transparent or flat-coloured background, 1000 pixels or more on the longer side. If it is a vector drawing, rasterise it large. If the background is busy, cut the figure out first (any tool) and save a PNG with transparency.
  24. ## Workflow
  25. 1. **Check the machine**: `$H/head check`. It works offline and contacts nobody; it says how to fix what is missing. Blender is required; Chrome is needed for the preview; three.js (`npm install` in the skill folder) for the local pages. Add `--online` only if the user wants to know whether the public generator is up: that sends a request to huggingface.co.
  26. 2. **Start a project**: `$H/head new <dir> <portrait.png>`. Put it next to the user's other asset sources, not inside the web app's source tree.
  27. 3. **Shape**: pick one.
  28. - `$H/head shape <dir> --source inflate`: made here from the outline. Always works. A puffy shape with a nose bump and no other face detail.
  29. - `$H/head shape <dir> --mesh FILE`: any mesh of this figure the user already has (GLB, glTF, OBJ, PLY, STL). If it faces another way, pass `--front` or `--up` to `build`.
  30. - `$H/head shape <dir> --source space --yes-upload`: the public generator. Only after the user agreed to the upload. It asks once. If it is refused (quota, busy), **do not retry in a loop**: fall back to inflate and say so.
  31. 4. **Mark**: `$H/head mark <dir> --auto`, then check the numbers against the picture. They are a guess.
  32. - If you can see the picture, compare: each eye oval should cover the whole eye including its outline; the mouth is the centre of the closed mouth with the size of the *open* mouth; the chin is the bottom of the chin.
  33. - To fix them, either edit `marks.json` by hand (pixels from the top-left; `references/formats.md`) or run `$H/head mark <dir> --page` and give the user the address it prints. That command waits until they press Save.
  34. 5. **Build**: `$H/head build <dir>`. About a minute. Read what it prints:
  35. - `fit: head overlap` should be above 0.9. Below 0.8 the mesh is probably facing the wrong way (`--front +y`, `--up +y`) or is not a shape of this picture.
  36. - `jaw moves N points` must not be 0. If it is, the mouth and chin marks are not on the face.
  37. - If it says the file is over budget it has already reduced quality, texture or faces. Tell the user what it gave up.
  38. 6. **Look**: `$H/head preview <dir>`, then **Read `out/preview.png`**. Never say it looks right without looking. Check:
  39. - front: does it match the picture? Features in the right place, no smears on the face;
  40. - turned left and right: are the sides acceptable? If not, lower `maxTurn` in `config.json` (0.4 hides most of it) and rebuild;
  41. - blink: do the lids cover both eyes completely, in a colour that matches the skin around them? If not, fix the eye marks (bigger `half`) or pass `colors: { lid }` to the viewer;
  42. - mouth open: does the opening hang from the drawing's own smile line, corners on the line's ends? The build prints `lip line found` or `not found`. If not found, or it caught the wrong line (a nose, a crease), move the mouth mark onto the line between the lips and rebuild;
  43. - turned, talking: do the overlays stay on the face?
  44. Fix the marks or config, rebuild, preview again.
  45. 7. **Verify**: `$H/head verify <dir>`. Every line must say `ok`.
  46. 8. **Put it in the page**:
  47. - Copy `out/head.glb` and `out/head.json` to the site's static assets, and `$H/viewer/viewer.js` and `math.js` into its source. three.js must be installed in the site (`npm i three`).
  48. - Mount it on a canvas the site sizes with CSS (square is best). Call `dispose()` when the component unmounts; the same canvas can be mounted again (StrictMode, hot reload).
  49. - Drive the mouth: `head.setTalking(true, level)` where `level()` returns 0 to 1. For an `<audio>` element use `audioLevel(audio)` from the viewer (create it inside a click handler). It returns `null` for audio from another origin without CORS (analysing it would mute it): then call `setTalking(true)` with no level, or serve the file with CORS and add `crossorigin="anonymous"`. For text-to-speech with no audio element, `head.setTalking(true)` gives a speech-like rhythm; call `setTalking(false)` when it ends.
  50. - Load the viewer lazily (dynamic `import()`) if the head is not at the top of the page: three.js is the heavy part.
  51. - Give the canvas an `aria-label`, and keep a static `<img>` of the portrait as the fallback for when WebGL or the files fail (`head.ready` rejects with the reason).
  52. 9. **Label it.** On every path (inflated, own mesh or generated), a head that talks to visitors must be labelled as computer-generated where it appears, for example "Animated, computer-generated character" next to it or in its `aria-label`. Add that to the page you build, and tell the user why. With the public generator its licence requires it; on the other paths it is still the honest thing to do.
  53. 10. **Tell the user** what the head cannot do (README, "Limits"), which shape source was used, and, if the public generator was used, that the model's licence asks for machine-made content to be identified as such and does not cover the EU, UK or South Korea.
  54. ## What to expect, honestly
  55. - From the front it is the drawing. Turned, it has real depth, but past about 35 degrees the sides are plain colour and stretched lines.
  56. - Eyelids are simple shapes laid on the surface. The open mouth is shader-drawn from the drawing's own lip line. Both suit flat cartoon styles and look plain on painterly ones.
  57. - The jaw follows loudness only. It is not lip-sync.
  58. - With `--source inflate` the profile is a balloon with a nose. Say so when you use it.
  59. ## Changing things
  60. - Smaller file: `--budget 800`, or `--faces 12000 --texture 1024`.
  61. - Jaw opens too much or too little: `"jawDrop"` in `config.json` (plane units; the default is 15% of mouth-to-chin). Rebuild.
  62. - Wrong lid or mouth colours: `createTalkingHead(canvas, { colors: { lid: '#…', mouth: '#…' } })`. No rebuild needed.
  63. - No outline wanted, or a thicker one: `outline: false` or `outline: { width: 0.012, color: '#…' }` in the viewer options.
  64. - A hand-made, already clean mesh: `--no-remesh` keeps its topology.
  65. ## Rules
  66. - One Blender process at a time. Each `shape --source inflate`, `mark --auto` and `build` starts one and waits for it.
  67. - Never upload a picture without the user's yes. Never retry the public generator in a loop.
  68. - Do not commit `work/` folders. The GLB, the JSON and the marks are what is worth keeping.
  69. - After changing anything in `pipeline/headmath.py` or `viewer/math.js`, run `$H/head test`.
README.md · README · 200 lines
  1. # talking-head
  2. [![test](https://github.com/VinVirtual/talking-head/actions/workflows/test.yml/badge.svg)](https://github.com/VinVirtual/talking-head/actions/workflows/test.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  3. One illustrated portrait in, a small 3D head and shoulders for a web page out. The head follows the pointer, blinks, and moves its jaw with a voice.
  4. You give it a picture. It gets a rough 3D shape for that picture, lines the shape up with the drawing, projects the drawing onto it as the texture, adds a `jaw` morph target, and exports a GLB (about 0.7 MB in the example) plus a small JSON file that says where the eyes and mouth sit. A framework-free three.js module (`viewer/viewer.js`) shows the result.
  5. It is packaged as a [Claude Code](https://claude.com/claude-code) skill (`SKILL.md` tells the assistant how to use it), and it also works by hand from the command line.
  6. ![Six poses of the example head: front, turned left, turned right, blink, mouth open, turned while talking](examples/juno/out/preview.png)
  7. The example character, Juno, is an original drawing made for this repository (`examples/juno/portrait.svg`). She is not a real person.
  8. ## What it makes
  9. - `head.glb`: one mesh, one JPEG texture, one morph target called `jaw`. Unlit: the drawing already carries its own light and shade.
  10. - `head.json`: where the eyes and mouth are on the surface (with a small grid of depths around each, so eyelids and the open mouth follow the curve of the head), the drawn line between the lips, how far the jaw drops, colours for the eyelids, lashes and lower lip taken from the picture, and the width and colour of the drawing's outline.
  11. - `preview.png`: a contact sheet of six poses, drawn by the real viewer in headless Chrome, so you can look before you ship.
  12. - In the page: pointer follow, blinking, a jaw driven by a loudness function (or a speech-like rhythm when there is no sound to follow), the drawing's outline redrawn around the head so it survives turning, no drawing while off screen, `prefers-reduced-motion` respected, and a `dispose()` that frees everything.
  13. ## Limits
  14. Read these before you plan around it.
  15. - **It works best on front-facing illustrated portraits**: a cartoon or drawn head and shoulders, looking at the viewer, on a transparent or flat-coloured background. Photos, three-quarter views, hands in front of the face, glasses and long fringes over the eyes all give poor results.
  16. - **It is not a face-capture, lip-sync or deepfake tool.** The jaw opens and closes with loudness. There are no visemes, no expressions, no eye movement, and nothing is learned from video of a person.
  17. - **Get consent before using a picture of a real person**, including a drawn likeness. Do not use it to impersonate anyone.
  18. - **With `--source space` the picture is uploaded to a third party**: Hugging Face (huggingface.co), to a public Space run by Tencent. It only happens with `--yes-upload` or a typed `yes`, after a message naming Hugging Face, the Space and the licence's territory limit. Only the picture is sent, as `input.png`, and anonymously: `gradio_client` would otherwise attach a Hugging Face login saved on your machine, so the request is made with `token=False` and `HF_HUB_DISABLE_IMPLICIT_TOKEN=1`. Nothing is sent at all with `--source inflate` or `--mesh`, and `head check` only contacts huggingface.co with `--online`.
  19. - **Say that the character is computer-generated.** A talking head that speaks to visitors should be labelled as computer-generated wherever it appears, whichever shape source made it. When the shape came from the public generator, its licence requires that anyway (see below).
  20. - **The picture only covers the front.** Past roughly 35 to 40 degrees of turn you see surfaces the drawing never showed. They get plain colour carried over from the nearest part of the drawing (hair stays hair-coloured, skin stays skin-coloured), with no detail. The viewer turns at most 0.6 radians (34 degrees) by default for this reason.
  21. - **Line work stretches at the sides.** Where the surface turns away, the projected drawing is stretched, so outlines near the edge smear into streaks when the head is turned.
  22. - **Eyelids and the open mouth are drawn on top, not modelled.** The eyelid is a skin-coloured patch, curved to the surface, with a lash line. The open mouth is drawn by a small fragment shader on a patch seated on the face: the opening starts on the drawing's own lip line (found in the picture by the build), its corners stay pinned to the line's ends, and only its lower edge drops, showing a shaded inside, a tooth edge, a tongue, a thin lower line and a soft lower-lip rim. This suits flat cartoon styles. On a painterly drawing it will look simpler than the rest, and when no lip line is found (an open-mouthed drawing, a very faint line) it opens from a straight line across the marked mouth instead.
  23. - **The jaw and the drawn mouth are separate.** The `jaw` morph target moves the chin and the skin below the lip; the opening is drawn over it. At full opening the drawing's own lower lip and any crease under it are covered by the drawn mouth.
  24. - **The texture is never sharper than the picture.** The face is laid out in the texture exactly as it is in the picture, so it keeps the picture's sharpness, but nothing can add detail that is not there. Start from a picture at least 1000 pixels on its longer side. If your source is a vector drawing, export it large.
  25. - **`--source inflate` knows nothing about faces.** It blows the outline up like a balloon and adds a bump for the nose. There are no eye sockets, lips, ears or separate hair volume. It is the offline fallback. A generated or hand-made mesh gives a much better profile.
  26. - **Hidden parts are guessed.** Areas hidden in the drawing (under the chin, inside a collar) take a plain colour from nearby. The build leaves line work out of that colour, to avoid the dark stripes that outlines otherwise cause there. This has only been tested on the inflated example, where little is hidden.
  27. - **The automatic marks are a guess** from typical proportions and what is drawn nearby. Always look at the preview, and fix them on the marking page when they are off.
  28. - **Tested on Linux only**, with Blender 5.3, Chrome and Node 24. The public-generator path could not be run to the end while making this release (see "What was and was not tested").
  29. ## Requirements
  30. | Needed | Why | Licence |
  31. |---|---|---|
  32. | Python 3.9 or newer | runs the `head` command (standard library only) | PSF |
  33. | [Blender](https://www.blender.org/) 4.2 or newer | cleans the mesh, bakes the texture, exports the GLB. Run as a separate program, headless | GPL-2.0-or-later |
  34. | [three.js](https://threejs.org/) r160 or newer | the viewer's peer dependency | MIT |
  35. | Google Chrome or Chromium (optional) | draws the preview sheet | Chrome: proprietary freeware. Chromium: BSD-style and others |
  36. | Node.js 18 or newer (optional) | runs the viewer's unit tests | MIT |
  37. | [gradio_client](https://pypi.org/project/gradio-client/) (optional) | only for `--source space` | Apache-2.0 |
  38. None of these is included in this repository. You install them yourself, and their licences apply to your use of them. About 1 GB of free memory is enough. No GPU is needed.
  39. ### Licence notes
  40. Checked on 21 November 2026. Check again before you rely on them. This is not legal advice.
  41. - **talking-head's own code and the example character** are under the **MIT License** (see `LICENSE`).
  42. - **Blender** is GPL-2.0-or-later. talking-head runs it as a separate program and does not include or link any Blender code. The scripts in `pipeline/blender/` call Blender's Python API (`bpy`) and are offered under MIT here. **Could not verify** (the Blender Foundation's licence page refused the request while this was written, so this is from memory): the Foundation's position is that what you create with Blender is yours, and that published scripts which call its Python API must be under a GPL-compatible licence. MIT is generally regarded as GPL-compatible. Read https://www.blender.org/about/license/ yourself if this matters to you.
  43. - **three.js** is MIT.
  44. - **The public generator** (`--source space`) is the Hugging Face Space [`tencent/Hunyuan3D-2`](https://huggingface.co/spaces/tencent/Hunyuan3D-2), running the model [`tencent/Hunyuan3D-2`](https://huggingface.co/tencent/Hunyuan3D-2). Both carry the **Tencent Hunyuan 3D 2.0 Community License Agreement** (the model card says `license: other`, `license_name: tencent-hunyuan-community`; the `LICENSE` files in the model and Space repositories were read in full). What it says, as read on that date:
  45. - **It does not apply in the European Union, the United Kingdom or South Korea.** The licence is limited to a "Territory" defined as the rest of the world, and section 5(c) says you must not use, reproduce, modify, distribute or display the model *or its Output* outside that Territory. If you or your site's visitors are in those places, do not use this source.
  46. - **Outputs:** "Tencent claims no rights in Outputs You generate. You and Your users are solely responsible for Outputs and their subsequent uses." (section 6(d)).
  47. - **Commercial use is not forbidden in general.** Section 4 ("Additional commercial terms") requires a separate licence from Tencent if your products or services had more than 1 million monthly active users in the preceding calendar month.
  48. - You must not use Outputs to improve any other AI model (section 5(b)).
  49. - The Acceptable Use Policy (Exhibit A) forbids, among other things, impersonating a person without consent, and placing generated content in any public context "without expressly and conspicuously identifying that the information and/or content is machine generated". If you publish a head whose shape came from this model, say so.
  50. - **Could not verify:** whether using the hosted Space through its API adds terms beyond this licence and Hugging Face's own terms of service; what the Space does with uploaded pictures (retention, logging, reuse); and whether the copy of the licence in the Space repository (which names an older Tencent entity) or the newer copy in the model repository governs the Space. Treat uploads as public.
  51. - The Space is a free shared demo on Hugging Face ZeroGPU. Anonymous use has a small quota and requests are refused when it is used up. `head shape` asks once and never retries.
  52. - **Any other mesh you bring** (`--mesh`) comes with the terms of whatever made it.
  53. - **The example voice** (`examples/juno/voice.mp3`) was made on the author's machine with the [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M) text-to-speech model (tagged Apache-2.0 on its model card). It is not a recording of a person.
  54. ## Install
  55. ```bash
  56. # 1. the skill itself (for Claude Code; any folder works if you only use the command line)
  57. git clone https://github.com/VinVirtual/talking-head ~/.claude/skills/talking-head
  58. cd ~/.claude/skills/talking-head
  59. # 2. Blender 4.2 or newer, any way you like, for example:
  60. sudo snap install blender --classic
  61. # 3. three.js for the preview and example pages (your own site uses its own copy)
  62. npm install
  63. # 4. only if you want the public generator
  64. python3 -m pip install gradio_client
  65. # 5. check
  66. ./head check
  67. ```
  68. Everything is found in default places that you can change with environment variables:
  69. | Variable | Default | What |
  70. |---|---|---|
  71. | `HEAD_BLENDER` | `blender` on PATH, then `/snap/bin/blender` and other usual places | the Blender program |
  72. | `HEAD_CHROME` | `google-chrome`, `chromium` and similar on PATH | browser for the preview sheet |
  73. | `HEAD_THREE` | `node_modules/three` in the skill folder, then in the current folder | three.js for the local pages (`preview`, `mark --page`, `serve`, `test --browser`). Nothing is loaded from a CDN: without it those commands stop and say to run `npm install` |
  74. | `HEAD_PYTHON` | the Python running `head` | Python that has `gradio_client` |
  75. ## Quick start
  76. ```bash
  77. H=~/.claude/skills/talking-head/head
  78. $H new my-head portrait.png # a project folder: portrait.png, config.json
  79. $H shape my-head --source inflate # a shape made on this machine. Or: --mesh your.glb or: --source space --yes-upload
  80. $H mark my-head --auto # estimate eyes, mouth, chin. Then check: $H mark my-head --page
  81. $H build my-head # out/head.glb and out/head.json
  82. $H preview my-head # out/preview.png. Look at it.
  83. $H verify my-head # loads, has the jaw, fits the size budget, JSON complete
  84. ```
  85. Then in your page (with three.js available to your bundler or import map):
  86. ```js
  87. import { createTalkingHead, audioLevel } from './talking-head/viewer/viewer.js';
  88. const head = createTalkingHead(document.querySelector('canvas'), { model: '/head.glb', surface: '/head.json' });
  89. await head.ready;
  90. const audio = document.querySelector('audio');
  91. let voice;
  92. button.addEventListener('click', () => {
  93. voice ??= audioLevel(audio); // first call must come from a click or key press; null if it cannot listen
  94. voice?.resume();
  95. audio.play();
  96. head.setTalking(true, voice?.level); // no level: a speech-like rhythm instead
  97. });
  98. audio.addEventListener('ended', () => head.setTalking(false));
  99. ```
  100. Copy `viewer/viewer.js` and `viewer/math.js` into your project (two files, about 35 KB together before minifying, most of it comments). Give the canvas a size with CSS; a square works best.
  101. About the voice: `audioLevel` routes the element's sound through a Web Audio analyser and on to the speakers. A file from another origin can only be analysed when it is fetched with CORS (`crossorigin="anonymous"` on the element and `Access-Control-Allow-Origin` on the file). Without that, analysing it would mute it, so `audioLevel` returns `null`, warns in the console and leaves the element playing normally; pass no level and the mouth follows a speech-like rhythm. An element can be connected to Web Audio only once in its life, so after `close()` use a new `<audio>` element.
  102. `dispose()` leaves the canvas usable, so a component can mount again on the same canvas (React StrictMode, hot reloading). Pass `releaseContext: true` to also force the WebGL context to be lost when you will not use that canvas again.
  103. ### The finished example
  104. ```bash
  105. $H serve # then open http://127.0.0.1:8437/examples/ (needs npm install in the skill folder)
  106. ```
  107. `examples/juno/` is a complete project folder (`head verify examples/juno` passes): the SVG she was drawn as, the rasterised `portrait.png`, `config.json`, `marks.json` (the automatic estimate, checked by eye against the picture and the preview), `out/head.glb`, `out/head.json`, `out/preview.png`, and a short voice line. The example page uses the fonts already on the visitor's machine and makes no request to any other site. Her shape is the inflated one (`--source inflate`): the public generator refused the request made for this release, so she has a puffy profile with a nose bump and no modelled ears or hair volume. To rebuild her from the portrait:
  108. ```bash
  109. $H new juno examples/juno/portrait.png
  110. $H mark juno --set examples/juno/marks.json
  111. $H shape juno --source inflate && $H build juno && $H preview juno
  112. ```
  113. ## Commands
  114. | Command | What it does |
  115. |---|---|
  116. | `head check` | checks Python, Blender and its version, node, Chrome, three.js and `gradio_client`, without using the network. `--online` also asks huggingface.co whether the public generator is running |
  117. | `head new <project> <portrait>` | starts a project folder from a PNG or JPEG. Pictures with an EXIF orientation tag are refused: rotate them upright and save without the tag, so Blender and the marking page see the same pixels |
  118. | `head shape <project>` | gets the raw shape into `work/`. `--source inflate` builds one from the outline on this machine. `--mesh FILE` uses a mesh you already have from any tool (GLB, glTF, OBJ, PLY, STL). `--source space --yes-upload` uploads the picture to the public Hunyuan3D-2 Space on Hugging Face (`--space` picks another Space with the same interface, `--seed N`); without `--yes-upload` it asks, and from a script it refuses. You must choose a source: nothing is uploaded by default. An existing shape is only replaced after the new one has arrived |
  119. | `head mark <project>` | with nothing else, prints and checks the marks. `--auto` estimates them (`--force` to replace). `--page` serves a page on this machine where you drag ovals onto the eyes and mouth and press Save (the neck is only saved if you move it; otherwise the build finds it). `--set FILE` copies a marks file in |
  120. | `head build <project>` | clean, fit, texture, jaw, feature spots, export. Options: `--faces N` (default 24000), `--texture 512\|1024\|2048\|4096`, `--budget KB` (default 1500), `--front -y\|+y\|-x\|+x` and `--up +z\|+y\|…` for a mesh that faces or stands another way, `--no-remesh`. If the file is over budget it lowers JPEG quality, then texture size, then face count, and says what it did. Exits non-zero if it still does not fit |
  121. | `head preview <project>` | draws `out/preview.png` with the real viewer in headless Chrome: front, turned left, turned right, blink, mouth open, turned while talking. `--tile N` sets the size of each picture |
  122. | `head verify <project>` | checks the GLB parses, has exactly one mesh, the `jaw` target and one texture, is within the budget, and that the JSON is complete |
  123. | `head serve [project]` | serves the skill folder (and a project at `/project/`) on 127.0.0.1 for the example page. It answers only requests addressed to 127.0.0.1, localhost or [::1] on its port, never serves dot-files, and accepts saves only as JSON carrying a token made for that run |
  124. | `head test` | runs the unit tests (`python -m unittest` and `node --test`, no extra packages; the Python tests also run under pytest). `--browser` also runs the viewer in headless Chrome (remounting on one canvas, disposing while loading, junk loudness values, `audioLevel`). `HEAD_BLENDER_TESTS=1` adds a full Blender build that feeds the example's own `head.glb` back in |
  125. `shape`, `mark` and `build` take `--verbose` to show everything Blender prints. Each Blender run's full output is kept in `work/blender-<task>.log`.
  126. `references/formats.md` describes `config.json`, `marks.json`, `head.json` and the viewer's options.
  127. ## How it works
  128. 1. **Shape** (`pipeline/generate_space.py`, `pipeline/blender/inflate.py`): a raw, untextured mesh of the figure. From the public generator, from your own file, or inflated from the outline.
  129. 2. **Mark** (`pipeline/blender/job.py`): where the eyes, mouth, chin and neck are in the picture, in pixels. Estimated, then corrected by you.
  130. 3. **Build** (`pipeline/blender/build.py`), in headless Blender:
  131. - the mesh is turned to face the front, any flat backing plate a generator left behind the figure is removed, and the surface is rebuilt from its volume;
  132. - its front outline is fitted to the figure's outline, the head and the body separately, and the mesh is moved into the picture's own space, so from the front it lines up with the drawing;
  133. - the picture is projected on from the front. Points the picture cannot see take a plain colour spread along the surface from the nearest points it can;
  134. - the texture is baked. Faces the picture covers are laid out exactly as in the picture, in one piece;
  135. - points between the mouth and the chin get a `jaw` morph target, strongest at the chin;
  136. - the depth of the surface around each eye and the mouth is sampled, the line between the lips is traced from the drawing's line work, and the eyelid, lash, lip and outline colours are read from the picture.
  137. 4. **View** (`viewer/viewer.js`): three.js loads the GLB, shows it unlit, drapes eyelids over the eyes and seats a shader-drawn mouth on the lip line using the depths from the JSON, and animates.
  138. ## What was and was not tested
  139. - The whole pipeline was run on the example with `--source inflate`, and with the same shape exported as an OBJ facing backwards (`--mesh`, `--front +y`), with a flat plate added behind it, from a JPEG with a flat background, and with a tight size budget. The preview sheets were looked at.
  140. - The viewer and the example page were run in headless Chrome (software WebGL) at desktop and phone widths, with the voice playing.
  141. - **Not tested:** a mesh that really came from the public generator. The Space refused the one request made while building this release ("exceeded your ZeroGPU runs limit"), so the example uses the inflated shape. The request code is the same call that produced the original head this skill was generalised from, but in this repository it has only been run as far as that refusal.
  142. - **Not tested:** macOS, Windows, Firefox, Safari, real GPUs, phones.
  143. ## Development
  144. ```bash
  145. ./head test # 79 Python tests and 26 JavaScript tests
  146. ./head test --browser # plus 5 viewer tests in headless Chrome
  147. HEAD_BLENDER_TESTS=1 ./head test # plus a full Blender build (about a minute)
  148. ./head build <project> --verbose # everything Blender says
  149. ./head preview <project> # then look at the PNG
  150. ```
  151. The maths that can be tested without Blender or a browser lives in `pipeline/headmath.py` and `viewer/math.js`. The Blender steps use `headmath.py` directly, so what the tests check is what runs.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.