# XRSProcess_v2 版本说明（隔离版本）

> 本目录是 `XRSProcess` 的**独立副本**，专门用于适配新版 DAQ 写出的数据文件（3D 图像直接放在 `entry/data` 下，例如 `D_LAMBDA`）。
> 原目录 `XRSProcess` 未做任何修改，两个版本互不影响，可同时运行。
> 基线版本：与 `XRSProcess` 同步于 2026-09-16（含"直接选文件读取"的界面改动）。

## 一、为什么需要这个版本

样本 `data/raw/14477_scan_20260916150924_1/14477_scan_20260916150924_1.nxs` 的 HDF5 结构：

```
/entry/data/D_LAMBDA          {21, 516, 516}   ← 2D 相机图像（3D 堆栈）
/entry/data/D_LAMBDA_image    {21}
/entry/data/D_SiC_Current1    {21}             ← I0 在这里（不是 entry/instrument）
/entry/data/D_SiC_I_A         {21}
/entry/instrument/M_DCM_B5Energy_readback {21} ← 能量轴
```

与旧版读取规则的区别：

| | 旧版 `XRSProcess` 支持的两种布局 | 本版新增支持 |
|---|---|---|
| 2D 图像 | ① `entry/data/data/data_*`（外部链接）② `entry/data/lambda` + `entry/data/minipix` | ③ `entry/data` 下**直接存放**的 3D 数据集（`D_LAMBDA`，任意名称） |
| 1D 计数 | `entry/data` 下 1 维数据集 | 同左（改为按 `ndim` 判定，不再把 Group / 3D 数据误当 1D） |
| I0 | `entry/instrument/D_SiC_Current1` | 自动在 `entry/data` 与 `entry/instrument` 两处查找（`D_SiC_Current1` → `D_SiC_I_A`） |

因此在旧版中：单探测器模式报"未找到二维探测器数据"，双探测器模式报 `'lambda'` KeyError。本版都能正常读取。

## 二、本版相对原版的改动（仅限本目录）

改动集中在 `utils/Controller.py`（另加少量文案）：

1. `_read_one_nxs()`：
   - 2D 图像在旧路径找不到时，自动取 `entry/data` 下第一个 3D 数据集（如 `D_LAMBDA`）；
   - 单探测器模式的 1D 通道改用 `dataset.ndim == 1` 判定，避免把 3D 图像或 Group 当成 1D 通道；
   - 双探测器模式下若文件里没有 `lambda` 数据集，给出明确提示"该文件只有单探测器数据（D_LAMBDA），请把探测器类型切换为 Lambda-flex"，而不是抛 KeyError。
2. `_scan_summary_message()`：单探测器模式下 2D 数据是数组而不是字典，摘要不再按名称索引（修复 `IndexError`）。
3. 新增 `_get_i0()`：按 `D_SiC_Current1` → `D_SiC_I_A` 的顺序，先在 `entry/data`（1D 计数）再在 `entry/instrument`（电机）里查找 I0；用于弹性峰 `DivideI0_elastic`、XRS 的 `divideI0` 以及标签页6 的 I0 检查。
4. `xrs.spec` / `build.sh`：打包产物名改为 `XRSProcessTool_v2`，避免与原版打包产物重名。
5. `configs/config.json`：默认 ROI 文件路径指向本目录下的 `ROI/`。
6. 读取失败的提示更明确（`_check_file_readable()` / `_file_error_hint()`）：
   - 文件不存在 / 选成了文件夹 / 没有读取权限（`os.access`）会在读取前就提示；
   - 打开文件时的权限不足（errno 13、Permission denied）、文件被其它程序占用（file is already open for write）、文件未写完或损坏（signature/truncated）都会翻译成中文提示写进日志面板，例如
     `文件打开失败 xxx.nxs: 没有读取权限（文件被占用或当前用户无权访问）：请关闭占用该文件的程序，或以有权限的账号重试`；
   - XRS 多文件读取时，坏文件只影响它自己，其余文件照常加载，状态栏把失败文件的编号标红列出。
7. 图像显示铺满画布（`MatplotlibCanvas`）：
   - `set_image()` 不再调用 `fig.tight_layout()`——它会在显示函数已设置好的铺满布局上再按刻度标签留边距，把图像压小（画布越扁越明显；实测窄扁画布里图像只占约 24% 面积，现在约 31%~74%）；
   - 显示两张探测器图像时按画布形状排布：画布偏宽（宽≥高）左右排，画布偏高上下排。以前不论画布形状都左右排，在偏高的画布里两张图各自只占约 15% 面积，现在约 36%。
8. 去掉 `display_all_peak_images_v2()` 里的调试残留 `np.save('img1.npy', ...)`：原版每处理一次双探测器弹性峰数据就会往工作目录写一个 35MB 的 `img1.npy`。
9. **ROI 文件改为可选**：不选 ROI 文件也能画图，只是不叠加方框，并在日志里提示
   `未选择ROI文件：只显示图像，不叠加ROI方框`；ROI 文件读不了（不存在/缺列）同样只提示、照常画图。
   - 双探测器模式下 `ROIFile-1` / `ROIFile-2` 各自可选，缺哪一个就只不叠加对应探测器的方框；
   - 标签页1（Filter Mask）在没有 ROI 时给出提示而不是报错。
