Load Images (ITK/SimpleITK)(ITK/SimpleITK 科学医学体数据加载)

Load Images (ITK/SimpleITK) - User Manual

Dragonfly Prototype Apps · Load Images (ITK/SimpleITK)...

版本 Version 1.0 · 2026-07-14

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

Load Images (ITK/SimpleITK) 是一个 Dragonfly Prototype Apps 插件,用于在 Dragonfly 内打开 Dragonfly 原生不便直接读取的科学/医学体数据格式,并将其发布为 Dragonfly 的 image Channel。它封装了两套开源影像 I/O 库:主流格式走 SimpleITK(Apache-2.0),Scanco 骨微 CT 专用格式走 ITK 的 itk-ioscanco 远程模块(Apache-2.0)。

支持的格式包括 MetaImage(.mha/.mhd)、NRRD、NIfTI(.nii/.nii.gz)、Analyze(.hdr/.img)、GIPL、VTK、MRC、DICOM(.dcm)、TIFF、PNG/JPG/BMP、HDF5,以及 Scanco microCT 的 .isq/.aim/.rad/.rsq。

输入是磁盘上的一个图像文件;输出是一个或多个发布到 Dragonfly 对象树的 image Channel(多分量/RGB 图像会拆成多个 Channel),并按用户所选单位把体素 spacing 写成米。它定位为 Bio-Formats 加载器(显微成像)的补充,覆盖 ITK/医学影像格式家族。

它不是分割、配准或重建工具;它只负责“读文件 → 建 Channel”。它也不做时间轴/4D 处理,不写回原文件。

2. 适用场景

• 把 NIfTI/NRRD/MetaImage/Analyze/GIPL/VTK 等常见医学与科学体数据导入 Dragonfly 做后续可视化与分析。
• 读取 Scanco 骨微 CT 的 .isq/.aim/.rad/.rsq 原始文件。
• 导入前先 Preview 查看格式、维度、X/Y/Z 尺寸、通道数、像素类型与体素 spacing,再决定是否加载与选用哪个单位。
• 读取 DICOM 单文件、MRC 电镜数据,或作为 2D 图像(TIFF/PNG/JPG/BMP)的通用入口。
• 处理 多分量/RGB 影像,自动拆分为逐通道 Channel。

3. 安装与启用

该插件随 Prototype Apps 完整包(Full Package) 分发。所有插件默认处于未勾选状态,需要手动勾选启用。

1. 把完整包 zip 解压到一个较短的目录(避免 Windows MAX_PATH 路径过长问题),例如 C:\PL。

2. 运行 Install_FullPackage.bat。

3. 在弹出的安装对话框中勾选 Load Images (ITK/SimpleITK)。

4. 点击 Install,安装到 %LOCALAPPDATA%(无需管理员权限)。

5. 完全重启 Dragonfly(菜单仅在启动时扫描一次)。

重启后,菜单项出现在 Prototype Apps > Load Images (ITK/SimpleITK)...,归入 Reconstruction & Imaging(重建与成像) 分组。之后可通过 Developer > Prototype Labs... > Menu Item Manager 随时开启/关闭该插件;每次开关后都需要重启 Dragonfly。

4. 运行环境与首次配置

该插件的计算引擎运行在一个独立 venv(manifest 中 env.kind = venv_in_code)里,与 Dragonfly 自带 Python 完全隔离。Dragonfly 进程内只做 Channel 发布,不导入 SimpleITK/itk。

首次使用需在 Setup 页点击 Setup Environment (SimpleITK + itk-ioscanco) 按钮。它会以 Dragonfly 自带 Python(或你指定的 Base Python)为基础,在插件安装目录下新建 venv/ 子目录并 pip install:numpy、Pillow、SimpleITK、itk-io、itk-ioscanco。这些全部是预编译 wheel —— 不需要 Java,不需要 MSVC 编译器。

