# chip-thumbnailer

The **chip-icon factory**. Give it a STEP file and it renders the
complete family of chip icons, in real time, from one source: shaded 3D
orientations, transparent icons, name-lasered variants, and a gallery of
vector outline styles. CLI + a live web app.

It is the single producer of every chip icon the rest of the Adom EDA
stack consumes (adom-symbol's centre overlay, library cards, wiki chip
pages). The heavy OCCT work runs on **service-step2glb**; chip-thumbnailer
stays a lean Rust client and does the alpha-keying locally.

> Symbol and footprint thumbnails are **not** this tool's job, those
> belong to **adom-symbol** and **adom-footprint**. chip-thumbnailer
> renders the *chip* (its 3D body) in every icon form.

![The live web app rendering a chip's full icon family](screenshots/app-live.png)

## The icon family (from one STEP)

| Output | What it is |
|---|---|
| `<MPN>-3d-iso[-<axis>][-<size>].png` | shaded 3D render, 6 face-up orientations x sm/md/lg |
| `<MPN>-3d-iso[-<axis>]-icon.png` | the same, alpha-keyed to a **transparent** background |
| `<MPN>-3d-iso-named[-icon].png` | part number **lasered** onto the chip top in the clean line-font (180, reads right-side-up) |
| `<MPN>-3d-iso-named90[-icon].png` | the name at a right angle (90), for chips taller than wide |
| `<MPN>-3d-outline-<style>[-named].svg` | **11 vector outline styles** via OCCT hidden-line removal |
| `<MPN>-thumbs.json` | self-describing manifest (palette, files, full-fidelity tool) |

## The part number, lasered onto the chip (no other EDA tool does this)

chip-thumbnailer **draws the manufacturer part number onto the chip's top
face** in the same crisp single-stroke line-font the vector outlines use. It is
not a flat label pasted over the render: the text is projected onto the top
plane through the live 3D camera, so it lies flat on the chip and follows the
isometric perspective. A clean engraved/laser look, not a noisy 3D extrusion.
The text always **faces the viewer** (the rotation is chosen per up-axis, so it
reads forward rather than upside-down or backwards), and an optional **second
line** carries a variant/date marking. The same mark comes on the vector
outlines too.

![Clean single-stroke laser-mark of the part number on the chip, plus the name-marked vector outline](screenshots/name-laser.png)

## How the part number lands on the top surface

Most parts have leads that splay past the body, a base flange, or bevels, so the
full bounding box is wider than the real top surface. chip-thumbnailer takes the
**top 10% slice** of the height and re-bounds just that geometry to get the true
top-face footprint, then insets the text 10% on every side. The mark lands on
the actual top surface on SOICs (leads excluded), QFNs, and domed/flanged
sensors alike. The dashboard shows this as a **placement-debug tile** (full
bounding box in red, top-slice box in cyan):

![How placement is derived: full bbox in red, top-slice bbox in cyan, then the lasered result with a 2-line variant](screenshots/placement.png)

## 11 outline styles

OCCT hidden-line removal gives a clean, complete isometric outline (body
silhouette, top face, every lead), in 11 styles across three axes: **colour**
(white + teal), **thickness** (hairline to heavy, plus dark "ink on paper"),
and **approach** (solid / dashed / neon / x-ray / blueprint / ink-on-paper).
Each comes plain and name-marked.

![All 11 outline styles](screenshots/outline-styles.png)

## Name-marked outlines, built for the schematic symbol

Every outline style also comes **name-marked**, the chip's line-art silhouette
with the manufacturer part number on it. This is exactly what a schematic
symbol wants in its body: the real chip shape and the part number, instead of a
featureless rectangle. adom-symbol drops one straight into the symbol body. The
name uses the **same top-slice placement and viewer-facing rotation as the 3D
laser**, so the outline and the shaded icon agree.

The mark comes two ways: the **facing** orientation (reads forward to the
camera) and a **right-angle** alternate, for a long part number on a narrow chip
that would otherwise spill:

![Name-marked outlines, facing orientation](screenshots/named-outlines.png)

![Name-marked outlines, right-angle alternate](screenshots/named90-outlines.png)

## Works across every package type

The same one STEP in, full-family out works on whatever the part is, an RF
module with a shield can, a fine-pitch TQFP, a leadless QFN, a mechanical
USB-C connector, or a tiny LGA sensor. The geometry comes straight from the
manufacturer's STEP, so the icon is the real chip and the part number lands on
its actual top face every time.

![chip-thumbnailer across package types: RF module, TQFP, QFN, USB-C connector, LGA sensor](screenshots/across-chip-types.png)

## The web app

```bash
chip-thumbnailer serve            # run the HTTP server
chip-thumbnailer app              # open it in a Hydrogen webview tab
```

Drop a STEP file (or pick a library chip) and watch every icon fill into
its dashed box in real time, each captioned with file name, format, pixel
size, KB, and true alpha transparency. A Regenerate button re-runs the
whole family; the orientations stay up top while the outline + name-laser
galleries collapse.

## CLI

```bash
chip-thumbnailer once <MPN>        # render the full family for one chip + manifest
chip-thumbnailer scan              # process every .thumb-pending marker in the library
chip-thumbnailer status <MPN>      # what's there, what's missing
chip-thumbnailer rerender <MPN>    # re-render (--kind 3d)
chip-thumbnailer serve | app       # the web app
chip-thumbnailer health | config   # probe deps / print paths
```

Every command prints `OK:` lines for humans and a final JSON line for AI
callers; `once`'s JSON inlines the manifest + a `_hints` block.

## Architecture

chip-thumbnailer calls **service-step2glb** for the OCCT-heavy work and
keeps itself dependency-light:

- `POST /thumbnail` -> the shaded orientation PNGs, plus the clean-font
  name-laser when called with `?name=` (the part number drawn on the chip top).
- `POST /outline` -> the 11 styled vector outlines (OCCT HLR), plain + name-marked.

The transparent icons are alpha-keyed from the shaded renders in pure
Rust (no Python, no extra deps). The chosen up-axis (`info.json`
`chosen_up_axis`) is honoured so Y-up parts pose correctly.

## Install

```bash
adom-wiki pkg install adom/adom-chip-thumbnailer
chip-thumbnailer install        # fetch SKILL.md + bash completions from the wiki
```

`chip-thumbnailer install` fetches `SKILL.md` fresh from
[wiki.adom.inc](https://wiki.adom.inc/adom/adom-chip-thumbnailer) at
install time (no `include_str!`, per the no-fallback install rule).

## Build

```bash
cargo build --release            # run as target/release/adom-chip-thumbnailer
```

No system deps to build. At runtime it needs `service-step2glb` reachable
(for the OCCT renders); the transparent-icon keying is self-contained.

## Open source under the Adom org

**chip-thumbnailer** is **open source** (MIT) under the **adom** org on the
[Adom Wiki](https://wiki.adom.inc/adom/adom-chip-thumbnailer). The source
lives in the page's repo (Files tab) and on
[github.com/adom-inc/chip-thumbnailer](https://github.com/adom-inc/chip-thumbnailer).
Contribute via the wiki's PR-per-page flow, or fork and drop a breadcrumb
on this page so Adom's AI can discover your fork.

## License

**MIT** - (c) 2026 Adom Industries Inc. See [LICENSE](LICENSE).