GUI 组件

┌──────────────────────────────────────┐
│            Browser（主窗口）            │
├────────────────┬─────────────────────┤
│ FileSelector   │    QMdiArea          │
│ （实验文件树）    │   ExperimentWindow   │
│                │   （单实验控制窗口）    │
├────────────────┴─────────────────────┤
│  顶部停靠：实验队列 / 准备台 / 循环器      │
├──────────────────────────────────────┤
│       ExperimentManager（执行引擎）     │
└──────────────────────────────────────┘

1 - 实验浏览器

概述

quatm/GUI/browser/main_window.py 提供 实验浏览器（Browser）：Quatm 的主应用 窗口，基于 QMainWindow + QMdiArea 多文档界面。左侧文件选择器浏览实验脚本， 顶部停靠实验队列、准备台与循环器，中央 MDI 区内每个实验一个子窗口。

布局

┌─────────────┬───────────────────────────────┐
│ FileSelector │   QMdiArea（实验子窗口区）      │
│ （实验文件树） │   ┌─────────────────────┐   │
│             │   │  ExperimentWindow    │   │
├─────────────┤   └─────────────────────┘   │
│ 队列 / 准备台 │                               │
│ / 循环器停靠  │                               │
└─────────────┴───────────────────────────────┘

核心组件

上述组件的细节见本目录的对应页面。

生命周期

• init_ui / create_dock_widgets：按屏幕适配默认几何，创建 MDI 画布与两侧停靠 部件（左侧文件选择器；顶部队列/准备台/循环器）。
• open_experiment：打开实验窗口；已打开则从最小化恢复并置前。
• closeEvent：先保存主窗口几何与全部实验子窗口状态，再停止队列/循环等 worker 线程，最后交给基类完成关闭。
• moveEvent / resizeEvent：防抖保存几何，下次启动时恢复窗口位置与尺寸。

用法

from quatm.GUI.browser.main_window import Browser

browser = Browser()
browser.show()

实验浏览器是运行除 Helper 之外所有实验的界面，通常作为主进程由进程管理器启动。

2 - 实验管理器

概述

quatm/GUI/experiment/experiment_manager.py 提供实验管理器（ExperimentManager ）：从实验队列（ExperimentQueue）取出任务并执行的引擎。其队列轮询运行在 worker 线程，任务按 测量（measurement）→ 重复（repetition）→ 序列/扫描 （sequence）→ 单次运行（run） 的层级结构调度。

执行流程

queue_fn（worker 线程持续轮询队列）
  └─→ run（任务包装：任何结束方式都保证收尾）
       ├─→ start_measurement（测量开始钩子）
       ├─→ start_sequence（序列/扫描开始钩子）
       │     └─→ … 多次带变化参数的 run …
       ├─→ end_sequence（序列结束钩子）
       └─→ end_measurement（测量结束钩子并清理任务表）

关键方法

用法

from quatm.GUI.experiment.experiment_manager import ExperimentManager

manager = ExperimentManager(browser)   # browser 提供队列与界面
manager.start_queue()                  # 启动常驻队列 worker

任务在独立 worker 线程中执行，不阻塞 GUI；浏览器关闭时调用 shutdown 停止队列 worker 以便进程干净退出。

3 - 实验队列

概述

ExperimentQ（quatm/GUI/experiment/experiment_queue.py）是 实验浏览器（Browser） 主窗口里的「实验队列」面板：一个由队列表格模型 ScheduleModel（模块 quatm/GUI/widgets/models.py）驱动的任务表格。任务字典以 任务号 为主键存放， 每个任务是一条含运行所需信息的记录；表格按优先级 priority（数值小者优先）→ 任务号排序。

任务状态

实验管理器（ExperimentManager） 与面板共同维护每个任务的状态：

操作与快捷键

• 按钮栏（由 create_buttons 创建）：暂停/恢复、终止选中任务、终止全部等 图标按钮。
• 右键菜单与单键快捷键（init_table_actions）：e 编辑参数、v 只读预览、 删除、休眠/唤醒、暂停等。
• 删除正在运行的任务：自动转为优雅终止（delete_clicked）。
• 终止（terminate_clicked / terminate_all）：优雅停止，让正在进行的运行 先跑完再结束。

