# sdcflows.transform module¶

The $$B_0$$ unwarping transform formalism.

class sdcflows.transform.B0FieldTransform(coeffs=None, xfm=None)[source]

Bases: object

Represents and applies the transform to correct for susceptibility distortions.

apply(spatialimage, pe_dir, ro_time, order=3, mode='constant', cval=0.0, prefilter=True, output_dtype=None)[source]

Apply a transformation to an image, resampling on the reference spatial object.

Parameters
• spatialimage (spatialimage) – The image object containing the data to be resampled in reference space

• reference (spatial object, optional) – The image, surface, or combination thereof containing the coordinates of samples that will be sampled.

• order (int, optional) – The order of the spline interpolation, default is 3. The order has to be in the range 0-5.

• mode ({‘constant’, ‘reflect’, ‘nearest’, ‘mirror’, ‘wrap’}, optional) – Determines how the input image is extended when the resamplings overflows a border. Default is ‘constant’.

• cval (float, optional) – Constant value for mode='constant'. Default is 0.0.

• prefilter (bool, optional) – Determines if the image’s data array is prefiltered with a spline filter before interpolation. The default is True, which will create a temporary float64 array of filtered values if order > 1. If setting this to False, the output will be slightly blurred if order > 1, unless the input is prefiltered, i.e. it is the result of calling the spline filter on the original input.

Returns

resampled – The data imaged after resampling to reference space.

Return type

spatialimage or ndarray

coeffs

B-Spline coefficients (one value per control point).

fit(spatialimage)[source]

Generate the interpolation matrix (and the VSM with it).

Implements Eq. $$\eqref{eq:1}$$, interpolating $$f(\mathbf{s})$$ for all voxels in the target-image’s extent.

Returns

updatedTrue if the internal field representation was fit, False if cache was valid and will be reused.

Return type

bool

mapped

A cache of the interpolated field in Hz (i.e., the fieldmap mapped on to the target image we want to correct).

to_displacements(ro_time, pe_dir, itk_format=True)[source]

Generate a NIfTI file containing a displacements field transform compatible with ITK/ANTs.

The displacements field can be calculated following Eq. (2) in the fieldmap fitting section.

Parameters
• ro_time (float) – The total readout time in seconds (only if vsm=False).

• pe_dir (str) – The PhaseEncodingDirection metadata value (only if vsm=False).

Returns

spatialimage – A NIfTI 1.0 object containing the distortion.

Return type

nibabel.nifti.Nifti1Image

xfm

A rigid-body transform to prepend to the unwarping displacements field.

sdcflows.transform.disp_to_fmap(xyz_nii, ro_time, pe_dir, itk_format=True)[source]

Convert a displacements field into a fieldmap in Hz.

This is the inverse operation to the previous function.

Parameters
• xyz_nii (os.pathlike) – Path to a displacements field in NIfTI format.

• ro_time (float) – The total readout time in seconds.

• pe_dir (str) – The PhaseEncodingDirection metadata value.

Returns

spatialimage – A NIfTI 1.0 object containing the field in Hz.

Return type

nibabel.nifti.Nifti1Image

sdcflows.transform.fmap_to_disp(fmap_nii, ro_time, pe_dir, itk_format=True)[source]

Convert a fieldmap in Hz into an ITK/ANTs-compatible displacements field.

The displacements field can be calculated following Eq. (2) in the fieldmap fitting section.

Parameters
• fmap_nii (os.pathlike) – Path to a voxel-shift-map (VSM) in NIfTI format

• ro_time (float) – The total readout time in seconds

• pe_dir (str) – The PhaseEncodingDirection metadata value

Returns

spatialimage – A NIfTI 1.0 object containing the distortion.

Return type

nibabel.nifti.Nifti1Image

sdcflows.transform.grid_bspline_weights(target_nii, ctrl_nii, dtype='float32')[source]

Evaluate tensor-product B-Spline weights on a grid.

For each of the N input samples $$(s_1, s_2, s_3)$$ and K control points or knots $$\mathbf{k} =(k_1, k_2, k_3)$$, the tensor-product cubic B-Spline kernel weights are calculated:

$\Psi^3(\mathbf{k}, \mathbf{s}) = \beta^3(s_1 - k_1) \cdot \beta^3(s_2 - k_2) \cdot \beta^3(s_3 - k_3), \label{eq:2}\tag{2}$

where each $$\beta^3$$ represents the cubic B-Spline for one dimension. The 1D B-Spline kernel implementation uses numpy.piecewise, and is based on the closed-form given by Eq. (6) of [Unser1999].

By iterating over dimensions, the data samples that fall outside of the compact support of the tensor-product kernel associated to each control point can be filtered out and dismissed to lighten computation.

Finally, the resulting weights matrix $$\Psi^3(\mathbf{k}, \mathbf{s})$$ can be easily identified in Eq. $$\eqref{eq:1}$$ and used as the design matrix for approximation of data.

Parameters
Returns

weights – A sparse matrix of interpolating weights $$\Psi^3(\mathbf{k}, \mathbf{s})$$ for the N voxels of the target EPI, for each of the total K knots. This sparse matrix can be directly used as design matrix for the fitting step of approximation/extrapolation.

Return type

numpy.ndarray ($$K \times N$$)