# 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.