跳转至

GUI 设计

HemiSpec GUI 是基于 customtkinter 的紧凑启动器，调用与 Python API 和 hemispec workflow CLI 相同的双向工作流；它不是另一套独立分析实现。

设计目标

  • 仅暴露常规 ANS/RNS 生成所需的用户决策；
  • 高级模型、阈值、后缀和验证参数保留在 CLI/API；
  • 显示等价 CLI 命令，便于复现；
  • 长时间运行前报告运行环境与模型就绪状态；
  • 日志、取消和打开输出目录等操作保持可见。

用户可见工作流

当前 GUI 包含六个功能卡片：

  1. 输入 GM 图 — 目录或 glob，解析为预处理后的 *_GM_masked.nii.gz 文件。
  2. 输出工作区 — 体素图、表格、验证结果和可选中间文件的目标目录。
  3. 设置状态 — 浅层检查 PyTorch、两个 DGN 方向、可选 atlas 文件和可选分类器包。
  4. 可选 ROI 表 — atlas NIfTI 与标签表路径。
  5. 可选验证 — 半球分类、TRT 可靠性和保留中间输出。
  6. 运行控制 — 等价 CLI 命令、运行/停止、日志、复制命令和打开输出目录。

半球分类器验证保持为选择性启用。启用分类器时也会启用 ROI 导出，因为分类器使用 ROI 特征。

封装的默认参数

GUI 有意隐藏：

  • DGN 检查点路径和方向特定模型包名；
  • 设备选择；
  • GM 与推理阈值；
  • 重建截断和文件后缀规则；
  • 分类器模式和模型路径；
  • TRT session 正则表达式与掩膜参数。

这些值由 GUI 状态到配置的适配层定义；高级用户或研究特定设置仍可通过 CLI/API 控制。

共享执行路径

GUI 状态
  -> make_workflow_config(...)
  -> BilateralWorkflowConfig
  -> run_bilateral_workflow(...)
  -> voxel_maps/ + tables/ + 可选 validation/

GUI 预览的 CLI 命令由同一工作流配置生成。tests/test_gui_contract.py 中的契约测试保护这种一致性。

运行时行为

GUI 在执行前只做浅层设置检查；刷新状态时不会加载大型检查点。后台工作线程执行流程，使界面能够持续显示日志并接收取消请求。取消为协作式，在主要工作流阶段之间检查。

维护规则

  • 可见字段必须与 WORKFLOW_VISIBLE_FIELDS 同步；
  • 隐藏默认值必须与 CLI 默认值和契约测试同步；
  • 不要增加 GUI 专用计算路径；
  • 新增高级参数默认作为 CLI/API 选项，除非常规用户必须作出该决策；
  • 可见卡片或标签变化时，同步更新 GUI 用户指南和截图。

ANS/RNS 与跨半球 DGN 框架源自 Wang 等人（2024），详见引用。