# XRSProcessTool 使用说明书

> X 射线拉曼散射（XRS）数据处理工具
> 版本：1.0 ｜ 含界面截图

---

## 一、软件简介

XRSProcessTool 是用于 B5 光束线 XRS 实验数据处理的桌面软件，主要功能包括：

- 加载弹性峰扫描数据与 XRS 扫描数据（`.nxs` 格式）
- 在 2D 探测器图像上显示/调整 ROI（晶体感兴趣区域）
- 对各 ROI 弹性峰进行洛伦兹拟合，剔除拟合不良的晶体
- 计算动量转移 q，按 q 区间筛选 ROI
- 将多个扫描、多个 ROI 的谱内插叠加，得到最终能量转移谱
- 保存结果为 `.txt` 文本文件

支持单探测器（det2D）与双探测器（lambda + minipix）两种数据模式，启动时默认为**双探测器模式**。

<figure class="md-figure">
  <img src="/media/software/daisy-xrs/main-operation.webp" alt="软件主界面全景" loading="lazy">
  <figcaption>图 1　软件主界面全景</figcaption>
</figure>

---

## 二、启动与界面布局

启动 `XRSProcessTool` 后，主界面分为三部分：

| 区域 | 说明 |
|------|------|
| **左侧面板** | 参数设置区，包含若干分组（基础设置、弹性峰设置、ROI设置、拟合设置、XRS扫描设置、最终谱等），随右侧标签页切换而自动显示/隐藏对应分组 |
| **右侧上方** | 标签页区，共 11 个标签页，从左到右对应处理流程的先后顺序 |
| **右侧下方** | 日志面板，记录操作信息与报错（可清空） |
| **底部状态栏** | 进度条 |

界面顶部菜单栏：**文件** → 保存结果 / 退出。

<figure class="md-figure">
  <img src="/media/software/daisy-xrs/ui-main.webp" alt="主界面：左侧参数区、右侧流程标签页、右下角日志面板" loading="lazy">
  <figcaption>图 2　主界面：左侧参数区、右侧流程标签页、右下角日志面板</figcaption>
</figure>

---

## 三、核心操作逻辑（务必先读）

### 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数据 → (标签5~8) 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：加载弹性峰数据（弹性峰设置分组）

1. 点击「浏览...」，在弹出的文件对话框中选择弹性峰扫描的 `.nxs` 文件（**只支持单个文件**）
2. 选择后软件立即读取该文件，并弹出内容总结窗；状态标签变绿「数据加载成功: 文件名」即成功
3. 若需按 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方框"

<figure class="md-figure">
  <img src="/media/software/daisy-xrs/roi-overlay.webp" alt="标签页 0：弹性峰 2D 图像与晶体 ROI 方框叠加" loading="lazy">
  <figcaption>图 3　标签页 0：弹性峰 2D 图像与晶体 ROI 方框叠加</figcaption>
</figure>

### 标签页 1：Filter Mask

显示过滤 mask（通过 `FilterVal` 阈值的像素）叠加图，同样叠加 ROI 方框。若勾选了 `useAutoRoiAdjust`，ROI 会自动居中到最亮像素并按 `ROIsize` 重设大小。

- 用此页检查 mask 质量，必要时调大/调小 `FilterVal` 或 `ROIsize` 后重新处理

<figure class="md-figure">
  <img src="/media/software/daisy-xrs/filter-mask.webp" alt="标签页 1：阈值过滤 mask 叠加图" loading="lazy">
  <figcaption>图 4　标签页 1：阈值过滤 mask 叠加图</figcaption>
</figure>

### 标签页 2：各ROI弹性峰曲线

显示每个 ROI 的弹性峰曲线：左图为原始 ROI 求和，右图为过滤后求和。

交互功能：
- **鼠标悬停**曲线 → 高亮变红加粗
- **点击图例短线** → 切换该曲线显示/隐藏
- **点击「Toggle All」图例** → 一键显示/隐藏全部曲线

<figure class="md-figure">
  <img src="/media/software/daisy-xrs/elastic-curves-1.webp" alt="标签页 2：各 ROI 弹性峰曲线" loading="lazy">
  <figcaption>图 5　标签页 2：各 ROI 弹性峰曲线</figcaption>
</figure>

### 标签页 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`，**在最终谱中自动排除**

<figure class="md-figure">
  <img src="/media/software/daisy-xrs/peak-fit.webp" alt="标签页 3：批量洛伦兹拟合结果表" loading="lazy">
  <figcaption>图 6　标签页 3：批量洛伦兹拟合结果表</figcaption>
</figure>

### 标签页 4：单ROI弹性峰拟合

用于检查单个 ROI 的拟合质量。左图显示某晶体的数据点与拟合曲线（标注 FWHM、中心能量），右图显示所有 ROI 曲线平移到弹性峰能量为零后的能量转移视图。

<figure class="md-figure">
  <img src="/media/software/daisy-xrs/single-roi-fit.webp" alt="标签页 4：单 ROI 拟合检查与能量转移视图" loading="lazy">
  <figcaption>图 7　标签页 4：单 ROI 拟合检查与能量转移视图</figcaption>
</figure>

### 步骤 3：加载 XRS 数据（XRS扫描设置分组）