主要方法

数据模型

# 任务字典结构（主键 = 任务号）
expDict = {
    1: {
        "expName": "Rabi 扫描",
        "filepath": "experiments/ion/rabi.py",
        "status": "Queued",
        "priority": 1,
        "args": {},
        "due": "",
    },
}

排序规则：priority（数值小者优先）→ 任务号（先入先出）。

与循环器的关系

循环器（Looper） 的任务条目提交也统一经 ExperimentQ.submit() 入队，因此桌面 界面与循环调度共用同一条“集中分配任务号”的入队通道。

4 - 准备台

概述

PrepStation 是实验浏览器（Browser）顶部 dock 中的一个标签页，作为实验队列的 “暂存区”：把尚未准备就绪的任务先存放于此，确认无误后再推入 ExperimentQ 排队 执行。任务列表持久化在 configuration/browser/prepfile.json，并可在浏览器端 实验控制台（Web 远程控制）中查看与操作。

功能

任务数据结构

每个暂存任务与队列任务同构（由实验窗口 setup_task_dict() 生成）：

task = {
    'task': 12,                 # 任务编号
    'expName': 'Absorption',    # 实验名
    'label': 'scan: freq 2:1',  # 标签（含扫描前缀）
    'priority': 0,
    'args': {'count': 5},       # 实验参数
    'nRuns': 21,                # 扫描点数
    'scanpars': ['freq'],       # 扫描参数
    'scanvals': [[...]],        # 扫描值
    'scansequence': [...],      # 扫描顺序（随机化后）
    'nReps': 1,
    'status': 'Queued',         # Queued / Sleeping / Waiting
    'filepath': '.../absorption.py',
}

持久化与共享

• 任务列表保存在 configuration/browser/prepfile.json，浏览器重启后自动恢复；
• 桌面 GUI 与 Web 远程控制 平台共用 同一份文件， 任意一端暂存/推送/排序/休眠的任务在另一端立即可见。

5 - 循环器

概述

Looper（循环器）是实验浏览器（Browser）顶部 dock 的标签页 （quatm/GUI/looper/），管理实验任务组，按顺序执行组内条目，并根据测量结果决定 跳转或终止。循环定义持久化在 configuration/browser/looper/loopfile.json，与浏览器 端实验控制台（Web 远程控制）共用 同一份文件。

核心逻辑

LoopManager.run_loop()：从起始组开始，无限循环直到 terminate
  └─→ 按顺序执行组内条目
       ├─ Task：提交任务到实验队列，等待完成后推进
       │        （可设最大次数 / 最大连续次数，达到即终止循环）
       └─ Conditional：读取数据流字段 → 比较（> >= == != =< <）
                ├─ 满足 → 跳转到指定条目 / 组尾 / 结束循环
                └─ 不满足 → 跳转到 else 条目

组件

使用方式

在 实验浏览器（Browser） 中通过循环器（Looper）标签页交互操作：

1. 添加组：新建标签页（New Tab #N），可重命名；
2. 添加条目：每个组内可添加 Task / List / Conditional / ConditionalDateTime / ConditionalReached / Caller 等条目；
3. 配置条目：Task 选择暂存器任务编号并设置最大次数；Conditional 选择数据 字段、比较符与阈值，配置 if/else 跳转目标（条目序号 / end box / end loop）；
4. 运行：选择起始组，点击运行；LoopManager 在后台线程执行，终止按钮随时 停止。

# 核心类（GUI 内部使用）
from quatm.GUI.looper import Looper, LoopManager

looper = Looper(parent=browser)
looper.loopManager.run_loop()      # 从起始组开始循环
looper.loopManager.terminate()     # 终止循环

持久化与共享

