Slice Registration (Non-Rigid)(非刚性切片配准)

Slice Registration (Non-Rigid) - User Manual

Dragonfly Prototype Apps · Slice Registration (Non-Rigid)...

版本 Version 1.0 · 2026-07-14

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

Slice Registration (Non-Rigid)（非刚性切片配准） 对一个 Dragonfly 图像 Channel（Z 方向为一叠 2D 切片的图像栈）逐切片做非刚性/弹性配准，并输出一个已对齐的新 Channel。它封装成熟开源库 SimpleITK（ITK 的简化 API，Insight Toolkit），许可证为 Apache-2.0。流程可选线性预配准（平移 / 刚性 / 仿射），再叠加非刚性步骤——B-spline 自由变形（FFD） 或 diffeomorphic Demons。

它用于弥补 Dragonfly 自带的切片配准只做刚性 / 平移的不足。当相邻切片之间存在局部形变（弯曲、拉伸、扭曲）而不仅是整体平移或旋转时，本插件的弹性配准能够恢复这种形变。输入为一个至少含 2 张切片的图像 Channel；输出为一个新 Channel 以及逐切片的 diagnostics.csv。

它不是：不做完整的三维体配准（每张切片在自身平面内独立配准）；不是仅刚性工具；也尚未将计算出的形变传播到关联的 ROI/MultiROI 标签栈。

2. 适用场景

• 连续切片（serial-section）显微 / 组织切片栈：物理切片过程在相邻切片间引入局部畸变。
• 电子显微镜切片序列，切片之间存在扭曲。
• 任意 Z 向图像栈：切片之间以局部形变（弯曲、拉伸、撕裂）为主，而非单纯的整体平移/旋转。
• 校正长序列切片间的累积漂移（使用“逐前一张（顺序传播）”参考方式）。
• 当 Dragonfly 自带的刚性切片配准仍残留明显错位时，作为更强的替代方案。

3. 安装与启用

本插件随 Prototype Apps 完整包（Full Package） 一起分发。所有插件默认均未勾选，因此安装时必须显式启用它。

1. 将完整包解压到一个短路径目录（例如 C:\PLApps），以避免 Windows MAX_PATH 长度问题。

2. 运行 Install_FullPackage.bat。

3. 在安装对话框中勾选 "Slice Registration (Non-Rigid)"，然后点击 Install。

4. 完全重启 Dragonfly——菜单仅在启动时扫描，正在运行的实例不会出现新条目。

5. 从 Prototype Apps > Slice Registration (Non-Rigid)... 打开，位于 "Reconstruction & Imaging(重建与成像)" 分组下。

之后可通过 Developer > Prototype Labs... > Menu Item Manager 启用或禁用。插件安装在 %LOCALAPPDATA% 下（无需管理员权限）。每次启用/禁用切换后都需重启 Dragonfly。开发机上也可用 Dragonfly 的 Python 运行 install_slice_registration_nonrigid_plugin.py（--uninstall 可卸载）。

4. 运行环境与首次配置

本插件采用 venv_in_code 模式：重依赖（SimpleITK）在独立的虚拟环境/子进程中运行，绝不进入 Dragonfly 自身的 Python。首次配准前，须先在 Setup 页构建该 venv。

• Setup Environment (numpy + SimpleITK) 按钮——创建一个 venv（由 runner/setup_env.py 完成），其 base 为 Dragonfly 自带的 Python 3.10，随后 pip install 精确安装 numpy 与 SimpleITK（runner/requirements.txt）。
• 下载大小： 约几十 MB。由于 Python 3.10 有 SimpleITK 的预编译 CPython wheel，安装无需编译器。
• 联网： 仅此一次配置时需要（needs_internet: true）。配准本身完全离线运行。
• GPU： 不使用（needs_gpu: false）。无需 Fiji、ImageJ、Java 或 WSL。
• venv 位置： 位于已安装代码目录内的 venv/ 文件夹（...\GenericMenuItems\SliceRegNonRigid\venv）。解析出的解释器会写回 Analysis venv python 字段并保存到 slicereg_config.json。
• Base Python 字段——用于创建 venv 的基础解释器的可选覆盖项。留空则自动探测 Dragonfly / 系统 Python；用 Browse... 指向具体的 python.exe（例如自动探测到的解释器缺少可用 pip 时）。
• Job root——导出栈和结果的工作目录，默认 C:\SliceRegNonRigidJobs。每次运行创建带时间戳的 slicereg_<YYYYMMDD_HHMMSS> 子文件夹。

