spatialimages

A simple spatial image class

The image class maintains the association between a 3D (or greater) array, and an affine transform that maps voxel coordinates to some world space. It also has a header - some standard set of meta-data that is specific to the image format, and extra - a dictionary container for any other metadata.

It has attributes:

  • extra

methods:

  • .get_fdata()

  • .to_filename(fname) - writes data to filename(s) derived from fname, where the derivation may differ between formats.

  • to_file_map() - save image to files with which the image is already associated.

properties:

  • shape

  • affine

  • header

  • dataobj

classmethods:

  • from_filename(fname) - make instance by loading from filename

  • from_file_map(fmap) - make instance from file map

  • instance_to_filename(img, fname) - save img instance to filename fname.

You cannot slice an image, and trying to slice an image generates an informative TypeError.

There are several ways of writing data.

There is the usual way, which is the default:

img.to_filename(fname)

and that is, to take the data encapsulated by the image and cast it to the datatype the header expects, setting any available header scaling into the header to help the data match.

You can load the data into an image from file with:

img.from_filename(fname)

The image stores its associated files in its file_map attribute. In order to just save an image, for which you know there is an associated filename, or other storage, you can do:

img.to_file_map()

You can get the data out again with:

img.get_fdata()

Less commonly, for some image types that support it, you might want to fetch out the unscaled array via the object containing the data:

unscaled_data = img.dataoobj.get_unscaled()

Analyze-type images (including nifti) support this, but others may not (MINC, for example).

Sometimes you might to avoid any loss of precision by making the data type the same as the input:

hdr = img.header
hdr.set_data_dtype(data.dtype)
img.to_filename(fname)

Files interface

The image has an attribute file_map. This is a mapping, that has keys corresponding to the file types that an image needs for storage. For example, the Analyze data format needs an image and a header file type for storage:

>>> import numpy as np
>>> import nibabel as nib
>>> data = np.arange(24, dtype='f4').reshape((2,3,4))
>>> img = nib.AnalyzeImage(data, np.eye(4))
>>> sorted(img.file_map)
['header', 'image']

The values of file_map are not in fact files but objects with attributes filename, fileobj and pos.

The reason for this interface, is that the contents of files has to contain enough information so that an existing image instance can save itself back to the files pointed to in file_map. When a file holder holds active file-like objects, then these may be affected by the initial file read; in this case, the contains file-like objects need to carry the position at which a write (with to_file_map) should place the data. The file_map contents should therefore be such, that this will work:

>>> # write an image to files
>>> from io import BytesIO
>>> import nibabel as nib
>>> file_map = nib.AnalyzeImage.make_file_map()
>>> file_map['image'].fileobj = BytesIO()
>>> file_map['header'].fileobj = BytesIO()
>>> img = nib.AnalyzeImage(data, np.eye(4))
>>> img.file_map = file_map
>>> img.to_file_map()
>>> # read it back again from the written files
>>> img2 = nib.AnalyzeImage.from_file_map(file_map)
>>> np.all(img2.get_fdata(dtype=np.float32) == data)
True
>>> # write, read it again
>>> img2.to_file_map()
>>> img3 = nib.AnalyzeImage.from_file_map(file_map)
>>> np.all(img3.get_fdata(dtype=np.float32) == data)
True

HeaderDataError

Class to indicate error in getting or setting header data

HeaderTypeError

Class to indicate error in parameters into header functions

ImageDataError

SpatialFirstSlicer(img)

Slicing interface that returns a new image with an updated affine

SpatialHeader([data_dtype, shape, zooms])

Template class to implement header protocol

SpatialImage(dataobj, affine[, header, ...])

Template class for volumetric (3D/4D) images

supported_np_types(obj)

Numpy data types that instance obj supports

HeaderDataError

class nibabel.spatialimages.HeaderDataError

Bases: Exception

Class to indicate error in getting or setting header data

__init__(*args, **kwargs)

HeaderTypeError

class nibabel.spatialimages.HeaderTypeError

Bases: Exception

Class to indicate error in parameters into header functions

__init__(*args, **kwargs)

ImageDataError

class nibabel.spatialimages.ImageDataError

Bases: Exception

__init__(*args, **kwargs)

SpatialFirstSlicer

class nibabel.spatialimages.SpatialFirstSlicer(img)

Bases: object

Slicing interface that returns a new image with an updated affine

Checks that an image’s first three axes are spatial

__init__(img)
check_slicing(slicer, return_spatial=False)

Canonicalize slicers and check for scalar indices in spatial dims

Parameters:
slicerobject

something that can be used to slice an array as in arr[sliceobj]

return_spatialbool

return only slices along spatial dimensions (x, y, z)

Returns:
slicerobject

Validated slicer object that will slice image’s dataobj without collapsing spatial dimensions

slice_affine(slicer)

Retrieve affine for current image, if sliced by a given index

Applies scaling if down-sampling is applied, and adjusts the intercept to account for any cropping.

Parameters:
slicerobject

something that can be used to slice an array as in arr[sliceobj]

Returns:
affine(4,4) ndarray

Affine with updated scale and intercept

SpatialHeader

