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_data()
- .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 filename fname.
You cannot slice an image, and trying to slice an image generates an informative TypeError.
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_data()
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)
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_data() == data)
True
>>> # write, read it again
>>> img2.to_file_map()
>>> img3 = nib.AnalyzeImage.from_file_map(file_map)
>>> np.all(img3.get_data() == data)
True
Header(*args, **kwargs) | Alias for SpatialHeader; kept for backwards compatibility. |
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 |
Bases: nibabel.spatialimages.SpatialHeader
Alias for SpatialHeader; kept for backwards compatibility.
Header class is deprecated. Please use SpatialHeader instead.instead.
Header class is deprecated. Please use SpatialHeader instead.instead.
Bases: object
Slicing interface that returns a new image with an updated affine
Checks that an image’s first three axes are spatial
Canonicalize slicers and check for scalar indices in spatial dims
Parameters: | slicer : object
return_spatial : bool
|
---|---|
Returns: | slicer : object
|
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: | slicer : object
|
---|---|
Returns: | affine : (4,4) ndarray
|
Bases: nibabel.filebasedimages.FileBasedHeader
Template class to implement header protocol
Copy object to independent representation
The copy should not be affected by any changes to the original object.
Read binary image data from fileobj
Write array data data as binary to fileobj
Parameters: | data : array-like
fileobj : file-like object
rescale : {True, False}, optional
|
---|
Bases: nibabel.dataobj_images.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: | dataobj : object
affine : None or (4,4) array-like
header : None or mapping or header instance, optional
extra : None or mapping, optional
file_map : mapping, optional
|
---|
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: | dataobj : object
affine : None or (4,4) array-like
header : None or mapping or header instance, optional
extra : None or mapping, optional
file_map : mapping, optional
|
---|
alias of SpatialFirstSlicer
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
|
---|
Notes
Subclasses should override this if they have additional requirements when re-orienting an image.
Class method to create new instance of own class from img
Parameters: | img : spatialimage instance
|
---|---|
Returns: | cimg : spatialimage instance
|
Get affine from image
get_affine method is deprecated. Please use the img.affine property instead.
alias of SpatialHeader
Plot the image using OrthoSlicer3D
Returns: | viewer : instance of OrthoSlicer3D
|
---|
Notes
This requires matplotlib. If a non-interactive backend is used, consider using viewer.show() (equivalently plt.show()) to show the figure.
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.
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)
Numpy data types that instance obj supports
Parameters: | obj : object
|
---|---|
Returns: | np_types : set
|