5. 界面说明

面板顶部有标题行，下含三个标签页——Setup、Registration、Summary，底部为状态栏与日志窗格。

Setup 页

• Analysis venv python——venv 解释器路径；通常由 Setup Environment 自动填写。
• Base Python（+ Browse...）——用于构建 venv 的可选基础解释器；留空为自动探测。
• Job root——工作目录（默认 C:\SliceRegNonRigidJobs）。
• Setup Environment (numpy + SimpleITK) 按钮——构建 venv 并安装依赖。

Registration 页 — Input Channel（图像栈）

• Stack Channel 下拉框——列出 Dragonfly 的 Channel（标题 + 形状）；Refresh 按钮重新扫描当前会话。

Registration 页 — Reference

• Reference mode——*Previous slice (sequential, propagated)*（逐前一张，顺序传播）或 *Fixed reference slice (all-to-one)*（固定参考切片，全部对到一张）。
• Reference/anchor index——顺序模式的锚点切片或固定模式的模板切片；-1 = 中间切片。其最大值随所选 Channel 的切片数自动钳制。

Registration 页 — Method

• Linear pre-alignment——None / Translation / Rigid (Euler) / Affine。
• Non-rigid method——B-spline 自由变形 / Diffeomorphic Demons / None（仅线性）。

Registration 页 — Parameters

• Similarity metric——Mattes 互信息 / 均方差 / 相关。当使用线性阶段或 B-spline 时可用。
• Iterations (linear/B-spline)、Metric sampling fraction、Pyramid levels——控制线性 + B-spline 优化器阶段。
• B-spline grid nodes——仅 B-spline 时可用；每维控制点网格节点数（越高越灵活/越慢）。
• Demons iterations 与 Demons smoothing sigma——仅 Demons 时可用；sigma 平滑位移场（单位像素）。
• Output interpolation——最终重采样用 Linear 或 Nearest neighbour。
• Fill value (out of bounds)——重采样后越界像素填充值。

Registration 页 — Output 与运行

• Output Channel——发布结果的标题（默认 *Slice-registered (non-rigid)*）。
• Run Non-Rigid Slice Registration 按钮——校验输入并启动任务。

Summary 页

• 运行后填充的 Metric / Value 两列表格（切片数、参考索引、方法、配准前后平均 MAD、改进百分比、失败数）。

6. 使用步骤

1. 仅首次： 打开 Setup 页，点击 Setup Environment (numpy + SimpleITK)；等待状态显示“Environment ready”且 venv python 路径出现。

2. 切到 Registration 页，点击 Refresh 列出 Channel，选择 Stack Channel（须 ≥ 2 张切片）。

3. 选择 Reference mode：序列切片有漂移用 *Previous slice*，全部对齐到一张模板用 *Fixed reference slice*。设置 Reference/anchor index（-1 = 中间）。

4. 选择 Linear pre-alignment 与 Non-rigid method（至少一项非 None）。

5. 调节 Parameters——度量、迭代、采样比例、金字塔层数，以及按方法设定的 B-spline 网格或 Demons 迭代/sigma；设置输出插值与填充值。

6. 填写 Output Channel 标题，点击 Run Non-Rigid Slice Registration。

7. 观察日志；完成后面板切到 Summary 页，发布对齐后的 Channel，并报告 diagnostics.csv 路径。

7. 参数说明

线性阶段使用 RegularStepGradientDescent（自限步长），B-spline 使用 LBFGS-B；Demons 使用 FastSymmetricForcesDemonsRegistrationFilter 并配合直方图匹配。金字塔作用于线性 + B-spline 优化器阶段。

8. 输出结果

成功后，插件通过 createChannelFromNumpyArray 用对齐后的图像栈创建一个新的 Dragonfly Channel，标题取自 Output Channel 字段（默认 "Slice-registered (non-rigid)"）。它像其他 Channel 一样出现在数据属性/对象树中。

• 几何： 输出复制源 Channel 的 spacing（X/Y/Z）与 origin，因此与输入对齐叠合。每张移动切片被重采样到参考网格，故对齐后的栈保持输入尺寸。
• 诊断： 逐切片的 diagnostics.csv（列 index, reference, ok, mad_before, mad_after, error）写入 Job root 下的带时间戳任务文件夹；其路径在状态栏中报告。
• 汇总： Summary 页表格报告 n_slices、n_registered、reference_index、ref_mode、所选方法/度量、mean_mad_before、mean_mad_after、improvement_percent 与 n_failed。