class nibabel.spatialimages.SpatialHeader(data_dtype=<class 'numpy.float32'>, shape=(0, ), zooms=None)

Bases: FileBasedHeader

Template class to implement header protocol

__init__(data_dtype=<class 'numpy.float32'>, shape=(0, ), zooms=None)
copy()

Copy object to independent representation

The copy should not be affected by any changes to the original object.

data_from_fileobj(fileobj)

Read binary image data from fileobj

data_layout = 'F'
data_to_fileobj(data, fileobj, rescale=True)

Write array data data as binary to fileobj

Parameters:
dataarray-like

data to write

fileobjfile-like object

file-like object implementing ‘write’

rescale{True, False}, optional

Whether to try and rescale data to match output dtype specified by header. For this minimal header, rescale has no effect

default_x_flip = True
classmethod from_fileobj(fileobj)
classmethod from_header(header=None)
get_base_affine()
get_best_affine()
get_data_dtype()
get_data_shape()
get_zooms()
set_data_dtype(dtype)
set_data_shape(shape)
set_zooms(zooms)
write_to(fileobj)

SpatialImage

class nibabel.spatialimages.SpatialImage(dataobj, affine, header=None, extra=None, file_map=None)

Bases: DataobjImage

Template class for volumetric (3D/4D) images

Initialize image

The image is a combination of (array-like, affine matrix, header), with optional metadata in extra, and filename / file-like objects contained in the file_map mapping.

Parameters:
dataobjobject

Object containing image data. It should be some object that returns an array from np.asanyarray. It should have a shape attribute or property

affineNone or (4,4) array-like

homogeneous affine giving relationship between voxel coordinates and world coordinates. Affine can also be None. In this case, obj.affine also returns None, and the affine as written to disk will depend on the file format.

headerNone or mapping or header instance, optional

metadata for this image format

extraNone or mapping, optional

metadata to associate with image that cannot be stored in the metadata of this image type

file_mapmapping, optional

mapping giving file information for this image format

__init__(dataobj, affine, header=None, extra=None, file_map=None)

Initialize image

The image is a combination of (array-like, affine matrix, header), with optional metadata in extra, and filename / file-like objects contained in the file_map mapping.

Parameters:
dataobjobject

Object containing image data. It should be some object that returns an array from np.asanyarray. It should have a shape attribute or property

affineNone or (4,4) array-like

homogeneous affine giving relationship between voxel coordinates and world coordinates. Affine can also be None. In this case, obj.affine also returns None, and the affine as written to disk will depend on the file format.

headerNone or mapping or header instance, optional

metadata for this image format

extraNone or mapping, optional

metadata to associate with image that cannot be stored in the metadata of this image type

file_mapmapping, optional

mapping giving file information for this image format

ImageSlicer

alias of SpatialFirstSlicer

property affine
as_reoriented(ornt)

Apply an orientation change and return a new image

If ornt is identity transform, return the original image, unchanged

Parameters:
ornt(n,2) orientation array

orientation transform. ornt[N,1]` is flip of axis N of the array implied by `shape`, where 1 means no flip and -1 means flip.  For example, if ``N==0 and ornt[0,1] == -1, and there’s an array arr of shape shape, the flip would correspond to the effect of np.flipud(arr). ornt[:,0] is the transpose that needs to be done to the implied array, as in arr.transpose(ornt[:,0])

Notes

Subclasses should override this if they have additional requirements when re-orienting an image.

classmethod from_image(img)

Class method to create new instance of own class from img

Parameters:
imgspatialimage instance

In fact, an object with the API of spatialimage - specifically dataobj, affine, header and extra.

Returns:
cimgspatialimage instance

Image, of our own class

get_data_dtype()
header_class

alias of SpatialHeader

orthoview()

Plot the image using OrthoSlicer3D

Returns:
viewerinstance of OrthoSlicer3D

The viewer.

Notes

This requires matplotlib. If a non-interactive backend is used, consider using viewer.show() (equivalently plt.show()) to show the figure.

set_data_dtype(dtype)
property slicer

Slicer object that returns cropped and subsampled images

The image is resliced in the current orientation; no rotation or resampling is performed, and no attempt is made to filter the image to avoid aliasing.

The affine matrix is updated with the new intercept (and scales, if down-sampling is used), so that all values are found at the same RAS locations.

Slicing may include non-spatial dimensions. However, this method does not currently adjust the repetition time in the image header.

update_header()

Harmonize header with image data and affine

>>> data = np.zeros((2,3,4))
>>> affine = np.diag([1.0,2.0,3.0,1.0])
>>> img = SpatialImage(data, affine)
>>> img.shape == (2, 3, 4)
True
>>> img.update_header()
>>> img.header.get_data_shape() == (2, 3, 4)
True
>>> img.header.get_zooms()
(1.0, 2.0, 3.0)

supported_np_types

nibabel.spatialimages.supported_np_types(obj)

Numpy data types that instance obj supports

Parameters:
objobject

Object implementing get_data_dtype and set_data_dtype. The object should raise HeaderDataError for setting unsupported dtypes. The object will likely be a header or a SpatialImage

Returns:
np_typesset

set of numpy types that obj supports