name: chip-thumbnailer description: "Render symbol / footprint / 3D thumbnails for chip-fetcher library entries — Adom-themed SVGs (symbol via gallia/symbol-creator/svg-theme + footprint via FpView dark canvas + PCB grid) and OCCT-direct PNGs in three sizes (sm/md/lg) via service-step2glb /thumbnail. Writes a self-describing -thumbs.json manifest per chip listing every file + the canonical Adom palette + which app to launch for full-fidelity inspection. Use when the user wants thumbnails for chips, wants to populate wiki chip pages, batch-renders the chip-fetcher library, or asks 'render thumbnails / make thumbnails / chip thumbs / preview a chip / generate symbol+footprint+3d previews'. Triggers: chip thumbnail, chip thumbs, render chip, generate chip preview, symbol thumbnail, footprint thumbnail, 3d thumbnail, preview chip in library, batch render chips, .thumb-pending, chip-thumbs.json, chip wiki hero, library card, chip-thumbnailer."

chip-thumbnailer

Renders three thumbnail kinds per chip in the chip-fetcher library and drops them next to the source files, plus a manifest:

library/<MPN>/<MPN>-symbol.svg        Adom-dark-themed KiCad symbol
library/<MPN>/<MPN>-footprint.svg     FpView-styled footprint
library/<MPN>/<MPN>-3d-iso-sm.png     160 × 120 — icon / list view
library/<MPN>/<MPN>-3d-iso.png        320 × 240 — card / index (canonical, back-compat)
library/<MPN>/<MPN>-3d-iso-lg.png     800 × 600 — wiki hero / detail page
library/<MPN>/<MPN>-thumbs.json       self-describing manifest (READ THIS)

Always read <MPN>-thumbs.json before consuming thumbnails. It declares which files actually exist for this chip (sources may be incomplete), the exact palette colors used (so you can match your container UI), and which Adom app to launch when the user clicks through for full-fidelity inspection.

Sizes (3D PNG)

Symbol + footprint are SVG — vectors scale infinitely, one file each.

Palette (canonical, baked into every output)

Sourced from gallia/symbol-creator/lib/svg-theme.js THEME_COLORS + gallia/viewer/adom-theme.js THEME + gallia/viewer/kicad-footprint-viewer.js.

The dark canvas + PCB grid + radial teal glow are baked into every themed SVG so the thumbnail looks correct standalone. If your host container (e.g. SymView) already provides these via CSS, the SVG's own atmosphere will simply layer on top — usually fine, occasionally double up. In that case, strip the <defs> adom-canvas-* IDs from the SVG.

Manifest schema (<MPN>-thumbs.json)

