# 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

参考文件：

```text
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 对应实现：

```text
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

参考文件：

```text
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 对应实现：

```text
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

参考文件：

```text
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 对应实现：

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

### gmoccapy

参考文件：

```text
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 对应实现：

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

### QtVCP / QtDragon

参考文件：

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

参考内容：

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

Web 对应实现：

```text
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 调用链。