# DaisyDataToolkit 使用说明

> 面向实验数据的桌面工具：HDF5 / HDF5 Master / TIFF 文件预览，HDF5 与 TIFF 双向转换，HDF5 转为 NPY 或 TXT，以及数据裁剪。
> 版本：1.0 ｜ 含界面截图

## 一、在哪里找到这个软件

登录 `torch.heps.ihep.ac.cn`，选择对应容器进入 Desktop，桌面上双击 `DaisyDataToolkit` 即可使用。Windows 版正在内部测试中。

<figure class="md-figure">
  <img src="/media/software/daisy-data-toolkit/entry-torch-desktop.webp" alt="在 TORCH 容器桌面启动 DaisyDataToolkit" loading="lazy">
  <figcaption>图 1　在 TORCH 平台容器桌面上启动 DaisyDataToolkit</figcaption>
</figure>

## 二、窗口长什么样

顶部是一排标签页，常用这几个：

| 标签页 | 干什么 |
| --- | --- |
| View | 只看不改：HDF5 树、TIFF 预览 |
| HDF5 ↔ TIFF | 图像堆栈双向转换（最常用） |
| ToMaster | 多个 HDF5 用外链收成一个 Master |
| HDF5 → TXT | 标量 / 一维曲线导出成表格 |
| NPY → TIFF | 三维 `.npy` 写成 TIFF |
| Crop | 裁 ROI、改位深、批量导出 |
| Help | 中英教程、排障 |

<figure class="md-figure">
  <img src="/media/software/daisy-data-toolkit/ui-main.webp" alt="DaisyDataToolkit 主界面" loading="lazy">
  <figcaption>图 2　主界面：顶部标签页、底部进度条与 Run / Cancel / Log</figcaption>
</figure>

多数转换页底部都有进度条、`Run` / `Cancel` 和 `Log`；`View` 没有独立 Log。点 `Log` 可展开看失败原因，长时间任务可点 `Cancel / STOP`。菜单里还有 `View → Tabs`（显示/隐藏标签）、`Help → Activity Log`（处理记录）。

## 三、先从 View 看一眼

- 顶部 `Source` 选 `HDF5 file` 或 `TIFF images`，打开文件（TIFF 可一次加多张）
- 左侧 `Contents` 点组或数据集；中间 `Object` 看路径、shape、dtype、属性
- 右侧 `Dataset view` 调 `Low % / High % / Gamma`；多帧时拖 `Frame index`
- 需要局部放大：开 `ROI zoom`，在图上拖一块

预览可能降采样，只影响显示，不影响后面 Run 的分辨率。看准某个 dataset 之后，可用 `Open in HDF5 → TXT` 或 `Open in HDF5 ↔ TIFF` 把当前文件和路径带到对应页，少填一遍路径。

<figure class="md-figure">
  <img src="/media/software/daisy-data-toolkit/view-page.webp" alt="View 页：HDF5 树与数据集预览" loading="lazy">
  <figcaption>图 3　View 页：左侧数据结构树、中间对象属性、右侧图像预览</figcaption>
</figure>

## 四、HDF5 ↔ TIFF（核心页）

推荐顺序：**选方向 → 选输入 → 在结构树里选 Dataset → Apply → 设输出目录和命名 → Run**。漏掉 `Apply`，`Run` 会提示没选 Dataset，这是最常见的卡点。

**HDF5 → TIFF**

1. 方向选 `HDF5 → TIFF`
2. `Browse` 选一个或多个 `.h5` / `.hdf5`（多个路径用英文分号 `;` 分隔）；表格里 `Use` 勾上要转的 Master，点某一行中间 `Structure` 会加载
3. 在树上：点 `Dataset` 选这一个；点 `Group` 会收齐它下面所有 Dataset；也可用勾选框多选
4. 必须点 `Apply`，目标才算生效，并做多 Master 校验（路径要有、维度要一致）
5. `Output Dir` 选输出文件夹。命名默认 `Simple` 是前缀 + 序号（如 `data_00001.tif`）；`Template` 可写 `{ds:/某条HDF5路径}`、`{index:05d}`，路径读不到会直接报错停
6. 多个 Master 时，可按文件名 / 父目录等分子文件夹，或选 `Shared folder` 共用一个目录、序号连着编
7. 点 `Run`，首帧出来后 Preview 会更新

写出 TIFF 无压缩，保持原来的 dtype 和尺寸。

<figure class="md-figure">
  <img src="/media/software/daisy-data-toolkit/hdf5-to-tiff.webp" alt="HDF5 → TIFF 转换页" loading="lazy">
  <figcaption>图 4　HDF5 → TIFF 页：选方向、选输入、在结构树里选 Dataset 后 Apply</figcaption>
</figure>

**TIFF → HDF5**

