step2urdf/README.md

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

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

生产构建（可选）

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

注意

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