Load Images (Bio-Formats)(Bio-Formats 图像加载)

Load Images (Bio-Formats) - User Manual

Dragonfly Prototype Apps · Load Images (Bio-Formats)...

版本 Version 1.0 · 2026-07-14

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 界面说明（续）

7. 使用步骤

8. 参数说明

9. 输出结果

10. 常见问题与故障排除

11. 注意事项与已知限制

12. 参考资料

1. 简介

Load Images (Bio-Formats) 用于在 Dragonfly 内打开其原生不支持的图像文件——约 150 种显微镜 / 厂商 / 数字病理格式，例如 CZI、LIF、ND2、OIB/OIF/OIR、OME-TIFF、LSM、VSI、SVS/NDPI/SCN、IMS 等，并将其 Publish 为 Dragonfly image Channel。

它封装 OME 项目的开源读取库 Bio-Formats（由 bioformats_jar wheel 附带的 formats-gpl JAR，GPL 许可）。通过 jpype + scyjava + bioformats_jar 桥接 JVM——全部为纯 wheel，因此环境安装无需编译器（无需 MSVC）、无需手动安装 JDK；Java 运行时会在首次读取时自动下载。

读取逻辑沿用 UnitedVision 项目 uv_engine 的 Bio-Formats 实现；唯一改动是把 JVM 桥从 python-bioformats + javabridge（编译需 JDK 与 MSVC）换成纯 wheel 的 jpype/scyjava 方案。

输入是磁盘上的文件（文件选择器选取），不是已有的 Dragonfly 对象；输出是一个或多个 image Channel。它是一个文件加载器——不做分割、网格化、配准或测量，只负责读取像素与几何信息并 Publish 为 Channel。

2. 适用场景

• 把共聚焦 / 宽场荧光图像栈（CZI、LIF、ND2、OIB、LSM）导入 Dragonfly 进行三维可视化或后续分析。
• 加载 Dragonfly 无法直接打开的光片及其他专有显微镜采集格式。
• 打开数字病理全切片图像（SVS、NDPI、VSI、SCN）与 OME-TIFF 数据集。
• 在导入前先用 Preview 快速查看文件的维度与元数据（格式、series 数、X/Y/Z、通道数、时间点、像素类型、物理体素尺寸），再决定导入哪个 series / 通道。
• 从 OME 物理像素尺寸元数据中恢复体素 spacing，使导入的 Channel 具有正确的真实世界尺度。

3. 安装与启用

本插件随 Prototype Apps 完整包（Full Package） 一同发布，不单独安装,需通过完整包安装器启用。

1. 将完整包解压到一个较短的目录路径（如 C:\PrototypeApps），以避免 Windows 路径长度限制。

2. 运行 Install_FullPackage.bat。

3. 在安装对话框中勾选 Load Images (Bio-Formats)——所有插件默认均未勾选。

4. 点击 Install。文件安装到 %LOCALAPPDATA% 下（无需管理员权限）。

5. 完全重启 Dragonfly——菜单仅在启动时扫描，运行中的实例不会显示新项。

重启后，它出现在 Prototype Apps > Load Images (Bio-Formats)...，位于 Reconstruction & Imaging(重建与成像) 分组下。

之后可通过 Developer > Prototype Labs... > Menu Item Manager 启用或禁用；每次切换后都需再次重启 Dragonfly 才能生效。

4. 运行环境与首次配置

环境类型：venv_in_code。Bio-Formats 在独立 Python venv中以子进程方式运行，绝不进入 Dragonfly 自身的 Python（Bio-Formats 为 GPL 且需要 JVM）。Dragonfly 进程只负责把子进程产生的 numpy 体数据 Publish 为 Channel。

在 Setup 页点击 Setup Environment (jpype + scyjava + Bio-Formats)。这会基于一个 base Python 创建 venv，并 pip 安装 numpy、Pillow、jpype1、scyjava、bioformats_jar——全部为预编译 wheel，无需编译、无需 MSVC、无需手动 JDK。