• 联网要求:仅首次 Setup 时需要联网下载 wheel(manifest needs_internet = true);之后离线可用。
• GPU:不需要(needs_gpu = false),纯 CPU 读取。
• WSL / 外部工具:无需 WSL,无外部可执行程序(wsl_distro = null)。
• venv 位置:安装后的代码目录 GenericMenuItems\ITKImageLoader\venv。Setup 成功后会把 venv 里的 python.exe 路径写入 Setup 页的 Analysis venv python 字段并保存到配置。
• Base Python 回退:Setup 页的 Base Python 字段留空时自动探测 Dragonfly/系统 Python;也可用 Browse... 手动指定用于建 venv 的 python.exe。
• Job root:临时作业目录,默认 C:\ITKImageLoaderJobs,每次 Preview/Import 会在其下建带时间戳的子目录存放缩略图与 .npy 中间文件。

5. 界面说明

面板顶部为标题说明,主体是一个含 Setup 与 Load 两个选项卡的 TabWidget;底部为状态行(绿色)与只读日志框。

Setup 选项卡

• Analysis venv python:只读展示/可编辑的 venv Python 路径;由 Setup Environment 自动填入(占位提示 “set by Setup Environment”)。
• Base Python + Browse...:建 venv 用的基础 Python;留空则自动探测(占位提示 “blank = auto-detect Dragonfly/system Python”)。
• Job root:作业根目录,默认 C:\ITKImageLoaderJobs。
• Setup Environment (SimpleITK + itk-ioscanco) 按钮:创建 venv 并安装依赖。

Load 选项卡 - File 分组

• Image file + Browse...:选择图像文件;文件过滤器覆盖上述所有 ITK/SimpleITK 扩展名。选文件后若 Output title 为空,会自动填入文件名(不含扩展名)。
• Voxel spacing unit(下拉):millimeter (mm)(默认)、micrometer (µm)、meter (m)、as-is / unitless。
• Preview 按钮:读取头信息 + 中间层缩略图。

Load 选项卡 - 预览区

• 缩略图:左侧显示中间 Z 层的灰度缩略图(默认 “No preview”)。
• 元数据表(Property / Value 两列):File、Format、Dimensions、Size X/Y/Z、Components、Pixel type、Spacing X/Y/Z。

Load 选项卡 - Import 分组

• Output Channel title:输出 Channel 标题;留空则用文件名(占位提示 “defaults to the file name”)。
• Import -> Publish as Channel(s) 按钮(蓝底白字):读入整卷并发布为 Channel。

6. 使用步骤

首次配置

1. 打开 Prototype Apps > Load Images (ITK/SimpleITK)...。

2. 切到 Setup 选项卡,(可选)填 Base Python 与 Job root。

3. 点击 Setup Environment (SimpleITK + itk-ioscanco),等待联网安装完成;状态行显示 “Environment ready.”,venv python 字段被自动填好。

预览与导入

1. 切到 Load 选项卡,用 Browse... 选择图像文件。

2. 选择 Voxel spacing unit(与文件真实单位一致,通常 mm)。

3. 点击 Preview 查看缩略图与元数据(格式、维度、尺寸、通道、像素类型、spacing)。

4. (可选)在 Output Channel title 填写自定义标题。

5. 点击 Import -> Publish as Channel(s);读入整卷,按所选单位把 spacing 换算成米并发布 Channel。

6. 在 Dragonfly 对象树中查看新建的 Channel;状态行会列出发布的 Channel 名称。

7. 参数说明

该插件是一个加载器,可调项很少;下表列出关键控件与其默认值/取值。

8. 输出结果

点击 Import 后,插件先在 venv 子进程内把整卷读入逐通道 .npy 文件,再在 Dragonfly 进程内通过 createChannelFromNumpyArray 发布为 image Channel。

• 单分量图像:发布 1 个 Channel,标题为 Output title(或文件名)。
• 多分量/RGB 图像(components > 1):按分量拆成多个 Channel,标题形如 <title> [C0]、<title> [C1] …
• 几何/spacing:X/Y/Z spacing 按所选单位换算成米(ORS 对象模型约定)写入 Channel;as-is 时不设 spacing。Origin 固定设为 (0,0,0)。
• 数据类型:uint8/uint16/int8/int16/float32 直接保留,其它类型(如 float64、int32)统一转成 float32。
• 位置:新 Channel 出现在 Dragonfly 对象树/数据面板;状态行显示导入的 Channel 数与名称。

