cnc_wams/web-rtcp-5axis-sim-plan/docs/linuxcnc-python-gui-reference.md

LinuxCNC Python 图形界面参考

生成时间：2026-06-20 CST

1. 目的

本文件补充说明：五轴数控系统仿真界面的设计不仅参考 LinuxCNC 的 C/C++ 解释器、运动学和配置案例，也参考 LinuxCNC 使用 Python 编写的图形界面和机床仿真程序。

这些 Python GUI 是 Web 界面的产品和结构参考，不是 Web 运行时依赖。浏览器版本不直接运行 Tk、OpenGLTk、PyQt、GTK/Glade、native HAL component 或 Python GUI process。

2. 参考对象

AXIS

参考文件：

src/emc/usr_intf/axis/scripts/axis.py
share/axis/*
configs/sim/axis/*

参考内容：

• 菜单栏、工具栏、运行/暂停/单段/停止/复位。
• Manual、MDI、Preview、DRO、G-code 文本区。
• G-code 当前行高亮。
• OpenGL 刀路预览和视图控制。
• E-stop、machine on、homing、坐标模式、状态栏。

Web 对应实现：

AXIS main window -> 单页 Web operator workspace
AXIS toolbar -> Web icon toolbar
AXIS preview -> Three.js viewport
AXIS DRO -> Web DRO panel
AXIS G-code list -> Web editor/source pane

vismach

参考文件：

lib/python/vismach.py
configs/sim/axis/vismach/5axis/bridgemill/*
configs/sim/axis/vismach/5axis/table-dual-rotary/*
configs/sim/axis/vismach/5axis/table-rotary-tilting/*
configs/sim/axis/vismach/5axis/table-rotary_spindle-rotary-nutating/vismach/*.py

参考内容：

• 机床几何树。
• Translate、Rotate 静态变换。
• HalTranslate、HalRotate 基于 HAL pin 的动态变换。
• 工作台、转台、摆头、主轴、刀具、工件的层级关系。
• vismach-clear 清空轨迹。
• STL/几何体组合机床模型。

Web 对应实现：

vismach Collection -> Three.js Group
vismach Translate/Rotate -> Three.js transform node
vismach HalTranslate/HalRotate -> virtual HAL-bound transform node
vismach component pins -> profile-declared observable values
vismach OpenGLTk scene -> Three.js scene

PyVCP

参考文件：

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

参考内容：

• SWITCHKINS multilabel。
• IDENTITY、TCP:XYZAC、TCP:XYZBC、USERK 按钮。
• joint 数值显示。
• offset / rot-point 参数显示或调节。
• HAL pin 到 GUI 控件的绑定。

Web 对应实现：

PyVCP XML -> Web panel schema
halpin -> virtual HAL binding
multilabel -> segmented/status indicator
button -> command/action button
number -> read-only numeric DRO field

gmoccapy

参考文件：

configs/sim/gmoccapy/gmoccapy_XYZAC.ini
configs/sim/gmoccapy/gmoccapy_*.ini
configs/sim/gmoccapy/*.glade
configs/sim/gmoccapy/*postgui.hal

参考内容：

• 面向操作员的大按钮布局。
• jog increment、feed override、spindle override、rapid override。
• 右侧嵌入面板。
• 多轴配置和状态显示。

Web 对应实现：

gmoccapy operator panel -> compact touch-friendly control panel
gladevcp embedded tab -> Web side panel
override controls -> sliders/steppers
jog increment -> segmented controls

QtVCP / QtDragon

参考文件：

configs/sim/qtvcp_screens/*
configs/sim/qtvcp_screens/qtdragon/*
share/qtvcp/*

参考内容：

• 现代化 CNC 操作屏布局。
• 状态区、工具区、探测区、程序区。
• 大屏/触控操作方式。
• panel handler 和 widget 分层。

Web 对应实现：

QtVCP screen -> responsive Web layout
QtVCP widgets -> reusable Web components
handler state -> runtime store/actions

3. 五轴界面重点参考项

第一阶段必须吸收这些界面元素：

• SWITCHKINS 状态：显示当前 kinstype。
• M428/M429/M430 操作：切换 TCP/identity/userk 模式。
• joint values：至少显示 J0-J6 或当前 profile joints。
• axis pose：显示 X/Y/Z/A/B/C/W。
• TCP pose：显示刀尖中心点和刀轴方向。
• offset/rot-point：显示旋转点和几何偏置。
• tool offset：显示刀具长度补偿。
• preview clear：清空已执行轨迹。
• status bar：显示 E-stop、machine on、session、run mode、RTCP state。

4. 不移植内容

以下内容不直接移植到 Web runtime：

• Tkinter 主循环。
• rs274.OpenGLTk。
• PyQt/QTVCP native widget。
• GTK/Glade native UI。
• native hal.component() 进程。
• LinuxCNC GUI 与 task/motion 的 native IPC。
• Python remap runtime。

如果后续需要 Python runtime，只能作为单独受控 milestone，不得混入 UI 参考转换。

5. 验收方式

文档和实现需要用机器可验证方式证明参考关系：

• profile 中记录 Python GUI source references。
• panel schema 中记录 PyVCP XML 和 postgui HAL source path。
• browser smoke 检查 SWITCHKINS、joint values、DRO、preview、statusbar 存在。
• canvas smoke 检查 Three.js 机床模型非空。
• state smoke 检查 M428/M429 或 kinstype 切换能反映到 UI。

6. 结论

Web 五轴仿真界面应以 LinuxCNC Python GUI 为交互和可视化参考，以 LinuxCNC C/C++ 源码为 CNC 语义和运动学参考。Python GUI 提供“界面长什么样、机床模型如何组织、HAL 控件如何连接”的依据；浏览器实现负责把这些参考转换为 Web 组件、Three.js 场景、virtual HAL 绑定和 WASM 调用链。