• 循环定义自动保存到 configuration/browser/looper/loopfile.json （{组名: [条目字典, ...]}），浏览器重启后自动恢复；
• 桌面 GUI 与 Web 远程控制平台共用同一份文件，任意一端的修改另一端立即可见； 浏览器端同样支持组管理、Task/Conditional 条目编辑与循环启停。

6 - 实验窗口

概述

quatm/GUI/browser/experiment_window.py 提供 实验窗口（ExperimentWindow）： 每个实验脚本在浏览器 MDI 区对应一个由 ExperimentSubWindow 承载的控制窗口，按 实验声明的参数对象自动生成参数网格，负责提交队列/预备、扫描构建与 JSON 参数存取 。

组件

关键方法（ExperimentWindow）

用法

from quatm.GUI.browser.experiment_window import ExperimentWindow

# 通常由 Browser.open_experiment 打开；也可自行构造
win = ExperimentWindow(filepath=..., props=props, parent=subwindow, browser=browser)

实验脚本声明的参数对象（如 NumberValue / BoolValue / StringCombo）会自动生 成带标签、单位与范围的编辑控件；参数组可保存为 json 并在以后加载复用。

7 - 参数系统

概述

quatm/GUI/entries/dashboard.py 提供一套“参数管理器”控件体系：每个管理器 把一个实验参数（存于属性库，内部一律用 SI 单位）映射为一个带标签的输入控件，并 在界面与属性库之间双向同步。

控件类体系

BasicManager（数值类参数条目的基类）
├── IntManager        → 整数微调框
├── FloatManager      → 浮点微调框（可带单位/步进/小数位）
├── BoolManager       → 勾选框
├── ComboManager      → 下拉框（字符串列表）
└── FrequencyManager  → DDS 频率微调框（属性存 Hz，界面显示 MHz）

用法（示意）

from quatm.GUI.entries.dashboard import IntManager, FloatManager, BoolManager

# 每个管理器绑定属性库 props 与实验 exp，按参数名读写
mgr = IntManager(props=props, exp=exp, parname="my_int")
fmgr = FloatManager(props=props, exp=exp, parName="cooling_time", unit="µs")
bmgr = BoolManager(props=props, exp=exp, parName="enable")

界面改动会换算成 SI 写回属性库；属性库变化也会由各控件周期同步到界面显示 （updateValue / updateSpin）。

另见「实验参数面板」：Dashboard 主面板据此把整台设备的参数自动排布成 可调控制面板。

8 - 属性编辑器

概述

quatm/GUI/entries/property_editor.py 提供基于 parametertree 的属性 编辑工具：把属性库的键值树展示成可展开/可编辑的参数树，支持搜索过滤，修改即写回。

组件

用法

from quatm.GUI.entries.property_editor import PropEdit

editor = PropEdit(name="设备状态", props=props, subtree="/", parent=parent)

注：以 subtree 限定只展示某一路径下的属性；TreeEdit 负责把属性字典转换为 Parameter 节点树。

9 - 实时绘图

概述

quatm/GUI/entries/updating_plot.py 提供 实时绘图：UpdatingPlot 是 PlotItem 子类，订阅数据流后定时拉取新数据并刷新曲线；LivePlot 则 是内嵌一个 UpdatingPlot 的控件容器，方便作为停靠面板嵌入其它窗口。

组件

关键方法（UpdatingPlot）

用法

from quatm.GUI.entries.updating_plot import UpdatingPlot, LivePlot

plot = UpdatingPlot(name="PMT 信号")        # 直接作为绘图项使用
host = LivePlot(name="PMT 信号", parent=parent)  # 或作为容器嵌入界面

订阅在绘图项的右键菜单中完成；LivePlot 也用作图像查看器中行/列剖面图的容器。

10 - LED 指示灯

概述

LedIndicator（quatm/GUI/widgets/qled.py）是一个可选中切换亮/灭外观的 LED 指示按钮：双层圆形外壳加中心渐变，选中（亮）时用高亮配色，未选中（暗）时呈暗色。 常用于显示设备连接状态、实验运行状态与循环条目执行反馈。

颜色模式

