---

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

# 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.