Load X-ray Images (fabio)(X射线探测器图像加载)

Load X-ray Images (fabio) - User Manual

Dragonfly Prototype Apps · Load X-ray Images (fabio)...

版本 Version 1.0 · 2026-07-14

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

Load X-ray Images (fabio) 是一个 Dragonfly Prototype App,用于在 Dragonfly 内打开约 30 种 2D X 射线探测器 / 同步辐射图像格式及其多帧序列,预览图像与元数据,并一键导入为一个 Dragonfly image Channel(通道)。底层封装的是 fabio(silx / ESRF 出品的开源探测器图像读取库,MIT 许可)。

支持的格式包括 EDF(ESRF Data Format)、CBF(imgCIF)、Pilatus / Dectris、MAR / MarCCD / MAR345、ADSC、Bruker、GE、TIFF、HDF5 等;fabio.open() 会根据文件内容自动识别格式。多帧文件(multi-frame series)会被逐帧读取并堆叠成 (N, Y, X) 体数据。

输入是磁盘上的一个图像文件(而非 Dragonfly 里已有的对象);输出是一个新的 image Channel。若文件头带探测器像素尺寸(EDF 的 PSize_1 / PSize_2,单位已是米),会写入通道的 X/Y 体素 spacing。

它不是断层重建工具:只读取 2D 探测器帧与投影序列,不产生带 Z 向真实间距的重建 3D 体;也不读取 Zeiss Xradia 的 .txrm/.txm(fabio 不覆盖,见 DESIGN.md)。原计划的 DXchange 因在 PyPI 上只有 0.0.1 占位包(真身仅 conda/GitHub 提供)不适合 pip venv 模式,故改用同领域、纯 wheel 的 fabio。

2. 适用场景

• 打开同步辐射 / 衍射 / 探测器线站产生的单张 2D 图像:ESRF EDF、Pilatus / Dectris、MarCCD、ADSC、Bruker、GE 帧等。
• 把多帧 EDF/CBF 投影序列作为一个 (N, Y, X) 栈整体导入 Dragonfly,便于后续浏览或进一步处理。
• 需要读取 Dragonfly 原生加载器不直接支持的探测器专有格式(imgCIF CBF、MAR345、SFRM 等)。
• 希望在导入前先预览缩略图与文件头元数据(格式、帧数、尺寸、数据类型、探测器像素尺寸)以确认文件正确。

3. 安装与启用

本插件随 Prototype Apps 完整安装包(Full Package) 一起分发,默认未勾选。

1. 把 Full Package 压缩包解压到一个短路径目录(例如 C:\PL),避免 Windows 路径过长问题。

2. 运行 Install_FullPackage.bat。

3. 在弹出的安装对话框中勾选 “Load X-ray Images (fabio)”(所有插件默认都不勾选)。

4. 点击 Install。

5. 完全重启 Dragonfly(菜单只在启动时扫描一次,不重启不会出现)。

安装后,它出现在 Prototype Apps ▸ Load X-ray Images (fabio)...,归入 “Reconstruction & Imaging(重建与成像)” 分组。

之后可通过 Developer ▸ Prototype Labs... ▸ Menu Item Manager 随时启用/停用本插件。插件安装在 %LOCALAPPDATA% 下,无需管理员权限;每次启用/停用后都需重启 Dragonfly 生效。

4. 运行环境与首次配置

本插件采用 venv_in_code 模式:fabio 只在一个独立虚拟环境 / 子进程里运行,绝不进入 Dragonfly 自身的 Python。首次使用前需在 Setup 页点击 Setup Environment (fabio) 按钮完成一次性配置。

该按钮会以 Dragonfly 自带 Python(或你指定的 Base Python)为基础,用 runner/setup_env.py 创建一个 venv 并 pip install runner/requirements.txt 里列出的依赖:fabio、numpy、Pillow。三者均为预编译 wheel,无需 Java、无需 MSVC 编译器、无需 GPU。