亮/灭（勾选）状态可用 setChecked(True/False) 控制；onColor1/onColor2、 offColor1/offColor2 属性可自定义亮态与暗态的主/辅颜色。

用法

from quatm.GUI.widgets.qled import LedIndicator

led = LedIndicator(parent=parent)
led.set_green()      # 设备就绪
led.setChecked(True) # 点亮
# ...
led.set_red()        # 设备异常

11 - GUI 基础类

概述

quatm/GUI/widgets/quatmQt.py 定义了 Quatm 图形界面各组件的基类与常用控件：提供 窗口几何持久化、Properties 属性命名空间，以及带补全的下拉框等。

类层次

QWidget  → BWidget
QFrame   → BFrame
QMainWindow → BMainWindow

基类与混入

from quatm.GUI.widgets.quatmQt import BWidget, BMainWindow

widget = BWidget(name="my_widget", parent=None)
window = BMainWindow(name="MainWindow", parent=None)

搜索与补全控件

from quatm.GUI.widgets.quatmQt import SearchComboBox

box = SearchComboBox(parent=parent)
box.add_if_new("my_stream")

12 - 图像监视器

概述

quatm/GUI/entries/image_monitor.py 提供自动更新的图像显示窗口（ImageDisplay ）：定时从属性中订阅的图像流拉取最新帧，按分辨率与偏移变换后刷新显示，并可同 步叠加掩码流；内置降噪、亮斑检测、当前帧保存与属性配置（显示级别、ROI 等）等 功能。

方法

用法

from quatm.GUI.entries.image_monitor import ImageDisplay

view = ImageDisplay(imagestreams=["camera/image"], parent=parent)
view.configureWindow()   # 调整显示级别、ROI 等

说明：ImageDisplay 既是ImageWindow 的中央显示器，也可单独嵌入其它界面。图 像流与掩码流列表保存在属性中，右键菜单提供订阅、掩码订阅与配置入口。

13 - 分析管理器

概述

quatm/GUI/entries/analysismanager.py 提供 分析管理器：以可勾选树表列出各分析 脚本（名称 / 脚本 / 类别 / 输入流），负责启停子进程、监视与自动重启，并支持新增、 删除与配置分析条目。

组件

功能

用法

from quatm.GUI.entries.analysismanager import AnalysisManager

mgr = AnalysisManager(name="AnalysisManager", parent=parent)

分析脚本是独立进程：勾选某条目后，管理器用当前解释器拉起脚本并把项目环境变量 注入子进程，因此分析代码与主程序相互隔离，脚本崩溃不会影响实验。

14 - 数据流监视器

概述

quatm/GUI/streammonitor/ 提供 数据流监视器：MainWindow 以标签页容纳数据流 （Data）、图像流（Image）、命令（Command）、消息日志（Message）与历史（History） 等监控；每个监控标签由 StreamMonitor 订阅单一数据流并实时展示。

组件

监控类型

用法

from quatm.GUI.streammonitor import MainWindow, StreamMonitor

win = MainWindow(parent=parent)   # 多标签监控主窗口
panel = StreamMonitor(name="PMT", stream_type="Data", parent=parent)  # 单流面板

该监控界面通常作为独立进程启动，也可在其它窗口中嵌入单流 StreamMonitor 面板。

15 - 序列编辑器

概述

quatm/GUI/editors/editor_sequencer.py 提供 编辑并模拟 工具（旧称 Combi / “打开模拟窗口”）：CodeEditorParser 组合主窗口把左侧 CodeEditor 代码编辑器 与右侧序列可视化组合起来：编辑实验脚本后可一键模拟运行，把各输出通道的时序画 成阶梯图，便于调试实验序列。

组件

关键方法

用法

from quatm.GUI.editors.editor_sequencer import CodeEditorParser

win = CodeEditorParser(parent=parent, filename="experiments/my_experiment.py")

说明：参数扫描（nD 扫描、随机化等）的编辑入口在实验窗口的 Edit 按钮 （SequenceEditor，见实验窗口），扫描定义保存于 实验属性树并与远程控制平台共享。