9. 常见问题与故障排除

• “Run Setup first, or set the analysis venv python.”——venv 尚未构建。请在 Setup 页点击 Setup Environment。
• 配置失败 / 无网络——首次安装需从 PyPI 拉取 numpy + SimpleITK，请确保联网。若自动探测的 base 缺少 pip，请在 Base Python 字段指向完整的 python.exe。
• 下拉框中无 Channel——先载入图像，再点击 Refresh。列表只显示 Channel 对象。
• “The selected Channel has fewer than 2 slices.”——非刚性切片配准需要 Z 栈；单张 2D 图像无法与自身配准。
• “Choose at least a linear or a non-rigid method.”——Linear pre-alignment 与 Non-rigid method 至少一项须非 None。
• CSV 中个别切片 ok = false——单张失败会回退到原始切片并记录，因此单个坏配对不会中断整个任务。可尝试更换度量、增加迭代或使用更粗的 B-spline 网格。
• 运行缓慢或占用内存高——降低 B-spline 网格节点、减少迭代/采样比例，或减少金字塔层数；大栈逐切片处理，但仍会导出完整 .npy。
• 结果过度扭曲——降低 B-spline 网格密度或 Demons 迭代，或先加一层更温和的线性预配准。

10. 注意事项与已知限制

• 仅 2D 逐切片——每张切片在自身平面内独立配准；不做完整三维体配准。
• 非刚性步骤（Demons / B-spline）在线性预配准后单尺度运行；多分辨率金字塔作用于线性 + B-spline 优化器阶段。
• 计算出的形变尚未传播到关联的 ROI/MultiROI 标签栈——这是自然的后续扩展方向。
• 配准在独立 venv 子进程中运行；SimpleITK 从不导入 Dragonfly 自身的 Python。
• 质量用与方法无关的平均绝对差（MAD） 代理指标衡量（逐图 min-max 归一化）——是方向性信号，而非绝对精度指标。
• 在 Dragonfly 内的实机验证尚待完成；SimpleITK 引擎与纯辅助函数已离线验证（tests/test_slicereg_core.py）。

11. 参考资料

• SimpleITK（ITK 简化 API）——https://simpleitk.org ，文档 https://simpleitk.readthedocs.io ；许可证 Apache-2.0。
• ITK (Insight Toolkit)——https://itk.org （底层配准框架）。
• 插件 README.md 与 DESIGN.md，位于 DragonflyPlugins/SliceRegistrationNonRigid-Plugin/。
• 引擎：slicereg_code/slicereg_core.py；运行器与环境：runner/slicereg_runner.py、runner/setup_env.py、runner/requirements.txt。

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

Slice Registration (Non-Rigid) elastically aligns the 2D slices of a Dragonfly image Channel (a Z stack of slices) to each other and publishes a new, aligned Channel. It wraps the mature open-source SimpleITK (the simplified API to ITK, the Insight Toolkit), which is Apache-2.0 licensed. The plugin offers an optional linear pre-alignment (translation / rigid / affine) followed by a non-rigid step — either B-spline free-form deformation (FFD) or diffeomorphic Demons.

It exists to complement Dragonfly's built-in slice registration, which is limited to rigid / translation correction. When consecutive slices bend, stretch, or warp locally — not just shift or rotate — this plugin's elastic registration can recover that deformation. Input is one image Channel with at least 2 slices; output is a new Channel plus a per-slice diagnostics.csv.

What it is NOT: it does not perform full 3D volumetric registration (each slice is registered independently in its own plane), it is not a rigid-only tool, and it does not yet propagate the computed deformation to an associated ROI/MultiROI label stack.

2. Use cases

• Serial-section microscopy / histology stacks where physical sectioning introduces local distortion between neighbouring slices.
• Electron microscopy section series with slice-to-slice warping.
• Any Z stack where slices differ by local deformation (bending, stretching, tearing) rather than only a global translation or rotation.
• Correcting cumulative drift across a long serial-section series (use the sequential / propagated reference mode).
• As a stronger alternative when Dragonfly's built-in rigid slice registration leaves visible residual misalignment.

