SlicerDSpace

3D Slicer 中的扩散 MRI 分析工作流。源码下载视频

原生扩散空间

SlicerDSpace 的输出结果。

展示各分析路线的代表性参数图、皮层表面、纤维通路和连接网络，所有结果均位于原生扩散空间。

完整结果总览：解剖先验、微结构参数图、四种纤维追踪方法、WMQL、TractCloud 与 WMA 纤维束，以及结构连接组 — 各分析路线的参数图、皮层表面、纤维束与连接组结果。查看完整矢量图

选择分析路线

工作流概览。

开始使用

从安装到获得第一份结果。

让 Agent 协助安装、分析与结果检查。（推荐）

查看 Skill

我们为 SlicerDSpace 提供安装与使用 Skill。将 SKILL.md 交给本地 Agent，即可按照指南准备环境、执行分析并检查结果。

下方指令以 SKILL.md 为入口。如需安装 Skill，请一并保留 slicerdspace 文件夹中的参考资料、脚本和模板。

安装并启用

Agent 安装指令

参考 https://github.com/NeuroDMRI/SlicerDSpace/blob/main/.agents/skills/slicerdspace/SKILL.md
帮我将 SlicerDSpace 安装并启用到本机的 3D Slicer 中，
配置需要的依赖环境，并下载相应的模型权重。

Agent 会检查存储空间和已有资源，在你选定存放位置后保存路径，并按所选分析准备环境。遇到许可或重启提示时请确认。

使用已安装的插件

替换输入与输出路径，并选择研究所需的方法。以下示例运行 DDParcel、CSD/ACT 纤维追踪和结构连接组分析。

Agent 分析指令

参考 https://github.com/NeuroDMRI/SlicerDSpace/blob/main/.agents/skills/slicerdspace/SKILL.md
使用 SlicerDSpace 对 /path/to/subject 运行 DDParcel 脑区分区、CSD/ACT 纤维追踪和结构连接组分析，结果保存到 /path/to/results。
先展示计划，等我确认后再运行；完成后汇总输出与 QC 结果。

也可以手动配置

安装插件

先安装 3D Slicer，本方案参考版本为 5.10。克隆源码并创建独立的插件安装目录：
bash
```
git clone https://github.com/NeuroDMRI/SlicerDSpace.git
cd SlicerDSpace
python3 scripts/stage_slicer_extension.py \
  --install-root ~/SlicerDSpace-extension --slicer-version 5.10 \
  --link-mode copy
```
将 5.10 替换为 Slicer“关于”窗口中显示的主次版本号。脚本会部署模块并报告安装目录。
添加模块路径

打开 Edit › Application Settings › Modules › Additional module paths，添加以下目录展开后的绝对路径： ~/SlicerDSpace-extension/SlicerDSpace/lib/Slicer-5.10/qt-scripted-modules，并与部署时选择的版本号保持一致。

通过 Slicer 的扩展管理器安装 SlicerDMRI 和 PyTorch。如需使用 UKF，还要安装独立的 UKFTractography 扩展。重启 Slicer 后打开 Modules › Diffusion › SlicerDSpace。
准备被试输入

填写 Subject ID 和 Subject root。已准备好的输入采用以下目录结构；输出目录留空时使用被试目录下的 outputs/ 文件夹。
```
sub-01/
  input/
    data.nii.gz
    bvals
    bvecs
    nodif_brain_mask.nii.gz   # optional; supply or generate
```
DWI 与脑掩膜必须使用相同体素网格。梯度数量应匹配 DWI 的体积数，运动校正后的影像需要配套旋转后的梯度。

对于 DICOM 或 NRRD/NHDR，在 Advanced settings › Regions & input import › Input import / conversion 中预览导入，再准备标准化输入。
选择方法并准备环境

首次试运行可只选择 Microstructure，取消其他产品，并在其“...”选择器中保留 DTI。需要更多分析时，可在各产品旁选择一种或多种算法；模型和追踪参数位于 Advanced settings。

打开 Environment and installation › Prepare selected analysis environment，确认所需工具、模型和资源许可。下载资源会校验并缓存；如提示重启，重启后再次选择 Prepare 继续。