10. 新增随机 ROI 测试文件 `ROI/roi_random15_14477.txt`：15 个随机方框（R01~R15，边长 26~44 px，散布在 516×516 探测器内，互不重叠），用于检查方框显示是否正确——之前的 ROI 文件是按四探测器位置写的，放到这份单探测器数据上位置没有意义。
11. 默认数据路径**按平台区分**：Linux（光束线机器）为 `/heps/beamline/ID33`，Windows 等其它系统**不设置**（常量 `DEFAULT_DATA_PATH` 定义在 `utils/Model.py`，按 `sys.platform` 判断）。这个默认值不仅填在「数据路径」框里，**同时是选择目录/文件对话框的默认起始目录**：
    - 点「数据路径」的「浏览...」→ 打开到当前数据路径；当前路径无效时用系统默认（Linux 为 `/heps/beamline/ID33`），再无效才退到程序当前目录；
    - 弹性峰 / XRS 的「浏览...」打开时同样从当前数据路径开始（不自动追加 `raw`）；
    - `configs/config.json` 里 `path0` 留空表示"用系统默认"；保存结果的默认目录仍是 `<数据路径>/processed/`，该目录不存在时退回用户主目录。
12. 默认探测器类型改为第一项 **`Lambda-flex`（单探测器）**（原版在 `show()` 里强制选中第二项）。启动后自动隐藏 `ROIFile-2`、把 modulelist 切到 `VB, HB, HL, VD`、取消并禁用 VU 模组勾选。
13. **两种读取方式并存，菜单切换**：菜单栏新增 **读取方式**，可在「按文件选择」（默认，= 目前的做法）和「按扫描号(scanID)」（= 原版做法）之间切换：
    - 按文件选择：弹性峰「浏览...」单选文件、XRS「浏览...」多选文件，选完立即读取；
    - 按扫描号：弹性峰填一个扫描号、「加载数据」；XRS 填扫描号（逗号分隔多个）、「加载数据」；
    - 扫描号方式在 `数据路径/raw` 下按 `<扫描号>_` 前缀匹配目录，再读目录里同名的 `.nxs`（一个扫描号匹配到多个目录时全部读取并提示）；
    - 两种方式最终都走同一套解析/读取代码，后续处理流程完全一致。
14. 修复 **单探测器模式下"XRS扫描"页不出图**的问题：原版（以及 v2 之前）在单探测器模式只清空画布不画内容，所以点了「开始处理」看起来"没有结果也没有报错"。现在单/双探测器都会画 I0-能量曲线（去跳变前/后各一张），去跳变在单探测器模式下也生效；能量轴自动在 `M_DCM_B5Energy_readback` / `M_DCM_B5Link_Energy_readback` 中选取。
15. 修复 **只有 QXBPM、没有 SiC 通道的扫描读不了 XRS** 的问题（例如 `14471_scan_20260916114533_1`：文件里只有 `D_QXBPM_I_*`，没有 `D_SiC_*`）。以前单探测器 XRS 只找 `D_SiC_Current1`/`D_SiC_I_A`，找不到就把整个文件判为失败。现在 I0 通道按「I0 PV 下拉框所选通道 → `D_SiC_Current1` → `D_SiC_I_A` → `D_QXBPM_I_Sum` → `D_QXBPM2_I_Sum`」的顺序自动查找，替换时在日志里提示，例如
    `I0通道替换 14471_....nxs: D_SiC_I_A → D_QXBPM_I_Sum`；确实一个都没有时，日志会列出文件里可用的 I0 候选通道，并提示"请取消 divideI0 或在 I0 PV 里选择上面列出的通道"。弹性峰的 `DivideI0_elastic` 也同样处理。
16. scanID 方式的交互与文件方式区分开：**每次点「加载数据」都替换之前载入的内容**（不累加），因此 **[清除] 按钮在 scanID 方式下隐藏**；状态栏只显示当前这一次的扫描号，不会越滚越长。文件方式仍是"选一个加一个 + 清除"。
17. 打包（`xrs.spec` / `build.sh`）**明确不包含 libgcc 的 .so**，运行时直接用目标机器的系统库：
    - `xrs.spec` 里新增 `EXCLUDE_SO_NAMES = ('libgcc_s.so.1', 'libgcc_s.so')`，在 `Analysis` 之后、`PYZ/EXE/COLLECT` 之前过滤 `a.binaries`（PySide6/numpy/scipy 的钩子会把 `libgcc_s.so.1` 一并收进来，包括 `PySide6/libgcc_s.so.1` 这种带路径的），并把剔除结果打印出来；
    - `build.sh` 在打包后增加校验：`find dist -name 'libgcc_s.so*'` 若仍有命中就直接报错退出，避免带着冲突库出厂；
    - 原因：包里自带的 `libgcc_s.so.1` 版本与系统/其它软件的库不一致时容易冲突（启动失败/符号冲突），统一用系统的更稳；
    - 需要连 `libstdc++.so.6` 一起剔除时，把名字加进 `EXCLUDE_SO_NAMES` 即可。

## 三、使用方法

```bash
cd XRSProcess_v2
python main.py
```

读取 `14477_scan_20260916150924_1.nxs`（或同结构的其他扫描）时：

- **探测器类型选 `Lambda-flex`（单探测器）**；
- 点「浏览...」选择该 `.nxs` 文件即可，读入后标签页 0～4 的 ROI 定位、拟合流程与原来一致；
- 若误选双探测器模式，日志面板会直接提示需要切换为 `Lambda-flex`。

旧格式（`entry/data/data` 外部链接）与新格式（`entry/data/lambda` + `minipix`）在本版中同样可以正常读取，用法不变。

## 四、注意

- 本版与 `XRSProcess` 各自有独立的 `configs/config.json` 与代码，修改本版不会影响原版；反过来也一样。
- 数据目录是共用的：默认数据路径仍为 `F:/Beamlines/B5/XRSdataProcessing/data`（可在界面「数据路径」中改成别处）。
- 两个版本不要同时用同一份配置文件互相同步，以免参数错乱。