3. Installation & enabling

This plugin ships inside the Prototype Apps Full Package. All plugins are unchecked by default, so you must explicitly enable it during install.

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

2. Run Install_FullPackage.bat.

3. In the installer dialog, check "Slice Registration (Non-Rigid)", then click Install.

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

5. Open it from Prototype Apps > Slice Registration (Non-Rigid)... in the "Reconstruction & Imaging(重建与成像)" section.

To enable or disable it later, use Developer > Prototype Labs... > Menu Item Manager. The plugin installs under %LOCALAPPDATA% (no administrator rights needed). Restart Dragonfly after every enable/disable toggle. On a developer machine you can instead run install_slice_registration_nonrigid_plugin.py with Dragonfly's Python (and --uninstall to remove).

4. Runtime environment & first-run setup

This plugin uses the venv_in_code pattern: the heavy dependency (SimpleITK) runs in an isolated virtual environment / subprocess, never inside Dragonfly's own Python. Before the first registration you must build that venv from the Setup tab.

• Setup Environment (numpy + SimpleITK) button — creates a venv (via runner/setup_env.py) whose base is Dragonfly's own Python 3.10, then pip installs exactly numpy and SimpleITK from PyPI (runner/requirements.txt).
• Download size: ~tens of MB. Because Python 3.10 has prebuilt CPython wheels for SimpleITK, installation needs no compiler.
• Internet: required only for this one-time setup (needs_internet: true). Registration itself runs fully offline.
• GPU: not used (needs_gpu: false). No Fiji, ImageJ, Java, or WSL is required.
• venv location: a venv/ folder inside the installed code directory (...\GenericMenuItems\SliceRegNonRigid\venv). The resolved interpreter is written back into the Analysis venv python field and saved to slicereg_config.json.
• Base Python field — optional override for the interpreter used to create the venv. Leave blank to auto-detect Dragonfly's / the system Python; use Browse... to point at a specific python.exe (e.g. if the auto-detected one lacks a working pip).
• Job root — working folder for exported stacks and results, default C:\SliceRegNonRigidJobs. Each run creates a timestamped slicereg_<YYYYMMDD_HHMMSS> subfolder.

5. Interface

The panel has a title line and three tabs — Setup, Registration, Summary — plus a status label and a log pane at the bottom.

Setup tab

• Analysis venv python — path to the venv interpreter; normally filled automatically by Setup Environment.
• Base Python (+ Browse...) — optional base interpreter for building the venv; blank = auto-detect.
• Job root — working directory (default C:\SliceRegNonRigidJobs).
• Setup Environment (numpy + SimpleITK) button — builds the venv and installs dependencies.

Registration tab — Input Channel (image stack)

• Stack Channel dropdown — lists Dragonfly Channels (title + shape); Refresh button re-scans the session.

Registration tab — Reference

• Reference mode — *Previous slice (sequential, propagated)* or *Fixed reference slice (all-to-one)*.
• Reference/anchor index — anchor slice (sequential) or template slice (fixed); -1 = middle slice. Its maximum is clamped to the selected Channel's slice count.

Registration tab — Method

• Linear pre-alignment — None / Translation / Rigid (Euler) / Affine.
• Non-rigid method — B-spline free-form deformation / Diffeomorphic Demons / None (linear only).

Registration tab — Parameters

• Similarity metric — Mattes mutual information / Mean squares / Correlation. Enabled when a linear stage or B-spline is used.
• Iterations (linear/B-spline), Metric sampling fraction, Pyramid levels — govern the linear + B-spline optimizer stages.
• B-spline grid nodes — enabled only for B-spline; control-point mesh nodes per dimension (higher = more flexible / slower).
• Demons iterations and Demons smoothing sigma — enabled only for Demons; sigma smooths the displacement field (in pixels).
• Output interpolation — Linear or Nearest neighbour for the final resampling.
• Fill value (out of bounds) — value written where a resampled slice falls outside the reference grid.

Registration tab — Output & Run

• Output Channel — title of the published result (default *Slice-registered (non-rigid)*).
• Run Non-Rigid Slice Registration button — validates inputs and launches the job.

Summary tab

• A two-column Metric / Value table populated after a run (slice counts, reference index, methods, mean MAD before/after, improvement percent, failure count).

6. How to use

