filebasedimages
¶
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 |
FileBasedHeader
¶
-
class
nibabel.filebasedimages.
FileBasedHeader
¶ Bases:
object
Template class to implement header protocol
-
__init__
()¶ x.__init__(...) initializes x; see help(type(x)) for signature
-
copy
()¶ Copy object to independent representation
The copy should not be affected by any changes to the original object.
-
classmethod
from_fileobj
(klass, fileobj)¶
-
classmethod
from_header
(klass, header=None)¶
-
write_to
(fileobj)¶
-
FileBasedImage
¶
-
class
nibabel.filebasedimages.
FileBasedImage
(header=None, extra=None, file_map=None)¶ 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 filenamefname
.
It also has a
header
- some standard set of meta-data that is specific to the image format, andextra
- 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 animage
and aheader
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 attributesfilename
,fileobj
andpos
.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 (withto_files
) should place the data. Thefile_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
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__
(header=None, extra=None, file_map=None)¶ 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
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
-
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
(*args, **kwargs)¶ filespec_to_files class method is deprecated. Please use the “filespec_to_file_map” class method instead.
- deprecated from version: 1.0
- Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 3.0
-
classmethod
from_file_map
(klass, file_map)¶
-
classmethod
from_filename
(klass, filename)¶
-
classmethod
from_files
(*args, **kwargs)¶ from_files class method is deprecated. Please use the
from_file_map
class method instead.- deprecated from version: 1.0
- Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 3.0
-
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
FileBasedImage
.Returns: cimg :
spatialimage
instanceImage, of our own class
-
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 associated 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
(*args, **kwargs)¶ Get header from image
get_header method is deprecated. Please use the
img.header
property instead.- deprecated from version: 2.1
- Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 4.0
-
header
¶
-
header_class
¶ alias of
FileBasedHeader
-
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 :
any FileBasedImage
instancefilename : 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
-
makeable
= True¶
-
classmethod
path_maybe_image
(klass, filename, sniff=None, sniff_max=1024)¶ Return True if filename may be image matching this class
Parameters: filename : str
Filename for an image, or an image header (metadata) file. If filename points to an image data file, and the image type has a separate “header” file, we work out the name of the header file, and read from that instead of filename.
sniff : None or (bytes, filename), optional
Bytes content read from a previous call to this method, on another class, with metadata filename. This allows us to read metadata bytes once from the image or header, and pass this read set of bytes to other image classes, therefore saving a repeat read of the metadata. filename is used to validate that metadata would be read from the same file, re-reading if not. None forces this method to read the metadata.
sniff_max : int, optional
The maximum number of bytes to read from the metadata. If the metadata file is long enough, we read this many bytes from the file, otherwise we read to the end of the file. Longer values sniff more of the metadata / image file, making it more likely that the returned sniff will be useful for later calls to
path_maybe_image
for other image classes.Returns: maybe_image : bool
True if filename may be valid for an image of this class.
sniff : None or (bytes, filename)
Read bytes content from found metadata. May be None if the file does not appear to have useful metadata.
-
rw
= True¶
-
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.
-
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
(*args, **kwargs)¶ to_files method is deprecated. Please use the “to_file_map” method instead.
- deprecated from version: 1.0
- Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 3.0
-
to_filespec
(*args, **kwargs)¶ to_filespec method is deprecated. Please use the “to_filename” method instead.
- deprecated from version: 1.0
- Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 3.0
-
valid_exts
= ()¶