Initial commit: step2urdf tool with handtuned JSON import.

Includes FastAPI backend, vendored step2urdf frontend, and A7 handtuned arm JSON for URDF generation.
2026-08-26 15:32:47 +08:00
commit 93773f3887
128 changed files with 20119 additions and 0 deletions
@@ -0,0 +1,99 @@
+# step2urdf-tool
+
+Local fork/extension of **[step2urdf](https://github.com/Democratizing-Dexterous/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
+
+```bash
+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`).
+
+```bash
+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)
+
+```bash
+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.