• 联网要求:仅首次 Setup 需要联网下载 wheel;之后预览/导入均在本地离线运行。
• GPU:不需要。
• WSL / 外部工具:不需要。
• venv 位置:建于已安装代码目录下的 venv\(即 ...\GenericMenuItems\FabioLoader\venv);Setup 成功后其 python.exe 路径会写回 Setup 页的 Analysis venv python 字段并存入 fabio_config.json。
• Base Python 回退字段:留空则自动探测 Dragonfly / 系统 Python;也可用 Browse... 手动指定一个 python.exe 作为建 venv 的基础解释器。
• Job root:中间文件(缩略图 PNG、.npy、status.json、results.json)的落盘根目录,默认 C:\FabioLoaderJobs。

5. 界面说明

面板顶部是标题说明,下方为 Setup 与 Load 两个选项卡;底部有一个绿色状态行和一个只读日志框(约 130px 高)。

Setup 选项卡

• Analysis venv python:分析用 venv 的 python.exe 路径;由 Setup 自动填写(占位提示 “set by Setup Environment”)。
• Base Python(输入框 + Browse...):建 venv 的基础解释器;留空自动探测。
• Job root:中间产物目录,默认 C:\FabioLoaderJobs。
• Setup Environment (fabio) 按钮:创建 venv 并安装 fabio + numpy + Pillow。

Load 选项卡 — File 组

• Image file(输入框 + Browse...):选择要打开的图像文件;文件对话框预置了 fabio 常见扩展名过滤器(*.edf *.cbf *.tif *.mccd *.mar3450 *.img *.h5 ...),但 fabio 会自动识别格式,与扩展名无关。选定文件后若 Output 标题为空,会自动填入不含扩展名的文件名。
• Preview 按钮:读取元数据并生成中间帧缩略图。

Load 选项卡 — 预览区(左右分栏)

• 左侧缩略图标签(最小 260×260):显示中间帧的等比缩略图,无预览时显示 “No preview”。
• 右侧元数据表(两列 Property / Value):列出 File、Format、Frames、Size X、Size Y、Data type、Pixel size X (m)、Pixel size Y (m),以及文件头前 12 个键(以 hdr: 前缀显示)。

Load 选项卡 — Import 组

• Output Channel title:导入后生成的通道标题;留空则默认用文件名。
• Import → Publish as Channel(蓝色按钮):读取全部帧堆叠为 (N,Y,X) 并发布为 Channel。

6. 使用步骤

1. (首次) 切到 Setup 页,(可选)填 Base Python 与 Job root,点 Setup Environment (fabio),等待状态行显示 “Environment ready.”。

2. 切到 Load 页,在 Image file 处 Browse... 选择一个 X 射线 / 探测器图像文件。

3. 点 Preview:左侧看缩略图,右侧核对格式、帧数、尺寸、数据类型和探测器像素尺寸等元数据。

4. (可选)在 Output Channel title 里改一个想要的通道名。

5. 点 Import → Publish as Channel:插件在 venv 子进程里读取全部帧,堆叠为 (N,Y,X),并在 Dragonfly 中发布为一个 Channel。

6. 在 Dragonfly 的对象浏览器里查看新生成的 Channel;状态行会显示导入帧数与通道名。

7. 参数说明

本插件是一个加载器,没有数值算法参数;下表列出其关键配置项与选项(均来自面板代码)。

8. 输出结果

导入会在 Dragonfly 中创建一个 image Channel。全部帧被堆叠为 (N, Y, X) 的三维数组(单帧文件则为 (1, Y, X)),先写成 channel_C0.npy,再经 createChannelFromNumpyArray(ZAxis=True) 发布。

• 命名:通道标题取自 Output Channel title,留空则用去扩展名的文件名。
• spacing(体素间距):若文件头含探测器像素尺寸(EDF PSize_1/PSize_2,单位米),则写入 X/Y spacing;否则保持默认。Z 向不设真实间距(纯帧堆叠)。
• origin(原点):设为 (0, 0, 0)。
• 数据类型:uint8/uint16/int8/int16/float32 原样保留,其余类型统一转为 float32。
• 位置:新 Channel 出现在 Dragonfly 的对象浏览器 / Data Properties 中,可直接在 2D/3D 视图查看。

