nibabel.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()
.get_data() (deprecated, use get_fdata() instead)
.get_affine() (deprecated, use affine property instead)
.get_header() (deprecated, use header property instead)
.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.
.get_shape() (deprecated)
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 filenamefname
.
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 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_files
) 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
Functions
|
Numpy data types that instance obj supports |
Classes
|
Alias for SpatialHeader; kept for backwards compatibility. |
|
Slicing interface that returns a new image with an updated affine |
|
Template class to implement header protocol |
|
Template class for volumetric (3D/4D) images |
Exceptions
|
Class to indicate error in getting or setting header data |
|
Class to indicate error in parameters into header functions |
|