# Scientific Image Viewer 用户手册

适用版本 **0.10.1**。

本文所有截图都来自**真实数据**：ID21 拼接图 `mosaic_weighted_float32.tif`，131,641 × 170,178
像素，83.5 GiB，放在 `/heps/beamline` 下的 DPC 分布式存储上。截图里的数值（面积、均值、
样本数、耗时）都是软件实际算出来的，不是示例。

---

## 1. 它是什么

一个**超大二维科学图像**的查看器。设计上只有一条规则：**屏幕留给图像**。

- 打开时**不会把图像读进内存**——图像始终留在磁盘上，只读取你看的那些分块（tile）。
- 所有显示调整（亮度、对比度、伽马、LUT、阈值）**只作用于显示像素**，原始数据不受影响。
- 测量**始终读 L0**（原始分辨率），绝不读屏幕上显示的降采样数据。

支持：TIFF / BigTIFF / OME-TIFF、HDF5 / NeXus、BigDataViewer XML、OME-Zarr。
不支持：RGB / 多通道、3D / 时间序列、把处理结果写回图像。

---

## 2. 打开与主界面

**文件 → 打开图像…**（`Ctrl+O`）。未打开图像时画布中央是提示和快捷键说明：

![空状态](/media/manuals/daisy-large-image-viewer/images/01-empty-state.png)

打开后：

![主界面](/media/manuals/daisy-large-image-viewer/images/02-main-window.png)

界面分成四块：

| 位置 | 内容 |
|---|---|
| 中央 | 画布。滚轮缩放，拖动平移 |
| 左侧 | **导航图**：整幅缩略图 + 当前视口（绿框）+ 导出选区（蓝框） |
| 右/下侧 | **六个面板**，全部可选：导航图、显示、工具、测量、对比、直方图 |
| 底部状态栏 | 来源与分辨率、正在使用的层级、光标处像素值、长任务进度 |

六个面板默认都是隐藏的，从**工具栏**或**视图 → 面板**打开。显示、工具、对比、直方图共用
右侧同一个停靠区（以标签页切换），所以同时打开两个不会占两列宽度。

---

## 3. 导航图：看全局、定导出范围

![导航图](/media/manuals/daisy-large-image-viewer/images/03-navigator.png)

- **缩略图**是整幅图像；**绿框**是主视图当前显示的范围。
- **蓝框**是**导出选区**——它和下方「导出区域」里的尺寸是同一件事。
- 在缩略图上**单击**会放置一个正好等于设定尺寸的选区；**拖动**可以画一个（上限就是该尺寸）。
- 下方下拉框是**导出区域尺寸**（512² … 8192²）。它决定蓝框多大、以及导出时按 L0 读多大范围。
  这不是测量 ROI；测量 ROI 在画布上画。

> 状态栏会实时显示「选区大小」，并说明导出会按 L0 读取该区域。

### 3.1 用选区直接看细节（以 8192² 为例）

![用 8192² 选区看细节](/media/manuals/daisy-large-image-viewer/images/15-selection-8192.png)

把「导出区域」选到 **8192 × 8192**，然后在缩略图上点一下想看的中心：

1. 蓝框落在该处，大小正好 8192²；
2. **画布同时跳到这个区域**——不必先缩放、再拖动去找；
3. 绿框表示画布当前显示的范围。**适应选区只保证蓝框完整落在画布里**；画布比例与
   选区不同时会多显示一些——上图里绿框就比蓝框宽。平移或缩放后它会继续移动，
   `Ctrl+Shift+0`（视图 → 适应选区）把它拉回蓝框；
4. `Ctrl+1` 切到 1:1 原始像素，看蓝框内的原生细节；`Ctrl+0` 回到整幅图像；
5. 想看清这块区域的明暗结构，点导航图里的 **适应显示范围**（或 图像 → 适应显示范围）：
   它按**选区内**当前屏幕上的像素（包括降采样屏；没有选区时按当前视图）重设显示窗口，
   不改原始数据。和显示面板的「自动」不同，它不看精确全图统计，所以选哪块就适配哪块。

上图的状态栏给出选区的 L0 坐标（x=40,904，y=45,904）和尺寸。画布跳过去之后仍然按
自己的需要流式读分块（状态栏会说明当前是怎么读的），**选区只决定导出时按 L0 读哪一块**；
`Ctrl+1` 才是原生像素。蓝框**不是测量 ROI**：测量 ROI 仍要用画布上的 ROI 工具画。