9. 常见问题与故障排除

• “Run Setup first, or set the analysis venv python.” — 尚未建 venv。先到 Setup 页点 Setup Environment (fabio),或手动填 Analysis venv python。
• Setup 失败 — 通常是首次安装时无网络或 pip 无法下载 wheel。确认可访问 PyPI,或指定一个已含 pip 的 Base Python 后重试;详细报错见底部日志框。
• “Select a valid image file first.” — 未选文件或路径无效。用 Browse... 重新选择一个存在的文件。
• 预览/导入失败,提示格式无法识别 — 该文件可能不是 fabio 支持的格式,或文件损坏。注意 fabio 按内容而非扩展名判断格式;Zeiss Xradia .txrm/.txm 不受支持。
• 大型多帧序列内存不足 — Import 会把全部帧一次性堆叠进内存再发布;超大序列可能耗尽内存,建议先用较小序列或分批处理。
• 导入的图像看起来太暗/太亮 — 缩略图为便于观察做了 0.5–99.5 分位对比拉伸;但导入的 Channel 是原始数据,请在 Dragonfly 里调整窗宽窗位(数据范围)。

10. 注意事项与已知限制

• 仅 2D 探测器帧与序列:只读取 2D 帧并堆叠,不进行断层重建,不产生带真实 Z 向间距的 3D 体。
• 不支持 Zeiss Xradia .txrm/.txm 及各设施专有的层析布局(为后续计划,需 olefile 读取器或经 conda/git 安装真正的 DXchange)。
• Z 向无间距:多帧堆叠仅在 X/Y 方向按探测器像素尺寸设 spacing。
• 元数据依赖文件头:仅当文件头提供 EDF PSize 时才写入物理像素尺寸,否则通道无真实标定。
• 验证状态:已通过对 EDF / CBF / TIFF(单帧与多帧)的往返读取验证;在真实 Dragonfly 会话内的端到端 live 验证仍待完成。
• fabio 严格运行在独立 venv/子进程内,不会污染 Dragonfly 自身的 Python 环境。

11. 参考资料

• fabio(silx / ESRF)—— 主页与文档:https://github.com/silx-kit/fabio 、https://fabio.readthedocs.io ;许可:MIT。
• 图像库 Pillow:https://python-pillow.org(生成预览缩略图);数值库 NumPy:https://numpy.org。
• 格式背景:ESRF EDF、imgCIF CBF、Dectris/Pilatus 等探测器格式。
• 插件内文档:DragonflyPlugins/FabioLoader-Plugin/README.md 与 DESIGN.md(含选用 fabio 而非 DXchange 的原因及后续计划)。

Part II English Manual

Contents

1. Introduction

2. Use cases

3. Installation & enabling

4. Runtime environment & first-run setup

5. Interface

6. How to use

7. Parameters

8. Output

9. FAQ & troubleshooting

10. Notes & known limitations

11. References

1. Introduction

Load X-ray Images (fabio) is a Dragonfly Prototype App that opens about 30 2D X-ray detector / synchrotron image formats and their multi-frame series inside Dragonfly, previews the image plus metadata, and imports the data with one click as a Dragonfly image Channel. Under the hood it wraps fabio (the open-source detector-image reader from silx / ESRF, MIT-licensed).

Supported formats include EDF (ESRF Data Format), CBF (imgCIF), Pilatus / Dectris, MAR / MarCCD / MAR345, ADSC, Bruker, GE, TIFF, HDF5, and more; fabio.open() auto-detects the format from the file contents. Multi-frame files are read frame by frame and stacked into an (N, Y, X) volume.

The input is a file on disk (not an existing Dragonfly object); the output is a new image Channel. When the header carries the detector pixel size (EDF PSize_1 / PSize_2, already in meters), it is written to the Channel's X/Y voxel spacing.

It is not a tomographic reconstruction tool: it only reads 2D detector frames and projection series, not reconstructed 3D volumes with true Z spacing. It also does not read Zeiss Xradia .txrm/.txm (fabio does not cover these; see DESIGN.md). DXchange was the original plan, but PyPI only carries a 0.0.1 stub (the real package is conda/GitHub-only) and does not fit the pip venv pattern, so fabio - same domain, pure wheels - was chosen instead.

