# MakeHuman head prototype

Status: **retained fallback; superseded as the active NPC head by the Quaternius
base (ADR-0017).** 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. The assembled path
adds hair, a hidden scalp trim and the procedural body. The 12 shipped GLBs have
not been rebuilt with it, and the Quaternius migration replaces it as the active
base. The development source files were removed from `tmp/` on 2026-11-05.

## 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, files removed after the Quaternius pivot;
  retained here as the historical method) — 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
  (development source files removed after the 2026-11-05 Quaternius pivot); 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. It is retained as a fallback, not the active NPC base.
- 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 were removed with the 2026-11-05 `tmp/` cleanup; the
  committed review sheet above is the retained evidence.

## 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.