• 联网： 需要，但仅首次安装（下载 wheel）与首次读取（下载 Java 运行时）时需要。
• Java 运行时： 首次*读取*时，scyjava/cjdk 会自动下载一个约 40 MB 的 JRE 到 %LOCALAPPDATA%\cjdk，无需系统预装 Java。
• GPU： 不使用。WSL / 外部工具（Fiji、ImageJ）： 不需要。
• venv 位置： 安装代码目录内的 venv 文件夹（GenericMenuItems\BioFormatsLoader\venv）。检测到的 venv python 路径保存在 bioformats_config.json 中，并显示在只读的 Analysis venv python 字段。
• Base Python 回退： 将 Base Python 字段留空可自动检测合适的 Python（依次为 Dragonfly 自带、py 启动器、PATH、常见 Miniconda/Anaconda/系统位置）；若自动检测选错，用 Browse... 手动指定。

5. 界面说明

面板以可停靠窗口打开，标题为 Load Images (Bio-Formats)，含 Setup 与 Load 两个标签页，底部有状态行与只读日志窗格。

Setup 页

• Analysis venv python： venv 解释器路径，由 Setup 自动填入（占位提示为 "set by Setup Environment"）。
• Base Python + Browse...：用于构建 venv 的解释器；留空则自动检测。
• Job root： 各次作业临时文件的工作目录，默认 C:\BioFormatsLoaderJobs。
• Setup Environment (jpype + scyjava + Bio-Formats) 按钮：构建 venv 并安装依赖，pip 输出实时写入日志。

6. 界面说明（续）

Load 页 — File 分组

• Image file: + Browse...：选取输入文件（过滤器列出常见 Bio-Formats 扩展名，始终可选 "All files"）。选取文件后会自动用其基础名填入 Output title。
• Series： 数值框（范围 0–100000，默认 0）；Preview 后其上限被限制为该文件的 series 数。
• Timepoint： 数值框（范围 0–100000，默认 0）；Preview 后其上限被限制为所选 series 的时间点数。
• Preview 按钮：读取头信息与缩略图，不加载完整像素数据。

Load 页 — 预览区

• 缩略图面板： 显示缩放后的预览图（中间 Z、通道 0），或显示 "No preview"。
• 元数据表： Property / Value 表（File、Format、Series count、Selected series、Size X/Y/Z、Channels (C)、Timepoints (T)、RGB channels、Pixel type、Little endian、Physical size X/Y/Z）。

Load 页 — Import 分组

• Output Channel title： 发布 Channel 的基础标题（默认为文件名）。
• Import → Publish as Channel(s) 按钮：读取所选 series/timepoint 并发布 Channel。

7. 使用步骤

1. 仅首次： 打开 Setup 页，点击 Setup Environment (jpype + scyjava + Bio-Formats)，等待出现 "Environment ready."。

2. 切到 Load 页，用 Browse... 选取图像文件。

3. 点击 Preview 查看缩略图与元数据，留意 series 数与维度。

4. 若文件含多个 series 或时间点，设置 Series 与 Timepoint。

5. 可选：修改 Output Channel title（默认为文件名）。

6. 点击 Import → Publish as Channel(s)。进度实时写入日志；成功后状态行列出所创建的 Channel 名称。

每次 Preview 与 Import 都是全新子进程（因而是全新的 JVM），因为 jpype 无法在同一进程内重启 JVM；重复运行是安全的。

8. 参数说明

本插件是加载器，可调项主要是文件选择、series/timepoint 选择，以及 Setup 页字段：

Analysis venv python 字段由 Setup 自动设置，通常无需手动编辑。内部缩略图尺寸上限为 512 px。

9. 输出结果

Import 会创建一个或多个 Dragonfly image Channel，发布到当前会话的对象树（Data Properties）。

• 命名： 单通道、单 series 的文件以基础标题命名。存在多个输出时，Channel 加后缀：<title> [S<series> C<c>]（打包 RGB 分量为 ... comp<k>），非 0 series 的单输出为 <title> [S<series>]。
• 多通道： 每个有效通道成为独立的灰度 Channel；打包 RGB 会拆分成各分量 Channel（不是单个合成图）。
• 几何： 体素 spacing（X/Y/Z）由 OME 物理像素尺寸换算为 米（ORS 约定）；origin 设为 (0, 0, 0)；体数据以 (Z, Y, X) 存储。
• 数据类型： uint8/uint16/int8/int16/float32 原样保留；其他像素类型在发布前转换为 float32。

