tools.correct_susceptibility

tools.correct_susceptibility#

bartorch.tools.correct_susceptibility()#

Correct susceptibility distortion from a pair with reversed phase encoding.

The displacement field is PyHySCO’s estimate [1]: the field that brings the two images, displaced in opposite directions along the phase-encoding axis, into register, under a smoothness penalty and an invertibility constraint. The computation stays in memory and on tensors; nothing is read from or written to disk.

Parameters:

  • blip_up (torch.Tensor) – Real images of one shape, 2D or 3D, with opposite phase-encoding polarity.

  • blip_down (torch.Tensor) – Real images of one shape, 2D or 3D, with opposite phase-encoding polarity.

  • voxel_size (tuple of float) – Voxel size per axis of the images, in millimetres.

  • phase_encoding_axis (int, default=0) – Phase-encoding axis: one of the first two axes of the images.

  • alpha (float, default=300.0) – Weight of the smoothness penalty on the field.

  • beta (float, default=0.0001) – Weight of the invertibility constraint.

  • optimizer ({"gauss-newton", "lbfgs", "admm"}, default='gauss-newton') – PyHySCO optimizer.

  • max_iter (int, default=10) – Optimizer iterations.

  • device (torch.device or str, default=None) – Device of the computation, which runs in float64; that of blip_up if None.

Return type:

SusceptibilityCorrection

Raises:

  • ImportError – If PyHySCO is not installed.

  • ValueError – If the images differ in shape, voxel_size does not give one value per axis, the phase-encoding axis is not one of the first two, or the optimizer is unknown.

  • NotImplementedError – If PyHySCO’s two-dimensional regularizer fails on a 2D pair.

References