wangdequan/cnc_wams

Fork 0

Files

wangdequan 3771b9eafe 接入 LinuxCNC TP 运行反馈

2026-06-21 23:29:56 +08:00

17 KiB

Raw Blame History

RTCP 五轴 Web 仿真技术路线

生成时间：2026-06-20 CST

1. 技术选型

推荐技术栈：

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. 目录建议

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

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 前端，而且适合作为本项目第一版数控系统仿真界面的首选风格。

参考图：

原始来源：

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 截图拆为固定操作台布局：

┌──────────────────────────────────────────────────────────────────────┐
│ 顶部标题栏：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 应扩展为：

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 组件映射

建议模块：

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，不需要前端框架：

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

状态更新路线：

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：

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：

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：

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 文件。

第一批：

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 第一批：

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 数据流

推荐数据流：

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. 里程碑

建议按以下顺序推进：

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

17 KiB Raw Blame History Unescape Escape