16 - 进程管理器

概述

quatm/GUI/entries/processmanager.py 提供 进程管理器：按 Servers / Driver / GUI / Viewer / Monitor 分类读取配置，为每个脚本条目生成一个 SingleProcess 启停按钮面板，统一管理整套实验软件的运行。进程以当前解释器按脚本或模块（python -m）方式启动，携带项目根与父进程看门狗环境。

进程类别

组件

关键方法（SingleProcess）

用法

from quatm.GUI.entries.processmanager import ProcessManager

pm = ProcessManager(parent=parent)
pm.show()

待管理条目由配置文件中的 scripts 定义；各条目的启动/停止通过对应的按钮面板完成。

17 - 设备管理器

概述

quatm/GUI/entries/device_manager.py 提供 设备管理器（VISADeviceLister）：通 过 PyVISA 扫描系统中的 VISA 仪器，查询设备标识（*IDN?）并选择驱动文件绑定， 把设备加入已选列表生成 DeviceInfo，供设备配置使用。

组件

工作流

1. refresh_devices()      → 扫描 VISA 总线，填充设备列表
2. query_device_info()    → 对选中设备发送 *IDN? 查询
3. select_driver_file()   → 选取并绑定驱动文件
4. add_device_to_selected() → 加入已选设备列表（去重）

用法

from quatm.GUI.entries.device_manager import VISADeviceLister

dl = VISADeviceLister(parent=parent)
dl.refresh_devices()   # 列表显示 USB/GPIB/LAN 等 VISA 设备

18 - 数据存储

概述

quatm/GUI/h5storage/ 提供 HDF5 数据存储 GUI（由旧单文件拆出的包，公开符号在 包级再导出）：汇总 / 单流 / 图像三类数据管理器订阅数据，按预约时刻、周期或 Looper 指令自动保存，也可手动把当前快照后台写入 .h5 文件并从文件回读历史测量 。

组件

保存方式（H5StorageDataMgr）

用法

from quatm.GUI.h5storage import H5StorageGui   # 包级再导出

win = H5StorageGui(parent=parent)
win.show()

数据保存由后台 H5SaveWorker 完成：GUI 线程先拷贝数据快照再交给 worker，因此 HDF5 磁盘写入不会卡住界面。

19 - 实时滚动图

概述

quatm/GUI/entries/live_plot.py 提供 实时滚动绘图：ScrollWindow 为多子图主 窗口，每个 ScrollPlot 子图订阅一条数据流的若干通道，维护环形缓冲并滚动显示散 点/曲线与滑动平均；PlotDataEditor 提供数据源下拉面板。

组件

关键方法（ScrollPlot）

用法

from quatm.GUI.entries.live_plot import ScrollWindow

host = ScrollWindow(name="PMT 滚动监视", parent=parent)
host.addPlot()   # 追加一个滚动子图

之后在子图右键菜单中订阅数据流、选择通道并调整显示。缓冲长度、滑动平均开关与 窗口大小等配置保存在属性中，重启后自动恢复。

20 - 自动保存编辑器

概述

AutoSaveEditor（quatm/GUI/editors/auto_save_editor.py）是一个弹窗编辑器，用来 维护 周期 h5 自动保存 的“时间点列表”：每一行 = 一个（勾选标记 + 日期时间），勾选 的行会按对应时刻触发一次自动保存。它由数据存储相关面板调用。

组件

主要方法

用法

from quatm.GUI.editors.auto_save_editor import AutoSaveEditor

editor = AutoSaveEditor(props=props, max_items=24, parent=parent)
editor.load_AutoSaveEditor_props(props, "H5Storage/auto_save_times")

21 - 实验辅助工具

概述

Quatm 将日常实验校准任务封装为对准/辅助工具，模块位于 quatm/GUI/alignment/， 配以若干独立入口控件，实现一键运行与自动优化。

ODT 对准辅助 — OdtAlignmentHelper

