# 基于 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、任意 external user-M host process、host tool DB process 等 hard block 仍不能伪装成浏览器 PASS；`tool.tbl` 和白名单 user-M 只允许在 `web_simulation_only` 边界内仿真。
- 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 host process；
- 任意未在白名单内的 user-M 行为；
- 完整工业级碰撞检测；
- 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 轨迹、关节姿态、刀尖中心点和机床模型同步显示的浏览器仿真界面。