tools.Gradunwarp

tools.Gradunwarp#

class bartorch.tools.Gradunwarp#

Bases:

Gradient nonlinearity correction of images from a coil’s coefficient table.

The coil’s spherical-harmonic field is evaluated at the scanner position \(r\) of every voxel of the target grid, giving the position \(r + d(r)\) at which that voxel was acquired, and the image is resampled there by cubic B-spline interpolation (SimpleITK), optionally multiplied by the Jacobian determinant \(|\det(I + \nabla d)|\). Geometry is in scanner coordinates, in millimetres; voxel centres are at center_mm + ((index - (n - 1) / 2) * fov_mm / n) @ orientation.T.

Parameters:

  • coefficients (str, bytes, pathlib.Path, CoefficientAccessor or GradientCoefficients) – The coil’s table, as GradientCoefficients.from_file() reads it, or already parsed.

  • shape (sequence of int) – Matrix of the acquired image, (z, y, x) or (y, x).

  • fov_mm (sequence of float) – Field of view per axis of shape, in millimetres; independent of the matrix, so a zero-filled reconstruction gives its own shape and the acquired field of view.

  • orientation (numpy.ndarray, default=None) – (3, ndim) direction cosines: column i is the unit scanner vector along which array axis i increases. None is the identity’s first ndim columns.

  • center_mm (sequence of float, default=(0.0, 0.0, 0.0)) – Scanner position of the image centre.

  • target_shape (sequence of int, default=None) – Matrix of the grid corrected onto; shape if None. The target grid shares orientation and center_mm, and correction and reslicing are one interpolation.

  • target_fov_mm (sequence of float, default=None) – Field of view of the target grid; fov_mm if None.

  • jacobian (bool, default=True) – Multiply by the Jacobian determinant of the mapping, which conserves the signal of a voxel whose volume the nonlinearity changes.

  • coefficient_format ({"auto", "dat", "grad", "coef"}, default='auto') – As in GradientCoefficients.from_file().

  • reference_radius_mm (float, default=None) – As in GradientCoefficients.from_file().

coefficients#

The parsed table.

Type:

GradientCoefficients

Examples

>>> correct = Gradunwarp("coil.grad", shape=(8, 16, 16), fov_mm=(80.0, 240.0, 240.0))
>>> corrected = correct(volume)  # (..., 8, 16, 16)
classmethod from_mrd()#

Correction for the image of one encoding of an MRD stream.

The header and the acquisition are read by attribute, as the ISMRMRD Python objects carry them; no MRD library is imported.

Parameters:

  • header (object) – MRD XML header. header.encoding[k].reconSpace gives the matrix and field of view; the table is read from the first entry of header.userParameters.userParameterString named for gradient coefficients (GradientCoefficients and similar).

  • acquisition (object) – An acquisition or its head: encoding_space_ref selects the encoding, slice_dir, phase_dir and read_dir the orientation of the (z, y, x) array axes, position the centre.

  • coefficients (str, pathlib.Path, CoefficientAccessor or GradientCoefficients, default=None) – The table, which takes precedence over the header’s; text is also accepted as bytes.

  • **kwargs – Passed to Gradunwarp.

Return type:

Gradunwarp

Raises:

ValueError – If the header has no such encoding, or no table is given or found.

classmethod from_affine()#

Correction for an image whose voxel centres map to scanner millimetres by affine.

Parameters:

  • coefficients (str, bytes, pathlib.Path, CoefficientAccessor or GradientCoefficients) – The coil’s table.

  • affine (numpy.ndarray) – (4, 4) map from array indices (i, j[, k], 1) to scanner position in millimetres.

  • shape (sequence of int) – Matrix of the image.

  • **kwargs – Passed to Gradunwarp.

Return type:

Gradunwarp

property shape#

Matrix size of the corrected image.

property source_grid#

Floating indices into the acquired image, one per corrected voxel.

property target_grid#

Scanner coordinates in millimetres of the grid being corrected onto.

property jacobian_grid#

The intensity multiplier, or ones when jacobian is off.

clear_cache()#

Drop the cached physical sampling grid and Jacobian.

__call__()#

Correct image onto the target grid.

Parameters:

image (torch.Tensor) – Real or complex image (..., *shape); the real and imaginary parts are resampled separately.

Returns:

(..., *target_shape), with the dtype and device of image (float32 for an integer image).

Return type:

torch.Tensor

Examples using Gradunwarp#

Gradient nonlinearity

Gradient nonlinearity