---
name: chip-thumbnailer
description: "The chip-icon factory. From a single STEP file it renders the complete family of CHIP icons (the 3D body in every form): 6 face-up shaded orientations x sm/md/lg, transparent alpha-keyed icons, the part-number LASERED onto the chip top (180 reads upright + a 90 right-angle variant), the embossed .step that travels to KiCad, and 11 vector OUTLINE styles via OCCT hidden-line removal (colours white + teal, thicknesses hairline..heavy, approaches solid/dashed/neon/x-ray/blueprint/ink-on-paper). Ships a live web app (chip-thumbnailer serve|app) that fills each icon into a dashed box in real time with per-icon size/format/KB/transparency, plus a CLI (once/scan/status/rerender). The heavy OCCT work runs on service-step2glb; chip-thumbnailer is a lean Rust client + does alpha-keying locally. NOT symbol/footprint thumbnails (those are adom-symbol / adom-footprint). Triggers: chip icon, chip thumbnail, chip thumbs, render chip, chip 3d icon, transparent chip icon, name on chip, laser part number, chip outline, vector outline, chip-thumbnailer, .thumb-pending, chip-thumbs.json, chip wiki hero, library card, regenerate chip icons."
user-invocable: true
---

# chip-thumbnailer, the chip-icon factory

Give it a STEP file, get the complete family of **chip** icons, the 3D
body rendered in every form a downstream surface needs. It is the single
producer of the icons adom-symbol's centre overlay, library cards, and
wiki chip pages consume.

> Symbol (`.kicad_sym`) and footprint (`.kicad_mod`) thumbnails are **not**
> this tool's job, they belong to **adom-symbol** and **adom-footprint**.
> This renders the chip.

## What it makes (written next to the source `<MPN>.step`)

```
<MPN>-3d-iso[-<axis>][-<size>].png     shaded render, 6 orientations x sm/md/lg
<MPN>-3d-iso[-<axis>]-icon.png         transparent (alpha-keyed) icon  <- adom-symbol reads this
<MPN>-3d-iso-named[-icon].png          part number lasered on top, 180 (reads upright)
<MPN>-3d-iso-named90[-icon].png        the name at a right angle, 90 (taller/wider fit)
<MPN>-named.step                       embossed STEP (the mark travels to KiCad)
<MPN>-3d-outline-<style>[-named].svg   11 OCCT-HLR vector outline styles, plain + name-marked
<MPN>-thumbs.json                      self-describing manifest (READ THIS first)
```

**Axes** (orientation token): none = `asIs` (Z-up canonical, ~80% of
chips), `yup`/`ydown`/`xup`/`xdown`/`zdown` for the rest. The
chosen-up-axis from chip-fetcher's `info.json` is honoured for the
single-pose outline + name-laser set. **Sizes**: `-sm` 160x120,
none = `md` 320x240 (canonical), `-lg` 800x600.

**11 outline styles**, three axes of variety:
- colour: `white`(dark) / `teal`
- thickness: `hairline` / `dark`(medium) / `heavy`, plus dark-ink `thin` / `bold` / `ink-heavy`
- approach: solid / `dashed` / `neon` (glow) / `xray` (hidden edges) / `blueprint`

## The web app

```bash
chip-thumbnailer serve            # HTTP server (default :8794)
chip-thumbnailer app              # open in a Hydrogen webview tab
```

POST a STEP (or pick a library chip) and every icon fills into a dashed
box in real time, captioned with file name, format, pixel size, KB, and
true alpha transparency. Regenerate button; orientations stay up top, the
outline + name-laser galleries collapse. Every action is curl-drivable
(`GET /api/state`, `POST /api/generate|/api/regenerate`).

## CLI

```bash
chip-thumbnailer once <MPN>        # render the full family + write the manifest
chip-thumbnailer scan              # process every .thumb-pending in the library
chip-thumbnailer status <MPN>      # which icons/sources/manifest exist
chip-thumbnailer rerender <MPN>    # re-render (--kind 3d is the only kind now)
chip-thumbnailer serve | app       # the web app
chip-thumbnailer health | config   # probe service-step2glb / print paths
```

`once` prints `OK:` lines plus a final JSON line that inlines the
`<MPN>-thumbs.json` manifest and a `_hints` block of next steps.

## Architecture, lean client + service

The OCCT-heavy work runs on **service-step2glb** (the server never blocks
on OCCT; jobs run in isolated subprocesses, `202 + job_id`, poll
`/jobs/{id}` then `/jobs/{id}/result`):

| call | produces |
|---|---|
| `POST /thumbnail?upAxis=<a>` | one shaded orientation PNG |
| `POST /outline?upAxis=<a>&name=&suffix=&rot=` | `{style: svg}` for the 11 styles (OCCT HLR) |
| `POST /name-emboss?upAxis=<a>&name=&rot=` | embossed STEP + rendered iso (base64) |

`rot` = text orientation: `180` (default, reads upright to the iso
camera), `90` (a right angle, the `named90` set, faces the viewer). The text is scaled to
the chip's top-face bounding box at whichever rotation.

chip-thumbnailer does the **transparent-icon alpha-key in pure Rust**
(median the four shaded-render corners as the background, feather to alpha
by RGB distance, T0=16/T1=44), so there are no Python/numpy deps in the
client.

## How AI agents should use this

When the user wants to show / preview a chip:
1. `cat library/<MPN>/<MPN>-thumbs.json` first, it lists what exists.
2. Pick the icon for the surface: list/card -> `-3d-iso.png` (md) or the
   transparent `-3d-iso-icon.png`; tooltip -> `-sm`; hero -> `-lg`.
3. Match your UI to `palette.canvas_bg` (#0d1117) + `palette.accent_teal`.
4. A `null` entry means the source `.step` was missing at render time.

## Related

- **chip-fetcher** writes `<MPN>.step` + touches `.thumb-pending`; it now
  calls `chip-thumbnailer once` for the full family (it no longer shells
  its own OCCT scripts).
- **service-step2glb** owns the OCCT endpoints (`/thumbnail`, `/outline`,
  `/name-emboss`).
- **adom-symbol** consumes the transparent `-3d-iso-icon.png` + the
  outline/named SVGs as its centre overlay (it does NOT make them).
- **adom-step** is the full-fidelity 3D viewer to launch on click-through.