---
name: step2glb
description: Thin Rust CLI for converting STEP (.step / .stp) files to color-preserving GLBs. Shells to the shared service-step2glb container (OCCT XCAF pipeline, 4.7GB+ runtime) — the local install is ~3 MB and ships no CAD kernel. Returns `OK:`/`ERROR:` lines + a JSON companion line so humans and AIs can both parse the result, and `preview` opens a Hydrogen webview with a materials HUD so the human verifies visually. Use when the user asks to convert a STEP file to GLB, render a component's 3D model with materials (not white), generate a chipfit input from a KiCad library part, or regenerate broken wiki 3dcomp GLBs. Triggers: step to glb, step2glb, convert step, cad to glb, kicad step to glb, occt gltf, step preview, chip 3d preview, component 3d viewer, regenerate chip glb.
---

# step2glb

Thin Rust client for STEP → GLB conversion. All CAD work happens on the shared **service-step2glb** container (OCCT 7.8 via `cadquery-ocp`, color-preserving XCAF pipeline). This CLI is a ~3 MB HTTP client — no Python, no venv, no OCCT runtime installed locally.

## Install (Tier B)

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

`step2glb install` fetches the latest `SKILL.md` from the wiki, deploys it to `~/.claude/skills/step2glb/`, and drops bash completions in `~/.local/share/bash-completion/completions/step2glb`. No heavy deps.

## Commands

Every command follows the adom-cli-design output contract:
- Successes start with `OK:` (green in a TTY, plain in pipes).
- Failures start with `ERROR:` and are followed by a `Hint:` line with the next action.
- Non-trivial commands also emit a machine-readable JSON line after `OK:` so AI callers get structured data without parsing human text.

### `step2glb health`
Round-trip to the shared service, reports version + kicad_base.
```
$ step2glb health
OK: service-step2glb v0.1.0 reachable at https://step2glb-TBD.adom.cloud (kicad_base=https://kicad-rk5ue5pcfemi.adom.cloud, converts=42, uptime=3600s)
```

### `step2glb config`
Print the effective service URL (useful when `STEP2GLB_SERVICE_API` overrides the baked default).

### `step2glb convert <input.step> [-o out.glb]`
POSTs STEP bytes to the service, streams the GLB back.

```
$ step2glb convert SOT-89-3.step -o SOT-89-3.glb
OK: GLB written from SOT-89-3.step → SOT-89-3.glb  (3 meshes, 2 materials, 25.3 KB, 78 ms)
{"durationMs":78,"meshes":3,"nodes":8,"materials":[...],"sizeBytes":25916,"output":"SOT-89-3.glb","ok":true}
```

### `step2glb from-library <Library>/<Name> [-o out.glb]`
Single-call convenience: the service fetches the STEP from **service-kicad** by library + name, converts, and streams the GLB back.

```
$ step2glb from-library Package_TO_SOT_SMD/SOT-89-3
OK: GLB written from Package_TO_SOT_SMD/SOT-89-3 → /tmp/step2glb-SOT-89-3.glb  (3 meshes, 2 materials, 25.3 KB, 87 ms)

$ step2glb from-library Package_QFP/LQFP-100_14x14mm_P0.5mm --out /tmp/stm32.glb
```

### `step2glb preview <source>`
`<source>` is either a local `.step` path or a `<Library>/<Name>` identifier. Converts via the service, then spawns a local HTTP server on a free port and opens a **Hydrogen webview** tab so a human can see the rendered GLB alongside the stats.

```
$ step2glb preview Package_QFP/LQFP-100_14x14mm_P0.5mm
OK: preview ready at https://…adom.cloud/proxy/45231/  (Ctrl-C to stop)
```

The webview shows:
- Pills (top-left): `meshes`, `materials`, `size`, `conv` — green when healthy, red when off.
- **Details drawer** (≡ top-right): per-material color swatches + RGB values so you can see whether the STEP's colors came through.
- Top / Front / Iso camera presets + keyboard shortcuts (T / F / I).

### `step2glb install`
Fetches the latest `SKILL.md` from the wiki, writes it to `~/.claude/skills/step2glb/SKILL.md`, generates bash completions, appends a one-line hook to `~/.bashrc`.

### `step2glb completions bash|zsh|fish`
Print shell completions to stdout (what the install step uses internally; also fine for manual sourcing).

## Exit codes

| Code | Meaning |
|------|---------|
| 0    | OK |
| 1    | Input / argument invalid (missing file, malformed path) |
| 2    | Service unreachable (see `Hint:` for how to recover) |
| 4    | Service returned an error (conversion failed, library part not found) |

## Env vars

| Var | Purpose | Default |
|-----|---------|---------|
| `STEP2GLB_SERVICE_API` | Override the shared-service URL (useful for testing a local instance) | Baked into the binary at build time |

## Architecture (why no local CAD kernel)

`cadquery-ocp` bundles OCCT + its dependencies and weighs **~1.1 GB** in a venv. Installing that on every gallia container would cost gigabytes across the fleet when most users never need it, so step2glb runs as a **shared-service app** on the adom-app-model:

- **adom-inc/service-step2glb** — private repo, default-light container, Python HTTP server wrapping the OCCT XCAF pipeline. Runs `server.py` under a venv, watchdog every 2 min for health + auto-update.
- **adom-inc/step2glb** — this binary. Tier B auto-discovered from the wiki, `/usr/local/bin/step2glb` only, ~3 MB.

Per-call cost from the client: one HTTPS round-trip (KB in, KB–MB out) + ~100 ms–4 s of OCCT work on the shared container. Compared to the ~3.4 s cold-start of running OCCT locally, the shared service is actually faster because the Python interpreter + OCP import stay warm.

## Policy for consumers (chipfit, 3d-component-creator, adom-tsci, InstaPCB)

When a STEP is available and a GLB is needed, call `step2glb from-library <Lib>/<Name>` or `step2glb convert <file.step>` rather than hand-rolling STEP→GLB. This keeps material handling consistent across every downstream viewer and fixes the legacy "all-white GLB" class of bug.