Editing: adom-chiplinter — 3D chip ↔ KiCad footprint linter

Field: AI Skill Technical Reference

---
name: adom-chiplinter
user-invocable: true
description: "3D chip ↔ KiCad footprint linter. Detect every chip's electrical-contact features (legs / pins / pads / balls / tabs) automatically from a 3D model, and validate placement against the KiCad footprint. Stage 5b pin-1 vision validation catches rotational ambiguity in QFN/QFP/BGA/SOIC packages where 4-fold or 2-fold symmetric pad layouts make the bake-time orientation an arbitrary tie-break. Use when: linting a 3D chip against a footprint, finding pin-1, validating pad alignment, baking annotated GLBs with chip-pad / FP-pad scene-graph entries for downstream Adom tools, debugging chip placement, building a chip test library. Trigger words: chiplinter, chip linter, validate chip footprint, chip pad detection, pin-1 detection, pin-1 vision, footprint vs 3d model, bbox-fit chip, chip rotational symmetry, chip-pads alignment, bake annotated glb, chiplinter inspect, chiplinter sweep, chiplinter run."
---

# adom-chiplinter — 3D chip ↔ KiCad footprint linter

Detects every chip's electrical-contact features (legs / pins / pads / balls /
tabs) automatically from a 3D GLB model, validates placement against the KiCad
footprint, and bakes an annotated GLB so downstream Adom tools can read pad
positions from the scene graph.

The "north star": you point chiplinter at a chip directory containing the GLB,
KiCad footprint, datasheet PDF, and `info.json`, and it answers the question
*"are these aligned?"* — with no human override required.

## Quick start

```bash
# Lint a single chip
chiplinter run path/to/chip-dir

# Lint every chip under test-cases/ and produce a coverage matrix
chiplinter sweep test-cases/

# Open the interactive inspector in a Hydrogen webview
chiplinter inspect path/to/chip-dir --port 18420
```

A chip directory contains:
- `<mpn>.kicad_mod` — KiCad footprint
- `<mpn>.glb` — 3D model (color-preserving GLB from `step2glb` or kicad-cli)
- `<mpn>.pdf` — datasheet (optional, used by Stage 0 datasheet extraction)
- `info.json` — structural classification + provenance

## Detection pipeline

Five stages, self-validating:

| Stage | What it does |
|---|---|
| 0 | Datasheet extraction (Claude vision → `<mpn>-datasheet.json` sidecar) |
| 1 | Load + classify (footprint pads, GLB triangles, body materials) |
| 2 | Z-band slab + 2D rasterize + connected-components → detected pad bboxes |
| 3 | 24-rotation fit-test + Hungarian matching (kind-aware inside-test) |
| 4 | Material-color rescue (filter to gold/metal triangles for inset pads) |
| 5 | Vision rescue (top-down render → Claude vision detects pin-1 indicator) |

Stage 3 produces both the orientation transform and the per-pad correspondence
in one pass. Stage 5b (pin-1 vision) is the deciding factor for rotationally-
symmetric chips — see "Rotational symmetry" below.

## Pin-1 confidence model

The bake step writes `chiplinter_pin1_marker.extras.chiplinter.confidence` based
on pad-fit symmetry detection:

| Confidence | When | Meaning |
|---|---|---|
| `high` | orient #0 uniquely won at 100% | kicad-packages3d STEPs author pin-1 in the conventional position; FP authors pad-1 in the matching position. Identity-rotation match means the chip's authored pin-1 indicator aligns by construction. |
| `ambiguous` | multiple rotations tied at 100% | The chip's pad layout is rotationally symmetric (QFN/QFP/BGA/SOIC). Vision validation is the deciding factor. |
| `assumed` | a non-identity rotation won uniquely | Position derives from FP pad-1; chip-body indicator is the ground truth. Verify visually before reflow. |
| `verified` | vision confirmed indicator at expected quadrant | High confidence — both pad geometry and the manufacturer's chip-body indicator agree. |
| `conflict` | vision saw indicator at a different quadrant | Real disagreement. Downstream tools should refuse to auto-flow; human review required. |
| `vision_inconclusive` | vision ran but couldn't see an indicator | Falls back to bake-time confidence. |

## Rotational symmetry

For QFN/QFP/BGA/SOIC packages with N-fold symmetric pad layouts, multiple
orientations of the chip will fit the footprint at 100% coverage. The bake step
detects ties by running the FP-projection raycast at every one of the 24
axis-aligned rotations; if more than one rotation matches the max hit count,
the marker carries `rotational_symmetry_detected: true` and
`tied_orientations: [0, 1, 2, 3]` (or [0, 2] for 2-fold, etc.).

