Files

T

sunxianghui 5fb598857d docs: update README for handtuned JSON workflow

Document the recommended load-JSON → export URDF path and demote Zhipu to optional.

2026-08-26 15:37:20 +08:00

3.8 KiB

Raw Permalink Blame History

step2urdf-tool

基于 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 需要）

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。

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（推荐）

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

生产构建（可选）

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

注意

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

3.8 KiB Raw Permalink Blame History Unescape Escape