9. 常见问题与故障排除

• “Run Setup first, or set the analysis venv python.”:尚未建 venv。到 Setup 页点 Setup Environment,或手动填入已有 venv 的 python 路径。
• Setup 失败:多为无网络或代理阻断了 pip 下载 wheel。确认联网后重试;也可指定一个干净的 Base Python。所有依赖均为预编译 wheel,不需要 Java 或 MSVC。
• “Select a valid image file first.”:未选文件或路径无效,请用 Browse 重新选择。
• Preview / Import failed:日志框会打印具体错误。常见原因是格式不受支持、文件损坏,或 Analyze/.hdr+.img 这类需要配对文件却缺一个。
• Scanco .isq 读取异常:Scanco 路径经 itk.ScancoImageIO 实现,已按文档 API 编写但仍待真实 .isq 样本全面验证;若失败请核对文件完整性。
• 内存不足:Import 会把整卷读入内存并写 .npy,超大体数据可能耗尽内存;可先 Preview 看尺寸,并确保 Job root 所在盘有足够空间。
• 菜单项不出现:确认在安装对话框已勾选该插件并完全重启了 Dragonfly。

10. 注意事项与已知限制

• 主流格式已针对真实 NRRD/MetaImage/NIfTI 验证;Scanco .isq 走文档 API,尚需真实样本端到端验证(live-verify pending)。
• 4D/时间数据按单个体数据读取,暂不做时间轴处理。
• itk-io 单独安装不会注册全部主流 ITK IO,因此主流格式固定走 SimpleITK,itk 仅用于 Scanco 扩展名。
• Origin 始终写 0;若文件带有非零原点信息,导入后不会保留。
• 多分量图像被拆成多个灰度 Channel,不合成 RGB 显示。
• 体素单位需人工选择:文件本身的物理单位因格式而异(常为 mm),选错会导致 spacing 换算错误。
• SimpleITK 与 itk / itk-ioscanco 均为 Apache-2.0,仅在隔离 venv/子进程中运行,绝不进入 Dragonfly 自带 Python。

11. 参考资料

• SimpleITK(Apache-2.0):https://simpleitk.org/ ,文档 https://simpleitk.readthedocs.io/
• ITK / Insight Toolkit(Apache-2.0):https://itk.org/
• itk-ioscanco(ITK 远程模块,读取 Scanco microCT):https://github.com/KitwareMedical/ITKIOScanco
• 插件内文档:DragonflyPlugins/ITKImageLoader-Plugin/README.md 与 DESIGN.md;引擎实现见 itkloader_code/itkloader_core.py。

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 Images (ITK/SimpleITK) is a Dragonfly Prototype Apps plugin for opening scientific/medical volume formats that Dragonfly cannot load natively, and publishing them as Dragonfly image Channels. It wraps two open-source imaging-I/O libraries: mainstream formats go through SimpleITK (Apache-2.0), while Scanco bone-microCT formats go through ITK's itk-ioscanco remote module (Apache-2.0).

Supported formats include MetaImage (.mha/.mhd), NRRD, NIfTI (.nii/.nii.gz), Analyze (.hdr/.img), GIPL, VTK, MRC, DICOM (.dcm), TIFF, PNG/JPG/BMP, HDF5, plus Scanco microCT .isq/.aim/.rad/.rsq.

Input is a single image file on disk; output is one or more image Channels published into Dragonfly's object tree (multi-component/RGB images are split into separate Channels), with voxel spacing written in meters using a user-chosen unit. It complements the Bio-Formats loader (microscopy) by covering the ITK/medical-imaging format family.

It is not a segmentation, registration, or reconstruction tool; it only does "read file → make Channel". It does no time-axis/4D handling and never writes back to the source file.

2. Use cases

