step2urdf-tool

Local fork/extension of step2urdf (UI same product as https://step2urdf.top/), plus a small FastAPI backend that proxies 智谱 (Zhipu) for link/joint suggestions.

Geometry parse + URDF export stay in the browser (OpenCASCADE WASM). The backend only helps propose a kinematic draft; you refine axes in the 3D view, then use step2urdf’s own 导出 URDF.

Architecture

Browser (Vite :5678)                    FastAPI (:8787)
┌─────────────────────────────┐         ┌──────────────────────────┐
│ step2urdf UI (frontend/)    │  /api/* │ ZHIPU_API_KEY (server)   │
│ OCCT WASM · links/joints    │ ──────► │ POST /api/propose        │
│ Export URDF (client ZIP)    │         │ optional /api/parse      │
└─────────────────────────────┘         └──────────────────────────┘

Upstream source is under frontend/ — see frontend/UPSTREAM.md for commit SHA.

The old MVP static page is demoted to http://127.0.0.1:8787/legacy/ only.

Quick start (dev)

1. Backend

cd ~/Projects/step2urdf-tool
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# edit .env → set ZHIPU_API_KEY (never commit .env)
python -m app.main

API: http://127.0.0.1:8787/api/health

2. Frontend (primary UI)

Needs Node 20+ and pnpm 10 (see frontend/package.json packageManager).

export PATH="$HOME/.local/node/bin:$PATH"   # if pnpm lives here
cd ~/Projects/step2urdf-tool/frontend
pnpm install
pnpm dev

Open: http://127.0.0.1:5678
Vite proxies /api → FastAPI :8787.

Test STEP: /home/lxqs/A7_step/A7_assembly.STEP

3. Zhipu button

After importing a STEP:

1. Left panel → 智谱建议关节
2. Confirm/edit part names + profile (a7 / generic) + optional hint
3. 请求智谱建议 → preview joints
4. 应用到结构树 → writes into step2urdf useURDFStore (links, joints, solid binds by name)
5. Tweak joint origins/axes in 3D (edge pick / axis offset) — LLM values are approximate
6. 导出 URDF (native step2urdf exporter)

Environment

Variable	Meaning
ZHIPU_API_KEY	Required for LLM propose
ZHIPU_MODEL	Default glm-4-plus
HOST / PORT	FastAPI default 127.0.0.1:8787

Layout

frontend/                 # step2urdf Vue/Vite app (+ Zhipu panel)
  UPSTREAM.md
app/
  main.py                 # FastAPI: /api/propose, CORS, /legacy
  services/zhipu.py       # Zhipu chat → RobotDraft JSON
  services/profiles.py    # a7 / generic seed grouping
  static/                 # legacy MVP UI (/legacy)
data/jobs/                # optional server-side parse jobs

Production-ish (optional)

cd frontend && pnpm build
# FastAPI serves frontend/dist at / when present
python -m app.main

Known gaps

• Joint origin/axis from Zhipu are estimates — always refine in the 3D viewer before trusting Export.
• Solid binding matches by part name; rename mismatches need manual bind.
• Server /api/export is legacy; prefer the UI exporter.
• Deep auto-snap from LLM to OCCT edge features is not implemented yet.