quatm/GUI/alignment/odt_helper.py — 对 xODT/cODT 各压电镜轴建单轴控制块，提供 整体运行/终止与补偿电压、BA 激光参数设置。每轴完整对准序列为：激光关的全范围扫 描 → 离子附近精细扫描 → 发布拟合结果 → 移到目标位置。

from quatm.GUI.alignment.odt_helper import OdtAlignmentHelper

helper = OdtAlignmentHelper(parent=parent)
helper.run_all()   # 执行完整对准流程（线程池保证逐轴进行）
helper.terminate_all()   # 安全停止全部轴

杂散场补偿 — CompensationHelper

quatm/GUI/alignment/comp_helper.py — 通过沿各阱轴的电压扫描与两拟合线交点求补 偿电压，自动最小化杂散场。

from quatm.GUI.alignment.comp_helper import CompensationHelper

comp = CompensationHelper(parent=parent)

压电镜控制 — PiezoMirrorControl

quatm/GUI/entries/piezo_mirror_controler.py — 用箭头/按键界面操纵直线促动器反 射镜方向的简易面板，W/A/S/D 对应上/左/下/右。

from quatm.GUI.entries.piezo_mirror_controler import PiezoMirrorControl

mirror = PiezoMirrorControl()   # 独立窗口；WASD 或点击方向键控制
mirror.show()

22 - 数据模型

概述

quatm/GUI/widgets/models.py 提供把 Python 字典 / 列表映射为 Qt 表格模型的基类（源自 ARTIQ 的 models）。实验队列、准备台与循环器的表格界面均基于此构建。

核心类

用法

from quatm.GUI.widgets.models import DictSyncModel

model = DictSyncModel(
    headers=["名称", "值", "单位"],
    dataNames=["name", "value", "unit"],
    init={"name": "param1", "value": 100, "unit": "µs"},
)

具体业务模型通过子类实现三个钩子定制行为：convert 把键/值/列转成单元格内容，sort_key 返回排序键，flags 决定各单元格可编辑等标志。

23 - 可折叠组件

概述

quatm/GUI/widgets/theexpandables.py 提供可折叠/展开的树形对话框 CollapsibleDialog： 每个“面板”由一个带展开/折叠按钮的树条目与一个内容控件组成，适合配置界面与高级参数设置。

组件

CollapsibleDialog 提供 add_section(title, widget) 直接添加面板；子类也可覆写 define_sections() 用 add_button / add_widget 细粒度组织树形结构。

用法

from quatm.GUI.widgets.theexpandables import CollapsibleDialog

class SetupDialog(CollapsibleDialog):
    def define_sections(self):
        self.add_section("相机设置", some_widget)
        self.add_section("触发设置", trigger_widget)

24 - 参数框

概述

quatm/GUI/widgets/arg_boxes.py 提供把实验参数类与 Qt 输入控件绑定的小部件： 用户改值即回写实验参数（内部以 SI 单位存储，界面可按需换算显示）。它们常由 “实验参数面板/参数系统”按参数类型自动创建。

控件

用法（示意）

from quatm.GUI.widgets.arg_boxes import FloatBox, BoolBox, ComboBox

# 数值参数：界面按 kHz 显示，底层以 SI（Hz）存储
fbox = FloatBox(argument=param_freq, unit="kHz", display_multiplier=1e3)

bcheck = BoolBox(parName="enable", value=param_enable)
cbox = ComboBox(parName="source", argument=param_source)  # 参数类内含 stringlist

通常这些控件由参数系统按实验声明自动生成，无需手工实例化。

25 - 实验参数面板

概述

Dashboard（quatm/GUI/entries/dashboard.py）是由 默认实验（DefaultExp） 驱动的“控制面板”主部件：DefaultExp 按设备数据库自动装配整机参数，Dashboard 再把这些参数按 整数/浮点/布尔 分段、以分组网格排布成可调的参数控制界面。

类体系

DefaultExp（实验基类：自动装配设备属性并分组）
     └─ Dashboard（控制面板：分段 + 分组网格 + 自适应列数）
            └─ 管理器控件（IntManager / FloatManager / BoolManager / ComboManager …）

关键特性

