app

Adom Step2GLB - STEP to GLB converter

Public Made by Adom

by adom

Color-preserving STEP (.step/.stp) to GLB converter. Thin Rust CLI shelling to a shared OCCT XCAF service. Formerly 'step2glb'.

stepglbcadconverterocct3d
Overview Files Skills Discover Packages Releases Dependencies Issues2 Breadcrumbs Pull Requests Activity
Open general

CLI parity with the OCCT service: molecule mode, job stats, artifact retrieval

Drew Owens · 14d ago

The service grew a set of molecule-pipeline capabilities that the CLI does not expose yet, so agents fall back to raw curl for the most important conversion path (KiCad/Fusion molecule with STEP but no GLB). Detailed ask below — all endpoints verified against the deployed service (git_sha f91cf2e, service 1.2.0).

1. Molecule mode on convert (the big one)

The service converts a molecule STEP end-to-end: MP-marker anchoring (Z-up, front-left pin origin at the L4-L5 board surface), canonical gold machine-pin material, silkscreen overlay, meter normalization, Draco optimize, and — when a board file is attached — footprint + symbol JSON generation with per-pad wire-attach Z injected. None of that is reachable from the CLI.

Proposed:

step2glb convert board.step --molecule [--pin medium|large] \
    [--board board.kicad_pcb] [--silk-top top.png] [--silk-bottom bottom.png] \
    [-o out.glb] [--footprint-out <slug>_footprint.json] [--symbol-out <slug>_symbol.json]

Wire protocol (existing, no service changes needed):

  • POST /convert?molecule=true&pin=<medium|large> — multipart fields: step (required), board (.kicad_pcb or .brd, auto-sniffed), silk_top, silk_bottom
  • Artifacts: GET /jobs/{id}/result (GLB), GET /jobs/{id}/footprint, GET /jobs/{id}/symbol (404 when not produced — plain PCBs/chips pass through gracefully)

The CLI should download the footprint/symbol JSON beside the GLB when present (default names <stem>_footprint.json / <stem>_symbol.json to match what the molecule packaging expects).

2. Surface molecule job stats + warnings on completion

GET /jobs/{id} carries per-stage results the user needs to see to trust the output: anchored, molecule_up_axis, fl_marker, molecule_origin_z, pin_size, gold_upgraded, silkscreen_applied/sides, footprint_applied, footprint_pins, footprint_contacts, contact_z, and warnings[] (e.g. "anchor skipped: <3 markers", "footprint gen failed: ..."). Today the CLI reports success/failure only. A short stats block after convert (and --json passthrough of the full status) would make molecule fallbacks visible instead of silent.

Heads-up: a pending service change (measured contact-top Z, branch molecule-measured-z) adds measured_contact_z_mm and contact_z_source: measured|ladder to the status — printing unknown status fields generically would future-proof this.

3. job verb for artifact retrieval

step2glb job <id> [--status | --glb out.glb | --footprint out.json | --symbol out.json] — poll a job and fetch any artifact after the fact. Useful when a conversion was kicked off elsewhere (e.g. the wiki publish flow) and an agent wants the side artifacts.

4. --molecule on from-library too

Same flags as #1 for the service-kicad fetch path, so a library part with markers can go straight to an anchored GLB.

5. (Lower priority) other service endpoints with no CLI verb

/step-meta, /create-chip, /create-footprint, /bake, /outline, /name-emboss, /queue, /jobs (list). Not needed for the molecule pipeline, but listing them for a full parity picture — a generic step2glb api <path> escape hatch would cover the tail cheaply.

Why now

The molecule upload flow (KiCad project + STEP, no GLB) is becoming the standard publish path, and today it requires hand-rolled curl with the right identity headers, query params, and three artifact downloads. The CLI already does headers + polling + downloads perfectly for plain converts — items 1+2 close the gap for molecules with flags only, no new service surface.

Happy to pair on it or send a PR to the CLI if useful — the service side is stable and documented.

1 Reply

Drew Owens · 14d ago

References — OCCT-service docs

Authoritative sources for the wire contract described above (repo: github.com/adom-inc/service-step2glb, private, adom-inc org):

  • CLAUDE.md — service overview: container/URL (https://step2glb-gmdoncpxdwx0.adom.cloud, internal :8782), the endpoint table, the deploy flow (push to main → watchdog auto-deploys within ~2 min), logs, and the OCP venv used for local testing.
  • api/server.py (top-of-file docstring + the do_GET/do_POST routes) — the precise HTTP contract: every POST returns 202 + job_id, poll GET /jobs/{id}, fetch GET /jobs/{id}/result; multipart /convert fields (step, board, silk_top, silk_bottom); query params ?molecule=true&pin=medium|large (server.py:212-213, 522-523); the /jobs/{id}/footprint and /jobs/{id}/symbol artifact routes (server.py:170-188).
  • api/job_queue.py — the molecule-mode pipeline order (anchor → silk → normalize → gold → optimize → footprint) and every stats/warnings field GET /jobs/{id} returns (_run + get_status).
  • api/molecule_anchor.py — docstrings for the anchoring semantics (MP-marker detection, Z-up rotation, front-left pin origin at the L4-L5 board surface, pin-size heights).

Known doc gap, being fixed: CLAUDE.md's endpoint table and the server.py header docstring predate molecule mode — neither mentions ?molecule=true, the board field, or the footprint/symbol artifact routes; the code + this issue are currently the authoritative description. A docs update goes out with the pending molecule-measured-z branch so the table matches the deployed surface.

Live verification: GET https://step2glb-gmdoncpxdwx0.adom.cloud/health → git_sha_short tells you exactly which commit is serving (currently f91cf2e2).

Log in to reply.