• Import common medical/scientific volumes such as NIfTI/NRRD/MetaImage/Analyze/GIPL/VTK into Dragonfly for downstream visualization and analysis.
• Read Scanco bone microCT raw files: .isq/.aim/.rad/.rsq.
• Preview format, dimensions, X/Y/Z sizes, components, pixel type and voxel spacing before importing, and decide whether/what unit to use.
• Open a single-file DICOM, MRC electron-microscopy data, or serve as a general entry for 2D images (TIFF/PNG/JPG/BMP).
• Handle multi-component/RGB images, auto-split into per-channel Channels.

3. Installation & enabling

This plugin ships in the Prototype Apps Full Package. All plugins are unchecked by default and must be enabled manually.

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

2. Run Install_FullPackage.bat.

3. In the installer dialog, check Load Images (ITK/SimpleITK).

4. Click Install; it installs under %LOCALAPPDATA% (no admin rights required).

5. Fully restart Dragonfly (the menu is scanned only at startup).

After restart the item appears under Prototype Apps > Load Images (ITK/SimpleITK)... in the Reconstruction & Imaging(重建与成像) section. You can later toggle it via Developer > Prototype Labs... > Menu Item Manager; restart Dragonfly after each toggle.

4. Runtime environment & first-run setup

The plugin's compute engine runs in an isolated venv (manifest env.kind = venv_in_code), fully separate from Dragonfly's own Python. The Dragonfly process only publishes Channels and never imports SimpleITK/itk.

On first use, open the Setup tab and click Setup Environment (SimpleITK + itk-ioscanco). Using Dragonfly's own Python (or a Base Python you specify), it creates a venv/ subfolder under the installed code directory and pip installs: numpy, Pillow, SimpleITK, itk-io, itk-ioscanco. These are all prebuilt wheels — no Java, no MSVC compiler.

• Internet: required only for the first Setup to download wheels (manifest needs_internet = true); offline afterward.
• GPU: not required (needs_gpu = false); pure-CPU reading.
• WSL / external tools: none (wsl_distro = null).
• venv location: GenericMenuItems\ITKImageLoader\venv under the installed code directory. On success the venv's python.exe is written into the Setup tab's Analysis venv python field and saved to config.
• Base Python fallback: leave the Base Python field blank to auto-detect Dragonfly/system Python, or use Browse... to pick the python.exe used to build the venv.
• Job root: a scratch directory (default C:\ITKImageLoaderJobs); each Preview/Import creates a timestamped subfolder there for the thumbnail and intermediate .npy files.

5. Interface

The panel has a title header, a TabWidget with Setup and Load tabs, and at the bottom a green status line plus a read-only log box.

Setup tab

• Analysis venv python: the venv Python path; auto-filled by Setup Environment (placeholder "set by Setup Environment").
• Base Python + Browse...: the base interpreter for building the venv; blank = auto-detect (placeholder "blank = auto-detect Dragonfly/system Python").
• Job root: scratch root, default C:\ITKImageLoaderJobs.
• Setup Environment (SimpleITK + itk-ioscanco) button: creates the venv and installs dependencies.

Load tab - File group

• Image file + Browse...: pick a file; the file filter covers all the ITK/SimpleITK extensions. Picking a file auto-fills the Output title with the file name (no extension) if it's empty.
• Voxel spacing unit (combo): millimeter (mm) (default), micrometer (µm), meter (m), as-is / unitless.
• Preview button: reads header info + a middle-slice thumbnail.

Load tab - preview area

• Thumbnail: left panel shows a grayscale middle-Z slice (default "No preview").
• Metadata table (Property / Value columns): File, Format, Dimensions, Size X/Y/Z, Components, Pixel type, Spacing X/Y/Z.

Load tab - Import group

• Output Channel title: output Channel title; blank = use the file name (placeholder "defaults to the file name").
• Import -> Publish as Channel(s) button (blue): reads the full volume and publishes Channel(s).

6. How to use

First-run setup

1. Open Prototype Apps > Load Images (ITK/SimpleITK)....

