VoxelMorph：基于学习的图像配准

VoxelMorph 是一个通用的库，用于构建基于学习的对齐/配准工具，以及更广泛地使用形变进行建模。

⚠️ 警告：VoxelMorph PyTorch 版本仍在积极开发中，接口可能会发生变化。

对于希望使用稳定 TensorFlow 版本的用户，可以使用 pip install voxelmorph，或者从 dev-tensorflow 分支拉取/克隆。

安装

要使用 VoxelMorph 库，您可以克隆此仓库并安装 setup.py 中列出的依赖项，或者直接通过 pip 进行安装。

pip install voxelmorph

教程

我们提供了多个 VoxelMorph 教程：

• 主要的 VoxelMorph 教程 解释了 VoxelMorph 和基于学习的配准；
• 一个 可变形 SynthMorph 演示，展示了如何在没有数据的情况下训练配准模型；
• 一个 仿射 SynthMorph 演示，介绍如何学习解剖结构感知且与采集无关的仿射配准；
• 一个 CT 到 MRI 的 SynthMorph 演示，演示了为多模态配准裁剪亨氏单位尺度的方法；
• 一个 SynthMorph 形状演示，逐步展示了运行已训练的 3D 形状模型的步骤；
• 一个 训练 VoxelMorph 的教程，基于 OASIS 数据，这些数据我们经过处理后免费发布用于 HyperMorph；
• 另一个简短的教程 将标注与图像一起变形；
• 还有一个关于使用 VoxelMorph 构建模板（图谱）的教程 链接；
• 可视化 变形场 作为变形后的网格；
• 反演非微分同胚的变形场。

使用说明

要使用 VoxelMorph 库，需克隆此仓库，并安装 setup.py 中列出的依赖项。

注意：目前尚不支持 pip install voxelmorph 命令。请直接从 GitHub 安装：

pip install git+https://github.com/voxelmorph/voxelmorph.git

预训练模型

预训练模型列表请参见 此处。

训练

如果您想训练自己的模型，可能需要针对您的数据集和数据格式自定义 voxelmorph/generators.py 中的部分数据加载代码。不过，在提供训练数据集的文件名列表的前提下，许多示例脚本可以直接运行。训练数据可以是 NIfTI、MGZ 或 npz（numpy）格式，假设您提供的每个 npz 文件都包含 vol 参数，指向待配准的图像数据；以及可选的 seg 变量，指向对应的离散分割标签（用于半监督学习）。此外，还假定所有训练图像数据的形状一致，当然，如果需要，也可以通过自定义生成器来处理这一问题。

对于给定的图像列表文件 /images/list.txt 和输出目录 /models/output，以下脚本将使用无监督损失训练一个图像到图像的配准网络（默认采用 MICCAI 2018 中描述的架构），并将模型权重保存到由 --model-dir 标志指定的路径。

./scripts/tf/train.py --img-list /images/list.txt --model-dir /models/output --gpu 0

--img-prefix 和 --img-suffix 标志可用于为图像列表中指定的每个路径添加一致的前缀或后缀。若要启用图像到图谱的配准，可以提供一个图谱文件，例如 --atlas atlas.npz。如果您希望使用原始的稠密 CVPR 网络（非微分同胚），请使用 --int-steps 0 标志指定不进行流积分步骤。使用 --help 标志可以查看所有可用于微调网络架构和训练过程的命令行选项。

配准

如果您只是想配准两张图像，可以使用 register.py 脚本并指定所需的模型文件。例如，如果我们有一个模型 model.h5，用于将受试者（移动图像）配准到图谱（固定图像），则可以运行：

./scripts/tf/register.py --moving moving.nii.gz --fixed atlas.nii.gz --moved warped.nii.gz --model model.h5 --gpu 0

这会将配准后的图像保存为 warped.nii.gz。若同时保存预测的变形场，可使用 --save-warp 标志。该脚本的输入和输出均可使用 npz 或 nifty 文件。

测试（计算 Dice 分数）