1. 方向改成 `TIFF → HDF5`
2. 选文件夹（文件很多时不必一个个点；需要包含子文件夹时看界面是否勾了递归）
3. 设 `Output Dir`、`File Name`（`.h5`）和 `Dataset Path`（例如 `/entry/data`）
4. 若要带外链的 Master：勾 `Create Master File with External Links`，再设 `Batch Size`、前缀、`Link Group`
5. `Run`

## 五、ToMaster：多个 HDF5 收成一本总账

把每个源文件里指定的 Dataset 用 `External Link` 挂到一个 Master 里（例如 `/entry/data/data_000000` …），方便总览或再拿去转 TIFF。

1. `Add Files` 或 `Add Directory` 加源
2. 确认每行的 Dataset 路径（默认如 `/entry/data`）；改默认后要点对应的 `Apply`
3. `Master group` 是挂链接的父组（如 `/entry/data`）；改完 `Apply` 会重建临时预览表
4. 表格勾选：参与 Master 的行；取消勾选会清掉该行的 Master 节点名
5. 看右侧临时 Master 树对不对
6. 设输出目录和文件名，生成最终 Master

<figure class="md-figure">
  <img src="/media/software/daisy-data-toolkit/tomaster.webp" alt="ToMaster 页" loading="lazy">
  <figcaption>图 5　ToMaster 页：把多个 HDF5 的 Dataset 用外链收进一个 Master</figcaption>
</figure>

## 六、HDF5 → TXT：一维数据转换

只适合标量或一维 Dataset，三维图像请走 TIFF 页。

1. `Browse` 打开 HDF5，左边树里找数据集，可用 `Search`
2. 在选择/排序表里排好要导出的列
3. 设输出目录和文件名（一般自动加 `.txt`，制表符分隔，Excel 能打开）
4. `Run`；已有同名文件会询问是否覆盖

如果是带外链的 Master，会按链接去源文件读。表格预览可能只显示前若干行，完整导出仍是全部行。

<figure class="md-figure">
  <img src="/media/software/daisy-data-toolkit/hdf5-to-txt.webp" alt="HDF5 → TXT 页" loading="lazy">
  <figcaption>图 6　HDF5 → TXT 页：挑选一维/标量数据集导出为制表符表格</figcaption>
</figure>

## 七、NPY → TIFF

要求 `.npy` 是三维，轴序按 `z, y, x`。

1. 选 Input `.npy` 文件，中间会出预览
2. `Low / High / Gamma` 只改显示，不改写出的数
3. `Mode`：一个多页 stack，或每个 z 一层一张 TIFF
4. 选 Output folder；逐切片时可改 `slice_{index:04d}.tif` 这种 Pattern
5. 点 `Convert`

Stack 模式输出名与输入同名的 `.tif`，已存在会询问是否覆盖。轴序不是 `z, y, x` 时，请先在 NumPy 里 transpose 再存。

<figure class="md-figure">
  <img src="/media/software/daisy-data-toolkit/npy-to-tiff.webp" alt="NPY → TIFF 页" loading="lazy">
  <figcaption>图 7　NPY → TIFF 页：三维数组转多页 TIFF 或逐层切片</figcaption>
</figure>

## 八、Crop：裁一块再批量出

- 可加 TIFF / HDF5
- 设 ROI、帧步长、8/16 bit、是否自动对比度
- 快速对比原图和处理后的图像
- 两侧图像可同步平移、放大、缩小

<figure class="md-figure">
  <img src="/media/software/daisy-data-toolkit/crop.webp" alt="Crop 页" loading="lazy">
  <figcaption>图 8　Crop 页：裁剪 ROI、调整位深并批量导出</figcaption>
</figure>

## 九、Core 版与完整版

如果拿到的是 Core 安装包：打开后 `View` / `Help` 一定有，其它 Tab 可能显示 `Not installed`，点该 Tab 会按需下载（需配置模块仓库地址）。完整安装包则所有 Tab 一开始就在。菜单 `View → Tabs` 可把暂时不用的页藏起来。

## 十、常见问题

**Run 说没选 Dataset？** HDF5 → TIFF 必须在 Structure 里选好并 `Apply`，看状态栏是不是"已应用"。

**多个 Master 校验失败？** 每个勾选的 Master 都要有同一条 Dataset 路径，而且维度一致；失败行会在列表里标出来。

**Template 文件名转失败？** 检查 `{ds:/...}` 路径是否存在、是不是 Dataset；一维长度是否和帧数对得上。对不上会停，不会闷头转。

**ToMaster 取消勾选一行？** 该行不再进 Master，节点路径会被清空。

**Linux 没有桌面？** 这是 GUI 程序，需要显示环境；无桌面请用脚本包 DaisyDataToolkit。

**预览和结果不一样锐？** 预览可能缩小了，Run 输出仍是原分辨率。