离线模型导入、修复和手动路径设置位于 More options。只运行 DTI 时，提供已复核的脑掩膜即可省去掩膜生成后端。
运行并检查

点击 Run SlicerDSpace。未填写的必需项会高亮，日志显示进度或具体修正提示。成功生成的关键结果自动加载到场景；DTI 提供 FA 和 MD 供检查。

在 Results and QC 中选择运行记录，查看检查结果并重新加载或替换输出，避免重复场景节点。接受结果前应复核掩膜覆盖、对齐及方法对应的 QC。

命令行运行与队列批处理

在代码目录中使用 Slicer 的 Python 检查 DTI 路线，先替换以下两个绝对路径：

bash

export SLICER_LAUNCHER="/path/to/Slicer"
export SUBJECT_ROOT="/path/to/sub-01"
"$SLICER_LAUNCHER" --launch PythonSlicer run_subject_pipeline.py \
  --subject-root "$SUBJECT_ROOT" --subject-id sub-01 --no-user-config \
  --targets microstructure --microstructure-stages dti --doctor

将上述选项换为 --plan 可查看处理计划，再使用 --execute 执行。三条命令的算法选项应保持一致。

例如， --microstructure-stages dti,noddi 选择两个微结构模型； --tractography-backend csd_act,ukf 选择两种追踪方法； --bundle-backend wmql,wma 选择两种纤维束方法。运行前仍会检查各方法的输入与依赖。

对于独立被试，可使用 scripts/run_batch_pipeline.py --batch-root /path/to/study --jobs 2 并添加所选分析参数。GUI 处理当前被试，批处理命令为各被试维护独立输出和日志。

运行时间

各模块实测运行时间。

每行对应一种算法，圆点为 CPU，空心菱形为 CUDA，共用对数时间轴。对齐列展示两种设备的计时，标题标明硬件配置。 — 共享 Linux 主机上的阶段计时，每行一种算法；七条路线同时记录 CPU 和 CUDA 时间，横杠表示该设备未测量。各方法线程预算不同且设备共享，不能将其视为受控的设备加速比或直接求和。SAF 对已有 100,000 条流线重新筛选；TractCloud 使用 50,000 条流线。

性能优化

运行效率优化。

各项操作的实测性能对比，附测量范围与实现细节。

目录更新于 2026 年 10 月 30 日

下载测量数据（JSON）

