zwitschi
2ba40f3578
Group the top-level docs into docs/project, docs/design, docs/assets and docs/process, each with its own README index. Delete the superseded docs/screens/head-review page and sheets. Rewrite every markdown link, absolute docs path and tool/test reference to the new locations, fix the pre-existing broken anchors and remove the dead Joke Shop photo-board link. check_docs OK, Python tooling 167/167.
141 lines
7.2 KiB
Markdown
141 lines
7.2 KiB
Markdown
# 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.
|
||
|
||
|
||
|
||
## 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.
|