wangdequan/cnc_wams
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
45b0f9bcf888224ff9de4c21733f29fa00c65aaa
cnc_wams/web-rtcp-5axis-sim-plan/docs/implementation-plan.md
wangdequan 626bcfe8e3 继续完成 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

16 KiB
Raw Blame History

基于 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，不泛化到任意机型。

优先参考案例：

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

优先参考源码：

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 作为浏览器依赖。

优先参考对象：

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 转换规则：

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

前端实现规则：

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 的界面结构。新项目界面要更偏向“五轴联动仿真工作台”：

顶部：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。

关键要求：

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：

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：

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 轨迹、关节姿态、刀尖中心点和机床模型同步显示的浏览器仿真界面。

Reference in New Issue View Git Blame Copy Permalink