Adom Step2GLB - The Adom STEP Engine

@@ -1,103 +1,77 @@ --- 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.+description: Convert STEP (.step/.stp) CAD files to color-preserving GLBs via the shared OCCT service — plain converts, geometric features, thumbnails, previews, and FULL MOLECULE MODE (--molecule/--board: MP-marker anchoring, gold machine pins, footprint + symbol JSON with per-pad wire-attach Z). Thin ~3MB Rust CLI; the 4.7GB OCCT runtime stays on the service. Use when the user asks to convert a STEP to GLB, convert a molecule board, render a component with real materials, extract STEP features, or make STEP thumbnails. Triggers: step to glb, step2glb, convert step, cad to glb, molecule convert, kicad step to glb, occt gltf, step preview, step thumbnail, step features. --- -# step2glb+# step2glb — STEP → GLB via the shared OCCT service -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.+Thin Rust CLI (~3 MB, no CAD kernel) that shells to the shared OCCT XCAF+service. Returns `OK:`/`ERROR:` + `Hint:` lines so humans and agents both+parse results. -## Install (Tier B)+- **Install / update:** `adom-wiki pkg install adom/adom-step2glb`+- **Service:** `https://step2glb-gmdoncpxdwx0.adom.cloud` (the canonical shared+  instance; override with `STEP2GLB_SERVICE_API`). `step2glb health` checks it;+  `/health` exposes `git_sha_short` so you can see exactly what's deployed.+- Every request auto-sends the required `X-Client`/`X-Job-Name` identity+  headers. Large STEPs gzip on upload and queue async (the CLI polls for you). -```-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+## Plain conversion -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)+```bash+step2glb convert part.step [-o part.glb]+step2glb from-library Package_TO_SOT_SMD/SOT-89-3   # fetch from service-kicad + convert+step2glb preview part.step                          # convert + open a Hydrogen webview to verify ``` -### `step2glb config`-Print the effective service URL (useful when `STEP2GLB_SERVICE_API` overrides the baked default).+Preserves per-face colors/materials (fixes the legacy all-white-GLB class of+bug). NOTE: if the output warns `molecule_markers_detected`, the STEP is a+molecule board — use molecule mode below instead; a plain GLB of a molecule+imports unanchored and unwireable. -### `step2glb convert <input.step> [-o out.glb]`-POSTs STEP bytes to the service, streams the GLB back.+## Molecule mode (boards with Adom machine pins) +```bash+step2glb convert board.step --board board.kicad_pcb --pin medium -o <slug>.glb+# --board implies --molecule; .brd (EAGLE/Fusion) boards work too+# optional: --silk-top top.png --silk-bottom bottom.png  (white art, transparent bg) ```-$ 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. +One command does the whole molecule pipeline server-side: MP-marker anchoring+(Z-up, front-left machine pin at origin, L4-L5 board-surface Z), canonical+gold machine-pin material, silkscreen overlay, meter normalization, Draco+optimization, and — with the board attached — **footprint + symbol JSON**+generation with per-pad wire-attach Z, downloaded beside the GLB as+`<stem>_footprint.json` / `<stem>_symbol.json`.++**Gate on the printed stats before publishing** (the molecule-publish skill+treats these as stop-signs):++| Stat | Expect | If not |+|---|---|---|+| `molecule_anchored` | `true` | MP1-MP4 markers missing from the STEP — fix the board/export |+| `pin_size` / `pin_size_source` | correct size, `markers` | size read from the marker names; `param` = fallback to `--pin` |+| `footprint_applied` + `footprint_pins` | `true`, 4 | board parse failed — read the warnings |+| `footprint_rebase` | absent or small | footprint re-based to the GLB's anchor pin (alignment guard) |+| `warnings` | none | every entry is actionable |++The final GLB carries `asset.extras.adomMolecule` (anchored, pin size, etc.) —+durable provenance you can check on any downloaded GLB. (Do NOT look for a+`molecule_anchor` node: the optimizer flattens it by design.)++## Other verbs++```bash+step2glb features part.step          # bbox, floor_z, longest axis, pin1 → JSON+step2glb thumbnail part.step         # PNG render (--width/--height/--pose)+step2glb thumbnail-batch part.step   # N orientations x M sizes in one call+step2glb config                      # show the service URL in effect+step2glb install                     # refresh this skill + bash completions ```-$ 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)+## Where this fits -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.+`molecule-publish` (wiki publishing) and the EDA export skills+(`kicad-export-molecule`, `fusion-export-molecule`) drive this CLI as their+conversion stage. For pipeline-wide guidance start at the+`molecule-pipeline` page on the wiki.