要通过计算图谱分割与变形后测试扫描分割之间的 Dice 重叠率来评估模型质量，可运行：

./scripts/tf/test.py --model model.h5 --atlas atlas.npz --scans scan01.npz scan02.npz scan03.npz --labels labels.npz

与训练数据类似，图谱和测试的 npz 文件均包含 vol 和 seg 参数，而 labels.npz 文件则包含用于计算 Dice 分数的相应解剖学标签列表。

参数选择

CVPR 版本

对于 CC 损失函数，我们发现 reg 参数设为 1 时效果最佳。而对于 MSE 损失函数，0.01 是最佳选择。

MICCAI 版本

对于我们的数据，我们发现 image_sigma=0.01 和 prior_lambda=25 的设置效果最好。

在原始的 MICCAI 代码中，这些参数是在速度场缩放之后应用的。而在最新版本的代码中，这一点已被“修复”，默认参数也反映了这一变化。我们建议使用更新后的代码。然而，如果您希望运行最原始的 MICCAI 2018 模式，请使用 xy 索引，并启用 use_miccai_int 网络选项，同时采用 MICCAI 2018 的参数设置。

空间变换与积分

• 空间变换代码位于 voxelmorph.layers.SpatialTransformer，支持 N 维的仿射和稠密变换，包括线性插值和最近邻插值选项。需要注意的是，VoxelMorph 的早期开发使用的是 xy 索引，而我们现在强调使用 ij 索引。

• 对于 MICCAI 2018 版本，我们使用 voxelmorph.layers.VecInt 来积分速度场。默认情况下，我们采用缩放平方法进行积分，这种方法被证明是高效的。

VoxelMorph 相关论文

如果您使用了 VoxelMorph 或其部分代码，请引用以下文献（参见 bibtex）：

• HyperMorph，无需调参即可实现配准：

  利用 HyperMorph 学习配准超参数的影响
  Andrew Hoopes、Malte Hoffmann、Bruce Fischl、John Guttag、Adrian V. Dalca
  MELBA：生物医学影像中的机器学习。2022年。arXiv 预印本 2203.16680

  HyperMorph：用于图像配准的超参数摊销学习。
  Andrew Hoopes、Malte Hoffmann、Bruce Fischl、John Guttag、Adrian V. Dalca
  IPMI：医学影像中的信息处理。2021年。arXiv 预印本 2101.01035

• SynthMorph，无需训练数据即可实现配准（！）：

  基于 SynthMorph 的解剖学感知且采集无关的联合配准。
  Malte Hoffmann、Andrew Hoopes、Douglas N. Greve、Bruce Fischl、Adrian V. Dalca
  影像神经科学。2024年。arXiv 预印本 2301.11329

  从虚构图像中学习的解剖特异性、采集无关的仿射配准。
  Malte Hoffmann、Andrew Hoopes、Bruce Fischl、Adrian V. Dalca
  SPIE 医疗影像：图像处理。2023年。

  SynthMorph：无需实际采集图像即可学习对比度不变的配准。
  Malte Hoffmann、Benjamin Billot、Juan Eugenio Iglesias、Bruce Fischl、Adrian V. Dalca
  IEEE TMI：医学影像汇刊。2022年。arXiv 预印本 2004.10282

• 关于图谱生成模型：

  利用卷积网络学习条件变形模板
  Adrian V. Dalca、Marianne Rakic、John Guttag、Mert R. Sabuncu
  NeurIPS 2019。arXiv 预印本 1908.02738

• 关于微分同胚或概率模型：

  面向图像和表面的概率性微分同胚配准的无监督学习
  Adrian V. Dalca、Guha Balakrishnan、John Guttag、Mert R. Sabuncu
  MedIA：医学图像分析。2019年。arXiv 预印本 1903.03545

  快速概率性微分同胚配准的无监督学习
  Adrian V. Dalca、Guha Balakrishnan、John Guttag、Mert R. Sabuncu
  MICCAI 2018。arXiv 预印本 1805.04605