继续向外滚，可见范围会明显超过 8192²。画布按屏幕大小重新采样：左下角会写
`已降采样`，再往外会写 `仅概览`。**宽视图下不是 L0 的逐像素清晰度**——屏幕就那么
多像素，每一格必然覆盖多个源像素；测量与导出仍然只读 L0，不受影响。

---

## 4. 显示面板：只改显示，不改数据

显示面板有四个标签页，对应四种调整方式。它们**都以同一件事为核心**：把原始数值映射到
8 位显示值，原始像素不动。

### 4.1 亮度 / 对比度（默认页）

![亮度对比度](/media/manuals/daisy-large-image-viewer/images/04-display-brightness.png)

- **直方图**：横轴是数值，纵轴是计数。黄色 `Min` 与青色 `Max` 两个手柄就是当前显示窗口的
  两端；**在两个手柄之间拖动**可整体平移窗口。
- **自动**：按百分位截取窗口；有精确全图统计时用全图，否则用当前可见分块/概览
  （见 4.4 的两个「自动下限/上限 %」）。
- **适应显示范围**（导航图下方 / 图像菜单）：按选区内当前屏幕上的像素（没有选区时
  按当前视图）重设 Min/Max；选中一块区域后用它，比「自动」更贴近这块区域。
- **重置**：回到自动状态的起点。
- **最小 / 最大**：手动输入窗口两端。
- **伽马**：0.3 之类的非线性拉伸，作用在窗口归一化后的值上。
- **asinh（0 = 关闭）**：对偏暗、偏斜的分布很有用——它把暗部抬起来又不裁掉亮端。
- **反转 LUT**：黑白反转。
- **以品红色标记 NaN/Inf**：把非有限值涂成品红，逐像素核对数据质量时用。
- **采样上限**：直方图最多取多少像素（影响速度，不影响测量）。
- **分辨率**：见「工具」面板。
- **插值**：屏幕放大时的采样方式（双线性 / 最近像素）。
- **LUT（仅影响显示）**：调色板。

### 4.2 窗位 / 窗宽

![窗位窗宽](/media/manuals/daisy-large-image-viewer/images/05-display-window-level.png)

和 4.1 是同一个窗口，只是用医学影像习惯的表示：**窗位**是窗口中心、**窗宽**是宽度。
`重置 W/L` 回到自动值。

### 4.3 阈值

![阈值](/media/manuals/daisy-large-image-viewer/images/06-display-threshold.png)

按 ImageJ 的样式，把一个数值范围涂成**红色叠加**。可以手填下限/上限，也可以
**自动（对可见分块用 Otsu）**——用当前屏幕上已缓存的分块算 Otsu 阈值。同样只影响显示。

### 4.4 LUT / 自动范围

![LUT 与自动范围](/media/manuals/daisy-large-image-viewer/images/07-display-lut.png)

- **LUT**：灰度、Fire、Ice、Spectrum 等调色板。
- **自动下限 % / 自动上限 %**：「自动」按钮按这两个百分位截取窗口；有精确全图统计时用
  全图，否则用当前可见分块/概览。默认 1% / 99%，
  所以画面两端按定义会被裁掉一点——把这两个值改小可以少裁。

---

## 5. 工具面板：怎么读这幅图

![工具](/media/manuals/daisy-large-image-viewer/images/11-tools.png)

- **分辨率**
  - `自动 · 放大到原始像素时用 L0`：按缩放自动选最合适的金字塔层。
  - `L0 … / L1 …`：强制使用某一层。列表里每项标出该层的尺寸和降采样倍数。
- **分块大小**（tile）：256² / 512² / 1024²。块越大，读得越少但单次读越大；网络存储上
  512² 是默认。
- **µm/px**：X 方向的物理像素尺寸。文件声明了就从元数据读，也可以手填覆盖。
- **Y µm/px** 与 **方形像素**：勾选「方形像素」时 Y 跟随 X；取消勾选可以分别设置。
  各向异性的数据会**按物理比例显示**（2:1 的像素画成两倍高），而坐标仍是 L0 像素，
  所以测量与导出的数值不受影响。

---

## 6. 测量面板：ROI 与统计

![测量面板](/media/manuals/daisy-large-image-viewer/images/08-measurements.png)

### 画 ROI

顶部「工具」下拉：

