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
parent 93773f3887
commit 5fb598857d
1 changed files with 56 additions and 53 deletions
@@ -1,99 +1,102 @@
 # 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.
+基于 **[step2urdf](https://github.com/Democratizing-Dexterous/step2urdf)**（与 https://step2urdf.top/ 同类 UI）的本地扩展：浏览器内 STEP 解析 + 结构树编辑 + URDF 导出，可选 FastAPI 后端做智谱建议。

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

-## Architecture
+## 架构

 ```
-Browser (Vite :5678)                    FastAPI (:8787)
+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      │
+│ step2urdf UI (frontend/)    │  /api/* │ POST /api/propose（智谱） │
+│ OCCT WASM · links/joints    │ ──────► │ /api/health              │
+│ 加载手调 JSON / 导出 URDF    │         │                          │
 └─────────────────────────────┘         └──────────────────────────┘
 ```

-Upstream source is under `frontend/` — see `frontend/UPSTREAM.md` for commit SHA.
+几何解析与 URDF 导出都在**浏览器**完成。上游说明见 `frontend/UPSTREAM.md`。

-The old MVP static page is demoted to **http://127.0.0.1:8787/legacy/** only.
+## 快速开始

-## Quick start (dev)
-
-### 1. Backend
+### 1. 后端（可选；仅智谱 / health 需要）

 ```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)
+cp .env.example .env   # 智谱功能才需要填 ZHIPU_API_KEY
 python -m app.main
 ```

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

-### 2. Frontend (primary UI)
+### 2. 前端（主界面）

-Needs Node 20+ and pnpm 10 (see `frontend/package.json` `packageManager`).
+需要 Node 20+、pnpm 10。

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

-Open: **http://127.0.0.1:5678**  
-Vite proxies `/api` → FastAPI `:8787`.
+打开：**http://127.0.0.1:5678**（`/api` 代理到 `:8787`）

-Test STEP: `/home/lxqs/A7_step/A7_assembly.STEP`
+### 3. 手调 JSON → URDF（推荐）

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

-After importing a STEP:
+JSON 约定：

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

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

-| Variable | Meaning |
-|----------|---------|
-| `ZHIPU_API_KEY` | Required for LLM propose |
-| `ZHIPU_MODEL` | Default `glm-4-plus` |
-| `HOST` / `PORT` | FastAPI default `127.0.0.1:8787` |
+### 4. 智谱建议（可选，旧路径）

-## Layout
+需后端已配置 `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 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
+frontend/                 # step2urdf Vue/Vite
+  public/handtuned_arm.json
+  src/.../applyHandtunedJson.ts
+data/handtuned_arm.json   # 手调源数据（与 public 同步）
+app/                      # FastAPI（智谱 / health / legacy）
+requirements.txt
 ```

-## Production-ish (optional)
+## 生产构建（可选）

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

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