# RTCP 五轴 Web 仿真技术路线

生成时间：2026-06-20 CST

## 1. 技术选型

推荐技术栈：

```text
UI: 原生 HTML + CSS + TypeScript/JavaScript ES modules
Build: Vite 或 esbuild，仅作为 TypeScript/ES module 打包工具，不引入 React/Vue 等 UI 框架
3D: Three.js
WASM: Emscripten
Core CNC reference: vendored LinuxCNC source
GUI reference: LinuxCNC Python GUI sources, PyVCP XML, HAL postgui wiring
Storage: OPFS
Tests: Node smoke + Playwright/Chromium browser smoke
Docs/gates: Markdown + machine-readable JSON/TSV artifacts
```

前端界面不使用 React、Vue、Angular、Svelte 等 UI 框架。原因是本项目核心复杂度在 LinuxCNC/WASM、五轴运动学、RTCP 数据流、Three.js 机床模型和验证链路，不在通用 UI 框架。直接使用 HTML/CSS + TypeScript/JavaScript ES modules 更贴近当前 `wasm-port/runtime/ui/simulation` 的实现方式，也更容易保持 WASM、OPFS、virtual HAL 和 Three.js 的边界清晰。

不使用框架不等于写成单个巨大脚本。必须按模块拆分 `ui/`、`runtime/`、`visualization/`、`profiles/`、`panel-schema/`、`workers/`、`state/`。LinuxCNC 的 Python GUI 只作为参考输入：AXIS 的操作界面、vismach 的机床模型层级、PyVCP XML 面板、gmoccapy/QtVCP 的操作面板都需要转换成 Web 组件和 Three.js 场景。

## 2. 目录建议

后续实现可在本目录扩展为：

```text
web-rtcp-5axis-sim-plan/
  README.md
  docs/
    implementation-plan.md
    technical-roadmap.md
    linuxcnc-python-gui-reference.md
    linuxcnc-gui-reference-gallery.md
    linuxcnc-reference-map.md
    rtcp-data-contract.md
    validation-plan.md
  app/
    index.html
    package.json
    src/
      main.ts
      ui/
      ui-reference/
      runtime/
      visualization/
      profiles/
      workers/
      panel-schema/
      state/
  core/
    linuxcnc_kinematics_wasm/
      include/
      src/
      build.sh
  tests/
    node/
    browser/
```

第一轮实现可以只创建 `app/`，后续再把 C/WASM ABI 放入 `core/`。

## 3. gmoccapy 5 轴风格 Web 实现方案

结论：`gmoccapy_5_axis.png` 的界面风格可以实现为 Web 前端，而且适合作为本项目第一版数控系统仿真界面的首选风格。

参考图：

![gmoccapy 5 Axis](../assets/reference/linuxcnc-gui/gmoccapy_5_axis.png)

原始来源：

```text
linuxcnc/docs/src/gui/images/gmoccapy_5_axis.png
```

### 3.1 可实现性判断

gmoccapy 5 轴界面由清晰的操作区域组成，适合直接拆成 Web 组件：

- 左侧大面积刀路/机床预览：可用 Three.js 实现。
- 右上大号绿色 DRO：可用 HTML/CSS 数字面板实现。
- 中右 G-code 当前行列表：可用虚拟滚动或普通 scroll list 实现。
- 右侧竖向模式按钮：可用原生 button + icon 实现。
- 下方信息面板：可用 tabs 和 table 实现。
- 中下 override、spindle、coolant 面板：可用 slider、stepper、toggle 实现。
- 底部运行控制：可用 icon button 实现。

这些控件不需要 React/Vue；原生 HTML/CSS + TypeScript/JavaScript ES modules 足够实现。核心状态由一个小型 runtime store 驱动，所有 CNC 语义仍来自 LinuxCNC/WASM/kinematics 边界。

### 3.2 页面布局

建议第一版按 gmoccapy 截图拆为固定操作台布局：

```text
┌──────────────────────────────────────────────────────────────────────┐
│ 顶部标题栏：machine/profile/session/run state                         │
├───────────────────────────────┬──────────────────────────────┬───────┤
│                               │ DRO + active G-code          │ 右侧   │
│ Three.js 五轴机床/刀路预览     │ X/Y/Z/A/B/C + G-code list     │ 模式栏 │
│                               │                              │       │
├───────────────────────────────┼──────────────────────────────┴───────┤
│ Tool info / G-code properties │ Velocity / Override / Spindle/Coolant │
├───────────────────────────────┴──────────────────────────────────────┤
│ 底部：open / reload / run / stop / pause / step / home / fullscreen    │
└──────────────────────────────────────────────────────────────────────┘
```

适配 Web 五轴 RTCP 后，右上 DRO 应扩展为：