• 自动装配：DefaultExp.build() 遍历设备库，为每个 attr/generic_attr 设备 建立参数对象并按其分组归类。
• 按类型分段：界面按 整数 / 浮点 / 布尔 等类型分段，段内再按参数分组。
• 自适应列数：adaptive_columns() 依据窗口宽度重排（4 列起，每约 200 px 加一列）， 窄窗口也不挤压。
• 就地生效：改动微调框即写回属性并直达硬件（运行体 run() 为空，适合纯手动调参）。

用法（示意）

from quatm.GUI.entries.dashboard import Dashboard, DefaultExp

# DefaultExp 自动装配设备参数；Dashboard 负责界面排布与分组
page = Dashboard(parent=parent)

“参数系统”页描述了其内部的管理器控件体系。

26 - FPGA DAC 控制

概述

quatm/GUI/entries/fpga_controller.py 提供用于调试与校准的 FPGA 简易手动控制： 用带标签的 -10 … +10 V 数值框逐路设置 DAC 电压，用勾选框网格设置 32 路 TTL 输出。

组件

用法

from quatm.GUI.entries.fpga_controller import DACvalues, TTLQW

# 先经设备数据库取得底层 FPGA 驱动句柄 controller
page = DACvalues(controller)

# TTL：勾选框状态经“Apply/状态变化”回调合成掩码写入 FPGA
ttl = TTLQW(controller)

硬件缺失或写入失败时只打印错误、不崩溃，便于无硬件环境下的界面调试。

27 - 后台工作线程

概述

quatm/GUI/widgets/browser_workers.py 与 helper_workers.py 提供基于 QRunnable 的通用后台线程封装：把耗时任务放到线程池执行，并经信号把结果/异常/进度传回界面线程。

信号

用法

from quatm.GUI.widgets.browser_workers import Worker

worker = Worker(callback=my_long_task, arg1, kw=...)   # 透传给回调函数
worker.signals.finished.connect(on_done)
worker.signals.error.connect(on_error)
QThreadPool.globalInstance().start(worker)

两处实现大同小异：helper_workers.py 供辅助/分析类后台任务复用，browser_workers.py 供浏览器类面板复用。

28 - 实验时间线

概述

quatm/GUI/entries/experiment_timeline.py 提供 实验时间线（Timeline）：加载 实验时序 JSON 文件（experiment.json），把各 DAC/TTL 输出通道随时间的变化绘制成 阶梯子图，并提供输出通道勾选面板决定哪些曲线可见，方便调试与验证实验时序逻辑。

组件

关键方法（Timeline）

用法

from quatm.GUI.entries.experiment_timeline import Timeline

tl = Timeline()
tl.load_file("experiment.json")   # 加载时序文件并绘图
tl.show()

29 - 滚动波形窗口

概述

quatm/GUI/entries/scrollwindow.py 提供 滚动波形窗口（ScrollWindow）： BMainWindow 子类的多通道实时滚动数据查看主窗口，按指定数量排布 ScrollPlot 子图（每两个换一行），统一把数据块分发到对应子图并刷新；PlotDataEditor 提供 数据/图像流的选择下拉。

组件

关键方法

用法

from quatm.GUI.entries.scrollwindow import ScrollWindow

win = ScrollWindow(name="PMT 滚动监视", parent=parent, n_plots=2)

在每个子图上通过右键菜单完成数据流订阅、数据通道选择与显示配置；该窗口也可作为 独立进程启动。

30 - 订阅编辑器

概述

SubscriptionEditor（quatm/GUI/editors/subscription_editor.py）管理程序对数据流/ 图像流的订阅：从属性库加载已存订阅、列出可用流供选择，支持添加/删除，并在属性变更 时热更新列表。它常作为实时绘图/监视类面板的数据源选择组件。

主要方法

用法

from quatm.GUI.editors.subscription_editor import SubscriptionEditor

editor = SubscriptionEditor(props=props, category="Data", parent=parent)
editor.loadSubscriptions()

31 - 表格参数

概述