| 工具 | 操作 | 测量内容 |
|---|---|---|
| 平移 | 拖动 | 只导航 |
| 编辑 | 拖动控制点或整个形状；点边加角；右键控制点删角 | — |
| 直线 | 拖出 | 长度 + 线剖面 |
| 矩形 / 椭圆 / 多边形 | 拖出 / 逐个点击顶点，回车完成 | 面积与强度统计 |
| 折线 | 逐个点击，回车完成 | 长度 + 沿长度剖面（无面积） |
| 自由手绘 | 拖动描出区域（会自动简化为多边形） | 面积与强度统计 |

**新建测量 ROI…**：直接输入 X、Y、宽、高。这是在**精确像素边界**上放置 ROI 的唯一方法
（手绘做不到可复现的边界）。

### ROI 表

每行一个 ROI，列的含义：

| 列 | 含义 |
|---|---|
| 显示 | ROI 是否画在画布上（隐藏的仍会测量和导出） |
| # | 当前行号（行序可拖动改变） |
| 类型 / 标签 | 形状与名字（标签可双击编辑） |
| 面积 (px²) / 面积 (µm²) | 几何面积 |
| 长度 (µm) | 开放路径（直线 / 折线）的长度 |
| 计数 (L0) | 参与统计的有限像素数（不含 NaN / 无穷） |
| 最小 / 最大 / 均值 / 标准差 (L0) | 精确强度统计 |

上图的三个 ROI 来自同一幅真实图像，均值分别是 **3373 / 6828 / 7902**——三个不同区域，
数值不同，这正是要并排看的原因。

### 测量

选中一行或多行，点 **测量所选**。软件会按 L0 逐个 ROI 流式计算，结果绑在 ROI 对象上：
删除后撤销能连值一起恢复，而改几何会让该 ROI 的测量值失效（表里显示破折号）。

状态栏会报告「已测量 L0：N 个有限像素 · 均值=…」。

---

## 7. 对比面板：并排看一组 ROI

![对比](/media/manuals/daisy-large-image-viewer/images/09-compare.png)

在 ROI 表里**选中两个或更多 ROI**，对比面板就会列出网格（没测量的显示破折号）：每一行一个统计量，
每一列一个 ROI，最后两列是**极差**（Spread，组内最大值减最小值）和 **RSD**（组内相对标准差）。

上图是真实结果：三个 ROI 的面积分别是 640,000 / 502,655 / 421,600 px²，
极差 218,400（面积的 RSD 是 21.7%）；三者的 L0 均值分别是 3,373 / 6,828 / 7,902，
极差 4,529，这就是图下说明里的 RSD 15.7%。**没测量的 ROI 会显示破折号**，不会编造数字。

导出的 CSV 只有这张对比表有的内容（极差、RSD）——每个 ROI 的原始值在「导出测量 CSV」里。

---

## 8. 直方图

![直方图](/media/manuals/daisy-large-image-viewer/images/10-histogram.png)

标题下面一行**总是说明计数来自哪里**，这是读直方图前必须先看的一句：

- `仅已缓存的可见分块——真实像素，但只有屏幕上这一部分`
- `整幅图像，采样了 N 行源数据（不是每一行）`
- `整幅图像，逐行精确面积均值，H×W`

上图是真实分布：**3,932,928 个有限样本**、整幅概览、范围 `[0, 655350]`。

- 拖动黄色 Min / 青色 Max 手柄，或在两者之间拖动，改的是**显示窗口**。
- **对数纵轴**：偏斜数据用线性轴时只剩一排贴边的梳齿，看不出形状。
- **用可见分块刷新**：只统计屏幕上的分块。
- **扫描整幅图像（精确）**：读每一个 L0 像素，得到精确分布（见第 10 节，耗时较长）。

---

## 9. 线剖面

选中一条直线或折线 ROI，点 **绘制线剖面**，打开剖面窗口：

![线剖面](/media/manuals/daisy-large-image-viewer/images/12-line-profile.png)

- 标题说明 ROI 名与「原生 L0」。
- 下面一行：**4,096 个点 · 4,096 个有限值 · 双线性 · 线宽 1px · 原生 L0，不受显示 LUT 影响**。
- 横轴是沿线的物理距离（µm），纵轴是原始 L0 数值；鼠标悬停显示该点的距离、数值与有效宽度。
- 折线会在转折处画虚线；距离跨转折连续计算。
- **导出剖面 CSV…** 写出 `distance_px`、`distance_um`、`raw_L0_value` 等列。

---

## 10. 长任务：扫描与预计时间

有两件事会读完整幅图像，因此可能要几分钟到几小时：

1. **构建精确缩略图**（图像 → 概览与缓存 → 构建 / 刷新精确缩略图）
2. **精确统计扫描**（图像 → 直方图… 打开面板，点其中的「扫描整幅图像（精确）」）