10. 常见问题与故障排除

• "Run Setup first, or set the analysis venv python." —— venv 尚未构建。到 Setup 页点击 Setup Environment。
• Setup 失败 / "No base Python found"。 —— 自动检测未找到含 venv + ensurepip 的可用 Python。用 Browse... 显式指定 Base Python（如 Dragonfly 自带 python.exe 或 Miniconda python）后重试。
• Setup 超时或 wheel 下载失败。 —— Setup 需要联网。检查网络/代理后重试，pip 输出见日志窗格。
• 首次读取很慢或似乎卡住。 —— 首次读取时 scyjava/cjdk 会下载约 40 MB 的 Java 运行时；之后读取会很快。
• "Select a valid image file first." —— 文件路径为空或不存在；用 Browse... 选取真实文件。
• 某个文件 Preview 或 Import 失败。 —— 该格式可能不受支持或文件损坏；错误类别与信息显示在状态行与日志中。若扩展名被过滤，可在选择器中选 "All files"。
• 大文件内存不足。 —— 整个 series 会在发布前读入内存。可导入较小的 series/timepoint，或使用内存更大的机器。

11. 注意事项与已知限制

• 每次导入一个时间点（可选）。完整 T 序列循环为后续工作。
• 多通道以独立灰度 Channel 发布，而非单个合成/RGB 通道。
• 整文件读取： 超大 / 金字塔图像在发布前完整读入内存；分块/惰性读取尚未实现。
• Bio-Formats（formats-gpl）为 GPL 许可。 它只在独立 venv/子进程中运行，绝不进入 Dragonfly 自身的 Python。
• 物理尺寸： 若文件无 OME 物理像素尺寸元数据，spacing 保持未设（单位间距）；origin 始终为 (0, 0, 0)。
• 验证状态： 读取引擎已在真实 CZI 文件上离线验证；在运行中的 Dragonfly 会话内对 Channel 发布环节的端到端验证仍待完成。

12. 参考资料

• Bio-Formats (OME) —— 读取库。主页：https://www.openmicroscopy.org/bio-formats/ ；文档：https://bio-formats.readthedocs.io/ 。许可：GPL（formats-gpl）。
• bioformats_jar（PyPI）—— 附带 Bio-Formats JAR 与 get_loci()：https://pypi.org/project/bioformats-jar/
• scyjava / cjdk —— JVM 桥与自动下载的 JRE：https://github.com/scijava/scyjava
• JPype (jpype1) —— Python 到 JVM 的桥：https://jpype.readthedocs.io/
• 仓库内插件文档：DragonflyPlugins/BioFormatsLoader-Plugin/README.md 与 DESIGN.md。

Part II English Manual

Contents

1. Introduction

2. Use cases

3. Installation & enabling

4. Runtime environment & first-run setup

5. Interface

6. Interface (continued)

7. How to use

8. Parameters

9. Output

10. FAQ & troubleshooting

11. Notes & known limitations

12. References

1. Introduction

Load Images (Bio-Formats) opens image files that Dragonfly does not read natively — roughly 150 microscopy / vendor / digital-pathology formats such as CZI, LIF, ND2, OIB/OIF/OIR, OME-TIFF, LSM, VSI, SVS/NDPI/SCN, IMS and many more — and publishes them as Dragonfly image Channel(s).

It wraps the open-source Bio-Formats reader from the OME project (the formats-gpl JAR shipped by the bioformats_jar wheel, GPL licensed). The JVM is bridged from Python with jpype + scyjava + bioformats_jar — all pure wheels — so the environment installs with no compiler (no MSVC) and no manually installed JDK; a small Java runtime is auto-provisioned on first read.

The reader logic is carried over from the UnitedVision project's uv_engine Bio-Formats implementation; the only change is swapping the JVM bridge from python-bioformats + javabridge (which needs a JDK and MSVC to build) to the pure-wheel jpype/scyjava stack.

Input is a file on disk (chosen with a file picker), not an existing Dragonfly object. Output is one or more image Channels. This is a file loader — it does not segment, mesh, register, or measure; it only reads pixels + geometry and publishes Channels.

2. Use cases

