Volume Registration (Elastix)（体积配准）

Volume Registration (Elastix) - User Manual

Dragonfly Prototype Apps · Volume Registration (Elastix)...

版本 Version 1.0 · 2026-08-01

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

把一个三维通道（移动图像）对齐到另一个三维通道（固定图像），使用开源的 elastix（Apache 2.0，基于 ITK）。支持平移、刚体、仿射与 B 样条自由形变，可以单独使用，也可以串联——例如「刚体 + B 样条」先做整体对齐再做局部形变，这是 elastix 的标准工作流程。

面板分为 6 个编号步骤。任何上游输入或参数变化都会使结果失效；配准在工作线程与独立子进程中运行，取消或失败都不会发布任何东西。

所有计算按物理毫米进行。 各向异性体素无需重采样——把真实间距交给 elastix 即可，既正确又无损。（这一点与「结构尺度分析」插件不同：那里的腐蚀步是体素操作，确实需要重采样。）

配准变差时不会伪装成成功。 结果页给出配准前后的 RMS 与改善百分比；若配准后反而更差，会明确提示，并且拒绝发布配准后的通道。

2. 适用场景

• 同一样品的两次扫描对齐：原位实验、加载前后、老化前后、腐蚀前后。
• 多模态 / 多能谱数据配准（用 Mattes 互信息测度）。
• 把一次扫描上已经做好的分割迁移到另一次扫描：用第 4 步的 ROI / MultiROI 变换。
• 模板或图谱配准。
• 不同分辨率、不同视野的数据之间的对齐。

3. 安装与启用

1. 安装 Prototype Apps 完整包（或在 App Store 中勾选本插件）。

2. 本插件默认未启用，请在 App Store 或菜单项管理器中启用。

3. 完全重启 Dragonfly（插件只在启动时被发现）。

4. 从菜单打开：Prototype Apps ▸ Volume Registration (Elastix)…（分组：Reconstruction & Imaging）。

4. 运行环境与首次配置

首次使用请在第 1 步点击 Set up environment (numpy + itk-elastix)。它会建立一个独立虚拟环境并联网下载约 120 MB 的预编译 wheel（CPython 3.10 / Windows，无需编译器）。完成后即可离线使用。

为什么用独立环境？ ITK 自带若干与 Dragonfly 同名的库，混用会出问题；而且本仓库的硬性规则是绝不修改 Dragonfly 自带的 Python。因此配准以子进程方式运行，通过作业目录交换 .npy 文件。

配置结束时会真正 import 一次 itk 并检查 elastix 接口是否可用——宁可在配置阶段（此时 pip 日志还在屏幕上）失败，也不要等到用户第一次配准时才失败。Check environment 按钮可随时复查，并显示 ITK 版本号。

作业目录默认 C:\ElastixJobs，遵循 App Store 的全局作业目录设置。每次运行会新建一个带时间戳的子目录，里面保存输入、elastix.log、runner_log.txt、变换文件与全部输出。

5. 界面说明

顶部固定显示运行环境、当前输入、当前任务、进度条与 Cancel。

1. 环境

venv 解释器路径、基础解释器（留空自动检测）、作业目录，以及配置与检查按钮。

2. 输入与掩膜

选择固定通道与移动通道（只列出已发布对象）、时间步，以及可选的固定 / 移动掩膜 ROI。选定后显示两者的形状与间距，并在必要时给出提示：尺寸不一致、间距各向异性、两者是同一个对象。

3. 变换与参数

变换链、多分辨率层数、每层迭代次数、相似性测度、B 样条最终网格间距、每次迭代采样点数、是否计算形变场，以及在对象缺少几何信息时手动指定体素尺寸。

4. 预览与运行

以一行文字列出将要执行的完整方案（含自动生成的网格间距序列、掩膜导致的参数改动），并可选择同时要变换的 ROI / MultiROI，然后运行。

5. 结果

配准前后的 RMS、改善百分比、各阶段、耗时、形状、ITK 版本、作业目录，以及（若已计算）形变幅值的最大值与平均值。

6. 应用与导出

发布配准后的通道、形变幅值通道、变换后的 ROI / MultiROI；导出结果 JSON；打开作业目录。

6. 使用步骤

1. 第 1 步点击 Set up environment（仅首次），等待显示 itk-elastix ready。

