sdcflows.interfaces.bspline module¶
Filtering of \(B_0\) field mappings with B-Splines.
- class sdcflows.interfaces.bspline.ApplyCoeffsField(from_file=None, resource_monitor=None, **inputs)[source]¶
Bases:
nipype.interfaces.base.core.SimpleInterface
Convert a set of B-Spline coefficients to a full displacements map.
- Mandatory Inputs
in_coeff (a list of items which are a pathlike object or string representing an existing file) – Input coefficients, after alignment to the EPI data.
- Optional Inputs
in_data (a list of items which are a pathlike object or string representing a file)
in_xfms (a list of items which are a pathlike object or string representing an existing file) – List of head-motion correction matrices.
num_threads (an integer) – Number of threads.
pe_dir (a list of items which are ‘i’ or ‘i-’ or ‘j’ or ‘j-’ or ‘k’ or ‘k-’)
ro_time (a list of items which are a float)
- Outputs
out_corrected (a list of items which are a pathlike object or string representing an existing file)
out_field (a list of items which are a pathlike object or string representing an existing file)
out_warp (a list of items which are a pathlike object or string representing an existing file)
- class sdcflows.interfaces.bspline.BSplineApprox(from_file=None, resource_monitor=None, **inputs)[source]¶
Bases:
nipype.interfaces.base.core.SimpleInterface
Approximate the \(B_0\) field using tensor-product B-Splines.
The approximation effectively smooths the data, removing spikes and other sources of noise, as well as enables the extrapolation of the \(B_0\) field beyond the brain mask, which alleviates boundary effects in correction.
This interface resolves the optimization problem of obtaining the B-Spline coefficients \(c(\mathbf{k})\) that best approximate the data samples within the brain mask \(f(\mathbf{s})\), following Eq. (17) – in that case for 2D – of [Unser1999]. Here, and adapted to 3D:
\[f(\mathbf{s}) = \sum_{k_1} \sum_{k_2} \sum_{k_3} c(\mathbf{k}) \Psi^3(\mathbf{k}, \mathbf{s}). \label{eq:1}\tag{1}\]References
- Unser1999
M. Unser, “Splines: A Perfect Fit for Signal and Image Processing,” IEEE Signal Processing Magazine 16(6):22-38, 1999.
See also
bspline_weights()
- for Eq. \(\eqref{eq:2}\) and the evaluation of the tri-cubic B-Splines \(\Psi^3(\mathbf{k}, \mathbf{s})\).- Mandatory Inputs
in_data (a pathlike object or string representing an existing file) – Path to a fieldmap.
- Optional Inputs
bs_spacing (a list of items which are a tuple of the form: (a float, a float, a float)) – Spacing between B-Spline control points. (Nipype default value:
[(40.0, 40.0, 20.0)]
)debug (a boolean) – Generate extra assets for debugging. (Nipype default value:
False
)extrapolate (a boolean) – Generate a field, extrapolated outside the brain mask. (Nipype default value:
True
)in_mask (a pathlike object or string representing an existing file) – Path to a brain mask.
recenter (‘mode’ or ‘median’ or ‘mean’ or False) – Strategy to recenter the distribution of the input fieldmap. (Nipype default value:
mode
)ridge_alpha (a float) – Controls the regularization. (Nipype default value:
0.01
)zooms_min (a float or a legal value) – Limit minimum image zooms, set 0.0 to use the original image. (Nipype default value:
4.0
)
- Outputs
out_coeff (a list of items which are a pathlike object or string representing an existing file)
out_error (a pathlike object or string representing an existing file)
out_extrapolated (a pathlike object or string representing a file)
out_field (a pathlike object or string representing an existing file)
- class sdcflows.interfaces.bspline.TOPUPCoeffReorient(from_file=None, resource_monitor=None, **inputs)[source]¶
Bases:
nipype.interfaces.base.core.SimpleInterface
Revise the orientation of TOPUP-generated B-Spline coefficients.
TOPUP-generated “fieldcoeff” files are just B-Spline fields, where the shape of the field is fixated to be a decimated grid of the original image by an integer factor and added 3 pixels on each dimension. This is one root reason why TOPUP errors (FSL 6) or segfaults (FSL 5), when the input image has odd number of voxels along one or more directions.
These “fieldcoeff” are fixated to be zero-centered, and have “plumb” orientation (as in, aligned with cardinal/imaging axes). The q-form of these NIfTI files is always diagonal, with the decimation factors set on the diagonal (and hence, the voxel zooms). The origin of the q-form is set to the reference image’s shape. All the director cosines of the output coefficients will be positive. In other words, the output orientation is either RAS, ARS, ASR, SAR, or SRA.
This interface modifies these coefficient files to be fully-fledged NIfTI images aligned with the reference image. Therefore, the s-form header of the coefficients file is updated to match that of the reference file. The s-form header is used because the imaging axes may be oblique.
The q-form retains the original header and is marked with code 0.
- Mandatory Inputs
fmap_ref (a pathlike object or string representing an existing file) – The fieldmap reference.
in_coeff (a list of items which are a pathlike object or string representing a file) – Input coefficients file(s) from TOPUP.
pe_dir (‘i’ or ‘i-’ or ‘j’ or ‘j-’ or ‘k’ or ‘k-’ or ‘x’ or ‘x-’ or ‘y’ or ‘y-’ or ‘z’ or ‘z-’) – Phase encoding direction.
- Outputs
out_coeff (a list of items which are a pathlike object or string representing an existing file) – Patched coefficients.
- class sdcflows.interfaces.bspline.TransformCoefficients(from_file=None, resource_monitor=None, **inputs)[source]¶
Bases:
nipype.interfaces.base.core.SimpleInterface
Project coefficients files to another space through a rigid-body transform.
- Mandatory Inputs
fmap_ref (a pathlike object or string representing an existing file) – The fieldmap reference.
in_coeff (a list of items which are a pathlike object or string representing a file) – Input coefficients file(s).
transform (a pathlike object or string representing an existing file) – Rigid-body transform file.
- Optional Inputs
fmap_target (a pathlike object or string representing an existing file) – The distorted EPI target (feed to set debug mode on).
- Outputs
out_coeff (a list of items which are a pathlike object or string representing an existing file) – Moved coefficients.
- sdcflows.interfaces.bspline.bspline_grid(img, control_zooms_mm=(40.0, 40.0, 20.0))[source]¶
Create a
Nifti1Image
embedding the location of control points.