python3 scripts/hero_glb.py <board-use.glb> <footprint.kicad_mod> <page.json> <slug>-hero.glb --png preview.png

OK stm32g071c8t6-hero.glb: pads 48, silk items 9, pin1 footprint silkscreen, labels 48; align OK (offset 0.0 mm)

---
name: component-hero
description: Build a component page's annotated 3D hero to the Adom standard (adom-hero 1.4) - the physical chip plus teal dashed pad outlines (50% opacity), silkscreen with pin 1 (70% transparent), and each pad's signal name - as a separate <slug>-hero.glb, with the board-use GLB left clean. Deterministic generator included (hero_glb.py, no model calls). Use when publishing or updating any component page's 3D model, when a page shows the bare chip without its footprint, or when asked for footprint outlines, pad labels, pin 1 or silkscreen in the 3D view. Trigger words - component hero, hero glb, footprint outline in 3d, teal dashed pads, pad outlines, silkscreen in the glb, pin 1 on silk, signal names on pads, pad labels 3d, model_3d, model_3d_plain, adomHero, adom-hero 1.4.
---

# component-hero

The wiki shows a component page's `component.parts.model_3d` in its 3D viewer. For a component, that model
is the **hero**: the physical chip with Adom's nonphysical reference artwork drawn under it on three layers:

- teal dashed pad outlines at 50% opacity;
- silkscreen with pin 1, 70% transparent;
- each pad's signal name at 50% opacity.

The board-use model stays clean and is declared as `model_3d_plain`.

The exact rules (names, colours, geometry, pin 1, labels, metadata and lint checks) are in
`reference/standard.md`. Do not re-derive them from prose: run the generator.

## Build a hero

Requirements: Python 3 with `numpy`, `pygltflib` and `mapbox-earcut` (`matplotlib` only for the optional --png preview)
(`pip install --user pygltflib mapbox-earcut`).

```
python3 scripts/hero_glb.py <board-use.glb> <footprint.kicad_mod> <page.json> <slug>-hero.glb --png preview.png
```

The inputs are the page's own files:

- the clean GLB, with the chip seated at the footprint origin in Z-up metres, as step2glb and service-occt
  produce it;
- the `.kicad_mod`;
- `page.json`, whose `component.pins` supplies the signal names.

It writes the hero, a sidecar `<slug>-hero.overlay.json` and, with `--png`, a top and oblique preview.
It prints one line:

```
OK stm32g071c8t6-hero.glb: pads 48, silk items 9, pin1 footprint silkscreen, labels 48; align OK (offset 0.0 mm)
```

## Before publishing

1. **Alignment:** it must read `align OK`. `FAIL` means the 3D model is offset or turned relative to the
   footprint. Fix the model's placement; never publish artwork over a misplaced chip.
2. **Preview:** look at the PNG. Check that every pad has a dashed outline, the labels sit beside the right
   pads, and pin 1 is at the chip's pin-1 corner.
3. **page.json:** set `component.parts.model_3d` to `<slug>-hero.glb` and `model_3d_plain` to the clean
   GLB. Add the hero and the sidecar to the page, and bump the version.
4. **Publish, then push `page.json` last.** A package publish rewrites the repo's page.json; pushing it last
   keeps the page hero and the model keys.
5. **Check in the wiki's own viewer.** Open the page, load the 3D model and look at the pixels. A
   successful upload is not proof of appearance.

## Rules of thumb

- **Pin names:** use the datasheet spelling from the page's pinout. Never use project net names. Pad
  numbers are the fallback when a pin has no real name.
- **No labels** on exposed pads or ball grids. The generator records why in the metadata.
- **Pin 1:** the footprint's own pin-1 mark counts. An added dot is recorded as AI-added.
- **Clean downloads:** the artwork never goes into the board-use model.