Nibabel images

A nibabel image object is the association of three things:

• an N-D array containing the image data;

• a (4, 4) affine matrix mapping array coordinates to coordinates in some RAS+ world coordinate space (Coordinate systems and affines);

• image metadata in the form of a header.

The image object

First we load some libraries we are going to need for the examples:

>>> import os
>>> import numpy as np

There is an example image in the nibabel distribution.

>>> from nibabel.testing import data_path
>>> example_file = os.path.join(data_path, 'example4d.nii.gz')

We load the file to create a nibabel image object:

>>> import nibabel as nib
>>> img = nib.load(example_file)

The object img is an instance of a nibabel image. In fact it is an instance of a nibabel nibabel.nifti1.Nifti1Image:

>>> img
<nibabel.nifti1.Nifti1Image object at ...>

As with any Python object, you can inspect img to see what attributes it has. We recommend using IPython tab completion for this, but here are some examples of interesting attributes:

dataobj is the object pointing to the image array data:

>>> img.dataobj
<nibabel.arrayproxy.ArrayProxy object at ...>

See Array proxies and proxy images for more on why this is an array proxy.

affine is the affine array relating array coordinates from the image data array to coordinates in some RAS+ world coordinate system (Coordinate systems and affines):

>>> # Set numpy to print only 2 decimal digits for neatness
>>> np.set_printoptions(precision=2, suppress=True)

>>> img.affine
array([[ -2.  ,   0.  ,   0.  , 117.86],
       [ -0.  ,   1.97,  -0.36, -35.72],
       [  0.  ,   0.32,   2.17,  -7.25],
       [  0.  ,   0.  ,   0.  ,   1.  ]])

header contains the metadata for this image. In this case it is specifically NIfTI metadata:

>>> img.header
<nibabel.nifti1.Nifti1Header object at ...>

The image header

The header of an image contains the image metadata. The information in the header will differ between different image formats. For example, the header information for a NIfTI1 format file differs from the header information for a MINC format file.

Our image is a NIfTI1 format image, and it therefore has a NIfTI1 format header:

>>> header = img.header
>>> print(header)                           
<class 'nibabel.nifti1.Nifti1Header'> object, endian='<'
sizeof_hdr      : 348
data_type       : b''
db_name         : b''
extents         : 0
session_error   : 0
regular         : b'r'
dim_info        : 57
dim             : [  4 128  96  24   2   1   1   1]
intent_p1       : 0.0
intent_p2       : 0.0
intent_p3       : 0.0
intent_code     : none
datatype        : int16
bitpix          : 16
slice_start     : 0
pixdim          : [   -1.      2.      2.      2.2  2000.      1.      1.      1. ]
vox_offset      : 0.0
scl_slope       : nan
scl_inter       : nan
slice_end       : 23
slice_code      : unknown
xyzt_units      : 10
cal_max         : 1162.0
cal_min         : 0.0
slice_duration  : 0.0
toffset         : 0.0
glmax           : 0
glmin           : 0
descrip         : b'FSL3.3\x00 v2.25 NIfTI-1 Single file format'
aux_file        : b''
qform_code      : scanner
sform_code      : scanner
quatern_b       : -1.94510681403e-26
quatern_c       : -0.996708512306
quatern_d       : -0.081068739295
qoffset_x       : 117.855102539
qoffset_y       : -35.7229423523
qoffset_z       : -7.24879837036
srow_x          : [  -2.      0.      0.    117.86]
srow_y          : [ -0.     1.97  -0.36 -35.72]
srow_z          : [ 0.    0.32  2.17 -7.25]
intent_name     : b''
magic           : b'n+1'

The header of any image will normally have the following methods:

• get_data_shape() to get the output shape of the image data array:

  >>> print(header.get_data_shape())
  (128, 96, 24, 2)
  

• get_data_dtype() to get the numpy data type in which the image data is stored (or will be stored if you save the image):

  >>> print(header.get_data_dtype())
  int16
  