2. 第 2 步选择固定通道与移动通道，必要时加掩膜。

3. 第 3 步先用默认的 rigid 试一次，确认整体能对上。

4. 需要局部形变时改用 rigid+bspline，并按结构尺度设置 B 样条网格间距。

5. 第 4 步（可选）选择要一起变换的 ROI / MultiROI，然后运行。

6. 第 5 步检查改善百分比；第 6 步发布或导出。

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

• 改善百分比为负 —— 优化发散了。先用更少的层数或换 rigid 试试；跨模态数据请确认测度选的是 mattes；也可以加掩膜把背景排除掉。此时插件不会发布结果。
• 配准失败并提示 elastix.log —— 错误信息中已附带 elastix 日志的末尾若干行，其中会指出 elastix 反对的具体参数。完整日志在作业目录里。
• Set up environment 失败 —— 通常是网络或代理问题；错误信息里带有 pip 日志末尾。可在第 1 步手动指定一个基础解释器（需 Python 3.10）。
• 两个通道尺寸不同 —— elastix 仍可配准，但配准前后的 RMS 无法计算，界面会说明「无法比较」，而不是显示 0。
• 变换后的标签出现了奇怪的数值 —— 不应发生：本插件对 ROI / MultiROI 强制使用最近邻插值。若确实遇到，请附作业目录反馈。
• B 样条很慢 —— 这是正常的，B 样条比刚体慢一个量级。可先降低层数与迭代次数试参数，确认后再跑完整设置。

10. 注意事项与已知限制

• 整卷读入内存，并以 float32 写入作业目录。超大体积请先裁剪。
• 输入必须是已发布的通道；未发布对象不会出现在下拉列表中。
• 发布是单独的一步。 运行结束不会自动发布任何对象，需要在第 6 步明确选择。
• 移动掩膜会自动关闭 ErodeMask。 否则最粗一层上掩膜会被腐蚀成空，elastix 报「所有采样点都落在图像外」。
• 本插件不重新实现任何配准算法，全部由 elastix 完成；插件负责 Dragonfly 集成与参数处理。
• 重新安装插件会刷新代码与 runner，但保留 venv 与 elastix_config.json。

11. 参考资料

S. Klein, M. Staring, K. Murphy, M.A. Viergever, J.P.W. Pluim, "elastix: a toolbox for intensity based medical image registration", IEEE Transactions on Medical Imaging, 29(1), pp. 196–205, 2010. 若发表使用本插件得到的结果，请引用该文。elastix 与 ITK 均采用 Apache 2.0 许可。

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

Aligns one 3D Channel (the moving image) onto another (the fixed image) using the open-source elastix toolkit (Apache 2.0, built on ITK). Translation, rigid, affine and B-spline free-form deformation are available alone or chained — "rigid + bspline" does a global alignment first and a local deformation second, which is the standard elastix workflow.

The panel has 6 numbered steps. Changing anything upstream invalidates the result; registration runs on a worker thread in a separate process, and cancelling or failing publishes nothing.

Everything is computed in physical millimetres. Anisotropic voxels need no resampling — passing elastix the true spacing is both correct and lossless. (This differs from the Structure Scale Analyzer, where an erosion step is a voxel operation and resampling genuinely is required.)

A registration that made things worse is not dressed up as success. The results tab reports RMS before and after with an improvement percentage; if the alignment got worse it says so, and publishing the registered Channel is refused.

2. Use cases

• Aligning two scans of one specimen: in-situ experiments, before/after loading, ageing, corrosion.
• Multi-modal or multi-energy registration (use the Mattes mutual-information metric).
• Carrying a finished segmentation from one scan to another, via the ROI / MultiROI warping in step 4.
• Template or atlas registration.
• Aligning data acquired at different resolutions or fields of view.

3. Installation & enabling

1. Install the Prototype Apps package (or tick this plugin in the App Store).

2. This plugin is disabled by default — enable it in the App Store or the Menu Item Manager.

3. Restart Dragonfly completely (plugins are discovered at startup only).

4. Open it from: Prototype Apps ▸ Volume Registration (Elastix)… (group: Reconstruction & Imaging).

4. Runtime environment & first-run setup