1. 点击「浏览...」，在弹出的文件对话框中**多选** XRS 扫描的 `.nxs` 文件；**每选一个就读一个**，可以分多次选择，重复选择同一个文件不会重复读取
2. 每个文件读取完成后，内容简要总结写入右下角**日志面板**（扫描号、文件名、2D 数据尺寸、1D 通道数、I0 通道、去跳变点数），状态标签显示「已加载 N 个文件: 编号1,编号2,…」列出所有已加载文件的扫描号；有文件读取失败时状态标签中会标红提示
3. 「清除」按钮清空已加载的 XRS 数据（内存数据与曲线一并复位）
4. 参数设置：
   - `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 质量。

<figure class="md-figure">
  <img src="/media/software/daisy-xrs/i0-scan.webp" alt="标签页 5：I0 随能量变化曲线（归一化 / 去跳变前后）" loading="lazy">
  <figcaption>图 8　标签页 5：I0 随能量变化曲线（归一化 / 去跳变前后）</figcaption>
</figure>

### 标签页 6：检查I0

在「检查I0数据」分组的 `index_to_remove` 填入要剔除的扫描序号（如 `1,3,5`），点「开始处理」后显示剔除前后的 I0 曲线对比，用于挑出坏扫描。

<figure class="md-figure">
  <img src="/media/software/daisy-xrs/i0-check.webp" alt="标签页 6：剔除指定扫描前后的 I0 对比" loading="lazy">
  <figcaption>图 9　标签页 6：剔除指定扫描前后的 I0 对比</figcaption>
</figure>

### 标签页 7：检查XRS

显示 2D 叠加的 XRS 探测器图像（对数刻度）并叠加 ROI 方框，双探测器模式下左右各一张。用于检查 XRS 图像质量与 ROI 覆盖情况。

<figure class="md-figure">
  <img src="/media/software/daisy-xrs/xrs-image.webp" alt="标签页 7：XRS 探测器 2D 叠加图与 ROI 覆盖检查" loading="lazy">
  <figcaption>图 10　标签页 7：XRS 探测器 2D 叠加图与 ROI 覆盖检查</figcaption>
</figure>

### 标签页 8：所有XRS谱

显示各扫描、各 ROI 的 XRS 谱（原始 vs 过滤）。

- 顶部下拉框选扫描号 + 「绘制」按钮重绘
- 鼠标悬停高亮、点图例切换显隐
- **点击图例文字** → 切换到该晶体的单谱视图（左原始、右过滤，标注扫描号）；再点「Toggle All」返回总览

<figure class="md-figure">
  <img src="/media/software/daisy-xrs/xrs-spectra-1.webp" alt="标签页 8：各扫描、各 ROI 的 XRS 谱" loading="lazy">
  <figcaption>图 11　标签页 8：各扫描、各 ROI 的 XRS 谱</figcaption>
</figure>

### 标签页 9：q计算

点「开始处理」，计算每个 ROI 的动量转移 q（基于各模组固定散射角与弹性峰能量），在表格中新增 `q_ave, dq_ave, q_range, dq_range` 列。此步为最终谱的 q 筛选做准备。

<figure class="md-figure">
  <img src="/media/software/daisy-xrs/q-result.webp" alt="标签页 9：动量转移 q 计算结果" loading="lazy">
  <figcaption>图 12　标签页 9：动量转移 q 计算结果</figcaption>
</figure>

### 标签页 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`。

<figure class="md-figure">
  <img src="/media/software/daisy-xrs/filter-mask.webp" alt="标签页 1：阈值过滤 mask 叠加图" loading="lazy">
  <figcaption>图 13　标签页 1：阈值过滤 mask 叠加图</figcaption>
</figure>

---

## 六、保存结果

处理完成后，点顶部菜单 **文件 → 保存结果**，弹出「保存结果」对话框：

1. **保存模式**（三选一）：

   | 模式 | 说明 | 输出文件 |
   |------|------|----------|
   | 合并叠加（默认） | 所有选中 ROI 叠加为一条谱 | `文件名_data.txt`（能量转移 + 强度） |
   | 分模组 | 各模组各一列，存在同一文件 | `文件名_data.txt`（能量 + 各模组列） |
   | 分晶体 | 每个晶体单独一个文件 + 汇总 | 各 `晶体_data.txt` + `文件名_all_data.txt` |

   三种模式均额外输出：
   - `文件名_rois.txt`：拟合结果（fitResult）
   - `文件名_info.txt`：本次所有处理参数记录

2. **保存路径**：目录默认 `数据路径/processed/`，文件名将作为子文件夹名（默认 `result`）
3. 确认后保存，弹出「保存成功」提示

<figure class="md-figure">
  <img src="/media/software/daisy-xrs/save-result.webp" alt="保存结果对话框：合并叠加 / 分模组 / 分晶体" loading="lazy">
  <figcaption>图 14　保存结果对话框：合并叠加 / 分模组 / 分晶体</figcaption>
</figure>

输出文件为制表符分隔的文本，示例（`_data.txt`）：
```
Energy Transfer (eV)  Intensity
90.2                  20.33
90.4                  18.41
…
```

---

## 七、参数配置保存与加载

左侧底部的「加载配置」「保存配置」按钮，可把当前所有参数（含探测器偏移、拟合阈值、q 范围等）保存为 `.json` 文件，下次直接加载复用，避免重复设置。

- **保存配置**：弹出参数预览，选路径保存为 `.json`
- **加载配置**：选 `.json` 文件，校验后预览（错误项标红、缺失项标灰），确认后应用到界面

<figure class="md-figure">
  <img src="/media/software/daisy-xrs/config-dialog.webp" alt="参数配置的保存与加载对话框" loading="lazy">
  <figcaption>图 15　参数配置的保存与加载对话框</figcaption>
</figure>

---

## 八、快速操作清单（速查）

| 步骤 | 操作 |
|------|------|
| 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：加载对话框中标红/标灰的项为有问题或缺失，会使用默认值，按提示修正原配置文件即可。

---

*本说明书随软件版本更新，如有疑问请联系维护人员。*
