fix(examples): redesign mesh-hygiene-audit as a flanged street valve with marked defects

[TMHSDigital]

What changed and why

The gallery review judged the mesh-hygiene-audit hero weak. It showed a crude octagonal brass spool twice, labelled "DIRTY" / "CLEAN". The defects were a thin orange wire that looked like a render glitch, and the floor labels could not be read at card size.

Redesign

• Subject: a designed upright street valve in eight named parts: Valve.Body casting (chamfered base and bonnet flanges, globe, domed bonnet), Valve.Outlet, Valve.FlangeBolts (22 hex bolts), Valve.GlandNut, a threaded Valve.Stem, and a brass handwheel (Valve.HandwheelHub, Valve.HandwheelRim, Valve.HandwheelSpokes). It uses four materials.
• Composition: a dirty copy (left) beside the clean valve (right). There are no labels. The defects on the dirty copy are designed to read at thumbnail size:
  • a hole through the globe, outlined by glowing red tubes built from its boundary edges
  • a flipped patch on the bonnet
  • an ngon merged into the base-flange annulus (amber tint)
  • three loose verts, shown as red beads
• The winding evidence comes from the renderer, not from paint. The paint mixes to red on the shader's Backfacing output. The flipped patch and the inside of the hole turn red on their own. The same material on the clean valve shows no red anywhere.
• Markers are read back from audit() incidence on the dirty mesh, not from the staging code. The render path exits 9 if staging loses any of the four defect classes.

The check is stronger, not weaker

• Gates 3–7 (ngon, loose, manifold, zero-area, winding) now run on all 8 parts instead of one mesh. Euler (8) runs on the body casting, which is genus-0 by design. The rim is a torus, and the bolts and spokes are multi-shell meshes.
• New gate: winding consistency via BMEdge.is_contiguous (exit 7). It catches flipped patches that the signed-volume test misses.
• --inject KIND [--inject-part NAME] falsifies every gate. --inject-ngon is kept as an alias.
• The render path now calls gallery_asset_quality (exit 11) as well as gallery_framing (exit 10).
• scripts/asset_sheet.py gains a SELECT row: "mesh-hygiene-audit": (r"^Valve\.", None).

Before / after

• Contact sheet: docs/gallery/contact-sheets/mesh-hygiene-audit-contact-sheet.webp
• Asset sheet: docs/gallery/asset-sheets/mesh-hygiene-audit.webp
• Before: the brass spool pair with DIRTY/CLEAN floor text (previous docs/gallery/assets/mesh-hygiene-audit-hero.webp on main)

Gate numbers (5.2.1 LTS, EEVEE)

Gate	Result
Framing: fill	x=0.766, y=0.728 (band 0.70–0.90) — ok
Framing: margins	L 0.113, R 0.122, B 0.150, T 0.122 (floor 0.02) — ok
Asset quality	no default names; 4 materials across 8 parts, dominant [email protected]; edge90 0.060 (384/6420), 0 degenerate faces; compactness 29.9 (informational) — aq_ok
Drift	measure_hero_drift --only mesh-hygiene-audit: mean_abs 0.00364, gt2pct 1.24%, luma 0.2196/0.2194 — matches

Contact sheet (vs armature-bend / damped-track-aim / bmesh-gear)

Tile	Luma	Stage	Wedge warmth	Saturation
Candidate	0.2196	0.1554	−0.020	0.196
armature-bend	0.2787	0.2132	−0.428	0.144
damped-track-aim	0.1511	0.1448	+0.277	0.231
bmesh-gear	0.2358	0.1772	+0.303	0.250

Per-criterion verdicts:

• Stage darkness: pass. Stage 0.155 sits between damped-track-aim and bmesh-gear.
• Wedge warmth: pass (neutral). The camera looks down on the pair, so the frame's backdrop is floor; the wedge pools warm on the floor behind the valves. Warmth falls inside the calibration range (−0.43…+0.30).
• Subject fill: pass (0.766 x).
• Saturation: pass (0.196). Saturated blue paint, red and amber markers.
• Thumbnail legibility: pass. At 427×240 the red-outlined hole, the red bonnet patch, the amber flange and the red beads all read against a pristine twin.
• Mean luminance: 0.220, against 0.151–0.279 for the calibration images.

Asset sheet: reference set from CLAUDE.md is collision-hull-proxy, socket-attach-points, vertex-color-ao, wheelbarrow, apothecary-shelf. Verdict: ships. In the isolated lineup the valve is not the least-designed object. It has more parts and edge treatment than the hydrant (bolted flanges, threaded stem, spoked handwheel, chamfered castings). It is simpler than the drone and the apothecary shelf.

Check runs (check-only path, tests/smoke/run_example.py)

Identical hygiene_ok on all three binaries: parts=8 … body_euler=2 body_volume=0.453344 body_min_area=1.223e-03.

Binary	Reported version	Result
E:\Blender-Developer-Tools\.scratch\blender-5.2.1-windows-x64\blender.exe	5.2.1 LTS	[PASS]
…\blender-5.1.2-windows-x64\blender.exe	5.1.2	[PASS]
…\blender-4.5.11-windows-x64\blender.exe	4.5.11 LTS	[PASS]

The render path (--output) also ran clean on 4.5.11 LTS (framing_ok, aq_ok), and the still is visually identical to the 5.2.1 one.

Falsifiers (5.2.1 LTS, each observed non-zero, then restored by dropping the flag)

Probe	Exit	Measured error
--inject ngon	3	Valve.Body: 1 ngon(s)
--inject-ngon (alias)	3	—
--inject ngon --inject-part Valve.HandwheelRim	3	Valve.HandwheelRim: 1 ngon(s) (per-part coverage)
--inject loose	4	1 loose vertex(es)
--inject boundary	5	nonman_edges=4 boundary_edges=4
--inject zero_area	6	2 zero-area face(s) (min_area=0.000e+00)
--inject flip_patch	7	4 winding seam edge(s) (new gate)
--inject flip	7	signed volume -0.453344
--inject shell	8	Euler characteristic V-E+F=4 != 2 (first live falsifier for the Euler gate)

Proven by live run vs established by inspection only

Proven by live run:

• all check results and falsifiers above
• the framing, asset-quality and drift numbers
• render_hero.py, contact_sheet.py and asset_sheet.py outputs
• build_gallery.py regenerated after rebase onto origin/main
• the generated <img alt> in docs/gallery/index.html and docs/gallery/mesh-hygiene-audit/index.html was read and matches the new alt
• the render path ran on 4.5.11

Established by inspection only:

• the render path on 5.1.2 was not run
• CI smoke on the floating 4.5.x / 5.2.x point releases has not run yet

🤖 Generated with Claude Code