sunxianghui
93773f3887
Includes FastAPI backend, vendored step2urdf frontend, and A7 handtuned arm JSON for URDF generation.
100 lines
3.4 KiB
Markdown
100 lines
3.4 KiB
Markdown
# 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.
|