{
  "mpn": "VL53L8CX",
  "generated_by": "chip-thumbnailer",
  "generated_by_version": "0.4.1",
  "generated_at_iso": "2026-05-05T16:57:00Z",

  "palette": { /* every color above as { token: hex } */ },

  "thumbnails": {
    "symbol": {
      "format": "svg",
      "path": "VL53L8CX-symbol.svg",
      "size_bytes": 84023,
      "full_fidelity": {
        "tool": "symbol-creator (SymView)",
        "command": "POST http://127.0.0.1:8781/sym/create … or open <MPN>-viewer.html",
        "description": "Interactive SymView — pin tooltips, group highlights, click-to-pin info, datasheet link, zoom/fit."
      }
    },
    "footprint": {
      "format": "svg",
      "path": "VL53L8CX-footprint.svg",
      "size_bytes": 11852,
      "full_fidelity": {
        "tool": "FpView (gallia/viewer/kicad-footprint-viewer.js)",
        "command": "generateFootprintViewer(<MPN>.kicad_mod) → <MPN>-fpview.html",
        "description": "Interactive FpView — pad tooltips with signal + dimensions, layer toggle, measure tool, solder-blob jet preview."
      }
    },
    "threeD": {
      "format": "png",
      "pose": "iso",
      "iso": {
        "sm": { "path": "VL53L8CX-3d-iso-sm.png", "width": 160, "height": 120, "sizeBytes": 1835 },
        "md": { "path": "VL53L8CX-3d-iso.png",    "width": 320, "height": 240, "sizeBytes": 4091 },
        "lg": { "path": "VL53L8CX-3d-iso-lg.png", "width": 800, "height": 600, "sizeBytes": 12637 }
      },
      "orientations": {
        "asIs": {
          "label": "As-is (Z-up — STEP canonical)",
          "description": "File rendered exactly as authored. STEP is Z-up canonically (ISO 10303-21 / KiCad / Solidworks / FreeCAD / AutoCAD), so this is the right answer for ~99% of chips.",
          "sizes": { "sm": { /* … */ }, "md": { /* … */ }, "lg": { /* … */ } }
        },
        "yUp": {
          "label": "Force Y-up source (fallback)",
          "description": "Source pre-rotated -90° about X. Use only when as-is renders the chip tipped on its side — happens with rare third-party exports authored Y-up (Maya / Blender / three.js convention).",
          "sizes": { "sm": { /* … */ }, "md": { /* … */ }, "lg": { /* … */ } }
        }
      },
      "inferredSourceUpAxis": "z",
      "bboxMm": [[-3.2, 3.2], [0.0, 1.13], [-3.25, 3.25]],
      "bboxMils": [[-126.0, 126.0], [0.0, 44.49], [-127.95, 127.95]],
      "full_fidelity": {
        "tool": "adom-step",
        "command": "adom-step view library/<MPN>/<MPN>.step",
        "description": "Interactive STEP viewer with measure tool, scene-graph navigation, geometric pin/pad detection."
      }
    }
  },

  "hints": [ "…" ]
}

Any kind whose source file (.kicad_sym / .kicad_mod / .step) isn't in the chip dir at render time will be null in the manifest.

3D orientation: as-is is canonical Z-up

STEP is Z-up by convention (ISO 10303-21 / KiCad / Solidworks / FreeCAD / AutoCAD all author Z-up), so the as-is render IS already Z-up in our pipeline — that's the right answer for ~99% of chips. Use library/<MPN>/<MPN>-3d-iso.png (the unsuffixed file) in every default surface.