• get_zooms() to get the voxel sizes in millimeters:

  >>> print(header.get_zooms())
  (2.0, 2.0, 2.19999..., 2000.0)
  

  The last value of header.get_zooms() is the time between scans in milliseconds; this is the equivalent of voxel size on the time axis.

The image data array

The image data array is a little more complicated, because the image array can be stored in the image object as a numpy array or stored on disk for you to access later via an array proxy.

Array proxies and proxy images

When you load an image from disk, as we did here, the data is likely to be accessible via an array proxy. An array proxy is not the array itself but something that represents the array, and can provide the array when we ask for it.

Our image does have an array proxy, as we have already seen:

>>> img.dataobj
<nibabel.arrayproxy.ArrayProxy object at ...>

The array proxy allows us to create the image object without immediately loading all the array data from disk.

Images with an array proxy object like this one are called proxy images because the image data is not yet an array, but the array proxy points to (proxies) the array data on disk.

You can test if the image has a array proxy like this:

>>> nib.is_proxy(img.dataobj)
True

Array images

We can also create images from numpy arrays. For example:

>>> array_data = np.arange(24, dtype=np.int16).reshape((2, 3, 4))
>>> affine = np.diag([1, 2, 3, 1])
>>> array_img = nib.Nifti1Image(array_data, affine)

In this case the image array data is already a numpy array, and there is no version of the array on disk. The dataobj property of the image is the array itself rather than a proxy for the array:

>>> array_img.dataobj
array([[[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]],

       [[12, 13, 14, 15],
        [16, 17, 18, 19],
        [20, 21, 22, 23]]], dtype=int16)
>>> array_img.dataobj is array_data
True

dataobj is an array, not an array proxy, so:

>>> nib.is_proxy(array_img.dataobj)
False

Getting the image data the easy way

For either type of image (array or proxy) you can always get the data with the get_fdata() method.

For the array image, get_fdata() just returns the data array, if it’s already the required floating point type (default 64-bit float). If it isn’t that type, get_fdata() casts it to one:

>>> image_data = array_img.get_fdata()
>>> image_data.shape
(2, 3, 4)
>>> image_data.dtype == np.dtype(np.float64)
True

The cast to floating point means the array is not the one attached to the image:

>>> image_data is array_img.dataobj
False

Here’s an image backed by a floating point array:

>>> farray_img = nib.Nifti1Image(image_data.astype(np.float64), affine)
>>> farray_data = farray_img.get_fdata()
>>> farray_data.dtype == np.dtype(np.float64)
True

There was no cast, so the array returned is exactly the array attached to the image:

>>> farray_data is farray_img.dataobj
True

For the proxy image, the get_fdata() method fetches the array data from disk using the proxy, and returns the array.

>>> image_data = img.get_fdata()
>>> image_data.shape
(128, 96, 24, 2)

The image dataobj property is still a proxy object:

>>> img.dataobj
<nibabel.arrayproxy.ArrayProxy object at ...>

Proxies and caching

You may not want to keep loading the image data off disk every time you call get_fdata() on a proxy image. By default, when you call get_fdata() the first time on a proxy image, the image object keeps a cached copy of the loaded array. The next time you call img.get_fdata(), the image returns the array from cache rather than loading it from disk again.

>>> data_again = img.get_fdata()

The returned data is the same (cached) copy we returned before:

>>> data_again is image_data
True

See Images and memory for more details on managing image memory and controlling the image cache.

Image slicing

At times it is useful to manipulate an image’s shape while keeping it in the same coordinate system. The slicer attribute provides an array-slicing interface to produce new images with an appropriately adjusted header, such that the data at a given RAS+ location is unchanged.

>>> cropped_img = img.slicer[32:-32, ...]
>>> cropped_img.shape
(64, 96, 24, 2)

The data is identical to cropping the data block directly:

