# MakeHuman head prototype

Status: **owner-accepted head, assembled prototype, not yet shipped.**
The owner accepted the basic human head on 2026-11-04. The automated vision gate
still records REJECT on the eye/lid region as deferred polish. The asset is a
standalone head/neck extracted from the CC0 MakeHuman base in
`tmp/npc-research/makehuman/base.obj`; the assembled path now adds hair, a hidden
scalp trim and the procedural body. The 12 shipped GLBs have not been rebuilt
with it yet.

## Asset

- GLB: [`assets/models/blender_src/makehuman_head.glb`](../assets/models/blender_src/makehuman_head.glb)
- Review sheet: [`blender_previews/sheet_makehuman_head.jpg`](blender_previews/sheet_makehuman_head.jpg)
- Source workflow (development-only): `tmp/npc-research/build_makehuman_head.py`
  — extracts the MakeHuman head, cuts it at the neck, keeps the head/eye/mouth
  components, cuts an almond aperture through a skin eyelid mask, adds recessed
  eyeballs with flat iris/pupil discs, anchors brows to the face surface, renders
  front/three-quarter/profile and exports the standalone GLB.
- Measurements (final standalone build, `inspect`): **12,641 triangles / 7,690
  split vertices**; bounds approximately `x ±0.094 m`, `y -0.180…0.042 m`,
  `z 1.530…1.803 m` in project Z-up space.
- Assembled `npc_casual --head mh`: **14,753 triangles / 12,823 seam-split
  vertices / 14 bones / 9 materials**, `inspect` clean. All 12 variants count
  14,693–15,987 triangles with the same head.
- Materials used: `skin`, `eye_white`, `iris`, `pupil`, `hair`. No textures are
  baked into this prototype.

![MakeHuman head review sheet](blender_previews/sheet_makehuman_head.jpg)

## What was done

1. Imported the CC0 MakeHuman base OBJ and cleared the importer axis rotation.
2. Applied the project scale/axis transform: 1.82 m body, Z-up, metres,
   front −Y.
3. Cut the head at the neck (`z ≈ 1.53`) rather than keeping the cut shoulders;
   capped the neck opening.
4. Built an eyelid mask by subtracting an almond aperture from a skin sphere
   centred on each eye (`solver = "EXACT"`), then recessed the globes so the
   cornea sits behind the lid plane.
5. Added flat iris/pupil discs on the globe axis; disabled backface culling so
   the discs stay visible at three-quarter angles.
6. Anchored brow strips to the skin with object-space ray casts and added a
   shallow supraorbital ridge so they do not float, then reduced the crown
   height to improve the profile silhouette.
7. Fixed a material-remap bug introduced by joining the extra eye objects: the
   joined head faces were pointing at the `eye_white` slot, making the whole
   head render as white clay. The largest connected component is now forced
   back onto `skin` after the join.
8. Rendered front/three-quarter/profile views in a neutral review studio and
   exported the standalone GLB.

## Provenance

- Base mesh: MakeHuman / MPFB base, CC0, from the local research set
  `tmp/npc-research/makehuman/`; see [`CREDITS.md`](../CREDITS.md).
- The head is a **derived prototype**, not a shipped NPC. It does not enter
  `assets/models/blender/npc/`, `npc_base`, the runtime `NpcAvatar` path, CI, or
  a release package until the NPC overhaul plan accepts it.
- Source photographs/proportions are not used as textures here; this is a
  geometry-only head built from the researched model data.

## Review criteria

Accept only if:

- the head reads as human at front/three-quarter/profile and the neck is a
  clean head/bust silhouette, not a shoulder cut;
- eyes, brow, nose, mouth and ears are readable without spikes, holes or
  floating shells;
- the asset is inside the character budget and has no script/contract violation;
- the prototype remains clearly local and un-integrated until the part pipeline
  is approved.

## Judge result

**Owner verdict: ACCEPT (basic human head, 2026-11-04).**
**Automated vision gate: REJECT** (vision judge `z-ai/glm-5.3-flash`, final
standalone build render set above). The eye/lid findings below remain deferred
polish; they are no longer a rollout blocker because the owner accepted the head.

Blocking findings:

- **P0 — globe depth is inconsistent across views.** The front/three-quarter
  reads still show a bead-like iris with a pale sclera halo, while the profile
  reduces the eye to a brown sliver. The judge reads this as a faked recess
  rather than a socketed globe under a lid.
- **P0 — no convincing lid overlap.** The iris remains nearly circular in front
  and the upper lid does not visibly clip the globe; the skin lid mask reads as
  a crater around a bead.
- **P0 — iris orientation reads decal-locked** at three-quarter, so the gaze
  appears to drift off the head axis.
- **P0 — the aperture/lid mask is too circular** and lacks medial/lateral
  canthi, so the eye still reads as a doll eye at portrait distance.

Should-fix findings:

- the brow tubes are better anchored but the medial ends still detach in
  three-quarter/profile;
- nose lacks a defined tip/wing and nostrils;
- mouth is a faint geometric seam with no lip volume;
- crown/back-of-skull is still faceted and egg-like in profile;
- the catchlight is baked geometry and is not consistent between eyes.

What passed: the skin/eye material remap is correct, the eye openings are
closed, the standalone GLB reports **12,641 triangles / 7,690 split vertices**,
and an assembled `npc_casual` with this head passes `inspect` at **14,753 /
16,000 triangles, 12,823 seam-split vertices, 14 bones, no issues**.

Known limits: bald mannequin-like presentation, stylized geometry-only
iris/pupil, no rig, no UV texture pass, and the neck cap is a review cut rather
than a body-welded seam.

## Assembled prototype (2026-11-04)

- `_makehuman_head` imports the GLB and adds a **skull-conforming hair cap**
  derived from the closed head shell (scaled shell + boolean front-sphere
  cut + decimate). Hair skips the old `hair_normal.png` because the skull UVs
  produced large dark tangent patches.
- Head faces fully covered by the cap are deleted to recover ~950 triangles;
  boundary faces stay as a safety band, so the accepted face geometry is
  untouched. The hidden neck plug uses 12 segments.
- The procedural body was narrowed at the neck and shoulders (chest 0.158,
  neck base 0.060, neck top 0.054, shoulder root z 1.345) and its skin decimate
  dropped to 0.21 so all 12 variants fit the 16,000 cap.
- Local review renders: `tmp/npc-parts/prototype_mh/renders/` (portrait
  front/three-quarter/profile and full-body front/three-quarter).

## Deferred polish

- Replace the radial lid mask with real upper/lower lid masses that fold over
  the globe, with pointed canthi, and pass the profile view.
- Move the iris onto a curved cornea cap so its orientation follows the globe at
  three-quarter angles, and use a lighting-driven catchlight instead of baked
  white geometry.
- Refine the hair cap silhouette (current short cap reads as a helmet) and
  improve the full-body shoulder/arm shape before the 12-variant rollout.
- Add a clean UV/material pass and a contract armature/weights when the head
  becomes part of the shipped library characters.