fsl.utils.image.resample

This module defines the resample() function, which can be used to resample an Image object to a different resolution.

The resampleToPixdims() and resampleToReference() functions are convenience wrappers around resample().

The applySmoothing() and calculateMatrix() functions are sub-functions of resample().

fsl.utils.image.resample.resampleToPixdims(image, newPixdims, **kwargs)

Resample image so that it has the specified voxel dimensions.

This is a wrapper around resample() - refer to its documenttion for details on the other arguments and the return values.

Parameters
  • imageImage to resample

  • pixdims – New voxel dimensions to resample image to.

fsl.utils.image.resample.resampleToReference(image, reference, **kwargs)

Resample image into the space of the reference.

This is a wrapper around resample() - refer to its documenttion for details on the other arguments and the return values.

Parameters
  • imageImage to resample

  • referenceNifti defining the space to resample image into

fsl.utils.image.resample.resample(image, newShape, sliceobj=None, dtype=None, order=1, smooth=True, origin='centre', matrix=None, mode='nearest', cval=0)

Returns a copy of the data in the image, resampled to the specified newShape.

The space that the image is resampled into can be defined in one of the following ways, in decreasing order of precedence:

  1. If a matrix is provided, it is applied to the voxel coordinates when retrieving values from the image

  2. Otherwise the image is simply scaled according to the ratio calculated by image.shape / newShape. In this case the origin argument may be used to adjust the alignemnt of the original and resampled voxel grids.

See the scipy.ndimage.affine_transform function for more details, particularly on the order, matrix, mode and cval arguments.

Parameters
  • newShape – Desired shape. May containg floating point values, in which case the resampled image will have shape round(newShape), but the voxel sizes will have scales self.shape / newShape (unless matrix is specified).

  • sliceobj – Slice into this Image. If None, the whole image is resampled, and it is assumed that it has the same number of dimensions as newShape. A ValueError is raised if this is not the case.

  • dtypenumpy data type of the resampled data. If None, the dtype() of this Image is used.

  • order – Spline interpolation order, passed through to the scipy.ndimage.affine_transform function - 0 corresponds to nearest neighbour interpolation, 1 (the default) to linear interpolation, and 3 to cubic interpolation.

  • smooth – If True (the default), the data is smoothed before being resampled, but only along axes which are being down-sampled (i.e. where newShape[i] < self.shape[i]).

  • origin'centre' (the default) or 'corner'. 'centre' resamples the image such that the centre of the corner voxels of this image and the resampled data are aligned. 'corner' resamples the image such that the corner of the corner voxels are aligned (and therefore the voxel grids are aligned). Ignored if offset or matrix is specified.

  • matrix – Arbitrary affine transformation matrix to apply to the voxel coordinates of image when resampling.

  • mode – How to handle regions which are outside of the image FOV. Defaults to ‘’nearest’`.

  • cval – Constant value to use when mode='constant'.

Returns

A tuple containing:

  • A numpy array of shape newShape, containing an interpolated copy of the data in this Image.

  • A numpy array of shape (4, 4), containing the adjusted voxel-to-world transformation for the spatial dimensions of the resampled data.

fsl.utils.image.resample.applySmoothing(data, matrix, newShape)

Called by the resample() function.

If interpolating and smoothing, we apply a gaussian filter along axes with a resampling ratio greater than 1.1. We do this so that interpolation has an effect when down-sampling to a resolution where the voxel centres are aligned (as otherwise any interpolation regime will be equivalent to nearest neighbour). This more-or-less mimics the behaviour of FLIRT.

See the scipy.ndimage.gaussian_filter function for more details.

Parameters
  • data – Data to be smoothed.

  • matrix – Affine matrix to be used during resampling. The voxel scaling factors are extracted from this.

  • newShape – Shape the data is to be resampled into.

Returns

A smoothed copy of data.

fsl.utils.image.resample.calculateMatrix(oldShape, newShape, origin)

Calculates an affine matrix to use for resampling.

Called by resample(). The matrix will contain scaling factors determined from the oldShape / newShape ratio, and an offset determined from the origin.

Parameters
  • oldShape – Shape of input data

  • newShape – Shape to resample data to

  • origin – Voxel grid alignment - either 'centre' or 'corner'

Returns

An affine matrix that can be passed to scipy.ndimage.affine_transform.