不同模型与测量范围不作横向排名。比值为原始实现耗时除以优化实现耗时。
计算内容 / 范围	优化类型	原始实现	优化实现	实测比值
全脑 / 记录 2026-10-29	同方法实现优化	15.64 分钟	11.89 分钟	1.32x耗时减少 23.99%
上游核查测量使用 DIPY 1.12.1，为 10 月 29 日的最新稳定版。稳定版与主分支的拟合定义通过哈希核验，本次全脑配对已包含有界协议缓存复用。优化方法在有界内部缓存中复用仅依赖采集协议的衰减、谱和网格数组，同时使用无显式对角矩阵的权重计算和经源码核验的张量辅助函数。原始实现参考为已安装的原始 DIPY WLS；两条路径均使用一个数值线程。一致性验证 13 个原始拟合参数、四个参数图或掩膜、仿射矩阵、数据类型和自动 QC 均一致，同样排除 116935 个体素。测量范围 740916 个掩膜体素、288 次测量；自动 QC 通过，待解剖复核。适用范围与限制共享 Linux 主机上的单被试配对，先运行优化实现；未清空操作系统缓存，两次调用均包含原始参数导出。
完整模块 / 记录 2026-10-20	同方法实现优化	102.10 分钟	74.22 分钟	1.38x耗时减少 27.31%
上游核查作者提交 4532b911386d 与核查时的主分支及测量源码字节一致。优化方法通过批量几何复制和已验证的配准输入复用，减少重复 Python/VTK 遍历与准备。原始实现对比原作者处理流程与等价的批量及缓存实现，使用完全相同的 UKF 输入和图谱。一致性验证 74 个解剖纤维束输出文件逐字节一致，源输入和作者代码未改变。测量范围包含完整配准和 74 束输出，未为计时增加流线降采样。适用范围与限制共享 Linux 主机上的一组完整模块配对。文件一致性与小束采样、解剖有效性分别评估；本组计时未包含后续坐标变换优化。
全脑 / 记录 2026-10-20	原生多线程	29.15 分钟	5.19 分钟	5.61x耗时减少 82.19%
上游核查两组计时均核验为 AMICO 2.1.1，即核查时最新稳定版。多线程为上游已有功能。优化方法使用 AMICO 原生多线程，对比 1 线程和 8 线程。原始实现使用相同作者实现和模型设置，对比线程配置。一致性验证 NDI、ODI、IsoVF、RMSE、NRMSE 及组织有效掩膜逐体素一致，仿射矩阵也一致。测量范围使用原始 740916 体素脑掩膜和全新输出目录。适用范围与限制共享主机上的一组配对，反映该硬件的多线程收益，不外推为通用速度或完整工作流收益。
64 体素数值计算块 / 记录 2026-10-22	Python 移植版计算	1.73 秒	1.09 秒	1.58x耗时减少 36.70%
上游核查 MATLAB 参考提交为 9a213e1a5850，测量使用 SciPy 1.18.1 稳定版。此处仅比较 Python 移植版内部实现，不比较 MATLAB 速度，也不将上游原生批处理列为新方法。优化方法复用协议与设计矩阵检查及 LAPACK 工作区大小，保留相同的列主元 QR 和完整 b0 网格。原始实现在同一 Python 移植版中，对比 SciPy 1.18.1 公共 gelsy 求解器与经核验的底层驱动及缓存调用。一致性验证三个被试的原始系数、完整曲线、所有参数图和有效性判断均一致，已检查参考与批处理求解器。测量范围三个真实的 64 体素计算块，181 次测量、完整的 200–201 点 b0 网格，使用一个数值线程。适用范围与限制表中为被试 100206 默认 QR 实现的中位数，预热后交替重复三次。数值块计时不含输入准备和导出，不外推为整个 ROI 或全脑耗时；SciPy 已提供原生批处理。
64 体素计算块 / QR 后续增量优化 / 记录 2026-10-29	Python 移植版计算	1.19 秒	1.06 秒	1.13x耗时减少 11.26%
上游核查 10 月 29 日使用 SciPy 1.18.1 测量，保留源码及输入校验和、单线程设置。比较的是 Python 移植版完成 QR 优化之后的增量改动。优化方法在每个计算块的完整合成 b0 扫描中复用非 b0 信号及其对数，只更新候选 b0 列。原始实现对照为先前经过核验的 QR Python 实现与新增信号复用的实现；求解器、扫描网格、校正规则和单数值线程设置一致。一致性验证三份采集数据、两种求解器的原始及校正系数、完整曲线、参数图、残差和有效掩膜均完全一致。测量范围三份采集数据，各取 64 个体素、181 次测量及 200–201 个合成 b0 采样点。reference QR 路径耗时减少 10.24%–11.26%。计时范围为数值计算，不含输入准备和文件导出。适用范围与限制表中使用采集数据 1，与之前 QR 记录的选取方式一致。预热一次后交替重复三次。批量求解路径的耗时变化为减少 -1.50% 至 +3.07%，因此默认仅在 reference 求解器启用信号复用。此处是之前 QR 实现上的增量对照，收益不可叠加。
原生网格 24³ ROI / 记录 2026-10-22	上游已有能力	37.11 秒	11.47 秒	3.24x耗时减少 69.09%
上游核查核查时 DIPY 1.12.1 为最新稳定版。数组参数计算已存在于上游，此项为插件接入优化。优化方法每个数据块一次调用作者已有的数组峰度计算，避免逐体素重复创建结果包装对象。原始实现对比插件原有逐体素接入和现有 DIPY 数组 API 的使用，不视为超越作者原生向量化 API。一致性验证三个被试的所有导出体素数组和仿射矩阵一致，各交替重复三次。测量范围三个被试，每条路径重复三次，使用原生网格 ROI，不重采样；DIPY 1.12.1、SciPy 1.18.1。适用范围与限制表中展示被试 100307 的中位数。此项采用 DIPY 已有原生功能；尚无完成的全脑 DKI 配对，ROI 耗时不外推到全脑。
原生网格 24³ ROI / 记录 2026-10-20	工作流调度	43.95 秒	24.63 秒	1.78x耗时减少 43.96%
上游核查插件调度器的历史对照，不作为最新上游算法性能结论。优化方法在共享输入就绪后并发运行独立模型子进程，同时保留下游依赖关系。原始实现相同模型计算，对比串行调度和两个并发工作进程。一致性验证全部导出参数和掩膜数组一致，计时包含进程启动。测量范围两个独立模型，受 CPU 和内存预算约束的调度；此处并非全脑计时。适用范围与限制一组 ROI 配对，缩短调度墙钟时间，单模型计算不变。默认并发数仍为一，内存或 CPU 预算可能限制并发。
单个子步骤 / 记录 2026-10-20	同方法实现优化	134.29 秒	2.48 秒	54.06x耗时减少 98.15%
上游核查与完整模块记录使用相同的固定 WMA 源码核查。优化方法用等价的批量坐标与拓扑操作替代 Python 逐点几何复制。原始实现在完整的 1989106 条流线配准图谱上运行未修改的作者筛选器。一致性验证输出坐标、拓扑及固定种子采样完全一致。测量范围仅包含完整配准图谱的长度筛选子步骤。适用范围与限制一组完整图谱子步骤配对，不包含全部 WMA；局部比值不能与完整 WMA 结果相乘或叠加。
1728 体素 ROI / 记录 2026-10-21	同方法实现优化	12.47 秒	5.17 秒	2.41x耗时减少 58.50%
上游核查在 Slicer 中测量 DIPY 1.12.1，作者 NLS、残差和雅可比源码哈希与注明日期的稳定版核查一致。优化方法直接调用经源码核验的作者 NLS、残差和雅可比函数主体，减少重复的关键字兼容性分派。原始实现比较原始 DIPY 1.12.1 串行 NLS 与相同函数主体，两条路径均使用一个数值线程。一致性验证三个被试的 13 个原始参数、导出参数图、仿射矩阵和 QC 判断全部一致。测量范围三个原生网格 12³ ROI，288 次测量；包含完整 ROI 处理和全新导出。适用范围与限制被试 100307 的中位数，预热后交替重复三次。仅限 ROI；测量早于后续 WLS 初始化及辅助函数修改，收益不可叠加。
1000 条流线 × 15 个点 / 记录 2026-10-21	同方法实现优化	24.6 毫秒	0.322 毫秒	76.31x耗时减少 98.69%
上游核查作者 register_two_subjects.py 的 SHA256 与 10 月 22 日 WMA 源码核查一致，测量批量 vtkTransform 路径。优化方法使用相同作者 vtkTransform，按有界数据块批量变换，替代逐点 Python/VTK 调用。原始实现对比原作者逐点循环与批量调用，保持 float64 点顺序和变换一致。一致性验证三个被试的全部变换点、小规模优化器完整轨迹和最终变换均一致。测量范围三个真实被试样例，独立优化器检查使用明确记录的合成偏移。适用范围与限制被试 100206 点变换重复五次的中位数，不包含完整配准。小规模优化器收益约为 1.27–1.28 倍，点变换比值不外推到整个 WMA。
20000 条流线 × 15 个点 / 记录 2026-10-21	同方法实现优化	0.59 秒	12.8 毫秒	45.84x耗时减少 97.82%
上游核查独立核验作者提交 4532b911386d 的 fibers.py；使用原生 VTK 数组采样，配准算法不变。优化方法按有界 NumPy 数据块，从 VTK 拓扑中提取与作者规则相同的最近邻流线采样点。原始实现对比原作者 FiberArray 转换与等价批量转换，不新增插值或流线缩减。一致性验证三个被试的全部数组、半球标记及独立小规模优化器轨迹和变换均一致。测量范围每个被试使用相同的 20000 条采样流线，保留原始最近邻规则和顺序。适用范围与限制被试 100206 转换重复五次的中位数；不代表完整 WMA。小规模优化器收益约 1.02–1.05 倍，历史采样失败状态不作改写。
三次准备调用 / 记录 2026-10-20	同方法实现优化	8.90 分钟	3.01 分钟	2.96x耗时减少 66.17%
上游核查保留相同作者实现的准备阶段配对，通过源码核验后复用，未重新标为最新版本测速。优化方法在不同种子间复用已验证的确定性图谱和被试长度筛选结果，每次仍执行作者随机采样。原始实现相同输入和固定种子下，对比三次原作者准备调用与首次缓存填充加后续复用。一致性验证配准输入签名逐位一致，源文件哈希不变。测量范围三次固定种子准备调用，包含首次缓存填充；不包含完整 WMA。适用范围与限制单被试一组配对，包含初次缓存建立；与 WMA 筛选和完整模块计时重叠，收益不能相加。
左半球四个叠加图 / 记录 2026-10-20	继承的上游优化	13.38 秒	3.52 秒	3.80x耗时减少 73.70%
上游核查优化继承 DDSurfer 提交 c3b2d40，不列为插件原创或最新 FreeSurfer 加速结论。优化方法将四个叠加图打包为一次多帧 mri_surf2surf 调用，共用表面配准。原始实现对比四次独立 FreeSurfer 调用和一次多帧调用；此优化继承 DDSurfer 上游 c3b2d40。一致性验证四个 MGH 输出逐字节一致，每图 163842 个顶点，源哈希不变。测量范围 100307 左半球，四次独立 FreeSurfer 调用对比一次多帧调用。适用范围与限制单被试的命令计时，不含额外打包和核验；不代表表面重建或新的 FreeSurfer 算法。
三个数据分块 / 记录 2026-10-20	压缩数据 I/O	37.25 秒	17.08 秒	2.18x耗时减少 54.15%
上游核查通用压缩及 I/O 对照，不涉及科学估计器本身的改变或上游版本新鲜度结论。优化方法将 gzip 一次解码到临时磁盘，再通过内存映射读取相同分块，保持源文件不变。原始实现对比重复读取压缩数组与一次顺序解码后按块读取；本次测量未使用 indexed_gzip。一致性验证三个分块的数组和仿射矩阵完全一致，输入哈希不变。测量范围三个真实数据分块，包含顺序解码，不代表模型拟合或完整流程加速。适用范围与限制单被试一组配对，未控制系统页缓存，需临时磁盘；仅测量 I/O，不外推为模型拟合或通用存储性能。