2. Use cases

• Open single 2D images from synchrotron / diffraction / detector beamlines: ESRF EDF, Pilatus / Dectris, MarCCD, ADSC, Bruker, GE frames, etc.
• Import a multi-frame EDF/CBF projection series into Dragonfly as one (N, Y, X) stack for browsing or further processing.
• Read detector-specific formats that Dragonfly's native loader does not open directly (imgCIF CBF, MAR345, SFRM, etc.).
• Preview a thumbnail and header metadata (format, frame count, size, data type, detector pixel size) before importing, to confirm the file is correct.

3. Installation & enabling

This plugin ships in the Prototype Apps Full Package and is unchecked by default.

1. Unzip the Full Package to a short directory (e.g. C:\PL) to avoid Windows long-path issues.

2. Run Install_FullPackage.bat.

3. In the installer dialog, check "Load X-ray Images (fabio)" (all plugins are unchecked by default).

4. Click Install.

5. Fully restart Dragonfly (the menu is scanned only at startup - it will not appear otherwise).

After installation it appears under Prototype Apps ▸ Load X-ray Images (fabio)..., in the "Reconstruction & Imaging(重建与成像)" section.

You can later enable or disable it via Developer ▸ Prototype Labs... ▸ Menu Item Manager. It installs under %LOCALAPPDATA% with no admin rights required; restart Dragonfly after each toggle for it to take effect.

4. Runtime environment & first-run setup

This plugin uses the venv_in_code model: fabio runs only inside an isolated virtual environment / subprocess and never loads into Dragonfly's own Python. Before first use, run the one-time setup by clicking Setup Environment (fabio) on the Setup tab.

That button uses Dragonfly's bundled Python (or a Base Python you specify) as the base, runs runner/setup_env.py to create a venv, and pip installs the dependencies listed in runner/requirements.txt: fabio, numpy, Pillow. All three are prebuilt wheels - no Java, no MSVC compiler, no GPU needed.

• Internet: required only for the first setup (to download wheels); previewing and importing afterward run fully offline.
• GPU: not required.
• WSL / external tools: not required.
• venv location: created under the installed code folder as venv\ (i.e. ...\GenericMenuItems\FabioLoader\venv); on success its python.exe path is written back to the Analysis venv python field and saved into fabio_config.json.
• Base Python fallback field: leave blank to auto-detect Dragonfly / system Python, or use Browse... to point at a specific python.exe to base the venv on.
• Job root: root folder where intermediate files (thumbnail PNG, .npy, status.json, results.json) are written; defaults to C:\FabioLoaderJobs.

5. Interface

The panel has a title line at the top, two tabs - Setup and Load - and, at the bottom, a green status line and a read-only log box (about 130px tall).

Setup tab

• Analysis venv python: path to the analysis venv's python.exe; filled automatically by Setup (placeholder "set by Setup Environment").
• Base Python (line edit + Browse...): the base interpreter for building the venv; blank = auto-detect.
• Job root: the intermediate-output folder; defaults to C:\FabioLoaderJobs.
• Setup Environment (fabio) button: creates the venv and installs fabio + numpy + Pillow.

Load tab - File group

• Image file (line edit + Browse...): pick the file to open; the dialog offers common fabio extensions (*.edf *.cbf *.tif *.mccd *.mar3450 *.img *.h5 ...), but fabio auto-detects the format regardless of extension. Selecting a file auto-fills the output title (file name without extension) if it is empty.
• Preview button: reads metadata and builds a middle-frame thumbnail.

Load tab - preview area (split view)

• Left thumbnail label (min 260x260): shows an aspect-preserving thumbnail of the middle frame; "No preview" when empty.
• Right metadata table (two columns Property / Value): lists File, Format, Frames, Size X, Size Y, Data type, Pixel size X (m), Pixel size Y (m), plus the first 12 header keys (shown with an hdr: prefix).

Load tab - Import group