• 关于原始 CNN 模型、MSE、CC 或基于分割的损失函数：

  VoxelMorph：用于可变形医学图像配准的学习框架
  Guha Balakrishnan、Amy Zhao、Mert R. Sabuncu、John Guttag、Adrian V. Dalca
  IEEE TMI：医学影像汇刊。2019年。
  arXiv 预印本 1809.05231

  用于可变形医学图像配准的无监督学习模型
  Guha Balakrishnan、Amy Zhao、Mert R. Sabuncu、John Guttag、Adrian V. Dalca
  CVPR 2018。arXiv 预印本 1802.02604

注释

• 关键词：机器学习、卷积神经网络、对齐、映射、配准
• 论文中的数据：
  在我们最初的几篇论文中，我们使用了公开可用的数据，但遗憾的是我们无法重新分发这些数据（受限于相关数据集的协议）。对于所使用的脑部图像，我们会进行一定程度的预处理，以消除变异来源，从而能够在公平的条件下比较不同算法。具体来说，我们会执行 FreeSurfer 的 recon-all 流程，直到去颅骨和仿射归一化到 Talairach 空间，并通过 ((48, 48), (31, 33), (3, 29)) 对图像进行裁剪。

我们鼓励用户自行下载并处理数据。请参阅 此处的医学影像数据集列表。请注意，您可能并不需要执行所有预处理步骤，事实上，VoxelMorph 已经被应用于其他研究中，使用不同的数据集。

可变形模板的创建

要尝试此方法，请使用 train_template.py 进行无条件模板的训练，以及 train_cond_template.py 进行条件模板的训练，这两者均采用与 VoxelMorph 相同的约定（请注意，这些文件的完善程度不如 VoxelMorph 库的其他部分）。

我们还在 data/generated_uncond_atlas.npz.npy 中提供了一个无条件图谱。

以 h5 格式保存的模型权重分别提供给 无条件图谱 和 条件图谱。

请在此处交互式地探索这些图谱，借助 tipiX！

SynthMorph

SynthMorph 是一种无需采集影像数据即可学习配准的策略，能够生成对 MRI 对比度无关的强大网络（eprint arXiv:2004.10282）。如需观看一段视频及演示，了解如何从噪声分布中生成随机标签图，并利用这些标签图训练网络，请访问 synthmorph.voxelmorph.net。

我们提供了 SynthMorph 的两种变体模型文件：一种是“shapes”变体（下载链接），该模型仅使用由随机形状合成的图像进行训练；另一种是“brains”变体（下载链接），它使用由脑部标签图合成的图像进行训练。在训练“brains”变体时，我们优化了一个衡量特定脑部标签体积重叠程度的损失项（相关标签列表见 这里）。无论是使用哪种模型进行配准，都请使用 register.py 脚本，并加载相应的模型权重。

为了实现准确的配准，输入图像需要进行 min-max 归一化，使体素强度范围在 0 到 1 之间，并且需要在一张参考图像的仿射空间内进行重采样（参考图像可从 这里 下载）。仿射配准可以使用多种工具完成，我们选择 FreeSurfer。首先，我们使用 SAMSEG 对图像进行去颅骨处理，仅保留脑部标签；其次，运行 mri_robust_register 命令：

mri_robust_register --mov in.nii.gz --dst out.nii.gz --lta transform.lta --satit --iscale
mri_robust_register --mov in.nii.gz --dst out.nii.gz --lta transform.lta --satit --iscale --ixform transform.lta --affine

其中，若需跨 MRI 对比度进行配准，可将 --satit --iscale 替换为 --cost NMI。

数据

尽管我们无法公开 VoxelMorph 论文中使用的大部分数据，因为这些数据的再分发受到限制，但在开发 HyperMorph 期间，我们对 OASIS1 数据集进行了彻底的处理并重新发布（详见 此处）。目前，我们还提供了一个简短的 VoxelMorph 教程，指导用户如何使用 neurite-oasis 数据训练 VoxelMorph 模型。

联系方式

