processing

Image processing functions

Image processing functions for:

  • smoothing

  • resampling

  • converting SD to and from FWHM

Smoothing and resampling routines need scipy.

adapt_affine(affine, n_dim)

Adapt input / output dimensions of spatial affine for n_dims

conform(from_img[, out_shape, voxel_size, ...])

Resample image to out_shape with voxels of size voxel_size.

fwhm2sigma(fwhm)

Convert a FWHM value to sigma in a Gaussian kernel.

resample_from_to(from_img, to_vox_map[, ...])

Resample image from_img to mapped voxel space to_vox_map

resample_to_output(in_img[, voxel_sizes, ...])

Resample image in_img to output voxel axes (world space)

sigma2fwhm(sigma)

Convert a sigma in a Gaussian kernel to a FWHM value

smooth_image(img, fwhm[, mode, cval, out_class])

Smooth image img along voxel axes by FWHM fwhm millimeters

adapt_affine

nibabel.processing.adapt_affine(affine, n_dim)

Adapt input / output dimensions of spatial affine for n_dims

Adapts a spatial (4, 4) affine that is being applied to an image with fewer than 3 spatial dimensions, or more than 3 dimensions. If there are more than three dimensions, assume an identity transformation for these dimensions.

Parameters:
affinearray-like

affine transform. Usually shape (4, 4). For what follows N, M = affine.shape

n_dimsint

Number of dimensions of underlying array, and therefore number of input dimensions for affine.

Returns:
adaptedshape (M, n_dims+1) array

Affine array adapted to number of input dimensions. Columns of the affine corresponding to missing input dimensions have been dropped, columns corresponding to extra input dimensions have an extra identity column added

conform

nibabel.processing.conform(from_img, out_shape=(256, 256, 256), voxel_size=(1.0, 1.0, 1.0), order=3, cval=0.0, orientation='RAS', out_class=None)

Resample image to out_shape with voxels of size voxel_size.

Using the default arguments, this function is meant to replicate most parts of FreeSurfer’s mri_convert --conform command. Specifically, this function:

  • Resamples data to output_shape

  • Resamples voxel sizes to voxel_size

  • Reorients to RAS (mri_convert --conform reorients to LIA)

Unlike mri_convert --conform, this command does not:

  • Transform data to range [0, 255]

  • Cast to unsigned eight-bit integer

Parameters:
from_imgobject

Object having attributes dataobj, affine, header and shape. If out_class is not None, img.__class__ should be able to construct an image from data, affine and header.

out_shapesequence, optional

The shape of the output volume. Default is (256, 256, 256).

voxel_sizesequence, optional

The size in millimeters of the voxels in the resampled output. Default is 1mm isotropic.

orderint, optional

The order of the spline interpolation, default is 3. The order has to be in the range 0-5 (see scipy.ndimage.affine_transform)

cvalscalar, optional

Value used for points outside the boundaries of the input if mode='constant'. Default is 0.0 (see scipy.ndimage.affine_transform)

orientationstr, optional

Orientation of output image. Default is “RAS”.

out_classNone or SpatialImage class, optional

Class of output image. If None, use from_img.__class__.

Returns:
out_imgobject

Image of instance specified by out_class, containing data output from resampling from_img into axes aligned to the output space of from_img.affine

fwhm2sigma

nibabel.processing.fwhm2sigma(fwhm)

Convert a FWHM value to sigma in a Gaussian kernel.

Parameters:
fwhmarray-like

FWHM value or values

Returns:
sigmaarray or float

sigma values corresponding to fwhm values

Examples

>>> sigma = fwhm2sigma(6)
>>> sigmae = fwhm2sigma([6, 7, 8])
>>> sigma == sigmae[0]
True

resample_from_to

nibabel.processing.resample_from_to(from_img, to_vox_map, order=3, mode='constant', cval=0.0, out_class=<class 'nibabel.nifti1.Nifti1Image'>)

Resample image from_img to mapped voxel space to_vox_map

Resample using N-d spline interpolation.

Parameters:
from_imgobject

Object having attributes dataobj, affine, header and shape. If out_class is not None, img.__class__ should be able to construct an image from data, affine and header.

to_vox_mapimage object or length 2 sequence