```text
X Y Z A B C
Abs / Rel / DTG
TCP X/Y/Z
Tool axis vector
RTCP: on/off
Kins: identity / TCP / userk
```

### 3.3 Web 组件映射

建议模块：

```text
ui/gmoccapy-shell.ts
ui/gmoccapy-dro-panel.ts
ui/gmoccapy-preview-toolbar.ts
ui/gmoccapy-gcode-panel.ts
ui/gmoccapy-status-sidebar.ts
ui/gmoccapy-override-panel.ts
ui/gmoccapy-spindle-coolant-panel.ts
ui/gmoccapy-bottom-controls.ts
ui/gmoccapy-info-tabs.ts
```

组件职责：

- `gmoccapy-shell`：整体布局和区域挂载。
- `dro-panel`：大号绿色坐标显示，显示 axis/joint/TCP/DTG。
- `preview-toolbar`：视角、缩放、清除预览、适配窗口。
- `gcode-panel`：程序行、当前行、运行进度。
- `status-sidebar`：E-stop、machine on、manual/mdi/auto、settings、tool 等模式按钮。
- `override-panel`：current velocity、rapid override、feed override。
- `spindle-coolant-panel`：spindle rpm、spindle override、coolant state。
- `bottom-controls`：open、reload、run、stop、pause、step、home、fullscreen。
- `info-tabs`：tool info、G-code properties、RTCP diagnostics、session readiness。

### 3.4 状态模型

gmoccapy 风格页面需要一个小型 store，不需要前端框架：

```text
GmoccapySimulationState
  machineProfile
  sessionReadiness
  runState
  activeProgram
  activeLine
  dro
  jointPose
  tcpPose
  rtcpState
  kinsType
  feedOverride
  rapidOverride
  spindleOverride
  coolantState
  previewState
  diagnostics
```

状态更新路线：

```text
LinuxCNC/WASM canonical events
  -> frame builder
  -> GmoccapySimulationState
  -> DOM renderers + Three.js scene
```

### 3.5 样式原则

保持 gmoccapy 的工业操作台气质：

- 黑色 3D 预览背景。
- 大号绿色 DRO 数字。
- 灰色面板和分区边框。
- 橙色 override 进度条。
- 大尺寸图标按钮。
- 底部运行控制固定高度。
- 右侧模式栏固定宽度。

Web 版需要改进的点：

- 适配 1366x768、1920x1080 和平板尺寸。
- 字体和按钮要避免溢出。
- 3D 预览和 G-code 面板可以响应式分配宽度。
- RTCP/TCP 专用状态必须比原图更明确。

### 3.6 与 LinuxCNC 源码边界

可 Web 化：

- 页面布局。
- 操作按钮。
- DRO 显示。
- override/coolant/spindle 仿真状态。
- G-code 当前行高亮。
- Three.js 五轴预览。
- RTCP/TCP 状态展示。

必须仍由 LinuxCNC/WASM 或 source-derived runtime 提供：

- G-code 解释。
- canonical event。
- modal state。
- tool/parameter 语义。
- 五轴 kinematics。
- RTCP/TCP frame。
- M428/M429/M430 remap 状态。

不直接实现：

- gmoccapy native GTK/Glade runtime。
- LinuxCNC native task/motion IPC。
- 真实 HAL component process。
- Python remap runtime。
- 真实机床 IO。

### 3.7 第一版验收标准

第一版 gmoccapy 风格 Web 前端完成时，应满足：

- 页面整体布局与 `gmoccapy_5_axis.png` 对齐：预览、DRO、G-code、右侧模式栏、底部控制、override/spindle/coolant 区都存在。
- 使用原生 HTML/CSS + TypeScript/JavaScript ES modules，无 React/Vue 等框架。
- Three.js 预览非空，能显示五轴机床、刀具和路径。
- DRO 显示 X/Y/Z/A/B/C 和 TCP 坐标。
- G-code 面板能高亮当前行。
- Run/Stop/Pause/Step 控件能驱动仿真 playback。
- RTCP/TCP 和 kinstype 状态在界面中可见。
- Browser smoke 做截图和 canvas 非空验证。

## 4. 核心模块拆分

### 4.1 `profiles`

管理 LinuxCNC 五轴机型 profile：

- `xyzac-trt`
- `xyzbc-trt`
- `bridge-xyzbcw`
- `tdr-xyzab`

每个 profile 记录：

- LinuxCNC config source path；
- coordinates/joints；
- kinematics source files；
- HAL pins；
- M428/M429/M430 remap；
- sample programs；
- limits 和默认参数。
- Python GUI 参考文件；
- PyVCP/HAL panel 控件；
- vismach model node 映射。

### 4.2 `runtime`

管理运行状态：

- machine session；
- G-code staging；
- interpreter run；
- kinematics frame calculation；
- RTCP mode state；
- diagnostics。

建议 API：