>>> np.array_equal(cropped_img.get_fdata(), img.get_fdata()[32:-32, ...])
True

However, unused data did not need to be loaded into memory or scaled. Additionally, the image affine was adjusted so that the X-translation is 32 voxels (64mm) less:

>>> cropped_img.affine
array([[ -2.  ,   0.  ,   0.  ,  53.86],
       [ -0.  ,   1.97,  -0.36, -35.72],
       [  0.  ,   0.32,   2.17,  -7.25],
       [  0.  ,   0.  ,   0.  ,   1.  ]])

>>> img.affine - cropped_img.affine
array([[ 0.,  0.,  0., 64.],
       [ 0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.]])

Another use for the slicer object is to choose specific volumes from a time series:

>>> vol0 = img.slicer[..., 0]
>>> vol0.shape
(128, 96, 24)

Or a selection of volumes:

>>> img.slicer[..., :1].shape
(128, 96, 24, 1)
>>> img.slicer[..., :2].shape
(128, 96, 24, 2)

It is also possible to use an integer step when slicing, downsampling the image without filtering. Note that this will induce artifacts in the frequency spectrum (aliasing) along any axis that is down-sampled.

>>> downsampled = vol0.slicer[::2, ::2, ::2]
>>> downsampled.header.get_zooms()
(4.0, 4.0, 4.399998)

Finally, an image can be flipped along an axis, maintaining an appropriate affine matrix:

>>> nib.orientations.aff2axcodes(img.affine)
('L', 'A', 'S')
>>> ras = img.slicer[::-1]
>>> nib.orientations.aff2axcodes(ras.affine)
('R', 'A', 'S')
>>> ras.affine
array([[  2.  ,   0.  ,   0.  , 117.86],
       [  0.  ,   1.97,  -0.36, -35.72],
       [ -0.  ,   0.32,   2.17,  -7.25],
       [  0.  ,   0.  ,   0.  ,   1.  ]])

Loading and saving

The save and load functions in nibabel should do all the work for you:

>>> nib.save(array_img, 'my_image.nii')
>>> img_again = nib.load('my_image.nii')
>>> img_again.shape
(2, 3, 4)

You can also use the to_filename method:

>>> array_img.to_filename('my_image_again.nii')
>>> img_again = nib.load('my_image_again.nii')
>>> img_again.shape
(2, 3, 4)

You can get and set the filename with get_filename() and set_filename():

>>> img_again.set_filename('another_image.nii')
>>> img_again.get_filename()
'another_image.nii'

Details of files and images

If an image can be loaded or saved on disk, the image will have an attribute called file_map. img.file_map is a dictionary where the keys are the names of the files that the image uses to load / save on disk, and the values are FileHolder objects, that usually contain the filenames that the image has been loaded from or saved to. In the case of a NiFTI1 single file, this is just a single image file with a .nii or .nii.gz extension:

>>> list(img_again.file_map)
['image']
>>> img_again.file_map['image'].filename
'another_image.nii'

Other file types need more than one file to make up the image. The NiFTI1 pair type is one example. NIfTI pair images have one file containing the header information and another containing the image array data:

>>> pair_img = nib.Nifti1Pair(array_data, np.eye(4))
>>> nib.save(pair_img, 'my_pair_image.img')
>>> sorted(pair_img.file_map)
['header', 'image']
>>> pair_img.file_map['header'].filename
'my_pair_image.hdr'
>>> pair_img.file_map['image'].filename
'my_pair_image.img'

The older Analyze format also has a separate header and image file:

>>> ana_img = nib.AnalyzeImage(array_data, np.eye(4))
>>> sorted(ana_img.file_map)
['header', 'image']

It is the contents of the file_map that gets changed when you use set_filename or to_filename:

>>> ana_img.set_filename('analyze_image.img')
>>> ana_img.file_map['image'].filename
'analyze_image.img'
>>> ana_img.file_map['header'].filename
'analyze_image.hdr'