扫描期间，画布顶部中央会出现一条悬浮条，**就地显示进度与预计剩余时间**，并带一个
**取消扫描** 按钮：

![扫描悬浮条](/media/manuals/daisy-large-image-viewer/images/13-scan-banner.png)

![扫描进行中](/media/manuals/daisy-large-image-viewer/images/14-scan-in-progress.png)

- 进度按已读行数计；**预计剩余时间**取自最近几秒的读取速率，所以速率变化时会跟着变。
- 取消通常在几十到几百毫秒内生效，**不会留下半成品缓存**。
- 状态栏右侧同时保留一行同样的信息（悬浮条只是把它放到你正在看的地方）。
- 在本机的 DPC 存储上实测：精确缩略图 **130–238 秒**，精确统计 **约 433 秒**（83.5 GiB）。
  换到更慢的存储会更久；ETA 会按实际速率调整。

---

## 11. 导出与会话

| 导出 | 菜单 | 说明 |
|---|---|---|
| 测量 CSV | 图像 → ROI 测量 → 导出测量 CSV… | 每个 ROI 一行，含所有统计量 |
| 所选测量 CSV | 图像 → ROI 测量 → 导出所选 ROI 测量 CSV… | 只导出选中的 |
| 对比 CSV | 图像 → ROI 测量 → 导出 ROI 对比 CSV… | 对比网格（含极差 / RSD） |
| ROI 像素掩膜 TIFF | 图像 → ROI 测量 → 导出 ROI 像素掩膜 (TIFF)… | 255 = 落在区内、0 = 区外 |
| 原始 ROI TIFF | 图像 → ROI 测量 → 导出所选 ROI (L0)… | 未修改的 `float32` 原始值 |
| 调整后 PNG | 图像 → ROI 测量 → 导出调整后 ROI PNG… | 8 位 RGB，**不能用于定量** |
| 会话 | 文件 → 保存会话…（`Ctrl+Shift+S`） | 视图状态 + 全部 ROI 与测量值，不含像素 |

会话只在改了原图（大小或修改时间变化）时提示：图像变了，**测量值会被丢弃**而几何仍会恢复
——一个不再描述当前图像的数字不该看起来像刚算的。

---

## 12. 语言

**视图 → 语言** 可在 English / 简体中文之间切换，**不会重建界面**：选中的表格行、当前标签页、
缩放与滚动位置都保留。选择会被记住（环境变量 `SIV_LANG` 可覆盖）。

---

## 13. 常用快捷键

| 操作 | 快捷键 |
|---|---|
| 打开图像 | `Ctrl+O` |
| 全部适应 / 适应选区 | `Ctrl+0` / `Ctrl+Shift+0` |
| 1:1 原始像素 | `Ctrl+1` |
| 撤销 / 重做 | `Ctrl+Z` / `Ctrl+Shift+Z` |
| 复制所选 ROI | `Ctrl+D` |
| 显示 / 隐藏所选 ROI | `Ctrl+H` |
| 微调所选 ROI | `Alt+方向键`（加 `Shift` 为 10 px） |
| 上移 / 下移 ROI 行 | `Ctrl+↑` / `Ctrl+↓` |
| 完成多边形 / 折线 | `Enter` 或右键 |
| 取消绘制 | `Esc` |
| 打开 B&C 面板 | `Ctrl+Shift+C` |
| 保存 / 载入会话 | `Ctrl+Shift+S` / `Ctrl+Shift+O` |
| 退出 | `Ctrl+Q` |

鼠标：**滚轮缩放**，**拖动平移**；在画布上拖动即按当前工具绘制；在导航图上单击放置导出选区。

---

## 14. 已知限制

- **只支持单个二维灰度图像**。RGB / 多通道、3D 体数据、时间序列暂不支持（3D 会被明确拒绝，
  不会悄悄打开其中一层）。
- **测量只读 L0**，不受显示 LUT、窗宽窗位或降采样影响；这也意味着测量一个很大的 ROI 需要
  读不少数据。
- **面积是几何面积**：ROI 超出图像边缘时，表格会给出提示（黄色底色 + 悬停说明），
  因为真实测量只覆盖图像内的部分。
- **压缩 / 分块的 TIFF、HDF5** 在只取小区域时可能有读放大；这是存储格式的属性。
- 精确统计的缓存按「文件 + 范围 + 桶数 + 百分位」做键；如果原图在大小与修改时间不变的情况下
  被改写，需要手动清理缓存（`~/.cache/scientific-image-viewer`）。