```text
loadMachineProfile(profileId)
stageProgram(programText)
runProgram()
buildFiveAxisFrames(canonicalEvents, machineProfile)
setRtcpEnabled(enabled)
setKinsType(type)
updateMachineParameter(name, value)
exportSessionSnapshot()
restoreSessionSnapshot(snapshot)
```

### 4.3 `linuxcnc_kinematics_wasm`

提供窄 C ABI：

```text
linuxcnc_xyzac_trt_forward(input, output)
linuxcnc_xyzac_trt_inverse(input, output)
linuxcnc_xyzbc_trt_forward(input, output)
linuxcnc_xyzbc_trt_inverse(input, output)
linuxcnc_bridge_5axis_forward(input, output)
linuxcnc_bridge_5axis_inverse(input, output)
linuxcnc_set_hal_float(pin, value)
linuxcnc_set_hal_bit(pin, value)
linuxcnc_get_last_error()
```

输入输出应使用稳定结构，不让 UI 直接理解 LinuxCNC 内部全局状态。

### 4.4 `visualization`

Three.js 负责：

- 机床底座、工作台、转台、摆头、主轴、刀具；
- 坐标轴和工作空间；
- TCP path；
- joint path；
- active segment；
- tool axis vector；
- RTCP on/off overlay。

机床模型初期可以用几何体组合，不要先追求 CAD 级模型。重点是五轴姿态和 TCP 点正确、可验证。

vismach 转换规则：

- `Collection` -> Three.js `Group`；
- `Translate` / `Rotate` -> 静态 transform node；
- `HalTranslate` / `HalRotate` -> 绑定 virtual HAL pin 的动态 transform node；
- STL/workpiece asset -> glTF/STL loader 或简化几何体；
- vismach plot clear -> Web runtime 的 path clear action；
- HAL component pin -> profile 中声明的 observable runtime value。

### 4.5 `ui`

界面组件：

- machine profile selector；
- RTCP/kins panel；
- G-code editor；
- run controls；
- DRO；
- joint position panel；
- HAL/diagnostics；
- Three.js viewport；
- session save/restore。
- gmoccapy-style shell；
- gmoccapy-style DRO / override / spindle / coolant / status sidebar。

UI 参考转换：

- AXIS：菜单、工具栏、Manual/MDI、预览、DRO、G-code、状态栏。
- PyVCP：`SWITCHKINS`、joint 数值、offset/rot-point 控件、`vismach-clear`。
- gmoccapy：首选界面风格；大按钮操作、jog increment、override、右侧模式栏、底部运行控制、黑底预览和绿色 DRO。
- QtVCP/QtDragon：现代触控面板、状态区、工具/探测/大屏布局。

### 4.6 `panel-schema`

把 PyVCP XML 和 postgui HAL 的参考关系整理为 Web 面板 schema。

建议 schema：

```text
PanelControl
  id
  type: label | multilabel | button | number | slider | toggle
  halpin
  signal
  sourceFile
  command
  displayFormat
  readonly
```

第一阶段不需要完整 XML parser，可以先把 `xyzac-trt.xml`、`xyzbc-trt.xml`、`5axis.xml`、`xyzab-tdr.xml` 手工整理成 JSON/TS profile。后续再决定是否写 PyVCP XML importer。

## 5. LinuxCNC 源码接入路线

### Step 1：建立引用清单

形成 `linuxcnc-reference-map.md`，记录每个能力引用哪些 LinuxCNC 文件。

第一批：

```text
trtfuncs.c
xyzac-trt-kins.c
xyzbc-trt-kins.c
5axiskins.c
switchkins.c / switchkins.h
kins_util.c
kinematics.h
emcpose.h / emcpose.c
```

Python GUI / panel 第一批：

```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/bridgemill/5axisgui.hal
configs/sim/axis/vismach/5axis/bridgemill/5axis_postgui.hal
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-rotary-tilting/switchkins_postgui.hal
configs/sim/axis/vismach/5axis/table-dual-rotary/xyzab-tdr.xml
configs/sim/axis/vismach/5axis/table-dual-rotary/xyzab-tdr-postgui.hal
configs/sim/gmoccapy/gmoccapy_XYZAC.ini
configs/sim/qtvcp_screens/qtdragon/README
```

### Step 2：建立 C ABI shim

不要把 LinuxCNC HAL module lifecycle 原样暴露给浏览器。应构造最小 shim：

- 初始化 profile；
- 分配 HAL 参数存储；
- 设置 HAL pin 值；
- 调用 forward/inverse；
- 输出 frame。

### Step 3：编译 WASM

使用 Emscripten 编译 kinematics core。初期可与当前 `wasm-port` 构建脚本分离，等稳定后再合并。

### Step 4：Node 验证

至少验证：