If object, has attributes shape giving input voxel shape, and affine giving mapping of input voxels to output space. If length 2 sequence, elements are (shape, affine) with same meaning as above. The affine is a (4, 4) array-like.

orderint, optional

The order of the spline interpolation, default is 3. The order has to be in the range 0-5 (see scipy.ndimage.affine_transform)

modestr, optional

Points outside the boundaries of the input are filled according to the given mode (‘constant’, ‘nearest’, ‘reflect’ or ‘wrap’). Default is ‘constant’ (see scipy.ndimage.affine_transform)

cvalscalar, optional

Value used for points outside the boundaries of the input if mode='constant'. Default is 0.0 (see scipy.ndimage.affine_transform)

out_classNone or SpatialImage class, optional

Class of output image. If None, use from_img.__class__.

Returns:
out_imgobject

Image of instance specified by out_class, containing data output from resampling from_img into axes aligned to the output space of from_img.affine

resample_to_output

nibabel.processing.resample_to_output(in_img, voxel_sizes=None, order=3, mode='constant', cval=0.0, out_class=<class 'nibabel.nifti1.Nifti1Image'>)

Resample image in_img to output voxel axes (world space)

Parameters:
in_imgobject

Object having attributes dataobj, affine, header. If out_class is not None, img.__class__ should be able to construct an image from data, affine and header.

voxel_sizesNone or sequence

Gives the diagonal entries of out_img.affine` (except the trailing 1 for the homogeneous coordinates) (``out_img.affine == np.diag(voxel_sizes + [1])). If None, return identity out_img.affine. If scalar, interpret as vector [voxel_sizes] * len(in_img.shape).

orderint, optional

The order of the spline interpolation, default is 3. The order has to be in the range 0-5 (see scipy.ndimage.affine_transform).

modestr, optional

Points outside the boundaries of the input are filled according to the given mode (‘constant’, ‘nearest’, ‘reflect’ or ‘wrap’). Default is ‘constant’ (see scipy.ndimage.affine_transform).

cvalscalar, optional

Value used for points outside the boundaries of the input if mode='constant'. Default is 0.0 (see scipy.ndimage.affine_transform).

out_classNone or SpatialImage class, optional

Class of output image. If None, use in_img.__class__.

Returns:
out_imgobject

Image of instance specified by out_class, containing data output from resampling in_img into axes aligned to the output space of in_img.affine

sigma2fwhm

nibabel.processing.sigma2fwhm(sigma)

Convert a sigma in a Gaussian kernel to a FWHM value

Parameters:
sigmaarray-like

sigma value or values

Returns:
fwhmarray or float

fwhm values corresponding to sigma values

Examples

>>> fwhm = sigma2fwhm(3)
>>> fwhms = sigma2fwhm([3, 4, 5])
>>> fwhm == fwhms[0]
True

smooth_image

nibabel.processing.smooth_image(img, fwhm, mode='nearest', cval=0.0, out_class=<class 'nibabel.nifti1.Nifti1Image'>)

Smooth image img along voxel axes by FWHM fwhm millimeters

Parameters:
imgobject

Object having attributes dataobj, affine, header and shape. If out_class is not None, img.__class__ should be able to construct an image from data, affine and header.

fwhmscalar or length 3 sequence

FWHM in mm over which to smooth. The smoothing applies to the voxel axes, not to the output axes, but is in millimeters. The function adjusts the FWHM to voxels using the voxel sizes calculated from the affine. A scalar implies the same smoothing across the spatial dimensions of the image, but 0 smoothing over any further dimensions such as time. A vector should be the same length as the number of image dimensions.

modestr, optional

Points outside the boundaries of the input are filled according to the given mode (‘constant’, ‘nearest’, ‘reflect’ or ‘wrap’). Default is ‘nearest’. This is different from the default for scipy.ndimage.affine_transform, which is ‘constant’. ‘nearest’ might be a better choice when smoothing to the edge of an image where there is still strong brain signal, otherwise this signal will get blurred towards zero.

cvalscalar, optional

Value used for points outside the boundaries of the input if mode='constant'. Default is 0.0 (see scipy.ndimage.affine_transform).

out_classNone or SpatialImage class, optional

Class of output image. If None, use img.__class__.

Returns:
smoothed_imgobject

Image of instance specified by out_class, containing data output from smoothing img data by given FWHM kernel.