Template class for volumetric (3D/4D) images
Methods
filespec_to_file_map(klass, filespec) | Make file_map for this class from filename filespec |
filespec_to_files(*args, **kwargs) | filespec_to_files class method is deprecated. |
from_file_map(klass, file_map) | |
from_filename(klass, filename) | |
from_files(*args, **kwargs) | from_files class method is deprecated. |
from_image(klass, img) | Class method to create new instance of own class from img |
get_affine(*args, **kwargs) | Get affine from image |
get_data([caching]) | Return image data from image with any necessary scalng applied |
get_data_dtype() | |
get_filename() | Fetch the image filename |
get_header(*args, **kwargs) | Get header from image |
get_shape(*args, **kwargs) | Return shape for image |
header_class | |
instance_to_filename(klass, img, filename) | Save img in our own format, to name implied by filename |
load(klass, filename) | |
make_file_map(klass[, mapping]) | Class method to make files holder for this image type |
orthoview() | Plot the image using OrthoSlicer3D |
path_maybe_image(klass, filename[, sniff, ...]) | Return True if filename may be image matching this class |
set_data_dtype(dtype) | |
set_filename(filename) | Sets the files in the object from a given filename |
to_file_map([file_map]) | |
to_filename(filename) | Write image to files implied by filename string |
to_files(*args, **kwargs) | to_files method is deprecated. |
to_filespec(*args, **kwargs) | to_filespec method is deprecated. |
uncache() | Delete any cached read of data from proxied data |
update_header() | Harmonize header with image data and affine |
Initialize image
The image is a combination of (array, 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
|
---|
Methods
filespec_to_file_map(klass, filespec) | Make file_map for this class from filename filespec |
filespec_to_files(*args, **kwargs) | filespec_to_files class method is deprecated. |
from_file_map(klass, file_map) | |
from_filename(klass, filename) | |
from_files(*args, **kwargs) | from_files class method is deprecated. |
from_image(klass, img) | Class method to create new instance of own class from img |
get_affine(*args, **kwargs) | Get affine from image |
get_data([caching]) | Return image data from image with any necessary scalng applied |
get_data_dtype() | |
get_filename() | Fetch the image filename |
get_header(*args, **kwargs) | Get header from image |
get_shape(*args, **kwargs) | Return shape for image |
header_class | |
instance_to_filename(klass, img, filename) | Save img in our own format, to name implied by filename |
load(klass, filename) | |
make_file_map(klass[, mapping]) | Class method to make files holder for this image type |
orthoview() | Plot the image using OrthoSlicer3D |
path_maybe_image(klass, filename[, sniff, ...]) | Return True if filename may be image matching this class |
set_data_dtype(dtype) | |
set_filename(filename) | Sets the files in the object from a given filename |
to_file_map([file_map]) | |
to_filename(filename) | Write image to files implied by filename string |
to_files(*args, **kwargs) | to_files method is deprecated. |
to_filespec(*args, **kwargs) | to_filespec method is deprecated. |
uncache() | Delete any cached read of data from proxied data |
update_header() | Harmonize header with image data and affine |
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.
Return image data from image with any necessary scalng applied
The image dataobj property can be an array proxy or an array. An array proxy is an object that knows how to load the image data from disk. An image with an array proxy dataobj is a proxy image; an image with an array in dataobj is an array image.
The default behavior for get_data() on a proxy image is to read the data from the proxy, and store in an internal cache. Future calls to get_data will return the cached array. This is the behavior selected with caching == “fill”.
Once the data has been cached and returned from an array proxy, if you modify the returned array, you will also modify the cached array (because they are the same array). Regardless of the caching flag, this is always true of an array image.
Parameters: | caching : {‘fill’, ‘unchanged’}, optional
|
---|---|
Returns: | data : array
|
See also
Notes
All images have a property dataobj that represents the image array data. Images that have been loaded from files usually do not load the array data from file immediately, in order to reduce image load time and memory use. For these images, dataobj is an array proxy; an object that knows how to load the image array data from file.
By default (caching == “fill”), when you call get_data on a proxy image, we load the array data from disk, store (cache) an internal reference to this array data, and return the array. The next time you call get_data, you will get the cached reference to the array, so we don’t have to load the array data from disk again.
Array images have a dataobj property that already refers to an array in memory, so there is no benefit to caching, and the caching keywords have no effect.
For proxy images, you may not want to fill the cache after reading the data from disk because the cache will hold onto the array memory until the image object is deleted, or you use the image uncache method. If you don’t want to fill the cache, then always use get_data(caching='unchanged'); in this case get_data will not fill the cache (store the reference to the array) if the cache is empty (no reference to the array). If the cache is full, “unchanged” leaves the cache full and returns the cached array reference.
The cache can effect the behavior of the image, because if the cache is full, or you have an array image, then modifying the returned array will modify the result of future calls to get_data(). For example you might do this:
>>> import os
>>> import nibabel as nib
>>> from nibabel.testing import data_path
>>> img_fname = os.path.join(data_path, 'example4d.nii.gz')
>>> img = nib.load(img_fname) # This is a proxy image
>>> nib.is_proxy(img.dataobj)
True
The array is not yet cached by a call to “get_data”, so:
>>> img.in_memory
False
After we call get_data using the default caching == ‘fill’, the cache contains a reference to the returned array data:
>>> data = img.get_data()
>>> img.in_memory
True
We modify an element in the returned data array:
>>> data[0, 0, 0, 0]
0
>>> data[0, 0, 0, 0] = 99
>>> data[0, 0, 0, 0]
99
The next time we call ‘get_data’, the method returns the cached reference to the (modified) array:
>>> data_again = img.get_data()
>>> data_again is data
True
>>> data_again[0, 0, 0, 0]
99
If you had initially used caching == ‘unchanged’ then the returned data array would have been loaded from file, but not cached, and:
>>> img = nib.load(img_fname) # a proxy image again
>>> data = img.get_data(caching='unchanged')
>>> img.in_memory
False
>>> data[0, 0, 0] = 99
>>> data_again = img.get_data(caching='unchanged')
>>> data_again is data
False
>>> data_again[0, 0, 0, 0]
0
Return shape for image
get_shape method is deprecated. Please use the img.shape property instead.
alias of SpatialHeader
True when array data is in memory
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.
Delete any cached read of data from proxied data
Remember there are two types of images:
If you call img.get_data() on a proxy image, the result of reading from the proxy gets cached inside the image object, and this cache is what gets returned from the next call to img.get_data(). If you modify the returned data, as in:
data = img.get_data()
data[:] = 42
then the next call to img.get_data() returns the modified array, whether the image is an array image or a proxy image:
assert np.all(img.get_data() == 42)
When you uncache an array image, this has no effect on the return of img.get_data(), but when you uncache a proxy image, the result of img.get_data() returns to its original value.
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)