# step2urdf-tool

基于 **[step2urdf](https://github.com/Democratizing-Dexterous/step2urdf)**（与 https://step2urdf.top/ 同类 UI）的本地扩展：浏览器内 STEP 解析 + 结构树编辑 + URDF 导出，可选 FastAPI 后端做智谱建议。

**当前推荐路径**：用手调 JSON（`data/handtuned_arm.json`）直接导入连杆/关节/Solid 绑定，再导出 URDF——**不依赖智谱**。

## 架构

```
Browser (Vite :5678)                    FastAPI (:8787，可选)
┌─────────────────────────────┐         ┌──────────────────────────┐
│ step2urdf UI (frontend/)    │  /api/* │ POST /api/propose（智谱） │
│ OCCT WASM · links/joints    │ ──────► │ /api/health              │
│ 加载手调 JSON / 导出 URDF    │         │                          │
└─────────────────────────────┘         └──────────────────────────┘
```

几何解析与 URDF 导出都在**浏览器**完成。上游说明见 `frontend/UPSTREAM.md`。

## 快速开始

### 1. 后端（可选；仅智谱 / health 需要）

```bash
cd ~/Projects/step2urdf-tool
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # 智谱功能才需要填 ZHIPU_API_KEY
python -m app.main
```

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

### 2. 前端（主界面）

需要 Node 20+、pnpm 10。

```bash
export PATH="$HOME/.local/node/bin:$PATH"
cd ~/Projects/step2urdf-tool/frontend
pnpm install
pnpm dev --host 127.0.0.1 --port 5678
```

打开：**http://127.0.0.1:5678**（`/api` 代理到 `:8787`）

### 3. 手调 JSON → URDF（推荐）

1. 导入与手调时相同的 STEP（Solid 编号需一致，如 `Solid_0`…）
2. 左侧 **Robot Structure** 底部点 **「加载手调 JSON」**  
   - 读取 `frontend/public/handtuned_arm.json`（与 `data/handtuned_arm.json` 同步）  
   - 或 **「选择 JSON…」** 选本地文件
3. 核对结构树、坐标系是否贴在零件上
4. **导出 URDF**

JSON 约定：

| 字段 | 含义 |
|------|------|
| `unit_linear` | 默认 `"m"`；导入时线性量 ×1000 → 页面内部 mm |
| `links[].solid_names` | 零件归属（`Solid_N`） |
| `joints[].origin_xyz/rpy` | 相对 **parent link**；限位在 `limits` |
| `base_link.origin_xyz` | 基坐标系在 STEP 世界中的位置（米） |

导入时：挂在 `base_link` 下的关节会烘焙成 STEP 世界坐标（与页面 FK / 拾取边一致），导出时再按 base 扣回 URDF 相对量。

### 4. 智谱建议（可选，旧路径）

需后端已配置 `ZHIPU_API_KEY`。左侧曾有「智谱建议关节」入口；现主流程以手调 JSON 为准。A7 金标逻辑仍在 `app/services/a7_gold.py`。

## 环境变量

| 变量 | 说明 |
|------|------|
| `ZHIPU_API_KEY` | 仅智谱 propose 需要；勿提交 `.env` |
| `ZHIPU_MODEL` | 默认 `glm-4-plus` |
| `HOST` / `PORT` | FastAPI，默认 `127.0.0.1:8787` |

## 目录

```
frontend/                 # step2urdf Vue/Vite
  public/handtuned_arm.json
  src/.../applyHandtunedJson.ts
data/handtuned_arm.json   # 手调源数据（与 public 同步）
app/                      # FastAPI（智谱 / health / legacy）
requirements.txt
```

## 生产构建（可选）

```bash
cd frontend && pnpm build
python -m app.main   # 若存在 frontend/dist，可由 FastAPI 托管
```

## 注意

- Solid 绑定按 **名称**（`Solid_N`）；换 STEP 或剖分结果不同会导致部分未绑定。
- 手调 JSON 的 xyz 是相对父连杆的米制数值；不要在导入后再整体 ×1000。
- 服务端 `/api/export` 为遗留接口；请用页面 **导出 URDF**。