On first use press Set up environment (numpy + itk-elastix) in step 1. It builds an isolated virtual environment and downloads about 120 MB of prebuilt wheels (CPython 3.10 / Windows, no compiler needed). After that it works offline.

Why an isolated environment? ITK ships its own copies of several libraries that Dragonfly also carries, and the repo rule is that Dragonfly's bundled Python is never modified. Registration therefore runs as a subprocess, exchanging .npy files through a job folder.

Setup finishes by importing itk once and checking the elastix entry points — better to fail during setup, with the pip log still on screen, than during the user's first registration. Check environment re-verifies at any time and reports the ITK version.

The job root defaults to C:\ElastixJobs and follows the App Store's global job-root setting. Each run creates a timestamped subfolder holding the inputs, elastix.log, runner_log.txt, the transform files and every output.

5. Interface

The header always shows the environment, the current input, the running task, a progress bar and Cancel.

1. Setup

The venv interpreter, an optional base interpreter, the job root, and the setup / check buttons.

2. Input & Masks

Pick the fixed and moving Channels (published objects only), the timestep, and optional fixed / moving mask ROIs. Shapes and spacings are shown, with warnings where they matter: mismatched shapes, anisotropic spacing, or the same object picked twice.

3. Transform & Parameters

The transform chain, number of resolutions, iterations per resolution, metric, B-spline final grid spacing, samples per iteration, whether to compute the deformation field, and a manual voxel size for objects that carry no geometry.

4. Preview & Run

One line spelling out exactly what will run — including the auto-generated grid-spacing schedule and any parameter forced by a mask — plus the optional ROI / MultiROI to warp alongside, then Run.

5. Results

RMS before and after, improvement percentage, the stages actually run, timing, shape, ITK version, the job folder, and (if computed) the maximum and mean deformation magnitude.

6. Apply & Export

Publish the registered Channel, the deformation-magnitude Channel, or the warped ROI / MultiROI; export the results as JSON; open the job folder.

6. How to use

1. Press Set up environment in step 1 (first time only) and wait for "itk-elastix ready".

2. In step 2 pick the fixed and moving Channels, adding masks if useful.

3. In step 3 try the default rigid chain first and confirm the global alignment works.

4. For local deformation switch to rigid+bspline and set the grid spacing to your structure scale.

5. In step 4 optionally choose an ROI / MultiROI to warp too, then Run.

6. Check the improvement percentage in step 5, then publish or export in step 6.

7. Parameters

8. Output

9. FAQ & troubleshooting

• The improvement percentage is negative — the optimiser diverged. Try fewer resolutions or the plain rigid chain; for multi-modal data make sure the metric is mattes; a mask that excludes background often helps. The plugin will not publish in this state.
• A failure mentions elastix.log — the tail of elastix's own log is attached to the error and names the parameter it objected to. The full log is in the job folder.
• Set up environment fails — usually network or proxy; the error carries the tail of the pip log. You can point step 1 at a specific base interpreter (Python 3.10).
• The two Channels have different shapes — elastix can still register them, but RMS before/after cannot be computed. The panel says the comparison is unavailable rather than showing 0.
• Warped labels contain odd values — this should not happen: ROI and MultiROI warping is forced to nearest neighbour. If you see it, please report the job folder.
• B-spline is slow — expected; it is an order of magnitude slower than rigid. Explore parameters at a low resolution/iteration count first.

10. Notes & known limitations

• The whole volume is read into memory and written to the job folder as float32. Crop very large volumes first.
• Inputs must be published Channels; unpublished objects do not appear in the pickers.
• Publishing is a separate step. Nothing is published automatically when a run finishes — choose it explicitly in step 6.
• A moving mask automatically turns ErodeMask off, otherwise the mask erodes to nothing at the coarsest resolution and elastix reports that every sample fell outside the image.
• No registration algorithm is reimplemented here — elastix does the work; the plugin provides the Dragonfly integration and the parameter handling.
• Reinstalling the plugin refreshes the code and runner but keeps the venv and elastix_config.json.

11. References

S. Klein, M. Staring, K. Murphy, M.A. Viergever, J.P.W. Pluim, "elastix: a toolbox for intensity based medical image registration", IEEE Transactions on Medical Imaging, 29(1), pp. 196–205, 2010. Please cite it if you publish results obtained with this plugin. elastix and ITK are both Apache 2.0 licensed.