The Y-up fallback (<MPN>-3d-iso-yup.png) exists for the genuine subset of manufacturer STEPs that author Y-up (Bosch BME688 / BMI270, TI INA226, Nordic nRF52840-CKAA, Espressif ESP32-S3-WROOM modules — verified in chip-fetcher's library). The fallback applies R_x(+π/2) server-side (canonical glTF / three.js / Blender / Adom convention) so the chip lands upright.

The manifest's inferredSourceUpAxis field is a bbox-aspect heuristic ("z" / "y" / "unknown"); use it as a hint when building an orientation picker UI, but the user always wins.

For anyone implementing or modifying a Y-up ↔ Z-up transform elsewhere in the Adom stack, read gallia/skills/up-axis-conventions/SKILL.md first. It captures the correct rotation sign (R_x(+π/2), always positive), reference implementations across Babylon.js / three.js / OCCT (Python) / glTF, and the testing trap that lets sign errors slip past visual review on Z-up sources. chip-thumbnailer 0.4.0 → 0.4.1 itself shipped a sign error caught only when the user pushed back on the rotation correctness — the gallia skill exists so nobody else hits it.

How AI agents should use this

When the user asks anything like "show me VL53L8CX" / "open this chip" / "preview ADS131M04IPBSR":

1. cat library/<MPN>/<MPN>-thumbs.json — read the manifest first.
2. Use the right thumbnail for the surface:
   • List / index card → .thumbnails.3d.iso.md.path (320×240 PNG) + .thumbnails.symbol.path (svg)
   • Tooltip / inline preview → .thumbnails.3d.iso.sm.path
   • Wiki hero / detail page → .thumbnails.3d.iso.lg.path
3. When the user wants more than the thumbnail (clicks through, asks to inspect, asks to measure), launch the full-fidelity app named in .thumbnails.<kind>.full_fidelity.tool via the suggested .command.
4. If your UI has its own background, adopt .palette.canvas_bg so thumbnails sit cleanly. If your UI has accents, use .palette.accent_teal (Adom brand teal) so it looks consistent.
5. Watch the _hints array in chip-thumbnailer once's JSON output for next-step suggestions specific to the chip you just rendered.

CLI

chip-thumbnailer once <MPN>             # render all kinds + all 3 sizes; write manifest
chip-thumbnailer scan                   # process every .thumb-pending in the library
chip-thumbnailer status <MPN>           # which thumbs/sources/manifest exist
chip-thumbnailer rerender <MPN>         # re-render all (or --kind sym|fp|3d to limit)
chip-thumbnailer touch-pending <MPN>    # mark a chip as out-of-date
chip-thumbnailer health                 # probe kicad-cli + step2glb + service-step2glb
chip-thumbnailer config                 # print library root + dependency paths

Every command emits OK: … lines for humans and a final JSON line for AI / scripted callers. The JSON of once includes the just-written manifest inline + a _hints block with concrete next steps so a single command-and-parse gives the AI everything it needs.

Install

curl -fsSL https://wiki-ufypy5dpx93o.adom.cloud/static/apps/chip-thumbnailer/chip-thumbnailer \
  -o /tmp/chip-thumbnailer && chmod +x /tmp/chip-thumbnailer && \
  sudo install -m 0755 /tmp/chip-thumbnailer /usr/local/bin/chip-thumbnailer && \
  chip-thumbnailer install

chip-thumbnailer install fetches SKILL.md fresh from the wiki at install time — no include_str! of SKILL.md in the binary, per the canonical no-fallback rule in gallia/skills/tool-publisher/SKILL.md. On any wiki error the install exits non-zero with a clear hint.

Pipeline (per chip)

1. Symbol — kicad-cli sym export svg → port of gallia's applyDarkTheme() regex pass (case-insensitive on hex tails to match #FFFFC2 and #ffffc2 both — the JS source uses /.../gi). <style> block wrapped in <![CDATA[…]]> so the literal <g class="stroked-text"> in the CSS comment doesn't trip strict XML parsers when the SVG is loaded via <object> or as a wiki asset. Canvas bg + 2.54 mm PCB grid + radial teal glow injected right after <svg> so the SVG looks correct standalone.

2. Footprint — stage .kicad_mod into a temp .pretty/, kicad-cli fp export svg --footprint <name>, strip <title>/<desc>/opacity="0" text + <g class="stroked-text"> groups (KiCad inflates the viewBox with these), inject FpView's dark canvas + PCB grid background, drop KiCad's white page bg. Pad / silk / courtyard colors stay as kicad-cli's native palette (which already matches FpView).

3. 3D — step2glb thumbnail <MPN>.step --pose iso --width N --height N for each of sm (160×120), md (320×240), lg (800×600). step2glb POSTs to service-step2glb 0.4.x /thumbnail which renders server-side via OCCT V3d offscreen + Xvfb (no pyrender, no per-render Hydrogen browser tab).

Failure handling

If a render fails, chip-thumbnailer:

• Writes library/<MPN>/.thumb-errors.json with which kind failed and why.
• Leaves the .thumb-pending marker in place so the next scan retries.
• Still writes the manifest — but with null for kinds that didn't render, so downstream apps know what's available.

The marker is only cleared when ALL three kinds (or all the sizes that were attempted) render successfully.

Related

• chip-fetcher writes the source files (.kicad_sym, .kicad_mod, .step) and touches .thumb-pending after each successful import.
• service-step2glb v0.4.x provides the OCCT-direct /thumbnail endpoint (replaced the prior pyrender stack).
• step2glb (Rust client) wraps /thumbnail for the 3D path.
• gallia/symbol-creator owns the canonical symbol dark-theme palette; chip-thumbnailer ports the regex pass into Rust to avoid a node shell-out at render time.
• gallia/viewer/kicad-footprint-viewer.js owns the FpView footprint styling.
• adom-step is the full-fidelity 3D viewer to launch when the user wants more than the thumbnail.