• Importing confocal / widefield fluorescence stacks (CZI, LIF, ND2, OIB, LSM) into Dragonfly for 3D visualization or downstream analysis.
• Loading light-sheet and other proprietary microscope acquisitions that Dragonfly cannot open directly.
• Opening whole-slide digital-pathology images (SVS, NDPI, VSI, SCN) and OME-TIFF datasets.
• Quickly inspecting a file's dimensions and metadata (format, series count, X/Y/Z, channels, timepoints, pixel type, physical voxel size) via Preview before deciding which series/channel to import.
• Recovering voxel spacing from OME physical pixel-size metadata so the imported Channel is correctly scaled in real-world units.

3. Installation & enabling

This plugin ships in the Prototype Apps Full Package. It is not installed on its own — you enable it through the Full Package installer.

1. Unzip the Full Package to a short directory path (e.g. C:\PrototypeApps) to stay within Windows path-length limits.

2. Run Install_FullPackage.bat.

3. In the installer dialog, tick Load Images (Bio-Formats) — all plugins are unchecked by default.

4. Click Install. Files are copied under %LOCALAPPDATA% (no administrator rights needed).

5. Fully restart Dragonfly — the menu is scanned only at startup, so a running instance will not show the new item.

After restart it appears under Prototype Apps > Load Images (Bio-Formats)... in the Reconstruction & Imaging(重建与成像) section.

You can later enable or disable it from Developer > Prototype Labs... > Menu Item Manager. Toggling requires another Dragonfly restart to take effect.

4. Runtime environment & first-run setup

Environment kind: venv_in_code. Bio-Formats runs in an isolated Python venv as a subprocess, never inside Dragonfly's own Python (Bio-Formats is GPL and needs a JVM). Dragonfly's process only publishes the resulting numpy volumes as Channels.

On the Setup tab, click Setup Environment (jpype + scyjava + Bio-Formats). This builds a venv from a base Python and pip-installs numpy, Pillow, jpype1, scyjava, and bioformats_jar — all prebuilt wheels, so there is no compilation, no MSVC, and no manual JDK.

