<!--
网页版说明书（精简），发布在 https://daisy.ihep.ac.cn/software/daisy-batch-integration/manual

* 这份是**站点版**：为平台的单文件上限（实测约 32 KB：32,426 B 可上传、35,430 B 被拒）
  做的精简；完整的长版仍随发布包（User Guide / Powder Guide）。
* 图片用的是站点 media 的 URL（`/api/v1/media/...`），由 `tools/fill_site_details.py`
  上传后在正文里替换得到；本文件是它的版本化副本。
* 修改后重新上传：维护者 Token → `POST /maintainer/software/{slug}/media`（kind=manual）。
-->

# Daisy Batch Integrator 使用说明书

**适用版本**：0.16.0（Windows / Linux 便携包，或源码运行）。网页版为精简版，完整表格与边界说明见随包用户手册。

## 1. 软件简介

Daisy Batch Integrator 是面向 HEPS 高通量散射/衍射实验的离线数据处理桌面软件。积分本身交给 **pyFAI**：本软件只做数据准备（翻转、掩膜、非有限像素、偏振校验），把帧交给 pyFAI 一次，不另写一套分箱。两条主线：

* **SAXS/WAXS**：批量方位角积分（1D / 2D / radial）与曲线处理（叠加、扣背底、平均、合并、Guinier）。
* **粉末衍射**：参考相与环预测、寻峰与 pseudo-Voigt 拟合、Search-Match、晶胞精修（可选 GSAS-II）、原位 Series 与逐帧峰跟踪。

## 2. 安装与启动

* **便携包**：解压后运行 `daisy-batch-integrator.exe`（Windows）或 `daisy-batch-integrator`（Linux），无需安装 Python。
* **源码**：Python ≥ 3.11；`pip install -r requirements.txt`；`python main.py`。
* 大文件建议先设线程上限：`export NUMEXPR_MAX_THREADS=8 OMP_NUM_THREADS=4`。

## 3. 界面布局

主窗口分六个区域：**A** 参数区、**B** 工作流标签页（File Selection / PONI / Integration Parameters / Batch Visualization / Diffraction Analysis）、**C** 探测器视图、**D** 1D 谱、**E** 右侧结果图、**F** 状态行。日志面板默认折叠（`Log ▶`），状态行镜像最近一条消息约 8 秒。

![衍射工作区总览](/api/v1/media/software/daisy-batch-integration/shot-mw4slv7e.webp)

## 4. SAXS / WAXS 常规流程

1. **File Selection**：添加 HDF5（2D / 3D `[帧,y,x]` / 4D `[帧,通道,y,x]`），滑块选帧；大文件按帧懒加载。
2. **PONI Configuration**：载入 `.poni`，或 `Open Calibration GUI` 调 pyFAI-calib 现场校准；设置掩膜（`.npy` / `.edf` / 图像）。
3. **Integration Parameters**：选方法（1D / 2D / Radial）、单位（2θ deg/rad、q nm⁻¹/Å⁻¹）、径向与方位角范围（可用右侧探测器图拖选）、偏振、输出格式与目录，然后 `Run Batch Integration`。
4. **Batch Visualization**：叠加曲线、扣背底、平均、两曲线合并、Guinier 分析；每条曲线可展开调整取点范围与 Scale/Offset。

![SAXS/WAXS 主界面](/api/v1/media/software/daisy-batch-integration/shot-mw4slvh1.webp)
![积分参数页](/api/v1/media/software/daisy-batch-integration/shot-mwkbg4bw.webp)
![可视化取区](/api/v1/media/software/daisy-batch-integration/shot-mwiv714w.webp)
![批量可视化](/api/v1/media/software/daisy-batch-integration/shot-mw4slwej.webp)
![Guinier 分析](/api/v1/media/software/daisy-batch-integration/shot-mwiv719y.webp)

## 5. Beamstop 计数器归一化（0.16.0 新增，默认关闭）

线站的一套数据通常是两个文件：探测器帧在 `*_master.h5`，扫描元数据在旁的 `.nxs`。打开 **Integration Parameters → `Normalize by beamstop counter`**，来源选 `Auto (same folder)`（同目录唯一 `.nxs`）或手动指定：

