Common interface for any image format–volume or surface, binary or xml.
FileBasedHeader | Template class to implement header protocol |
FileBasedImage([header, extra, file_map]) | Abstract image class with interface for loading/saving images from disk. |
ImageFileError |
Bases: object
Template class to implement header protocol
x.__init__(...) initializes x; see help(type(x)) for signature
Copy object to independent representation
The copy should not be affected by any changes to the original object.
Bases: object
Abstract image class with interface for loading/saving images from disk.
The class doesn’t define any image properties.
It has:
attributes:
- extra
properties:
- shape
- header
methods:
- .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.
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.
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.
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 numpy as np
>>> 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:
Initialize image
The image is a combination of (header), with optional metadata in extra, and filename / file-like objects contained in the file_map mapping.
Parameters: | 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 (header), with optional metadata in extra, and filename / file-like objects contained in the file_map mapping.
Parameters: | header : None or mapping or header instance, optional
extra : None or mapping, optional
file_map : mapping, optional
|
---|
Make file_map for this class from filename filespec
Class method
Parameters: | filespec : str
|
---|---|
Returns: | file_map : dict
|
Raises: | ImageFileError :
|
filespec_to_files class method is deprecated. Please use the “filespec_to_file_map” class method instead.
from_files class method is deprecated. Please use the from_file_map class method instead.
Class method to create new instance of own class from img
Parameters: | img : spatialimage instance
|
---|---|
Returns: | cimg : spatialimage instance
|
Fetch the image filename
Parameters: | None : |
---|---|
Returns: | fname : None or str
|
Get header from image
get_header method is deprecated. Please use the img.header property instead.
alias of FileBasedHeader
Save img in our own format, to name implied by filename
This is a class method
Parameters: | img : any FileBasedImage instance filename : str
|
---|
Class method to make files holder for this image type
Parameters: | mapping : None or mapping, optional
|
---|---|
Returns: | file_map : dict
|
Return True if filename may be image matching this class
Parameters: | filename : str
sniff : None or (bytes, filename), optional
sniff_max : int, optional
|
---|---|
Returns: | maybe_image : bool
sniff : None or (bytes, 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
|
---|
Write image to files implied by filename string
Parameters: | filename : str
|
---|---|
Returns: | None : |
to_files method is deprecated. Please use the “to_file_map” method instead.
to_filespec method is deprecated. Please use the “to_filename” method instead.