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() function is a sub-function of resample().

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

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:

  • image – Image to resample

  • pixdims – New voxel dimensions to resample image to.

fsl.utils.image.resample.resampleToReference(image, reference, matrix=None, **kwargs)[source]

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.

When resampling to a reference image, resampling will only be applied along the spatial (first three) dimensions.

Parameters:

  • image – Image to resample

  • reference – Nifti defining the space to resample image into

  • matrix – Optional world-to-world affine alignment matrix

fsl.utils.image.resample.resample(image, newShape, sliceobj=None, dtype=None, order=1, smooth=True, origin=None, matrix=None, mode=None, cval=0)[source]

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.

Note

If a custom resampling matrix is specified, the adjusted voxel-to-world afffine cannot be calculated by this function, so None will be returned instead.

Parameters:

  • image – Image object to resample

  • 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.

  • dtype – numpy 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, or None if a matrix was provided.

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

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.