* `experiment_mode` = **SAXS** → `entry/data/beamstop1`
* `experiment_mode` = **USAXS** → `entry/data/beamstop3`
* `experiment_mode` = **WAXS** → 无 beamstop，scale = 1（记录为“未施加”）

每一帧的 intensity 与 sigma 都除以**该帧**的计数器（在 pyFAI 内部完成，与 BioXTAS RAW 的 `1/I1` 口径一致），因此帧间束流衰减被一并去掉。记录写进 `.dat` 头、`.h5` 属性与 `_metadata.txt`（`normalization_*`），曲线明细里显示如 `Beamstop: beamstop1 = 344 → ×0.002907 (SAXS, …nxs)`。

要注意：**几何仍来自 PONI**（线站 `*_master.h5` 自带的 distance / beam_center 为 0，实测）；归一化只保证不同模态之间可比，**不是绝对标度**（绝对标度需水/玻璃碳标定）。缺 `.nxs`、多个候选、未知模式、计数器长度与帧数不符、计数器 ≤ 0 —— 一律在开跑前报错并说明原因，不写任何文件。

## 6. 粉末衍射流程

1. **Reference**：从 CIF（7 晶系）或内置标样建立参考相，按晶胞预测低角环；随包 `gemmi` 应用完整空间群消光。
2. **Peaks**：设定 Typical FWHM / Min SNR / 背景后 `Detect Peaks`；峰表可增删。`Fit Selected` 单峰拟合；`Fit All` 联合多峰拟合在后台线程运行、按钮变 `Cancel Fit` 并显示已运行时间，取消的结果丢弃。
3. **Search**：把实测峰与参考相按 d 值匹配，给出候选排序。
4. **Refine**：在匹配峰上做晶胞最小二乘精修，给出精修值与不确定度；可选 GSAS-II 做 Le Bail / Rietveld（子进程隔离、可取消）。
5. **Series**：多帧/原位数据构建 Series，热图、瀑布图、逐帧峰跟踪与批分析。

![Reference 标签页](/api/v1/media/software/daisy-batch-integration/shot-mw4slvmh.webp)
![Peaks 标签页](/api/v1/media/software/daisy-batch-integration/shot-mw4slvqk.webp)
![Search 标签页](/api/v1/media/software/daisy-batch-integration/shot-mw4slvtv.webp)
![Refine 标签页](/api/v1/media/software/daisy-batch-integration/shot-mw4slvyp.webp)
![Series 标签页](/api/v1/media/software/daisy-batch-integration/shot-mw4slw3i.webp)

## 7. 导出与记录

支持 `.dat`（ASCII）、`.h5`、TIFF 与 PNG/PDF/SVG 图；`Export Session…` 另写 `session.json` 与 `metadata.json`。几何、积分参数、拟合口径、误差来源、归一化因子与软件版本都会写进文件与日志；Session 可保存并恢复。

## 8. 常见问题

| 现象 | 原因与处理 |
|---|---|
| 积分结果为空 / 报 “no pixel” | 范围与探测器不相交：清空径向范围，或检查单位是否选错 |
| 曲线里某段是 NaN | 该径向 bin 没有像素（未覆盖），不是测量值 |
| 越界帧号 | 直接报错；请选范围内的帧 |
| `Fit All` 很慢 | 峰多时耗时随峰数平方增长（100 峰约 10 分钟）；按钮显示已运行时间，可随时 `Cancel Fit` |
| 与其它软件数值不同 | 先确认单位、掩膜、偏振与归一化设置一致；本软件不另写分箱 |

## 9. 已知边界

* 参考环与 sticks 是**位置模型**（不含结构因子与强度）；Search-Match 的结构因子强度仅作打分辅助。
* 晶胞精修是峰位最小二乘，**不是 Rietveld**（可选 GSAS-II 承担全谱精修）。
* Pink 光束只做理论可视化。
* 绝对标度（水 / 玻璃碳）不在本软件内。

## 10. 反馈

问题请附：软件版本（启动画面 / About）、操作步骤、数据规模，以及日志面板（`Log ▶`）中的相关行。联系邮箱：huyu@ihep.ac.cn