In this case bake-time confidence is `ambiguous` — the manufacturer's pin-1
indicator on the chip body is the only signal that breaks the tie. Pin-1 vision
validation is built in: render top-down via `chiplinter inspect`, click
"Validate pin-1," and the inspector ships a labeled top-down PNG to Claude
vision with a structured-output schema. The result writes back to the baked
GLB extras.

## Output artifacts

`chiplinter run <chip-dir>` produces:
- `chiplinter-report.json` — per-pad verdict + scoring metadata
- `chiplinter-inspector.json` — manifest for the inspector webview
- `<mpn>-chiplinter.glb` (after baking) — annotated GLB with three named groups:
  - `chiplinter_chip_pads` (under `__root__`) — chip-frame rectangle meshes
  - `chiplinter_fp_pads` (at scene root) — FP pads in PCB frame
  - `chiplinter_pin1_marker` — pin-1 location + confidence metadata

`chiplinter sweep` produces a coverage matrix (`coverage-matrix.json` +
`coverage.html`) showing every chip's pass/warn/refuse status across the
detection pipeline.

## Inspector webview

`chiplinter inspect <chip-dir> --port 18420` serves an interactive Babylon.js
webview at `http://localhost:18420` showing:

- The chip GLB rendered with FP pad bboxes + raycast lines + pin-1 marker
- Per-pad walkthrough that proves each FP pad ↔ chip-surface association
- 24-orientation iteration table with coverage % and σ
- One-click "Bake annotated GLB" → writes `<mpn>-chiplinter.glb`
- One-click "Validate pin-1" → captures top-down PNG, ships to vision, shows
  verdict (Verified / Conflict / Inconclusive) with the bake-time symmetry
  context

The inspector uses a vendored ESM build of `adom-3d-viewer-babylon9` (Babylon
9.5.0 with the new Inspector v9). Open the page in a Hydrogen webview tab —
**not** in the deprecated Adom Viewer panel.

## CLI flags

```
Usage: chiplinter <COMMAND>

Commands:
  run      Run detection on one chip directory; emits chiplinter-report.json
  sweep    Run all chips under a test-cases directory; emits coverage matrix
  inspect  Generate inspector manifest + serve the webview
  install  Deploy this binary + SKILL.md to the user's PATH
  help     Print this message or the help of the given subcommand(s)

Run options:
  --verbose          Detailed per-band diagnostics

Inspect options:
  --port <PORT>      [default: 18420]
  --no-serve         Generate manifest only, don't serve

Sweep options:
  [cases_dir]        [default: test-cases]
```

## Required infra (auto-checked by `chiplinter install`)

- `step2glb` — used to convert STEP → color-preserving GLB at chip-staging time
  (chiplinter consumes pre-staged GLBs, but the staging pipeline assumes
  step2glb is on PATH)
- `claude` CLI — used for Stage 5b pin-1 vision validation
- `adom-wiki` (optional) — for publishing chip libraries

## Troubleshooting

- **`chiplinter inspect` shows blank canvas** — the vendored 3d-viewer assets
  weren't installed alongside the binary. The binary must be co-located with
  `web/inspector.html` and `vendor/3d-viewer/`. For now, run `inspect` from a
  checkout of `adom-inc/adom-chiplinter`.
- **Vision verdict is "conflict"** — the manufacturer pin-1 indicator on the
  chip body disagrees with KiCad pad-1's quadrant. For 4-fold symmetric chips
  this is a true ambiguity that needs human review before reflow.
- **`chiplinter sweep` REFUSES on multiple chips** — check `info.json` for the
  `structural_type` field; some classes (`smd_inset_pads`,
  `hybrid_smd_plus_mech_clip`) need Stage 4 material rescue or Stage 5 vision
  rescue, which require the corresponding flags to be enabled in
  `DetectionParams`.

## Related

- `adom-3d-viewer-babylon9` — vendored 3D viewer ESM bundle (Babylon 9.5.0 +
  Inspector v9). Also published to the Adom Wiki.
- `adom-chipfit` — sister tool, validates a chip GLB against a footprint with a
  simpler single-chip scope; chiplinter is the rebuilt "north-star" detector.
- `step2glb` — STEP → GLB converter; chiplinter consumes the GLB output.

Cancel

You must be logged into Adom to save. Edits are applied immediately but subject to review.