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.