2. Go to the Setup tab and optionally fill Base Python and Job root.

3. Click Setup Environment (SimpleITK + itk-ioscanco) and wait for the online install; the status line shows "Environment ready." and the venv python field is auto-filled.

Preview & import

1. Switch to the Load tab and pick a file with Browse....

2. Choose the Voxel spacing unit matching the file's real unit (usually mm).

3. Click Preview to inspect the thumbnail and metadata (format, dimensions, sizes, components, pixel type, spacing).

4. Optionally type a custom Output Channel title.

5. Click Import -> Publish as Channel(s); the full volume is read, spacing is converted to meters using the chosen unit, and Channel(s) are published.

6. Find the new Channel(s) in Dragonfly's object tree; the status line lists the published Channel names.

7. Parameters

This plugin is a loader with few tunables; the table lists the key controls and their defaults/values.

8. Output

After Import, the plugin first reads the full volume into per-channel .npy files inside the venv subprocess, then publishes them as image Channels in the Dragonfly process via createChannelFromNumpyArray.

• Single-component image: 1 Channel, titled with the Output title (or file name).
• Multi-component/RGB image (components > 1): split into multiple Channels, titled like <title> [C0], <title> [C1], …
• Geometry/spacing: X/Y/Z spacing is converted to meters (the ORS object-model convention) using the chosen unit; as-is sets no spacing. Origin is fixed to (0,0,0).
• Data type: uint8/uint16/int8/int16/float32 are preserved as-is; other types (e.g. float64, int32) are cast to float32.
• Location: new Channels appear in Dragonfly's object tree/data panel; the status line reports how many Channels were imported and their names.

9. FAQ & troubleshooting

• "Run Setup first, or set the analysis venv python.": no venv yet. Click Setup Environment on the Setup tab, or point the field at an existing venv python.
• Setup failed: usually no internet or a proxy blocking pip from downloading wheels. Confirm connectivity and retry; you can also specify a clean Base Python. All deps are prebuilt wheels — no Java or MSVC needed.
• "Select a valid image file first.": no file selected or the path is invalid; re-pick via Browse.
• Preview / Import failed: the log box prints the exact error. Common causes: unsupported format, corrupt file, or a paired-file format like Analyze .hdr+.img missing one member.
• Scanco .isq read errors: the Scanco path uses itk.ScancoImageIO; it follows the documented API but is still pending full verification against a real .isq sample — check file integrity if it fails.
• Out of memory: Import loads the whole volume into memory and writes .npy; very large volumes may exhaust RAM. Preview the size first and ensure the Job root drive has free space.
• Menu item missing: make sure you checked the plugin in the installer dialog and fully restarted Dragonfly.

10. Notes & known limitations

• Mainstream formats are validated against real NRRD/MetaImage/NIfTI; Scanco .isq uses the documented API and still needs an end-to-end check with a real sample (live-verify pending).
• 4D/time data is read as a single volume; no explicit time-axis handling yet.
• Installing itk-io alone does not register all mainstream ITK IOs, so mainstream formats always go through SimpleITK and itk is used only for the Scanco extensions.
• Origin is always written as 0; any non-zero origin stored in the file is not preserved.
• Multi-component images are split into grayscale Channels, not composited into an RGB display.
• Voxel unit must be chosen manually: the file's physical unit varies by format (often mm); the wrong choice yields wrong spacing conversion.
• SimpleITK and itk / itk-ioscanco are all Apache-2.0 and run only in the isolated venv/subprocess, never inside Dragonfly's own Python.

11. References

• SimpleITK (Apache-2.0): https://simpleitk.org/ , docs https://simpleitk.readthedocs.io/
• ITK / Insight Toolkit (Apache-2.0): https://itk.org/
• itk-ioscanco (ITK remote module for Scanco microCT): https://github.com/KitwareMedical/ITKIOScanco
• In-plugin docs: DragonflyPlugins/ITKImageLoader-Plugin/README.md and DESIGN.md; engine implementation in itkloader_code/itkloader_core.py.