quatm/GUI/widgets/table_parameter.py 提供 ParameterTree 的表格编辑 节点：table_parameter 参数类型配合 table_parameterItem 控件项，可在参数树中直接 编辑 numpy 结构化数组（如校准表、扫描序列）。

组件

table_parameterItem 会按数组 dtype 建列（含字段名/类型），单元格改动即时回写数组； valueIsDefault() 用于判断是否需要单独持久化该值。

用法

from quatm.GUI.widgets.table_parameter import table_parameter
import numpy as np

dt = np.dtype([("freq", float), ("amp", float)])
param = table_parameter(name="扫描表", value=np.zeros(10, dtype=dt))

32 - 远程 ROI

概述

quatm/GUI/widgets/ROI.py 提供 ROI：继承 ROI，以唯一名称 通过中心属性库通信其颜色、位置与尺寸，使远程客户端能同步查看与调整 ROI 区域。

方法

用法

from quatm.GUI.widgets.ROI import ROI

roi = ROI(name="分析区域", parent=view)   # name 需唯一，重名会共享属性
roi.update_from_properties()

说明：name 是该 ROI 在中心属性库中的键，务必确保不与属性字典中的任何名字冲 突；属性变化后调用 update_from_properties 即同步刷新 ROI 外观与位置。

33 - 图像查看器

概述

quatm/GUI/entries/image_group.py 提供 图像查看窗口（ImageWindow）：以中央 ImageDisplay 图像显示器为主控件，四周停靠 行/列线剖面 与 直方图色标 等面 板，用于成像实验的实时监视与分析。

布局结构

其中每个剖面图是一个 LivePlot 容器，内部由 UpdatingPlot 订阅对应数据流实时 刷新（详见实时绘图）。

显示参数持久化

显示参数存放在属性库 Viewer/ 命名空间下，构造时按属性恢复，关闭时自动保存：

拖动直方图电平或色标刻度后，分别经 update_min_max 与 get_tick_position 把当 前值写回属性，closeEvent 在关闭前统一保存视图范围与刻度。

方法

用法

from quatm.GUI.entries.image_group import ImageWindow

win = ImageWindow(name="吸收成像")   # 独立主窗口，parent 可省略
win.show()

该窗口常作为独立进程启动，也可作为 BMainWindow 实例嵌入其它界面。图像流与 行/列剖面流的订阅，在各子面板（图像显示器 / 剖面图）的右键菜单中完成。

34 - 属性检查器

概述

PropertiesChecker（quatm/GUI/entries/properties_checker.py）是一个属性分发 看门狗：它通过一个属性句柄设置标记，再用第二个句柄读回；若中枢没有把该变化传播 过来，就弹出告警，说明属性服务可能已停摆。检查在定时器上周期运行，因此窗口正常 显示且界面事件循环保持响应。

用法

from quatm.GUI.entries.properties_checker import PropertiesChecker

checker = PropertiesChecker(parent=parent)
checker.check_once()   # 手动执行一次看门狗检查

面板自身会周期调用 check_once()（每次把标记置真再置假并读回验证）。

35 - 辅助绘图

概述

quatm/GUI/alignment/plotter.py 提供 辅助绘图（DataPlotterWidget）：订阅并绘 制测量过程中采集的数据。支持数据源切换、x 轴与多个 y 轴选择器，每个 y 轴经一条 可配置的数据链（缩放系数 → 过滤器 → 分箱/拟合）处理后画入图区，并可导出 PDF。

组件

关键方法

Y 轴链（YAxisWidgetHelper）：updateYscale 设置缩放系数，右键菜单可 addBinning 分箱、addFitting 拟合（如高斯/线性），reevaluateData 在过滤器等 变化后重跑整条数据链。

用法

from quatm.GUI.alignment.plotter import DataPlotterWidget

plotter = DataPlotterWidget(
    axis_name="myaxis",
    prop_root="...",
    datastream_names=[".../data"],
    n_yaxis=1,
    parent=parent,
)
plotter.toggleConfig()   # 展开数据源 / x、y 轴选择配置