- `xyzac` forward/inverse；
- `xyzbc` forward/inverse；
- tool offset 变化影响 TCP；
- rot point 变化影响结果；
- kinstype 0/1 切换状态；
- source file hash 与 vendor 一致。

### Step 5：Browser 验证

至少验证：

- WASM 在浏览器加载；
- Three.js canvas 非空；
- 五轴姿态非默认；
- RTCP 开关改变显示状态；
- 加载 sample program 后 path 点数非零。
- `SWITCHKINS` 面板能显示 `IDENTITY` / `TCP` / `USERK` 状态。
- joint value 面板与 five-axis frame 中的 joint pose 对齐。
- `vismach-clear` 类操作能清空预览路径，不改变 LinuxCNC semantic state。

### Step 6：Python GUI 参考验收

该步骤不是运行 Python GUI，而是证明 Web 界面已经吸收其关键设计：

- AXIS 区域齐全：toolbar、Manual/MDI、preview、DRO、G-code、statusbar。
- PyVCP 控件齐全：switchkins multilabel、type buttons、joint values、clear path。
- vismach 模型层级齐全：动态平移、动态旋转、工具、工作台、旋转点。
- gmoccapy/QtVCP 操作形态齐全：大按钮、override、jog increment、operator status。

## 6. RTCP 数据流

推荐数据流：

```text
LinuxCNC G-code text
  -> interpreter WASM
  -> canonical events / modal output
  -> five-axis frame builder
  -> LinuxCNC kinematics WASM forward/inverse
  -> FiveAxisMotionFrame[]
  -> Three.js visualization + DRO + status panels
```

`FiveAxisMotionFrame` 是 UI 的唯一运动数据输入。这样可以避免 UI 从多个地方拼状态导致错位。

## 7. 测试路线

### Node smoke

- profile inventory；
- source reference map；
- kinematics ABI；
- frame builder；
- OPFS/session pure helpers；
- no JS CNC semantics guard。

### Browser smoke

- 页面加载；
- profile 切换；
- sample program run；
- RTCP status；
- canvas pixel 非空；
- tool marker 移动；
- active G-code line；
- session save/restore。

### Visual regression

先做轻量检查：

- canvas 非空；
- tool marker 坐标在视口内；
- path bounding box 合理；
- A/B/C 非零时刀轴方向变化。

## 8. 里程碑

建议按以下顺序推进：

1. `M0-docs`：当前方案和技术路线。
2. `M1-web-shell`：独立 Web app、Three.js 空机床、普通 G-code 执行接通。
3. `M2-python-gui-reference-panels`：AXIS/PyVCP/vismach/gmoccapy/QtVCP 参考界面转换为 Web panel/schema。
4. `M3-profile-loader`：`xyzac-trt` / `xyzbc-trt` profile、INI/HAL/remap asset 可见。
5. `M4-kinematics-wasm`：LinuxCNC 五轴运动学 C/WASM ABI。
6. `M5-rtcp-preview`：RTCP/TCP path、joint/work/TCP 同步显示。
7. `M6-kinematics-frame-proof`：Web RTCP frame/boundary adapter 接入 `xyzac-trt` kinematics WASM Node proof。
8. `M7-browser-kinematics-runtime`：浏览器 asset copy/worker 加载 kinematics WASM。
9. `M8-session`：OPFS 保存/恢复五轴仿真会话。
10. `M9-release-gate`：Node/browser/docs/release gate。
11. `M10-profile-switching`：`xyzac-trt` / `xyzbc-trt` profile 切换并重载对应 kinematics WASM。

## 9. 验收标准

最小可验收版本：

- 浏览器中可以选择 `xyzac-trt`；
- 可以加载并运行一个 5 轴 sample 或 representative program；
- 可以看到 XYZAC 或 XYZBC 轴值；
- 可以切换或识别 RTCP/TCP 状态；
- Three.js 中显示机床、刀具姿态和 TCP 轨迹；
- UI 中有参考 PyVCP 的 `SWITCHKINS` 面板和 joint 数值区；
- Three.js 机床模型能体现 vismach Python 示例的动态层级；
- 结果来自 LinuxCNC interpreter + LinuxCNC kinematics WASM 边界；
- browser smoke 通过；
- 文档明确哪些功能 blocked。

## 10. 下一步动作

当前已完成到 `M11-profile-session-business-closure`。建议下一轮优先做：

- 把 interpreter WASM 调用迁移到 Worker，保持 UI 主线程只做渲染和状态编排；
- 接入 OPFS machine-session 的 INI/HAL/tool table staging，让 interpreter execution 使用真实会话文件；
- 继续推进 remap/planner 边界，不把普通 canonical execution 冒充完整 LinuxCNC task/motion runtime；
- 保持 source/browser/dist 三层 smoke：interpreter canonical frame、kinematics worker frame、DRO/preview 同步。
- 启动本地 dev server 给出访问地址。