548 lines
17 KiB
Markdown
548 lines
17 KiB
Markdown
# 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 前端，而且适合作为本项目第一版数控系统仿真界面的首选风格。
|
||
|
||
参考图：
|
||
|
||
|
||
|
||
原始来源：
|
||
|
||
```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 给出访问地址。
|