security-game/docs/makehuman-head-review.md

# MakeHuman head prototype

Status: **local prototype, rejected by the automated visual gate, not integrated.**
The asset is a standalone head/neck extracted from the CC0 MakeHuman base in
`tmp/npc-research/makehuman/base.obj`. It is kept as a reviewable experiment and
is not part of the shipped NPC contract.

## 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 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. It is inside the 16,000/16,000
  character cap.
- 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

**VERDICT: REJECT** (vision judge `z-ai/glm-5.3-flash`, final build render set
above). The gate is blocked; the prototype is not presented as an accepted 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**
with no issues, and an assembled `npc_casual` with this head passes `inspect` at
**15,532 / 16,000 triangles, 13,310 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.

## Next steps after the gate passes

- 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.
- Compare against the project `_face` baseline and decide whether this head is
  the base for the local head/face overhaul.
- Add a clean UV/material pass and a contract armature/weights if it becomes
  part of a library character.
- Keep the source script under `tmp/`; promote only the reviewed GLB and durable
  docs/preview sheet.