• Internet: required, but only for this one-time setup (downloading wheels) and for the first read (downloading the Java runtime).
• Java runtime: on the first *read*, scyjava/cjdk auto-downloads a small JRE (~40 MB) to %LOCALAPPDATA%\cjdk. No system Java is needed.
• GPU: not used. WSL / external tools (Fiji, ImageJ): not required.
• venv location: a venv folder inside the installed code directory (GenericMenuItems\BioFormatsLoader\venv). The detected venv python path is stored in bioformats_config.json and shown in the read-only Analysis venv python field.
• Base Python fallback: leave the Base Python field blank to auto-detect a suitable Python (Dragonfly's own, then py launcher, PATH, common Miniconda/Anaconda/system locations). Set it explicitly with Browse... if auto-detection picks the wrong interpreter.

5. Interface

The panel opens as a dockable window titled Load Images (Bio-Formats) with two tabs — Setup and Load — plus a status line and a read-only log pane at the bottom.

Setup tab

• Analysis venv python: path to the venv interpreter; populated by Setup (placeholder "set by Setup Environment").
• Base Python + Browse...: interpreter used to build the venv; blank = auto-detect.
• Job root: working directory for per-job temp files; defaults to C:\BioFormatsLoaderJobs.
• Setup Environment (jpype + scyjava + Bio-Formats) button: builds the venv and installs dependencies, streaming pip output to the log.

6. Interface (continued)

Load tab — File group

• Image file: + Browse...: pick the input file (filter lists common Bio-Formats extensions; "All files" is always available). Picking a file auto-fills the Output title with the base file name.
• Series: spin box (range 0–100000, default 0); its maximum is clamped to the file's series count after Preview.
• Timepoint: spin box (range 0–100000, default 0); its maximum is clamped to the selected series' T count after Preview.
• Preview button: reads headers + a thumbnail without loading full pixel data.

Load tab — preview area

• Thumbnail panel: shows a scaled preview image (middle Z, channel 0) or "No preview".
• Metadata table: a Property / Value table (File, Format, Series count, Selected series, Size X/Y/Z, Channels (C), Timepoints (T), RGB channels, Pixel type, Little endian, Physical size X/Y/Z).

Load tab — Import group

• Output Channel title: base title for published Channels (defaults to the file name).
• Import → Publish as Channel(s) button: reads the chosen series/timepoint and publishes the Channel(s).

7. How to use

1. First run only: open the Setup tab and click Setup Environment (jpype + scyjava + Bio-Formats); wait for "Environment ready."

2. Switch to the Load tab and Browse... to your image file.

3. Click Preview to see the thumbnail and metadata; note the series count and dimensions.

4. If the file has multiple series or timepoints, set Series and Timepoint.

5. Optionally edit Output Channel title (defaults to the file name).

6. Click Import → Publish as Channel(s). Progress streams to the log; on success the status line lists the Channel name(s) created.

Each Preview and each Import is a fresh subprocess (hence a fresh JVM), because jpype cannot restart a JVM within one process. Re-running is safe.

8. Parameters

This is a loader, so the tunable inputs are the file selection and the series/timepoint choice, plus the setup fields:

The Analysis venv python field is set automatically by Setup and is normally not edited by hand. The internal thumbnail size cap is 512 px.

9. Output

Import creates one or more Dragonfly image Channel(s), published into the current session's object tree (Data Properties).

• Naming: a single-channel, single-series file is titled with the base title. When there is more than one output, Channels are suffixed: <title> [S<series> C<c>] (or ... comp<k> for packed-RGB components), and <title> [S<series>] for a single output of a non-zero series.
• Multi-channel: each effective channel becomes its own grayscale Channel; packed-RGB is split into per-component Channels (not a single composite).
• Geometry: voxel spacing (X/Y/Z) is set from the OME physical pixel size, converted to meters (the ORS convention). Origin is set to (0, 0, 0). Volumes are stored as (Z, Y, X).
• Data types: uint8/uint16/int8/int16/float32 are preserved; any other pixel type is cast to float32 before publishing.

10. FAQ & troubleshooting

• "Run Setup first, or set the analysis venv python." — The venv is not built yet. Go to the Setup tab and click Setup Environment.
• Setup fails / "No base Python found". — Auto-detection could not find a usable Python with venv + ensurepip. Set Base Python explicitly via Browse... (e.g. Dragonfly's own python.exe or a Miniconda python) and retry.
• Setup times out or a wheel fails to download. — Setup needs internet. Check connectivity/proxy and re-run; pip output is in the log pane.
• First read is slow or seems to hang. — On the first read, scyjava/cjdk downloads a ~40 MB Java runtime; subsequent reads are fast.
• "Select a valid image file first." — The file path is empty or does not exist; use Browse... to pick a real file.
• Preview or Import fails on a specific file. — The format may be unsupported or the file corrupt; the error category and message are shown in the status line and log. Try "All files" in the picker if the extension was filtered out.
• Out-of-memory on a very large file. — The whole series is read into memory before publishing. Import a smaller series/timepoint, or a machine with more RAM.

11. Notes & known limitations

• One timepoint per import (selectable). A full T-series loop is future work.
• Multi-channel is published as separate grayscale Channels, not a single composite/RGB channel.
• Whole-file read: very large / pyramidal images are read fully into memory before publishing; tiled/lazy reading is not yet implemented.
• Bio-Formats (formats-gpl) is GPL. It runs only in the isolated venv/subprocess, never inside Dragonfly's own Python.
• Physical size: if the file has no OME physical pixel-size metadata, spacing defaults are left unset (unit spacing); origin is always (0, 0, 0).
• Validation status: the reader engine was validated offline on a real CZI file; end-to-end verification of the Channel publish step inside a live Dragonfly session is still pending.

12. References

• Bio-Formats (OME) — reader library. Home: https://www.openmicroscopy.org/bio-formats/ ; docs: https://bio-formats.readthedocs.io/ . License: GPL (formats-gpl).
• bioformats_jar (PyPI) — ships the Bio-Formats JAR + get_loci(): https://pypi.org/project/bioformats-jar/
• scyjava / cjdk — JVM bridge and auto-provisioned JRE: https://github.com/scijava/scyjava
• JPype (jpype1) — Python-to-JVM bridge: https://jpype.readthedocs.io/
• Plugin docs in the repo: DragonflyPlugins/BioFormatsLoader-Plugin/README.md and DESIGN.md.