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 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:

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.