XRSProcessTool 使用说明书
X 射线拉曼散射(XRS)数据处理工具 版本:1.0 | 含界面截图
一、软件简介
XRSProcessTool 是用于 B5 光束线 XRS 实验数据处理的桌面软件,主要功能包括:
- 加载弹性峰扫描数据与 XRS 扫描数据(
.nxs格式) - 在 2D 探测器图像上显示/调整 ROI(晶体感兴趣区域)
- 对各 ROI 弹性峰进行洛伦兹拟合,剔除拟合不良的晶体
- 计算动量转移 q,按 q 区间筛选 ROI
- 将多个扫描、多个 ROI 的谱内插叠加,得到最终能量转移谱
- 保存结果为
.txt文本文件
支持单探测器(det2D)与双探测器(lambda + minipix)两种数据模式,启动时默认为双探测器模式。
二、启动与界面布局
启动 XRSProcessTool 后,主界面分为三部分:
| 区域 | 说明 |
|---|---|
| 左侧面板 | 参数设置区,包含若干分组(基础设置、弹性峰设置、ROI设置、拟合设置、XRS扫描设置、最终谱等),随右侧标签页切换而自动显示/隐藏对应分组 |
| 右侧上方 | 标签页区,共 11 个标签页,从左到右对应处理流程的先后顺序 |
| 右侧下方 | 日志面板,记录操作信息与报错(可清空) |
| 底部状态栏 | 进度条 |
界面顶部菜单栏:文件 → 保存结果 / 退出。
三、核心操作逻辑(务必先读)
1. 「开始处理」按钮只处理当前标签页
「开始处理」不会自动跑完整个流程,它只会执行当前选中的右侧标签页对应的处理步骤。所以完整流程需要手动、从左到右依次点击各标签页的「开始处理」。
每个标签页处理时,按钮变红显示「执行中」并禁用,完成后恢复绿色。
2. 两处都直接选择数据文件
读取方式可在菜单栏切换(本版新增):菜单 读取方式 → 按文件选择 / 按扫描号(scanID),切换后左右两处的输入控件会跟着变:
| 读取方式 | 弹性峰设置区 | XRS扫描设置区 |
|---|---|---|
| 按文件选择(默认) | 「浏览...」选单个 .nxs(选完立即读取) |
「浏览...」多选 .nxs(选一个读一个) |
| 按扫描号(scanID) | 填扫描号(如 11049)→ 点「加载数据」 |
填扫描号,多个用英文逗号分隔(如 11049,11052)→ 点「加载数据」 |
扫描号方式在 数据路径/raw 下按 <扫描号>_ 前缀匹配目录并读取其中的同名 .nxs(单个扫描号若匹配到多个目录,会全部读取并在日志里提示)。
两种方式的差别:按文件选择是"选一个加一个"(可累积多个,用「清除」清空);按扫描号每次点「加载数据」都会替换上一次载入的内容,状态栏只显示当前这一次的扫描号,因此该方式下不显示「清除」按钮。
I0 通道:divideI0(或弹性峰的 DivideI0_elastic)打开时,按「I0 PV 所选通道 → D_SiC_Current1 → D_SiC_I_A → D_QXBPM_I_Sum → D_QXBPM2_I_Sum」的顺序自动查找;发生替换时日志会提示,例如 I0通道替换 ...: D_SiC_I_A → D_QXBPM_I_Sum。若文件里确实没有任何 I0 通道,日志会列出可用的候选通道,并提示取消 divideI0 或在 I0 PV 中选择列出的通道。
- 弹性峰设置区「浏览...」:选择单个
.nxs文件(用于 ROI 定位、弹性峰拟合),选完立即读取并弹出内容总结 - XRS扫描设置区「浏览...」:可多选
.nxs文件,每选一个就读取一个;每个文件的加载内容写入右下角日志面板,状态标签显示已加载总数和全部已加载文件的扫描号(即文件名最前面的数字)。「清除」用于清空已加载的 XRS 数据
两处都要选择文件,缺一不可。参数(如 I0 归一化、I0 PV、去跳变)修改后,重新「浏览...」选一次文件,或在标签页5点一次「开始处理」,软件会按新参数重新读取;参数未变的文件不会重复读取。
3. 数据复用
加载过的数据会保留在内存中,后续标签页直接复用,无需重复加载。修改左侧参数后,需重新点「开始处理」对应标签页才会生效。
四、数据准备
本版(v2)默认数据根目录:Linux 为 /heps/beamline/ID33,Windows 等其它系统不设置(默认路径同时用作「浏览...」打开对话框时的起始目录)。其下结构:
data/
├── raw/ # 原始扫描数据
│ └── 11050_scan_20260414205302_1/
│ └── 11050_scan_20260414205302_1.nxs # 一次扫描一个子目录,内含同名 .nxs
└── processed/ # 处理结果输出目录
- 原始数据:位于
raw/下,结构为<扫描号>_scan_<时间戳>_<序号>/<同名>.nxs - 数据路径指向数据根目录(如
.../data),软件不会在其后自动追加raw:文件对话框从该目录打开,再进入raw/选取.nxs文件;处理结果保存到该目录下的processed/ - 数据路径留空时,软件会根据所选文件自动推断并填入(不会覆盖你已经设置好的路径)
- 本版(v2)支持的 HDF5 布局(按探测器类型选择):
Lambda-flex(单探测器):entry/data/data外部链接(旧格式),或entry/data下直接存放的 3D 图像数据集(新格式,如D_LAMBDA)Lambda-flex, minipix(双探测器):entry/data/lambda+entry/data/minipix- I0 通道自动在
entry/data(1D 计数)和entry/instrument(电机)两处查找
- 随机 ROI 测试文件:
ROI/roi_random15_14477.txt(15 个随机方框 R01~R15),用于验证方框与图像的坐标对应是否正确(自带的其他 ROI 文件是按四探测器布局写的,用在这份单探测器数据上位置没有意义) - ROI 文件:制表符分隔的
.txt,每行一个晶体,列为roi_label, x1, x2, y1, y2, x_shift, y_shift, x_expand, y_expand。软件自带示例 ROI 文件位于XRSProcess/ROI/目录(如roi_60crystals-v3.txt、roi_minipix-v3-2.txt)。
ROI 文件示例(前几行):
roi_label x1 x2 y1 y2 x_shift y_shift x_expand y_expand VB-A1 35 66 3 31 0 0 0 0 VB-A2 112 144 57 86 0 0 0 0
五、完整操作流程
下面按推荐的先后顺序,逐步说明每个标签页的操作。流程主线:
设基础参数 → 加载弹性峰数据 → (标签0
4) ROI定位与拟合 → 加载XRS数据 → (标签58) XRS检查 → (标签9~10) q计算与最终谱 → 保存结果
步骤 0:基础设置(基础设置分组)
在左侧「基础设置」分组设置:
| 参数 | 说明 | 默认值 |
|---|---|---|
useFilter |
是否用 ROI 方框内强度高于阈值的像素做 mask 取数(建议勾选) | ✅ |
useAutoRoiAdjust |
是否自动调整 ROI 方框位置/大小到最亮像素(建议勾选) | ✅ |
| 数据路径 | 数据根目录(指向存放 raw/ 的目录)。点「浏览...」会从这里打开 |
Linux:/heps/beamline/ID33;Windows 等其它系统不设置 |
| 探测器类型 | Lambda-flex(单)/ Lambda-flex, minipix(双)/ Lambda-flex-2, minipix(双) |
Lambda-flex(第一项,单探测器) |
| modulelist | 选用哪些模组,VB,HB,HL,VD 或 VB,HB,HL,VD,VU |
含 VU |
步骤 1:加载弹性峰数据(弹性峰设置分组)
- 点击「浏览...」,在弹出的文件对话框中选择弹性峰扫描的
.nxs文件(只支持单个文件) - 选择后软件立即读取该文件,并弹出内容总结窗;状态标签变绿「数据加载成功: 文件名」即成功
- 若需按 I0 归一化,先勾选
DivideI0_elastic,再点一次「浏览...」重新选择该文件(同一文件可以重复选择)
步骤 2:ROI 设置(ROI设置分组)
| 控件 | 说明 |
|---|---|
ROIFile-1 浏览 |
选择主探测器 ROI 文件(可选:不选也能画图,只是不叠加方框,日志会给出提示) |
ROIFile-2 浏览 |
选择第二个探测器(minipix) ROI 文件(双探测器模式下显示,同样可选) |
ROIsize |
自动调整时 ROI 方框的像素边长(10–100,默认 30) |
FilterVal |
过滤阈值(0–1,默认 0.2):ROI 内强度高于 FilterVal × 最大强度 的像素才计入 |
| 调整偏移参数 | 弹出对话框,设置各模组(VB/HB/HL/VD/VU/ROI2)的 x、y 偏移,用于对齐 |
ROIs保存 |
把在标签页0 中拖动调整过的 ROI 几何导出为新文件 |
标签页 0:弹性峰图片叠加
第一个可视化步骤。选中本标签后点「开始处理」,显示弹性峰扫描的 2D 探测器图像(对数刻度叠加图),并叠加红色 ROI 方框与标签。双探测器模式下左右各显示一张(lambda / minipix)。
- ROI 可交互:可直接在图上拖动 ROI 方框调整位置
- 调整后可用「ROIs保存」导出更新后的 ROI 文件
- 未选择 ROI 文件时也会正常显示图像,只是不叠加方框,日志面板会提示"未选择ROI文件:只显示图像,不叠加ROI方框"
标签页 1:Filter Mask
显示过滤 mask(通过 FilterVal 阈值的像素)叠加图,同样叠加 ROI 方框。若勾选了 useAutoRoiAdjust,ROI 会自动居中到最亮像素并按 ROIsize 重设大小。
- 用此页检查 mask 质量,必要时调大/调小
FilterVal或ROIsize后重新处理
标签页 2:各ROI弹性峰曲线
显示每个 ROI 的弹性峰曲线:左图为原始 ROI 求和,右图为过滤后求和。
交互功能:
- 鼠标悬停曲线 → 高亮变红加粗
- 点击图例短线 → 切换该曲线显示/隐藏
- 点击「Toggle All」图例 → 一键显示/隐藏全部曲线
标签页 3:批量拟合弹性峰
先在「拟合设置」分组设阈值:
| 参数 | 说明 | 默认 |
|---|---|---|
energy_resolution_threshold |
能量分辨率阈值(eV),FWHM 超过则判为坏拟合 | 2.0 |
r_squared_threshold |
拟合 R² 下限,低于则判为坏拟合 | 0.8 |
E_lowlim / E_highlim |
弹性峰中心能量合理范围(keV) | 9.67 / 9.69 |
选中本标签后点「开始处理」,软件对每个 ROI 用洛伦兹函数拟合弹性峰,结果以表格显示,包含列:crystal, x1, x2, y1, y2, center[eV], width[eV], height, background, r-square, NumPixels。
- 满足任一坏拟合条件(R²过低、中心越界、振幅为负、FWHM 过大)的 ROI 会被加入
BadFitList,在最终谱中自动排除
标签页 4:单ROI弹性峰拟合
用于检查单个 ROI 的拟合质量。左图显示某晶体的数据点与拟合曲线(标注 FWHM、中心能量),右图显示所有 ROI 曲线平移到弹性峰能量为零后的能量转移视图。
步骤 3:加载 XRS 数据(XRS扫描设置分组)
- 点击「浏览...」,在弹出的文件对话框中多选 XRS 扫描的
.nxs文件;每选一个就读一个,可以分多次选择,重复选择同一个文件不会重复读取 - 每个文件读取完成后,内容简要总结写入右下角日志面板(扫描号、文件名、2D 数据尺寸、1D 通道数、I0 通道、去跳变点数),状态标签显示「已加载 N 个文件: 编号1,编号2,…」列出所有已加载文件的扫描号;有文件读取失败时状态标签中会标红提示
- 「清除」按钮清空已加载的 XRS 数据(内存数据与曲线一并复位)
- 参数设置:
divideI0:按 I0 归一化(建议勾选)removeI0glitch:剔除 I0 跳变点(相邻点比值 <0.7 视为跳变,用邻域均值替代)I0 PV:选择 I0 信号通道(D_SiC_I_A/D_QXBPM_I_Sum/D_QXBPM2_I_Sum)logFig:对数绘图 改完参数后,再点一次「浏览...」选文件,或在标签页5点「开始处理」,会按新参数重新读取;参数未变的文件不重复读取
标签页 5:XRS扫描
选中后点「开始处理」,显示 I0 随能量变化曲线(归一化+去跳变前后两个子图),用于确认 XRS 数据与 I0 质量。
标签页 6:检查I0
在「检查I0数据」分组的 index_to_remove 填入要剔除的扫描序号(如 1,3,5),点「开始处理」后显示剔除前后的 I0 曲线对比,用于挑出坏扫描。
标签页 7:检查XRS
显示 2D 叠加的 XRS 探测器图像(对数刻度)并叠加 ROI 方框,双探测器模式下左右各一张。用于检查 XRS 图像质量与 ROI 覆盖情况。
标签页 8:所有XRS谱
显示各扫描、各 ROI 的 XRS 谱(原始 vs 过滤)。
- 顶部下拉框选扫描号 + 「绘制」按钮重绘
- 鼠标悬停高亮、点图例切换显隐
- 点击图例文字 → 切换到该晶体的单谱视图(左原始、右过滤,标注扫描号);再点「Toggle All」返回总览
标签页 9:q计算
点「开始处理」,计算每个 ROI 的动量转移 q(基于各模组固定散射角与弹性峰能量),在表格中新增 q_ave, dq_ave, q_range, dq_range 列。此步为最终谱的 q 筛选做准备。
标签页 10:最终谱图
在「最终谱」分组设置最终谱参数:
| 参数 | 说明 | 默认 |
|---|---|---|
q_range |
只叠加 q_ave 落在此区间的 ROI | 0–10 |
E_step |
能量内插步长(eV) | 0.2 |
ROIremoveList |
手动排除的晶体(点「选择」从晶体网格中勾选) | 空 |
Module_add_list |
选择参与叠加的模组(HB/VB/HL/VD/VU 复选框) | 全选 |
点「开始处理」生成最终谱:上图为叠加后的总谱,下方为各扫描的子图(用于检查弹性峰能量扣除是否正确)。
工具栏按钮:
- Scan_N 下拉框:选扫描号
- 最终图谱:只显示叠加总谱
- 能移谱:显示选中扫描号的能量转移子图
最终谱中,满足以下任一条件的 ROI 会被排除:在 ROIremoveList 中、在 BadFitList 中、模组未选、q 超出 q_range。
六、保存结果
处理完成后,点顶部菜单 文件 → 保存结果,弹出「保存结果」对话框:
保存模式(三选一):
模式 说明 输出文件 合并叠加(默认) 所有选中 ROI 叠加为一条谱 文件名_data.txt(能量转移 + 强度)分模组 各模组各一列,存在同一文件 文件名_data.txt(能量 + 各模组列)分晶体 每个晶体单独一个文件 + 汇总 各 晶体_data.txt+文件名_all_data.txt三种模式均额外输出:
文件名_rois.txt:拟合结果(fitResult)文件名_info.txt:本次所有处理参数记录
保存路径:目录默认
数据路径/processed/,文件名将作为子文件夹名(默认result)确认后保存,弹出「保存成功」提示
输出文件为制表符分隔的文本,示例(_data.txt):
Energy Transfer (eV) Intensity
90.2 20.33
90.4 18.41
…
七、参数配置保存与加载
左侧底部的「加载配置」「保存配置」按钮,可把当前所有参数(含探测器偏移、拟合阈值、q 范围等)保存为 .json 文件,下次直接加载复用,避免重复设置。
- 保存配置:弹出参数预览,选路径保存为
.json - 加载配置:选
.json文件,校验后预览(错误项标红、缺失项标灰),确认后应用到界面
八、快速操作清单(速查)
| 步骤 | 操作 |
|---|---|
| 1 | 基础设置:填数据路径、选探测器类型、选模组 |
| 2 | 弹性峰设置:按文件选择则浏览选单个 .nxs(自动读取);按扫描号则填扫描号后点「加载数据」 |
| 3 | ROI设置:选 ROIFile-1(双模式再加 ROIFile-2)、设 ROIsize/FilterVal、按需调偏移 |
| 4 | 标签0 → 开始处理 → 检查/拖动 ROI,按需 ROIs保存 |
| 5 | 标签1 → 开始处理 → 检查 mask |
| 6 | 标签2 → 开始处理 → 检查各 ROI 弹性峰 |
| 7 | 拟合设置:设阈值 |
| 8 | 标签3 → 开始处理 → 查看拟合表,记录坏拟合 |
| 9 | 标签4 → 开始处理 → 抽查单 ROI 拟合 |
| 10 | XRS扫描设置:按文件选择则浏览多选 .nxs;按扫描号则填扫描号(逗号分隔)后点「加载数据」 |
| 11 | 标签5 → 开始处理 → 检查 I0 |
| 12 | 检查I0:填 index_to_remove → 标签6 开始处理 |
| 13 | 标签7 → 开始处理 → 检查 XRS 2D 图 |
| 14 | 标签8 → 开始处理 → 检查所有 XRS 谱 |
| 15 | 标签9 → 开始处理 → 查看q表 |
| 16 | 最终谱:设 q_range / E_step / ROIremoveList / 模组 |
| 17 | 标签10 → 开始处理 → 查看最终谱 |
| 18 | 文件 → 保存结果 → 选模式/路径 → 确定 |
九、常见问题
Q:「开始处理」点了没反应? A:请确认已在弹性峰设置区选好单个数据文件、在 XRS 扫描设置区选好数据文件(选完会立即读取,结果见日志面板);并确认当前选中的是想要处理的标签页。
Q:某标签页显示空白? A:通常是缺少前置步骤的数据。请从左到右依次处理,确保前置标签页已执行「开始处理」。
Q:最终谱里 ROI 太少?
A:检查 BadFitList(标签3 坏拟合)、ROIremoveList(手动排除)、Module_add_list(模组未选)、q_range(q 越界)。放宽拟合阈值或扩大 q 范围可纳入更多 ROI。
Q:双探测器模式下只看到一个探测器? A:确认「探测器类型」选的是双探测器模式,且 ROIFile-2 已选择 minipix 的 ROI 文件。
Q:中文显示为方块?
A:打包版已内置中文字体;源码运行需系统安装中文字体(Linux:sudo dnf install google-noto-sans-cjk-sc-fonts)。
Q:加载配置后部分参数异常? A:加载对话框中标红/标灰的项为有问题或缺失,会使用默认值,按提示修正原配置文件即可。
本说明书随软件版本更新,如有疑问请联系维护人员。