Add AC/BC RTCP programs and 3D machine manager

2026-09-20 12:31:12 +08:00
parent 1c1e5f9672
commit 8aab531b02
363 changed files with 53213 additions and 58 deletions
--- a/docs/glb-machine-manager/01-项目功能内容.md
+++ b/docs/glb-machine-manager/01-项目功能内容.md
@@ -0,0 +1,45 @@
+# 项目功能内容
+
+## 目标
+
+在 Web LinuxCNC 控制面板的机床预览区增加“三维机床管理”按钮。对话框内完成机床部件装配和坐标标定，最终生成可由现有 XYZAC/XYZBC TRT 运行链使用的机床模型。
+
+## 功能范围
+
+1. 对话框包含独立的 Three.js 三维预览，实时显示正在配置的机床。
+2. 支持逐个导入自包含 `.glb` 机床部件，不允许依赖外部纹理或网格文件。
+3. 每个部件可绑定 `底座、X、Y、Z、刀具、A/B、C、工件` 角色，并编辑父级关系。可运行结构必须满足：
+   - 刀具链：底座 → X → Y → Z → 刀具。
+   - 转台链：底座 → A/B → C → 工件。
+4. 每个部件可定义局部坐标原点。模型网格相对该原点偏移，运动关节围绕该原点运动。
+5. 每个部件可独立显示或隐藏原点坐标轴辅助线。
+6. 每个部件可用数值和 Three.js 操纵器平移、旋转；变换只修改装配配置，不修改原 GLB 字节。
+7. 可定义 C 轴原点位置和 A/B 到 C 的运动学偏置。应用时写入底座场景节点及整机场景的 `userData.linuxcncMachineGeometry`，同时生成 URDF：
+   - `C 原点 P = (x-rot-point, y-rot-point, z-rot-point)`。
+   - `A/B 偏置 D = (x-offset, y-offset, z-offset)`。
+   - 倾转关节原点 `T=P+D`，C 关节原点 `U=-D`，工件固定原点 `-P`。
+8. 可定义 X/Y/Z/A或B/C 的物理零点。模型运动量为 LinuxCNC 实际关节值减去配置的物理零点。
+9. 应用后，控制面板程序执行、Jog、RTCP 切换和刀长变化继续以 Worker/WASM 快照为唯一运动输入；模型不得在 React 中重新计算刀尖逆解。
+
+## 数据和单位
+
+- UI 中平移、局部原点、C 原点和偏置使用毫米；旋转和物理旋转轴零点使用度。
+- GLB 遵循 glTF 米制、Y-up；生成的 URDF 使用米和弧度、Z-up。
+- 部件源文件、哈希和原始场景保持不变；运行装配使用深复制后的几何与材质。显式“导出组合 GLB”会生成新文件，并将标定数据同时写入整机场景和底座节点 `userData`。
+- 底座 `userData` 至少保存 schema、机型、C 原点、A/B 偏置、物理零点和部件装配摘要。
+
+## 安全边界
+
+- 当前只生成项目已有求解器支持的 XYZAC 或 XYZBC 双分支 TRT 结构。
+- 层级编辑器允许建立关系，但“应用到控制器”前必须严格验证两条受支持机械链、角色唯一性和无环结构。
+- 未完成八个角色时允许预览和保存草稿，不允许应用到控制器。
+- 模型外观变换不能代替 INI/运动学参数；C 原点和 A/B 偏置必须通过现有配置重载进入 WASM。
+- 不做碰撞、质量、刚体动力学或任意 URDF 求解。
+
+## 验收结果
+
+- AC 与 BC 均能由八个独立部件建立结构并应用。
+- 对话框预览、原点辅助、平移/旋转和层级变化实时可见。
+- 底座 `userData` 含完整几何及物理零点字段。
+- 运行控制面板后，X/Y/Z/A或B/C Jog 和五轴程序驱动对应部件；工件路径继续附着 C 轴，刀具长度来自 WASM。
+- 非法层级、重复角色、缺失部件、错误机型和外部资源 GLB 明确拒绝，已生效模型不改变。
--- a/docs/glb-machine-manager/02-项目程序开发详细步骤.md
+++ b/docs/glb-machine-manager/02-项目程序开发详细步骤.md
@@ -0,0 +1,13 @@
+# 项目程序开发详细步骤
+
+1. `MGR-01`：建立本专项 01–06 与 README，冻结数据字段、坐标单位、机械链和验收边界。
+2. `MGR-02`：实现部件 GLB 加载、哈希、外部资源拒绝、装配草稿类型和生命周期清理。
+3. `MGR-03`：实现角色/父级编辑、唯一性和无环校验，生成 XYZAC/XYZBC 严格 URDF 与运行场景。
+4. `MGR-04`：实现对话框 Three.js 预览、部件选择、显示/隐藏和原点坐标轴辅助。
+5. `MGR-05`：实现部件局部原点、数值平移/旋转和 Three.js TransformControls 操纵器。
+6. `MGR-06`：实现 C 原点、A/B 偏置、物理零点，写入底座及整机 `userData`，并映射到 URDF/INI。
+7. `MGR-07`：接入控制面板“应用机床”，复用现有 `LOAD_WORKSPACE`、`PROGRAM_LOAD`、回零失效和 GLB 资源清理事务。
+8. `MGR-08`：验证 WASM 关节值到部件链的映射、刀具/工件/路径坐标一致性及 AC/BC 五轴程序。
+9. `MGR-09`：浏览器交互、错误边界、类型检查、生产构建、截图和报告收口。
+
+每轮只推进任务矩阵中依赖已满足的任务。代码完成后必须同步更新 03、04、05；若改变数据契约或坐标定义，先更新 06。
--- a/docs/glb-machine-manager/03-推进台账.md
+++ b/docs/glb-machine-manager/03-推进台账.md
@@ -0,0 +1,22 @@
+# 推进台账
+
+## R02 / 2026-09-20 / 部件装配、标定、应用与验收完成
+
+- 新增 `machine-manager.ts`：通用自包含 GLB 部件加载、SHA-256、深复制、八角色和两条机械链校验、AC/BC URDF 生成、组合场景、底座/整机 userData、组合哈希。
+- 新增 `MachineManagerPanel.tsx`：机床预览区“三维机床管理”按钮、可拖动大对话框、独立 Three.js 预览、批量部件导入、角色/父级、显隐、原点辅助、数值平移/旋转、TransformControls、C 原点、A/B 偏置和物理零点编辑。
+- 新增“导出组合 GLB”；导出的新文件包含 `linuxcnc.machine/1` URDF，以及整机场景和底座节点上的 `linuxcnc.machine-manager/1` 标定 userData。
+- 接入 App 原有 `LOAD_WORKSPACE` + `PROGRAM_LOAD` 事务。配置和程序应用成功后替换机床；失败候选被释放。关机且空闲门控、程序重解析和回零要求保持。
+- `buildImportedMachine` 按 `WASM joint - physicalZero` 驱动 X/Y/Z/A或B/C，刀长、路径和 RTCP 仍来自 Worker/WASM；有效 INI 参数同步回运行克隆的底座 userData。
+- 浏览器 E01/E02 覆盖 8 个独立 GLB、原点/变换、导出、AC 应用、同一部件切 BC、BC 五轴程序、物理零点、非法层级和生产包。无浏览器错误。
+- 旧五轴整机回归重新通过：AC/BC 各 41 个五轴同时变化 tick、42 个样本，坐标误差低于 `2.5e-16` 视图单位。
+- `gltf-validator` 当前未安装，因此没有重跑旧 Khronos 校验器；旧四个示例 GLB 未修改，历史 `coverage/glb-machine/gltf-validation.report.json` 仍为 verified。本专项生成并下载的组合 GLB 已由浏览器 GLTFExporter 完成往返导出。
+- MGR-01 至 MGR-09 全部完成。下一步按用户体验反馈扩展草稿持久化、部件库或任意新运动学 profile；不自动扩大到碰撞/动力学。
+
+## R01 / 2026-09-20 / 专项建立与实现启动
+
+- 用户要求在机床预览区新增“三维机床管理”对话框，覆盖部件级 GLB 导入、层级、原点、姿态、RTCP 几何参数、物理零点和控制坐标对应。
+- 核对现有 `docs/glb-machine`、`MachineImportPanel`、严格 URDF 解析、`buildImportedMachine` 和 WASM 关节投影。现有能力只支持已经包含完整层级与 URDF 的整机 GLB，本轮扩展为部件装配编辑器。
+- 建立本目录 01–06 和 README；新增 MGR-01 至 MGR-09 任务链。
+- 决定复用 `linuxcnc.machine/1` 结构：管理器生成合法场景和 URDF，现有 INI/Worker/WASM 继续作为运动和 RTCP 权威。
+- 当前任务：已完成。
+- 下一步：按新需求继续；本专项不重复执行。
--- a/docs/glb-machine-manager/04-任务矩阵.md
+++ b/docs/glb-machine-manager/04-任务矩阵.md
@@ -0,0 +1,13 @@
+# 任务矩阵
+
+|任务|状态|依赖|交付与验收标准|
+|---|---|---|---|
+|MGR-01 文档与契约|verified|-|01–06 与 README 存在；字段、单位、机械链、权威边界明确|
+|MGR-02 部件 GLB 加载|verified|MGR-01|多文件导入、SHA-256、外部资源拒绝、资源释放测试通过|
+|MGR-03 层级与 URDF|verified|MGR-02|八角色、父级编辑、无环/唯一性、AC/BC URDF 生成与严格解析通过|
+|MGR-04 管理器预览|verified|MGR-03|对话框 Three.js 预览、选择、显隐和相机控制可用|
+|MGR-05 原点与部件变换|verified|MGR-04|原点辅助显示；数值和操纵器平移/旋转同步|
+|MGR-06 RTCP 几何与物理零点|verified|MGR-03|C 原点、A/B 偏置、物理零点写入底座 userData，并正确生成 URDF|
+|MGR-07 控制面板接入|verified|MGR-03,MGR-06|“三维机床管理”入口；应用复用 LOAD_WORKSPACE/PROGRAM_LOAD，失败不改旧模型|
+|MGR-08 坐标一致性|verified|MGR-07|AC/BC 的 X/Y/Z/A或B/C、刀长、工件和路径由 WASM 状态正确驱动|
+|MGR-09 浏览器验收收口|verified|MGR-04,MGR-05,MGR-08|交互/错误/构建/浏览器截图报告通过，03–05 完整更新|
--- a/docs/glb-machine-manager/05-验收证据.md
+++ b/docs/glb-machine-manager/05-验收证据.md
@@ -0,0 +1,39 @@
+# 验收证据
+
+## E01 / R01 / 文档与基线
+
+- 状态：verified。
+- 文档目录：`docs/glb-machine-manager/`。
+- 基线能力：现有整机 GLB 导入、严格 URDF、几何参数重载和 WASM 关节投影保留。
+- 实现和运行证据见 E02–E04。
+
+## E02 / R02 / 开发源浏览器闭环
+
+- 命令：`PLAYWRIGHT_MODULE=/home/mes006/.npm/_npx/e41f203b7505f1fb/node_modules/playwright/index.mjs node scripts/test_machine_manager_browser.mjs`
+- report_id：`GLB-MGR-E01`
+- 报告：`coverage/glb-machine-manager/browser.report.json`
+- SHA-256：`d3d15da19d3e8a8c958935a0e9c3840b70fb646d5bc8ffb72805dc744df078a3`
+- 状态：verified；浏览器错误 0。
+- 覆盖：8 部件导入和预览、原点显隐、数值/TransformControls 变换、组合 GLB 导出、AC/BC 应用、底座 userData、物理零点、非法层级拒绝、BC 五轴程序。
+- 截图：
+  - `coverage/glb-machine-manager/manager-ac-config.png`，SHA-256 `5ca01d26cb83da726319be107aa90069ce96c3197f4297a26e1f836d171a1501`
+  - `coverage/glb-machine-manager/managed-bc-running.png`，SHA-256 `6e14ff6bc4e493f57e55bb601ded84319ce86f064f7a811595c1e4498b1827a0`
+
+## E03 / R02 / 生产构建浏览器闭环
+
+- 构建：`npm --prefix web/react run build`，通过；只有既有大 chunk 提示。
+- 命令：`MACHINE_MANAGER_SOURCE_MODULES=0 ... node scripts/test_machine_manager_browser.mjs`
+- report_id：`GLB-MGR-E02`
+- 报告：`coverage/glb-machine-manager/browser-production.report.json`
+- SHA-256：`5ba840aa92c37a06e2f19bce7c57234871b085e27951fb44623af74253215388`
+- 状态：verified；生产资产执行 AC/BC UI 应用和 BC WASM 程序运动，浏览器错误 0。
+
+## E04 / R02 / 回归与静态契约
+
+- `node scripts/test_axis_control_inventory.mjs`：verified，99 个文档化控件。
+- `node web/react/src/test_dual_canvas_contract.mjs`：verified。
+- `node web/react/src/test_xyzac_threejs.mjs`：verified。
+- `npm --prefix web/react run typecheck`：通过。
+- `node scripts/test_glb_machine_motion.mjs`：verified；报告 `coverage/glb-machine-manager/regression-motion/motion.report.json`，SHA-256 `91c3fa8ed8037aac8e71b8c76d54c38db9dc011ae25f63553966860b624aa626`。AC/BC 各 41 个同时五轴变化 tick、42 个样本，最大误差分别约 `2.26e-16`、`2.48e-16`。
+- `git diff --check`：通过。
+- `scripts/validate_glb_machines.mjs` 未重跑：本地缺少 `gltf-validator` 包；旧示例 GLB 未修改，历史 Khronos 校验报告仍为 verified。该依赖边界不影响新管理器的浏览器导入、导出和运行证据。
--- a/docs/glb-machine-manager/06-决策记录.md
+++ b/docs/glb-machine-manager/06-决策记录.md
@@ -0,0 +1,29 @@
+# 决策记录
+
+## D01 / 继续使用 LinuxCNC WASM 作为运动权威
+
+部件编辑器只生成模型结构和标定参数。程序执行、Jog、刀长、运动学类型和关节位置仍来自 Worker/WASM 快照。Three.js 不实现第二套 RTCP 或逆运动学。
+
+## D02 / 运行结构保持 `linuxcnc.machine/1`
+
+现有严格 URDF 校验、配置写入和运行投影已经验收。部件管理器输出同一结构，可复用所有运行能力并避免引入并行格式。编辑草稿使用独立 schema，只有验证成功后才转换成运行结构。
+
+## D03 / 编辑层级自由，应用层级受求解器限制
+
+UI 允许用户选择父级以建立层级和发现错误；应用时只接受底座→X→Y→Z→刀具及底座→A/B→C→工件。当前 WASM 只支持这两类 TRT，不能把任意树伪装成可执行机床。
+
+## D04 / 原 GLB 不原地改写
+
+导入部件的源字节和场景保持不变。局部原点和平移/旋转存在装配配置中，应用时创建深复制运行场景。标定数据写入运行装配中底座节点及整机场景的 userData；“导出组合 GLB”将该装配序列化为新的自包含 GLB，原部件文件不被覆盖。
+
+## D05 / C 原点与 A/B 偏置的唯一映射
+
+沿用 `trtfuncs.c` 和既有参数契约：C 原点 P 对应 rot-point，A/B 偏置 D 对应 offset；URDF 使用 T=P+D、U=-D、work=-P。该公式是控制模型坐标对应的唯一来源。
+
+## D06 / 物理零点是模型校准，不改控制器关节值
+
+物理零点保存为每轴的模型零姿态标定值。渲染位移/转角使用 `WASM joint - physicalZero`，但不修改 Worker、INI 的回零位置或程序坐标。改变真实回零参数仍应通过机床配置完成。
+
+## D07 / 组合 GLB 只通过显式导出生成
+
+普通编辑和“应用到 Web LinuxCNC”不触碰用户原文件。只有用户点击“导出组合 GLB”时才用 GLTFExporter 生成新文件。导出包含部件层级、URDF、底座标定 userData 和整机场景标定 userData。
--- a/docs/glb-machine-manager/README.md
+++ b/docs/glb-machine-manager/README.md
@@ -0,0 +1,25 @@
+# Web LinuxCNC 三维机床管理器
+
+本目录是“三维机床管理器”专项的唯一接续入口。工作顺序固定为：
+
+1. 阅读 [04-任务矩阵](04-任务矩阵.md)，选择首个未完成且依赖满足的任务。
+2. 阅读 [03-推进台账](03-推进台账.md) 最新一轮和 [06-决策记录](06-决策记录.md)。
+3. 按 [02-项目程序开发详细步骤](02-项目程序开发详细步骤.md) 实施。
+4. 验收后把命令、报告、截图写入 [05-验收证据](05-验收证据.md)，同步任务状态和推进台账。
+
+专项目标是在 Web LinuxCNC 机床预览区提供“三维机床管理”对话框，支持 GLB 部件导入、AC/BC 两条机械链装配、部件原点和姿态编辑、原点辅助显示、RTCP 几何参数及物理零点定义，并保证模型运动与 LinuxCNC WASM 的实际关节坐标一致。
+
+现有整机 GLB + 内嵌 URDF 导入能力继续保留。新管理器生成与现有 `linuxcnc.machine/1` 相同的严格结构，再通过已有配置、Worker、WASM 和 Three.js 投影链运行。
+
+当前状态：MGR-01 至 MGR-09 全部 verified。最新台账 R02，浏览器证据 `GLB-MGR-E01/E02`，截图和报告位于 `coverage/glb-machine-manager/`。
+
+文档：
+
+- [01-项目功能内容](01-项目功能内容.md)
+- [02-项目程序开发详细步骤](02-项目程序开发详细步骤.md)
+- [03-推进台账](03-推进台账.md)
+- [04-任务矩阵](04-任务矩阵.md)
+- [05-验收证据](05-验收证据.md)
+- [06-决策记录](06-决策记录.md)
+
+相关旧专项：[GLB / URDF 五轴机床子项目](../glb-machine/README.md)。旧专项已完成整机导入、AC/BC 识别、几何参数同步和实际关节驱动，本专项不重复这些底层能力。