linuxcncWebWASM/doc-g/gmoccapy-analysis.md

GMOCCAPY 分析与加载测试

更新时间：2026-08-25

结论

“没有看到加载程序按钮”不是按钮缺失，而是首次启动提示和 GMOCCAPY 的模式门控共同造成的视觉结果：

1. 首次启动会弹出模态的 Important change(s) 窗口。该窗口覆盖主界面并阻止底层点击；用户截图中的右侧 X 是关闭按钮，底部复选框是 Don't show this again。
2. 加载按钮只属于 AUTO 页面按钮组，不属于 MANUAL/JOG 页面。源码将它声明为 btn_load，提示为 Load a new program，图标为 img_open。
3. AUTO 模式还受机器状态和 homing 门控。gmoccapy.py 在未满足状态时会禁用 rbt_auto，并提示 It is not possible to change to Auto Mode at the moment。
4. 关闭首次提示、进入 AUTO 后，点击文件夹/打开文件图标会进入文件选择页。当前 gmoccapy.ini 的 PROGRAM_PREFIX = ../../nc_files/ 解析到 linuxcnc/nc_files。

用户截图分析

用户提供的图片尺寸为 697 x 837，内容是 GMOCCAPY 3.5.x 的版本变更提示：

• LinuxCNC 2.10/GMOCCAPY 3.5.0 不再在换刀后自动保留 G43；需要通过 REMAP 实现自动重新激活。
• 3.5.1 的工具表和偏置页默认使用计算器输入，可在设置或按钮中改变。
• MDI 和 G-code 编辑模式新增调用计算器的按钮。
• release notes 是橙色链接；右下方复选框用于永久隐藏该提示。

这张提示不是文件选择器，也不是加载失败信息。应先关闭它，再操作主界面。

新截图的源码逐项对照

这张截图与前一张内容一致，尺寸为 697 x 837，SHA-256 为 df7322c30bcb6af131591a04b11cad24e7b6d186beaff83059fcfd8ffbae2d1b。截图中的每一块文字都能在当前系统安装的 /usr/bin/gmoccapy 中找到：

截图区域	源码证据	含义
Important change(s) 标题	/usr/bin/gmoccapy:557-560	_startup_message() 建立启动提示标题；注释要求新增消息只能追加，不能删除旧消息，否则隐藏索引会错位。
3.5.0 G43 提示	/usr/bin/gmoccapy:561-563	GMOCCAPY 3.5.0 不再承诺换刀后自动保留 G43；想自动恢复必须使用 REMAP，示例在 GMOCCAPY 仿真配置中。
3.5.1 计算器提示	/usr/bin/gmoccapy:564-565	工具表和偏置页默认启用计算器输入；设置或页面按钮可以关闭；MDI 和 G-code 编辑页也增加了计算器按钮。
release notes 链接	/usr/bin/gmoccapy:570-573	以 Pango markup 拼接 LinuxCNC 官方 release notes URL，并通过通知组件显示。点击它会打开文档，不会关闭提示。
Don't show this again	notification.py:151-155	show_checkbox=True 时创建 GTK CheckButton；它不是普通说明文字，而是真正影响后续启动行为的复选框。
右侧 X	notification.py:156-164	创建名为 notification_close 的 48x48 关闭按钮；点击后删除该消息，并把复选框状态发回 GMOCCAPY。

弹窗什么时候出现

系统运行时在 GUI 初始化和周期任务准备完成后，于 /usr/bin/gmoccapy:519 调用 _startup_message()。它读取偏好项 hide_startup_messsage（注意源码中确实有三个 s 的拼写）：

hide_message = self.prefs.getpref("hide_startup_messsage", 0, int)
if hide_message < len(messages):
    ...
    self.notification.add_message(message, INFO_ICON, show_checkbox=True)

当前消息数组有两项，因此默认值 0 会显示两项。关闭时如果复选框被勾选，/usr/bin/gmoccapy:6241-6242 将 self.num（当前为 2）写回 hide_startup_messsage。下次启动判断 2 < 2 为假，提示不再出现。普通点击 X 不勾选复选框时，只删除本次通知，下次仍会显示。

版本边界：截图运行时与仓库锁定源不同

这是本次分析中最重要的来源边界：

• 截图对应的实际运行程序是 /usr/bin/gmoccapy，其中 _RELEASE = "3.5.2"，并包含 _startup_message()、3.5.0/3.5.1 文本和隐藏偏好逻辑。
• 仓库锁定源是 linuxcnc/VERSION = 2.10.0~pre0；linuxcnc/src/emc/usr_intf/gmoccapy/gmoccapy.py:79 的版本为 3.4.3，该文件没有 _startup_message() 实现，也没有截图中的 3.5.0/3.5.1 文本。
• 本地启动日志曾显示 LinuxCNC 2.10.0~pre1 和 gmoccapy 3.5.2，与截图完全一致。因此这张截图是系统安装包的运行时证据，不应反向宣称锁定仓库 2.10.0~pre0/3.4.3 源码已经包含该功能。

已记录的运行时文件哈希：

/usr/bin/gmoccapy                         11e7aee9216d24e4cc41018306f2541845bca9a9d6e16c38580f3ede9cca8d4d
/usr/share/gmoccapy/gmoccapy.glade       5fdc1557b02a716d30414fe739614fcd7c1d14cbe2e0a4c202c567a60b460adb
/usr/lib/python3/dist-packages/gmoccapy/notification.py
                                           e0317fea738745f480c79d1f690bc52e88cc7f81bb4d14fa09c8c7196afb4e2f

用户应如何处理