阅读完整优化报告

方法与资源

已集成的方法

在各产品旁选择一种或多种方法。工作流会检查采集适用性、处理依赖并复用共同准备步骤。

各分析路线的方法、实现及所需资源。
阶段	方法	集成内容	运行环境与资源	论文
输入	DICOM / NIfTI / NRRD	格式转换、梯度验证与空间检查。	dcm2niix 或 Slicer DWIConvert；可使用已有脑掩膜。	[36] [27] [28]
脑掩膜	PNL CNN（默认）	作者扩散 CNN 脑掩膜模型及配准。	托管 PNL 环境、权重及 ANTs。	[37] [38]
脑掩膜	SynthStrip	使用作者模型进行脑提取。	隔离环境及模型权重。	[32]
脑掩膜	MRtrix3 dwi2mask	原生扩散体积掩膜生成。	MRtrix3	[29]
预处理	MP-PCA	随机矩阵去噪及噪声估计。	DIPY or MRtrix3 dwidenoise	[39] [52] [53] [29] [30]
预处理	Local PCA	过完备局部 PCA 去噪。	DIPY；可选去噪方法。	[40] [30]
预处理	Patch2Self	自监督扩散体积去噪。	DIPY；可选去噪方法。	[41] [30]
预处理	Gibbs 振铃去除	局部亚体素位移振铃校正。	DIPY or MRtrix3 mrdegibbs	[42] [29] [30]
预处理	体积间配准	体积间运动校正及梯度旋转。	DIPY；不执行 FSL eddy 校正。	[30]
预处理	FSL eddy	涡流及运动校正。	MRtrix3 dwifslpreproc 与 FSL。	[43] [29]
预处理	FSL topup	磁敏感畸变估计与校正。	FSL；需反向相位编码数据及采集元数据。	[44] [29]
微结构	DTI（默认）	LS/WLS 张量拟合；输出 FA、MD、AD、RD、特征值和张量迹。	SlicerDMRI	[45] [27] [28]
微结构	自由水	自由水比例及组织校正 FA/MD；支持 WLS 或 NLS 拟合。	DIPY；需适合的多壳层采样。	[4] [5] [6] [30]
微结构	NODDI / AMICO	输出 NDI、ODI、IsoVF 及拟合残差。	AMICO；需适合的多壳层采样。	[7] [31]
微结构	DKI	WLS/OLS 拟合；输出 MK、AK、RK、KFA、MKT、RTK 和有效性掩膜。	DIPY；检查壳层、方向数及设计矩阵秩。	[8] [30]
微结构	MK-Curve	校正曲线、校正后的峰度图及各参数有效性。	内置 Python 后端；检查 DKI 适用条件。	[9]
解剖先验	DDSeg	使用转换后的 PyTorch 模型输出组织标签和概率。	PyTorch；DDSeg 权重。	[2]
解剖先验	DDParcel	使用源自作者的模型推断解剖脑区。	PyTorch；权重及配准模板。	[3]
解剖先验	DDSurfer	重建原生空间白质面和软脑膜面网格。	PyTorch；DDSurfer 权重。	[1]
解剖先验	BRAINSFit 配准	为适用的解剖路线执行模板配准。	Slicer BRAINSFit / BRAINSResample	[51] [27]
解剖先验	表面后处理	厚度、曲率、球面配准和 DK/Destrieux 图谱映射。	有许可的原生组件运行包；完整软件套件可选。	[33] [47] [48] [49]
纤维追踪	响应函数估计	Dhollander 三组织响应函数估计。	MRtrix3	[12] [13] [29]
纤维追踪	CSD / MSMT-CSD	单组织或多组织纤维方向分布。	MRtrix3；取决于所选采集路线。	[11] [46] [10] [29]
纤维追踪	多组织归一化	对数域信号强度和不均匀性归一化。	MRtrix3 mtnormalise	[17] [18] [29]
纤维追踪	iFOD2 / ACT（默认）	使用 DDSeg 组织约束的概率追踪。	MRtrix3；需复核解剖先验。	[14] [15] [29]
纤维追踪	DTI 确定性追踪	基于张量方向及终止条件的纤维追踪。	SlicerDMRI 与 DIPY。	[45] [28] [30]
纤维追踪	UKF 双张量	自动调用官方追踪命令行工具。	UKFTractography 扩展及 SlicerDMRI。	[19] [28]
纤维追踪	SAF	表面约束的短联络纤维追踪与几何筛选。	MRtrix3；后处理后的原生表面。	[20]
纤维束	WMQL（默认）	官方束查询；支持子集选择及可选小脑区域查询。	作者 tract_querier；DDParcel 标签。	[21]
纤维束	WMA	ORG、East-West 或 NABA 图谱配准与聚类；自动衔接 UKF。	WMA；所选图谱；UKF 参考路线	[22] [23] [24] [26] [54] [55]
纤维束	TractCloud	调用作者学习型纤维分区模型并导出纤维束。	PyTorch 后端、模型及质心。	[25] [22]
连接组	流线计数	将流线端点分配到 DDParcel 节点。	Python 或适用的 MRtrix3 后端。	[50] [29]
连接组	SIFT2 加权计数	利用 FOD 计算权重，并使用匹配流线构建矩阵。	MRtrix3；对应的流线文件及权重。	[16] [29] [50]
连接组	标量与长度统计	FA、MD、ODI 等参数均值，以及流线平均长度和总长度。	Python API；需匹配参数图、节点及流线。	[50] [29] [30]
区域分析	指定脑区分析	复用参数图进行 ROI 统计、筛选流线并提取节点子矩阵。	Advanced settings；基于已完成输出的工作流工具。	[3] [30] [50]

默认使用 DTI、CSD/ACT 和 WMQL。详细参数位于 Advanced settings，所选依赖在 Environment and installation 中单独准备。外部工具和模型安装前会请求确认。

实现来源与验证记录记录各后端版本及单项测试范围。

SlicerDSpace

宣传片

SlicerDSpace 的输出结果。

工作流概览。

从安装到获得第一份结果。

A让 Agent 协助安装、分析与结果检查。 （推荐）

查看 Skill

安装并启用

使用已安装的插件

B也可以手动配置

安装插件

添加模块路径

准备被试输入

选择方法并准备环境

运行并检查

C命令行运行与队列批处理