--- 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: - `.kicad_mod` — KiCad footprint - `.glb` — 3D model (color-preserving GLB from `step2glb` or kicad-cli) - `.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 → `-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 ` produces: - `chiplinter-report.json` — per-pad verdict + scoring metadata - `chiplinter-inspector.json` — manifest for the inspector webview - `-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 --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 `-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 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 [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.