1. 只想本次继续操作：点击右侧 X，不要勾选复选框。
2. 不想以后重复看到：先勾选 Don't show this again，再点击 X。
3. 想查看变更依据：点击 release notes，但这需要浏览器/网络或本地文档可用。
4. 使用 G43 的程序：不要仅依赖界面自动行为；在 AUTO 程序中按机床配置和 REMAP 约定明确处理刀具长度补偿，并在正式加工前验证工具表和偏置。

实际界面证据

未加载状态

主界面顶部显示 No Program loaded。右侧竖向按钮中第三个为 AUTO 模式图标；在 MANUAL 页面时，AUTO 页面里的 Load a new program 不会显示在当前按钮组。

文件选择页

这张截图是实际运行 GMOCCAPY 后进入的文件选择页。页面显示 gcmc_lib、macros、ngcgui_lib 等目录以及 3D_Chips.ngc、3dtest.ngc 等程序。底部右侧绿色对勾是确认选择，右下黄色回退箭头是返回。

进入这张页面的完整点击链是：

1. 关闭首次 Important change(s) 模态提示。
2. 在主界面右侧点击第三个模式图标，进入 AUTO；源码控件为 rbt_auto。
3. 等待 AUTO 按钮组出现，在其中点击打开文件图标；源码控件为 btn_load，tooltip 为 Load a new program。
4. on_btn_load_clicked() 将按钮页切换到文件选择页；此时才会看到本截图中的文件网格。
5. 选中 .ngc 文件后点击底部绿色对勾，源码控件为 btn_select。

因此，文件网格不是主界面的固定按钮，也不是 MDI 入口；在 MANUAL/JOG 页面直接寻找它不会找到。

加载后的程序

通过 LinuxCNC 的 command.program_open() 加载：

/home/mes006/linuxcncWebWASM/linuxcnc/nc_files/3dtest.ngc

加载成功的证据是：

• 顶部由 No Program loaded 变成完整程序路径；
• 预览区出现 G-code 刀具轨迹；
• linuxcnc.stat().file 返回上述路径；
• interp_state 保持空闲，加载本身不会自动运行程序。

源码与界面映射

层	文件/符号	结论
主逻辑	linuxcnc/src/emc/usr_intf/gmoccapy/gmoccapy.py	on_btn_load_clicked() 切到文件选择页；on_IconFileSelection1_selected() 调用 hal_action_open.load_file(path)。
加载按钮	btn_load / img_open	tooltip 是 Load a new program，只在 AUTO 按钮页 hbtb_auto。
运行按钮	btn_run / img_run	tooltip 是 Run the loaded program；加载后仍需手动运行。
文件确认	btn_select / img_select	tooltip 是 select the highlighted file and return the path。
返回	btn_back_file_load / img_back_file_load	关闭文件选择页但不返回路径。
文件资源	linuxcnc/lib/python/gladevcp/iconview.py 及 GMOCCAPY 初始化	读取 PROGRAM_PREFIX，按配置扩展名展示文件和目录。
首次提示	GMOCCAPY preferences/release-notes 逻辑	模态提示优先于主界面，必须先关闭。

配置与资源分析

默认配置为 linuxcnc/configs/sim/gmoccapy/gmoccapy.ini：

• [DISPLAY] DISPLAY = gmoccapy：选择 GMOCCAPY GUI。
• [DISPLAY] PROGRAM_PREFIX = ../../nc_files/：从配置目录解析到 linuxcnc/nc_files。
• [RS274NGC] PARAMETER_FILE = sim.var：仿真参数文件。
• [RS274NGC] SUBROUTINE_PATH = macros：宏和子程序搜索路径。
• [EMCIO] TOOL_TABLE = tool.tbl：工具表。
• [HAL] 加载 core_sim.hal、spindle_sim.hal、simulated_home.hal，并在 GUI 启动后加载 gmoccapy_postgui.hal。

configs/sim/gmoccapy 不是单一案例，而是一组配置族，包含标准三轴、四轴、XYZAB/XYZAC/XYZCW、多轴、侧面板、消息、工具传感器、用户页、等离子和车床配置。完整逐文件路径与哈希见 文件清单。

运行环境与限制

• 启动入口：../run-gmoccapy.sh，默认执行 gmoccapy.ini。
• 实际 GUI 进程：/usr/bin/python3 /usr/bin/gmoccapy -ini .../gmoccapy.ini。
• 当前环境没有实时内核，LinuxCNC 日志明确回退到 POSIX non-realtime；这不影响本次“加载和预览”验证，但不等同于实时硬件运行验证。
• simulated_home.hal 的共享 home switch 在本次手动尝试中报告 Cannot home while shared home switch is closed j=2，因此 AUTO 模式按钮可能保持禁用。加载程序本身仍可通过 GUI 文件页/API 验证。
• 加载和运行是两个动作：program_open 只读入程序并生成预览；需要 AUTO 页面中的 Run 按钮或 R 快捷键才会执行。

推荐操作顺序

1. 启动 ./run-gmoccapy.sh。
2. 关闭首次 Important change(s) 提示；可勾选 Don't show this again。
3. 确认急停复位、机器上电，并按配置完成 homing；否则 AUTO 可能被门控。
4. 点击右侧 AUTO 图标，进入 AUTO 按钮页。
5. 点击带打开文件/文件夹图标的 Load a new program。
6. 选择 linuxcnc/nc_files 下的 .ngc 文件，点击底部绿色对勾。
7. 检查顶部路径和预览轨迹，再使用 Run；不要把加载误认为已经执行。

证据文件

• gmoccapy-important-changes.png：用户原始提示截图。
• gmoccapy-before-load.png：未加载程序。
• gmoccapy-after-popup-close.png：关闭提示后的主界面。
• gmoccapy-load-file-page.png：实际文件选择页。
• gmoccapy-program-loaded.png：加载后的程序和轨迹。
• gmoccapy-file-inventory.json：逐文件 SHA-256 清单。