如您在代码使用过程中遇到任何问题或疑问，请在 GitHub 仓库的 Issues 页面 提交 Issue，或在 讨论区 中发起关于通用配准及 VoxelMorph 相关话题的讨论。

VoxelMorph 快速上手指南

VoxelMorph 是一个基于深度学习的通用医学图像配准（对齐）库，支持变形建模。它主要用于将移动图像（moving image）对齐到固定图像（fixed image）或图谱（atlas）。

注意：目前 PyTorch 版本仍在积极开发中，接口可能变动。本指南基于稳定的 TensorFlow 版本编写。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux 或 macOS（Windows 需使用 WSL 或 Docker）。
• Python 版本：推荐 Python 3.8 - 3.10。
• GPU 支持：强烈建议使用 NVIDIA GPU 以加速训练和推理。
  • 需安装对应的 CUDA 和 cuDNN。
  • 确保已安装与 CUDA 版本匹配的 tensorflow-gpu。
• 前置依赖：
  • numpy, scipy, nibabel (用于处理 NIfTI 医疗图像格式)。
  • matplotlib (可选，用于可视化)。

2. 安装步骤

虽然支持 pip install voxelmorph，但为了获取最新稳定功能，建议直接从 GitHub 源码安装。

方法一：使用 pip 直接安装（推荐）

pip install git+https://github.com/voxelmorph/voxelmorph.git

国内加速提示：如果下载速度较慢，可以使用清华或阿里镜像源加速安装依赖：

pip install git+https://github.com/voxelmorph/voxelmorph.git -i https://pypi.tuna.tsinghua.edu.cn/simple

方法二：克隆仓库安装（适合开发者）

如果您需要修改源码或运行示例脚本：

git clone https://github.com/voxelmorph/voxelmorph.git
cd voxelmorph
pip install -e .

3. 基本使用

VoxelMorph 的核心工作流分为 训练模型 和 执行配准。以下是最简单的命令行使用示例。

场景 A：使用预训练模型进行图像配准

如果您已经有一个训练好的模型（例如 model.h5），可以将一张“移动图像”配准到“固定图像”。

假设您有：

• 移动图像：moving.nii.gz
• 固定图像（或图谱）：atlas.nii.gz
• 模型文件：model.h5

运行以下命令：

./scripts/tf/register.py --moving moving.nii.gz --fixed atlas.nii.gz --moved warped.nii.gz --model model.h5 --gpu 0

• --moved: 输出配准后的图像文件名。
• --save-warp: （可选）添加此参数可同时保存预测的形变场（deformation field）。
• 支持输入/输出格式：.nii.gz (NIfTI) 或 .npz (NumPy)。

场景 B：训练自己的配准模型

若要训练新模型，需准备一个包含图像路径的文本列表文件（如 /images/list.txt），每行一个文件路径。数据支持 NIfTI (.nii/.nii.gz)、MGZ 或 NPZ 格式。

无监督训练示例（基于 MICCAI 2018 架构）：

./scripts/tf/train.py --img-list /images/list.txt --model-dir /models/output --gpu 0

• --img-list: 包含训练图像路径的文本文件。
• --model-dir: 模型权重保存目录。
• --atlas atlas.npz: （可选）若进行“图像到图谱”的配准，指定图谱文件。
• --int-steps 0: （可选）若使用原始 CVPR 网络（非微分同胚），设置此参数为 0。

场景 C：评估模型质量 (Dice Score)

通过计算图谱分割与配准后测试图像分割的重叠率（Dice 系数）来测试模型：

./scripts/tf/test.py --model model.h5 --atlas atlas.npz --scans scan01.npz scan02.npz --labels labels.npz

• --scans: 测试扫描文件列表。
• --labels: 包含解剖标签的文件，用于计算特定结构的 Dice 分数。

---

提示：

• 代码中默认使用 ij 索引方式（较新版本），旧版代码可能使用 xy 索引。
• 对于多模态配准（如 CT 到 MRI）或无需真实数据的训练（SynthMorph），请参考官方提供的 Colab 教程链接。