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_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 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_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)
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
>>> 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 ([data_dtype, shape, zooms]) |
Template class to implement header protocol |
HeaderDataError |
Class to indicate error in getting or setting header data |
HeaderTypeError |
Class to indicate error in parameters into header functions |
ImageDataError |
|
ImageFileError |
|
SpatialImage (dataobj, affine[, header, ...]) |
Initialize image |
supported_np_types (obj) |
Numpy data types that instance obj supports |
Header
¶
-
class
nibabel.spatialimages.
Header
(data_dtype=<type 'numpy.float32'>, shape=(0, ), zooms=None)¶ Bases:
object
Template class to implement header protocol
-
__init__
(data_dtype=<type '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: data : array-like
data to write
fileobj : file-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
(klass, fileobj)¶
-
classmethod
from_header
(klass, 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:
object
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
Object containg image data. It should be some object that retuns an array from
np.asanyarray
. It should have ashape
attribute or propertyaffine : None or (4,4) array-like
homogenous 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.header : None or mapping or header instance, optional
metadata for this image format
extra : None or mapping, optional
metadata to associate with image that cannot be stored in the metadata of this image type
file_map : mapping, 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, affine matrix, header), with optional metadata in extra, and filename / file-like objects contained in the file_map mapping.
Parameters: dataobj : object
Object containg image data. It should be some object that retuns an array from
np.asanyarray
. It should have ashape
attribute or propertyaffine : None or (4,4) array-like
homogenous 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.header : None or mapping or header instance, optional
metadata for this image format
extra : None or mapping, optional
metadata to associate with image that cannot be stored in the metadata of this image type
file_map : mapping, optional
mapping giving file information for this image format
-
affine
¶
-
dataobj
¶
-
files_types
= (('image', None),)¶
-
classmethod
filespec_to_file_map
(klass, filespec)¶ Make file_map for this class from filename filespec
Class method
Parameters: filespec : str
Filename that might be for this image file type.
Returns: file_map : dict
file_map dict with (key, value) pairs of (
file_type
, FileHolder instance), wherefile_type
is a string giving the type of the contained file.Raises: ImageFileError :
if filespec is not recognizable as being a filename for this image type.
-
classmethod
filespec_to_files
(klass, filespec)¶
-
classmethod
from_file_map
(klass, file_map)¶
-
classmethod
from_filename
(klass, filename)¶
-
classmethod
from_files
(klass, file_map)¶
-
classmethod
from_filespec
(klass, filespec)¶
-
classmethod
from_image
(klass, img)¶ Class method to create new instance of own class from img
Parameters: img :
spatialimage
instanceIn fact, an object with the API of
spatialimage
- specificallydataobj
,affine
,header
andextra
.Returns: cimg :
spatialimage
instanceImage, of our own class
-
get_affine
()¶ Get affine from image
Please use the affine property instead of get_affine; we will deprecate this method in future versions of nibabel.
-
get_data
(caching='fill')¶ 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 proxydataobj
is a proxy image; an image with an array indataobj
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 toget_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
See the Notes section for a detailed explanation. This argument specifies whether the image object should fill in an internal cached reference to the returned image data array. “fill” specifies that the image should fill an internal cached reference if currently empty. Future calls to
get_data
will return this cached reference. You might prefer “fill” to save the image object from having to reload the array data from disk on each call toget_data
. “unchanged” means that the image should not fill in the internal cached reference if the cache is currently empty. You might prefer “unchanged” to “fill” if you want to make sure that the call toget_data
does not create an extra (cached) reference to the returned array. In this case it is easier for Python to free the memory from the returned array.Returns: data : array
array of image data
See also
uncache
- empty the array data cache
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 callget_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 useget_data(caching='unchanged')
; in this caseget_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
-
get_data_dtype
()¶
-
get_filename
()¶ Fetch the image filename
Parameters: None :
Returns: fname : None or str
Returns None if there is no filename, or a filename string. If an image may have several filenames assoctiated with it (e.g Analyze
.img, .hdr
pair) then we return the more characteristic filename (the.img
filename in the case of Analyze’)
-
get_header
()¶ Get header from image
Please use the header property instead of get_header; we will deprecate this method in future versions of nibabel.
-
get_shape
()¶ Return shape for image
This function deprecated; please use the
shape
property instead
-
header
¶
-
in_memory
¶ True when array data is in memory
-
classmethod
instance_to_filename
(klass, img, filename)¶ Save img in our own format, to name implied by filename
This is a class method
Parameters: img :
spatialimage
instanceIn fact, an object with the API of
spatialimage
- specificallydataobj
,affine
,header
andextra
.filename : str
Filename, implying name to which to save image.
-
classmethod
load
(klass, filename)¶
-
classmethod
make_file_map
(klass, mapping=None)¶ Class method to make files holder for this image type
Parameters: mapping : None or mapping, optional
mapping with keys corresponding to image file types (such as ‘image’, ‘header’ etc, depending on image class) and values that are filenames or file-like. Default is None
Returns: file_map : dict
dict with string keys given by first entry in tuples in sequence klass.files_types, and values of type FileHolder, where FileHolder objects have default values, other than those given by mapping
-
set_data_dtype
(dtype)¶
-
set_filename
(filename)¶ Sets the files in the object from a given filename
The different image formats may check whether the filename has an extension characteristic of the format, and raise an error if not.
Parameters: filename : str
If the image format only has one file associated with it, this will be the only filename set into the image
.file_map
attribute. Otherwise, the image instance will try and guess the other filenames from this given filename.
-
shape
¶
-
to_file_map
(file_map=None)¶
-
to_filename
(filename)¶ Write image to files implied by filename string
Parameters: filename : str
filename to which to save image. We will parse filename with
filespec_to_file_map
to work out names for image, header etc.Returns: None :
-
to_files
(file_map=None)¶
-
to_filespec
(filename)¶
-
uncache
()¶ Delete any cached read of data from proxied data
Remember there are two types of images:
- array images where the data
img.dataobj
is an array - proxy images where the data
img.dataobj
is a proxy object
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 toimg.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 ofimg.get_data()
returns to its original value.- array images where the data
-
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: obj : object
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 aSpatialImage
Returns: np_types : set
set of numpy types that obj supports