继续完成 web-rtcp-5axis-sim-plan

结论：完成 LinuxCNC kinematics WASM ABI 覆盖，并将 web-rtcp-5axis-sim-plan 的 RTCP frame/boundary adapter 接到 xyzac-trt kinematics SDK；Node、build、browser smoke 验证通过。
2026-06-21 16:44:29 +08:00
parent a6eda3fbff
commit 626bcfe8e3
101 changed files with 101586 additions and 770 deletions
--- a/web-rtcp-5axis-sim-plan/docs/implementation-plan.md
+++ b/web-rtcp-5axis-sim-plan/docs/implementation-plan.md
@@ -0,0 +1,396 @@
+# 基于 Web 的 RTCP 五轴联动数控系统仿真实现方案
+
+生成时间：2026-06-20 CST
+
+## 1. 项目定位
+
+本项目建设一个独立的 Web 数控系统仿真界面，重点支持五轴联动与 RTCP/TCP 模式展示。系统以 LinuxCNC 源码、`configs/sim` 案例和 LinuxCNC Python 图形界面程序为参考基础，复用当前项目已经完成的 WASM、OPFS、virtual HAL、AXIS 风格 UI、G-code 执行仿真和 5 轴 source coverage 成果。
+
+边界必须清晰：
+
+- 这是 Web 数控系统仿真，不是硬实时机床控制器。
+- 浏览器不直接驱动真实伺服、IO 或 Linux kernel realtime ABI。
+- G-code 解释、canonical event、五轴运动学、remap 语义、tool/parameter 行为应尽量保持 LinuxCNC-owned。
+- JavaScript 只做 UI、会话、文件 staging、WASM 调用、状态编排和可视化映射。
+- 前端界面采用原生 HTML/CSS + TypeScript/JavaScript ES modules，不使用 React/Vue 等 UI 框架。
+- LinuxCNC Python GUI 是界面和仿真结构参考，不是浏览器 runtime 依赖；Web 侧不直接运行 Tk/OpenGLTk、PyQt、GTK/Glade 或 native HAL GUI 进程。
+
+## 2. 当前项目完成情况基线
+
+当前 `wasm-port` 已经具备以下可继承能力：
+
+- 浏览器真实仿真页面：`wasm-port/runtime/ui/simulation/index.html` 已实现 AXIS 风格界面、程序选择、编辑器、DRO、状态栏、Three.js 预览、播放控制和 browser smoke。
+- LinuxCNC 解释器 WASM：已有 `createLinuxCncInterpSdk()` 路径，可运行内置和用户输入的 G-code，并输出 LinuxCNC canonical 事件。
+- OPFS/session：已有 INI、参数文件、刀具表、G-code 程序、会话快照的浏览器侧持久化和加载工作流。
+- virtual HAL：已有仿真级 HAL pin/signal/param、halcmd 风格命令、motion feedback stepping 和浏览器状态展示。
+- 5 轴源码覆盖：已 vendored LinuxCNC `5axiskins.c`、`trtfuncs.c`、`xyzac-trt-kins.c`、`xyzbc-trt-kins.c`、`switchkins.*`、`userkfuncs.c` 等，且 source reuse 文档明确这些文件的验证边界。
+- 5 轴案例覆盖：已纳入 LinuxCNC `configs/sim/axis/vismach/5axis/bridgemill`、`table-dual-rotary`、`table-rotary-tilting` 的 INI/HAL/NGC/remap assets。
+- 当前 sim config inventory 基线：`executed=82`、`passed=82`、`skipped=77`、`unexpected_fail=0`；77 个 skipped row 已有实现覆盖账本，但不是全部 promotion。
+- 本地 LinuxCNC 源码中可参考 Python 图形界面：`src/emc/usr_intf/axis/scripts/axis.py`、`lib/python/vismach.py`、`configs/sim/axis/vismach/5axis/*`、`configs/sim/gmoccapy/*`、`configs/sim/qtvcp_screens/*`。
+
+未完成或不能直接宣称完成的点：
+
+- RTCP/TCP 五轴联动还没有作为独立 Web 产品能力完整闭环。
+- 当前浏览器页面主要是通用 AXIS 风格仿真，还不是专门的五轴/RTCP 操作界面。
+- TRT/bridge 五轴运动学虽然有 source coverage 和 probe 基础，但需要形成面向 UI 的统一五轴 pose/joint/TCP 数据模型。
+- Python remap、tool DB、external user-M process 等 hard block 仍不能伪装成浏览器 PASS。
+- Python GUI 的 native 控件、HAL component 进程、Tk/PyQt/GTK 主循环和 OpenGLTk 不能直接作为 Web 运行时使用，需要转换成 Web 组件、Three.js 场景和 virtual HAL 数据绑定。
+
+## 3. LinuxCNC 参考案例选择
+
+第一阶段建议聚焦 LinuxCNC 已有 5 轴 sample，不泛化到任意机型。
+
+优先参考案例：
+
+```text
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini
+configs/sim/axis/vismach/5axis/bridgemill/5axis.ini
+configs/sim/axis/vismach/5axis/table-dual-rotary/xyzab-tdr.ini
+```
+
+优先参考源码：
+
+```text
+src/emc/kinematics/trtfuncs.c
+src/emc/kinematics/xyzac-trt-kins.c
+src/emc/kinematics/xyzbc-trt-kins.c
+src/emc/kinematics/5axiskins.c
+src/emc/kinematics/switchkins.c
+src/emc/kinematics/switchkins.h
+src/emc/kinematics/userkfuncs.c
+src/emc/kinematics/kins_util.c
+```
+
+关键 LinuxCNC 机制：
+
+- `M428`：切换到 TCP/RTCP 相关五轴运动学模式，示例中设置 `motion.switchkins-type=1`。
+- `M429`：恢复 identity/trivkins 模式，示例中设置 `motion.switchkins-type=0`。
+- `M430`：切换到 user kinematics，作为后续扩展，不作为第一阶段必做。
+- `HAL_PIN_VARS=1`：remap 子程序通过 `_hal[motion.switchkins-type]` 读取 HAL 状态。
+- `M68`/`M66`：设置 analog output 并同步 HAL 状态。
+- TRT 参数：`x-rot-point`、`y-rot-point`、`z-rot-point`、`x/y/z-offset`、`tool-offset`、`conventional-directions`。
+
+## 4. Python 图形界面参考范围
+
+LinuxCNC 的五轴仿真界面大量使用 Python 图形界面程序和 XML/HAL 配置组合。Web 项目应参考这些界面形态，但不把 Python GUI 作为浏览器依赖。
+
+优先参考对象：
+
+```text
+src/emc/usr_intf/axis/scripts/axis.py
+lib/python/vismach.py
+configs/sim/axis/vismach/5axis/bridgemill/5axis.xml
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.xml
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.xml
+configs/sim/axis/vismach/5axis/table-dual-rotary/xyzab-tdr.xml
+configs/sim/axis/vismach/5axis/*/*postgui.hal
+configs/sim/gmoccapy/gmoccapy_XYZAC.ini
+configs/sim/qtvcp_screens/qtdragon/*
+```
+
+可借鉴的界面能力：
+
+- AXIS 的菜单、工具栏、Manual/MDI、预览、DRO、G-code 高亮、状态栏。
+- vismach 的层级机床模型：`Translate`、`Rotate`、`HalTranslate`、`HalRotate`，通过 HAL pin 驱动几何体姿态。
+- PyVCP XML 的 `SWITCHKINS` 多状态标签、`TCP:XYZAC`/`IDENTITY`/`USERK` 按钮、joint 数值显示和 `vismach-clear` 操作。
+- gmoccapy 的操作员面板、jog increment、override、嵌入式右侧面板和多轴配置。
+- QtVCP/QtDragon 的现代面板布局、探测/刀具/状态区和大屏操作方式。
+- LinuxCNC 文档中已有实际界面截图，可先用 `docs/linuxcnc-gui-reference-gallery.md` 中的图册做界面选型。
+
+Web 转换规则：
+
+```text
+Python Tk/OpenGLTk/PyQt/GTK 控件 -> Web components
+vismach OpenGL scene graph -> Three.js scene graph
+HAL pin widget binding -> virtual HAL subscription/render binding
+PyVCP XML controls -> declarative Web panel schema
+AXIS/gmoccapy workflow -> browser operator workflow
+native GUI process -> no direct browser dependency
+```
+
+前端实现规则：
+
+```text
+HTML/CSS: 页面结构、布局、主题、响应式约束
+TypeScript/JavaScript ES modules: UI 控件、状态订阅、WASM/OPFS 调用、事件编排
+Three.js: 五轴机床和刀路 3D 预览
+Web Worker: LinuxCNC interpreter/kinematics WASM 计算隔离
+Vite/esbuild: 只做开发服务器、TypeScript 编译和模块打包
+```
+
+禁止引入 React/Vue 等框架作为默认 UI 架构，避免把 CNC runtime 状态包进框架生命周期，增加调试和验证复杂度。
+
+## 5. 总体架构
+
+建议独立项目采用四层架构。
+
+### 5.1 Web UI 层
+
+职责：
+
+- 五轴数控系统主界面；
+- 程序编辑/加载/保存；
+- 机床配置选择；
+- RTCP 开关状态、kins 类型、刀具长度、旋转中心、A/B/C 角度展示；
+- DRO、关节坐标、工件坐标、TCP 坐标、距离到达、运行状态；
+- 三维机床模型、刀具姿态、刀尖中心点轨迹、已执行轨迹与完整轨迹；
+- 报警、边界、未支持功能提示。
+
+界面首选按 `gmoccapy_5_axis.png` 的工业操作台风格实现，并同时吸收 vismach/PyVCP/QtVCP 的界面结构。新项目界面要更偏向“五轴联动仿真工作台”：
+
+```text
+顶部：gmoccapy 风格标题栏，显示 machine/profile/session/run state
+左侧：黑底 Three.js 五轴机床和 TCP 刀路预览
+右上：大号绿色 DRO，显示 X/Y/Z/A/B/C、TCP、RTCP、DTG
+中右：G-code 当前行列表和运行进度
+右侧：竖向模式按钮栏，参考 gmoccapy 大按钮
+中下：tool info / G-code properties / RTCP diagnostics tabs
+下方：velocity、rapid/feed override、coolant、spindle 面板
+底部：open、reload、run、stop、pause、step、home、fullscreen
+```
+
+额外要求：
+
+- 左侧或右侧保留 PyVCP 风格的 `SWITCHKINS` 面板，清楚显示 `IDENTITY`、`TCP:XYZAC`、`TCP:XYZBC`、`USERK`。
+- DRO 同时显示 axis pose、joint pose、TCP pose，不把关节坐标和工件坐标混在一起。
+- Three.js 机床模型按 vismach 层级构建，所有旋转/平移节点都能追溯到 HAL pin 或 kinematics frame。
+- 操作按钮参考 AXIS/gmoccapy 的 F1/F2/home/jog/run/step/stop/reset 逻辑，但只触发仿真 runtime。
+
+### 5.2 Web Runtime/Session 层
+
+职责：
+
+- OPFS 会话管理；
+- INI、HAL、tool table、parameter、G-code 文件 staging；
+- 运行模式管理：standalone、machine-session、5axis-rtcp-session；
+- program run summary；
+- status/event history；
+- diagnostics artifact。
+
+已有 `runtime/opfs` 能作为参考，但新目录后续应建立独立命名空间，避免直接把原页面做成越来越大的单文件。
+
+### 5.3 LinuxCNC WASM/Source Boundary 层
+
+职责：
+
+- 调用 LinuxCNC 解释器 WASM；
+- 调用 LinuxCNC 五轴运动学 C/WASM ABI；
+- 提供 `forwardKinematics()`、`inverseKinematics()`、`switchKinsType()` 这类窄接口；
+- 捕获 canonical events、modal state、named parameters、tool offsets；
+- 输出 source-derived motion frames。
+
+关键要求：
+
+```text
+RTCP/五轴姿态计算必须优先由 vendored LinuxCNC kinematics 源码编译到 WASM 暴露；
+JavaScript 不直接复写 trtfuncs.c / 5axiskins.c 的公式作为最终语义源。
+```
+
+### 5.4 Visualization/Playback 层
+
+职责：
+
+- 将 LinuxCNC 输出的 motion frame 映射为 Three.js 对象；
+- 插值播放已验证 motion events；
+- 显示 TCP 点、刀轴向量、刀具长度补偿、旋转中心、工作台/主轴姿态；
+- 区分 programmed path、joint path、TCP executed path；
+- 显示 RTCP on/off 对比。
+- 用 Three.js 重建 vismach 的机床树，不直接移植 Python OpenGLTk 绘制代码。
+- 支持显示 PyVCP/vismach 示例中的旋转中心、偏置点、真实旋转点、刀具长度和关节反馈。
+
+注意：插值只用于显示，不能成为新的运动规划器。
+
+## 6. RTCP 功能实现定义
+
+本项目中的 RTCP 功能定义为仿真级 RTCP/TCP 能力：
+
+- 读取或配置五轴机床类型：XYZAC、XYZBC、XYZBCW、XYZAB 等；
+- 能识别 `M428/M429` 或 UI 切换产生的 kinstype 状态；
+- 在 RTCP 模式下，以刀尖中心点为显示核心，展示旋转轴变化时 TCP 位置保持或按程序轨迹运动；
+- 同时展示关节坐标和笛卡尔/TCP 坐标；
+- 支持刀具长度、旋转中心、偏置参数改变后重新计算预览；
+- 以 LinuxCNC forward/inverse kinematics 结果作为验算基础；
+- 浏览器 smoke 能证明同一段 5 轴程序在 RTCP 模式下产生非空 A/B/C 姿态和 TCP 轨迹。
+
+第一阶段不承诺：
+
+- 真实伺服周期硬实时；
+- 完整 LinuxCNC task/motion 进程；
+- 任意 Python remap runtime；
+- 任意 external user-M process；
+- 完整工业级碰撞检测；
+- CAM 后处理器。
+
+## 7. 数据模型
+
+建议定义统一 frame：
+
+```text
+FiveAxisMotionFrame
+  sequence
+  sourceLine
+  time
+  kinsType
+  rtcpEnabled
+  workPose: X/Y/Z/A/B/C/U/V/W
+  jointPose: joint[0..N]
+  tcpPose: x/y/z + toolAxisVector
+  toolOffset
+  pivot/rotPoint
+  feed
+  spindle
+  canonicalEventRef
+  diagnostics
+```
+
+建议定义 machine profile：
+
+```text
+FiveAxisMachineProfile
+  id
+  title
+  family: xyzac-trt | xyzbc-trt | bridge-xyzbcw | tdr-xyzab
+  iniPath
+  coordinates
+  joints
+  kinematicsSource
+  halPins
+  remapCodes
+  limits
+  toolTable
+  samplePrograms
+  pythonGuiReferences
+  pyvcpControls
+  vismachModelNodes
+```
+
+## 8. 阶段计划
+
+### Phase 0：方案和边界文档
+
+当前交付。
+
+输出：
+
+- 独立目录；
+- 实现方案；
+- 技术路线；
+- 明确当前完成情况和未完成边界。
+
+### Phase 1：独立 Web 仿真骨架
+
+目标：
+
+- 新建独立 Web app；
+- 复用或引入现有 SDK/WASM 产物；
+- 页面能加载、选择五轴机床、显示 G-code、运行普通 LinuxCNC-backed 程序；
+- Three.js 显示一个基础五轴机床模型和非空刀路。
+- UI 布局参考 AXIS/gmoccapy，包含菜单、工具栏、Manual/MDI、预览、DRO、G-code、状态栏。
+
+验收：
+
+- 本地 dev server 可启动；
+- browser smoke 截图非空；
+- 运行现有线性/圆弧/G81 程序不回退。
+
+### Phase 2：五轴 profile 和 5 轴 demo 接入
+
+目标：
+
+- 接入 `xyzac-trt`、`xyzbc-trt` 两个 profile；
+- staging 对应 INI/HAL/tool table/remap_subs/demo；
+- UI 能显示 kinematics 参数、HAL pins、M428/M429 状态；
+- 执行 LinuxCNC 5 轴 sample 或经过裁剪的 representative demo。
+- 解析 PyVCP XML/HAL 参考，生成 `SWITCHKINS`、joint value、offset/rot-point 等 Web 面板。
+
+验收：
+
+- 能展示 A/C 或 B/C 角度；
+- 能显示 kinstype 0/1 切换；
+- browser smoke 验证 `motion.switchkins-type` 状态。
+
+### Phase 3：LinuxCNC 五轴运动学 WASM ABI
+
+目标：
+
+- 将 `trtfuncs.c`、`xyzac-trt-kins.c`、`xyzbc-trt-kins.c`、`5axiskins.c` 的 forward/inverse 调用通过窄 C ABI 暴露给 Web runtime；
+- 建立 HAL pin shim，为旋转中心、偏置、刀具长度提供输入；
+- 输出 joint/work/TCP frame。
+
+验收：
+
+- Node smoke：forward -> inverse roundtrip；
+- browser smoke：同一 frame 显示 joint pose、work pose、TCP pose；
+- source sync guard 仍通过。
+
+### Phase 4：RTCP/TCP 预览与播放
+
+目标：
+
+- RTCP mode on/off 可视化；
+- 显示 programmed path、TCP path、joint path；
+- 刀轴方向随 A/B/C 变化；
+- 刀尖中心点轨迹与 LinuxCNC kinematics frame 对齐。
+- Three.js 机床层级与 vismach Python 示例的几何层级一致：工作台、转台、摆头、主轴、刀具和工件分别建模。
+
+验收：
+
+- RTCP 开启时，旋转轴变化不导致 UI 随机漂移；
+- 对 `M428/M429` 状态有明确显示；
+- 截图 smoke 校验 canvas 非空、刀具姿态非默认、路径点数非零。
+
+### Phase 5：操作级数控系统仿真
+
+目标：
+
+- Manual/MDI、单段、连续、暂停、复位；
+- 程序行高亮、motion segment 高亮；
+- 坐标系、刀具长度、旋转中心参数编辑和重新仿真；
+- OPFS 保存/恢复完整 5 轴会话。
+
+验收：
+
+- 保存 -> 恢复 -> 重新运行结果一致；
+- UI 提供 operator-facing 状态，不只是 diagnostics dashboard。
+
+### Phase 6：扩展验证和发布
+
+目标：
+
+- 建立 release gate；
+- 建立 regression fixtures；
+- 添加更多 LinuxCNC 5 轴案例；
+- 文档化不支持范围。
+
+验收：
+
+- `git diff --check`；
+- source/vendor sync；
+- Node/browser smoke；
+- screenshot/canvas-pixel check；
+- release readiness artifact。
+
+## 9. 风险与处理
+
+主要风险：
+
+- 把 RTCP 公式写在 JS 中，破坏 LinuxCNC semantic boundary。
+- 5 轴 demo 依赖 remap/HAL 同步，直接跑全量程序可能遇到 runtime boundary。
+- Vismach Python GUI 不能直接迁移到浏览器。
+- 把 Python GUI 参考误解成要在浏览器中运行 Python/Tk/PyQt，会导致架构失控。
+- WebGL 3D 和 G-code 执行状态容易脱节。
+- 过早承诺完整工业 RTCP 会扩大范围。
+
+处理策略：
+
+- 第一阶段只做 source-derived kinematics ABI，不做 JS-owned CNC semantics。
+- demo 程序分 representative subset 和 full upstream demo 两级。
+- Vismach 只作为机床结构参考，浏览器用 Three.js 重建可视化，不移植 Python GUI。
+- PyVCP/gmoccapy/QtVCP 只作为 panel schema 和 operator workflow 参考，控件用 Web 原生实现。
+- 所有 UI frame 都要带 canonical/ref 或 kinematics/ref 追踪字段。
+- hard block 保持显式 blocked，不因为 UI 能显示就 promotion。
+
+## 10. 结论
+
+当前项目已经具备 Web 数控系统仿真的基础设施，但 RTCP 五轴联动还需要单独产品化。下一步应在独立目录中先搭建五轴 Web 仿真骨架，界面形态参考 LinuxCNC 的 AXIS、vismach、PyVCP、gmoccapy 和 QtVCP Python 图形界面，再把 LinuxCNC TRT/bridge 五轴运动学通过 WASM ABI 接入，最后形成 RTCP/TCP 轨迹、关节姿态、刀尖中心点和机床模型同步显示的浏览器仿真界面。