1. First run only: open the Setup tab and click Setup Environment (numpy + SimpleITK); wait until the status shows "Environment ready" and the venv python path appears.

2. Go to the Registration tab and click Refresh to list Channels, then pick your Stack Channel (must have ≥ 2 slices).

3. Choose a Reference mode: *Previous slice* for serial sections with drift, or *Fixed reference slice* to register everything to one template. Set the Reference/anchor index (-1 = middle).

4. Choose a Linear pre-alignment and a Non-rigid method (you must pick at least one non-None).

5. Tune Parameters — metric, iterations, sampling fraction, pyramid levels, and (per method) B-spline grid or Demons iterations/sigma; set output interpolation and fill value.

6. Set the Output Channel title and click Run Non-Rigid Slice Registration.

7. Watch the log; on completion the panel switches to the Summary tab, publishes the aligned Channel, and reports the diagnostics.csv path.

7. Parameters

The linear stage uses RegularStepGradientDescent (self-limiting) and B-spline uses LBFGS-B; Demons uses FastSymmetricForcesDemonsRegistrationFilter with histogram matching. The pyramid applies to the linear + B-spline optimizer stages.

8. Output

On success the plugin creates one new Dragonfly Channel built from the aligned stack via createChannelFromNumpyArray, titled from the Output Channel field (default "Slice-registered (non-rigid)"). It appears in the Data Properties / object tree like any other Channel.

• Geometry: the output copies the source Channel's spacing (X/Y/Z) and origin, so it overlays the input. Each moving slice is resampled into the reference grid, so the aligned stack keeps the input dimensions.
• Diagnostics: a per-slice diagnostics.csv (columns index, reference, ok, mad_before, mad_after, error) is written into the timestamped job folder under the Job root; its path is reported in the status line.
• Summary: the Summary tab table reports n_slices, n_registered, reference_index, ref_mode, chosen methods/metric, mean_mad_before, mean_mad_after, improvement_percent, and n_failed.

9. FAQ & troubleshooting

• "Run Setup first, or set the analysis venv python." — The venv is not built yet. Open the Setup tab and click Setup Environment.
• Setup fails / no internet — The first-time install pulls numpy + SimpleITK from PyPI; ensure network access. If pip is missing on the auto-detected base, point the Base Python field at a full python.exe.
• No Channels in the dropdown — Load an image first, then click Refresh. Only Channel objects are listed.
• "The selected Channel has fewer than 2 slices." — Non-rigid slice registration needs a Z stack; a single 2D image cannot be registered to itself.
• "Choose at least a linear or a non-rigid method." — At least one of Linear pre-alignment / Non-rigid method must be non-None.
• A few slices show ok = false in the CSV — A per-slice failure falls back to the raw slice and is logged, so one bad pair never aborts the whole job. Try a different metric, more iterations, or a coarser B-spline grid.
• Slow or memory-heavy runs — Reduce B-spline grid nodes, lower iterations/sampling fraction, or reduce pyramid levels; large stacks are processed slice by slice but still export a full .npy.
• Result looks over-warped — Lower the B-spline grid density or Demons iterations, or add a gentler linear pre-alignment first.

10. Notes & known limitations

• 2D per-slice only — each slice is registered independently in its own plane; this is not full 3D volumetric registration.
• The non-rigid (Demons / B-spline) step runs single-scale after the linear pre-alignment; the multi-resolution pyramid applies to the linear + B-spline optimizer stages.
• The computed deformation is not yet propagated to an associated ROI/MultiROI label stack — a natural future extension.
• Registration runs in an isolated venv subprocess; SimpleITK is never imported into Dragonfly's own Python.
• Quality is measured with a method-agnostic mean-absolute-difference proxy (per-image min-max normalized) — a directional signal, not an absolute accuracy metric.
• Live in-Dragonfly verification is pending; the SimpleITK engine and pure helpers are validated offline (tests/test_slicereg_core.py).

11. References

• SimpleITK (simplified ITK API) — https://simpleitk.org and docs at https://simpleitk.readthedocs.io ; license Apache-2.0.
• ITK (Insight Toolkit) — https://itk.org (the underlying registration framework).
• Plugin README.md and DESIGN.md in DragonflyPlugins/SliceRegistrationNonRigid-Plugin/.
• Engine: slicereg_code/slicereg_core.py; runner + env: runner/slicereg_runner.py, runner/setup_env.py, runner/requirements.txt.