gradunwarp

gradunwarp是一个Python/Numpy包，用于去歪扭曲的体积（由于梯度场不均匀性）。目前，它可以去除西门子数据。

这是人类连接组项目版本的gradunwarp包。

它从一个“不再积极维护”的gradunwarp包中分支出来。

这个分支包含WU-Minn人类连接组项目联盟（HCP）为HCP最小预处理管道使用所做的更改。

安装

为所有用户安装

您可以使用以下命令在大多数基于Ubuntu或Debian的发行版中安装必要的先决条件

sudo apt install python3-numpy python3-pip

为了方便，可以从中这里下载最新的gradunwarp tarball。

首先，提取gradunwarp tarball，然后cd到它创建的文件夹中。然后执行

sudo pip3 install -r requirements.txt
sudo pip3 install .

仅使用用户权限安装

如果您在机器上没有超级用户权限，可以使用pip install的--user开关而不是使用sudo

pip3 install -r requirements.txt --user
pip3 install . --user

如果您使用--user开关，您需要将/home/<username>/.local/bin添加到您的PATH环境变量中，用<username>替换您的用户名。

使用虚拟环境安装

您可以选择将gradunwarp安装到Python虚拟环境中，以避免与现有的Python设置发生冲突。如果尚未安装Python虚拟环境模块，则可能需要运行以下命令。

sudo apt install python3-venv

在运行以下命令之前。

首先，提取gradunwarp tarball，然后cd到它创建的文件夹中。然后执行

python3 -m venv gradunwarp.build
source gradunwarp.build/bin/activate
pip install -r requirements.txt
pip install . 
deactivate

命令deactivate确保您的Python环境设置回到之前的状态。

安装完成后，您可以通过添加以下内容来使用gradunwarp：

source "$PATH_TO_INSTALLATION"/gradunwarp.build/bin/activate

到您的脚本中，其中"$PATH_TO_INSTALLATION"应替换为您安装gradunwarp的路径。注意，您可能需要在脚本中运行gradunwarp后，使用deactivate虚拟环境来使用其他环境。

使用Python2虚拟环境安装

使用Python2的安装方法与上面Python3的略有不同。

如上所述，提取gradunwarp的tar包，然后使用cd进入创建的文件夹。然后执行：

virtualenv -p python2 gradunwarp.build
source gradunwarp.build/bin/activate
pip install -r requirements.txt
pip install . 
deactivate

注意，使用的是virtualenv而不是venv。

此虚拟环境可以像上面Python3中描述的那样使用。

依赖项

• Python (>=2.7或3.x)
• Numpy
• Scipy
• Numpy开发包（如果单独提供），用于编译用C编写的外部模块
• nibabel（Python2.7的2.0或更高版本，Python3.x的3.2.1或更高版本）

nibabel的依赖项

• PyDICOM 0.9.5或更高版本（用于DICOM支持）
• nose 0.11或更高版本（用于运行测试）
• sphinx（用于构建文档）

用法

骨架

gradient_unwarp.py infile outfile manufacturer -g <coefficient file> [optional arguments]

典型用法

gradient_unwarp.py sonata.mgh testoutson.mgh siemens -g coeff_Sonata.grad  --fovmin -.15 --fovmax .15 --numpoints 40

gradient_unwarp.py avanto.mgh testoutava.mgh siemens -g coeff_AS05.grad -n

位置参数

输入文件（Nifti或MGH格式）后跟输出文件名（具有Nifti或MGH扩展名--.nii/.nii.gz/.mgh/.mgz）后跟厂商名称。

必需选项

-c <coef_file>
-g <grad_file>

使用-g选项指定从厂商获取的系数文件，用于类型为.grad的文件。

或者，如果拥有.coef文件，可以使用-c指定。

这两个选项是互斥的。

其他选项

-n : If you want to suppress the jacobian intensity correction
-w : if the volume is to be warped rather than unwarped

--fovmin <fovmin> : a float argument which specifies the minimum extent of the grid where spherical harmonics are evaluated. (in meters). Default is -.3
--fovmax <fovmax> : a float argument which specifies the maximum extent of the grid where spherical harmonics are evaluated. (in meters). Default is .3
--numpoints <numpoints> : an int argument which specifies the number of points in the grid. (in each direction). Default is 60

--interp_order <order of interpolation> : takes values from 1 to 4. 1 means the interpolation is going to be linear which is a faster method but not as good as higher order interpolations.

--help : display help

内存考虑

gradunwarp由于执行了多次密集的球谐计算和插值，因此往往需要大量的内存。例如，它使用了一个2GB内存、2.2GHz双核系统大约85%的内存来对256^3体积进行去扭曲，使用了40^3球谐网格。（整个去扭曲通常需要4到5分钟）

一些想法

• 如果可能，请使用较低分辨率的体积
• 在具有更多内存的计算机上运行gradunwarp
• 使用-numpoints来减少网格大小。-fovmin和-fovmax可以用来将网格移至您的数据范围附近。
• 使用非压缩源体积。即.mgh和.nii而不是.mgz/.nii.gz
• 较新版本的Python、numpy和scipy

HCP新增功能

• 逐片处理
• x-y翻转错误修复
• 在64位系统中强制输出32位
• 修改以兼容Python3

许可证

请参阅发行版中的Copying.md文件。

信用

• Jon Polimeni - gradunwarp遵循他的原始MATLAB代码
• Karl Helmer - 项目负责人
• Nibabel团队

关于变更历史的说明

为HCP所做的某些代码库更改是在此代码尚未分叉到其自己的存储库时进行的。当时，此修改后的梯度去扭曲代码被嵌入到HCP管道存储库的src/gradient_unwarping子目录中。

这些更改的历史（提交注释、变更日志等）尚未迁移到此存储库。该HCP管道存储库将保留该历史。

要获取在梯度解缠绕代码分离之前的HCP Pipelines仓库的最新版本，检索提交 2e06194921638394c7c0ffd90805fdf06051449a。为此，在克隆HCP Pipelines仓库后，使用

$ git checkout 2e06194921638394c7c0ffd90805fdf06051449a