• Output Channel title: title for the resulting Channel; defaults to the file name if blank.
• Import → Publish as Channel (blue button): reads all frames, stacks them into (N,Y,X), and publishes as a Channel.

6. How to use

1. (First run) Go to the Setup tab, optionally set Base Python and Job root, click Setup Environment (fabio), and wait for the status line to read "Environment ready.".

2. Switch to the Load tab and Browse... to an X-ray / detector image file in Image file.

3. Click Preview: check the thumbnail on the left and verify format, frame count, size, data type, and detector pixel size on the right.

4. (Optional) Edit Output Channel title to the name you want.

5. Click Import → Publish as Channel: the plugin reads all frames in the venv subprocess, stacks them into (N,Y,X), and publishes a Channel in Dragonfly.

6. Find the new Channel in Dragonfly's object browser; the status line reports the number of frames imported and the Channel name.

7. Parameters

This plugin is a loader and has no numeric algorithm parameters; the table below lists its key configuration items and options (all taken from the panel code).

8. Output

Import creates one image Channel in Dragonfly. All frames are stacked into a 3D (N, Y, X) array (single-frame files become (1, Y, X)), first written as channel_C0.npy and then published via createChannelFromNumpyArray(ZAxis=True).

• Naming: the Channel title comes from Output Channel title, or the file name (without extension) if left blank.
• Spacing: if the header carries the detector pixel size (EDF PSize_1/PSize_2, in meters), it is written to X/Y spacing; otherwise defaults are kept. No true Z spacing is set (plain frame stack).
• Origin: set to (0, 0, 0).
• Data type: uint8/uint16/int8/int16/float32 are preserved; any other type is converted to float32.
• Location: the new Channel appears in Dragonfly's object browser / Data Properties and can be viewed directly in 2D/3D.

9. FAQ & troubleshooting

• "Run Setup first, or set the analysis venv python." - the venv has not been built. Click Setup Environment (fabio) on the Setup tab, or fill in Analysis venv python manually.
• Setup fails - usually no internet on first setup or pip cannot download wheels. Confirm PyPI is reachable, or point Base Python at an interpreter that already has pip, then retry; see the log box for the full error.
• "Select a valid image file first." - no file selected or the path is invalid. Use Browse... to pick an existing file.
• Preview/import fails with an unrecognized-format error - the file may not be a fabio-supported format, or it is corrupt. Note that fabio decides by content, not extension; Zeiss Xradia .txrm/.txm is unsupported.
• Out of memory on large multi-frame series - Import stacks all frames into memory at once before publishing; very large series can exhaust RAM. Try smaller series or process in batches.
• Imported image looks too dark/bright - the thumbnail uses a 0.5-99.5 percentile contrast stretch for display, but the imported Channel holds the raw data; adjust the window/level (data range) in Dragonfly.

10. Notes & known limitations

• 2D detector frames and series only: reads and stacks 2D frames; it does not reconstruct tomography or produce a 3D volume with true Z spacing.
• No Zeiss Xradia .txrm/.txm or facility-specific tomography layouts (a planned follow-up - would need an olefile-based reader or the real DXchange via conda/git).
• No Z spacing: multi-frame stacks only get X/Y spacing from the detector pixel size.
• Metadata depends on the header: physical pixel size is written only when the header provides EDF PSize; otherwise the Channel has no true calibration.
• Validation status: verified by round-tripping EDF / CBF / TIFF (single- and multi-frame); end-to-end live verification inside a running Dragonfly session is still pending.
• fabio runs strictly in the isolated venv/subprocess and never pollutes Dragonfly's own Python environment.

11. References

• fabio (silx / ESRF) - home & docs: https://github.com/silx-kit/fabio and https://fabio.readthedocs.io ; license: MIT.
• Pillow: https://python-pillow.org (used to render preview thumbnails); NumPy: https://numpy.org.
• Format background: ESRF EDF, imgCIF CBF, Dectris/Pilatus and other detector formats.
• In-plugin docs: DragonflyPlugins/FabioLoader-Plugin/README.md and DESIGN.md (rationale for fabio over DXchange and the follow-up plan).