sunxianghui
5fb598857d
Document the recommended load-JSON → export URDF path and demote Zhipu to optional.
103 lines
3.8 KiB
Markdown
103 lines
3.8 KiB
Markdown
# 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**。
|