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__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

copy()

Copy object to independent representation

The copy should not be affected by any changes to the original object.

classmethod from_fileobj(fileobj)
classmethod from_header(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 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
headerNone or mapping or header instance, optional

metadata for this image format

extraNone or mapping, optional

metadata to associate with image that cannot be stored in the metadata of this image type

file_mapmapping, 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
headerNone or mapping or header instance, optional

metadata for this image format

extraNone or mapping, optional

metadata to associate with image that cannot be stored in the metadata of this image type

file_mapmapping, optional

mapping giving file information for this image format

files_types = (('image', None),)
classmethod filespec_to_file_map(filespec)

Make file_map for this class from filename filespec

Class method

Parameters
filespecstr

Filename that might be for this image file type.

Returns
file_mapdict

file_map dict with (key, value) pairs of (file_type, FileHolder instance), where file_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(filespec)

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(file_map)
classmethod from_filename(filename)
classmethod from_files(file_map)

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(img)

Class method to create new instance of own class from img

Parameters
imgspatialimage instance

In fact, an object with the API of FileBasedImage.

Returns
cimgspatialimage instance

Image, of our own class

get_filename()

Fetch the image filename

Parameters
None
Returns
fnameNone 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()

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(img, filename)

Save img in our own format, to name implied by filename

This is a class method

Parameters
imgany FileBasedImage instance
filenamestr

Filename, implying name to which to save image.

classmethod load(filename)
classmethod make_file_map(mapping=None)

Class method to make files holder for this image type

Parameters
mappingNone 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_mapdict

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(filename, sniff=None, sniff_max=1024)

Return True if filename may be image matching this class

Parameters
filenamestr

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.

sniffNone 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_maxint, 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_imagebool

True if filename may be valid for an image of this class.

sniffNone 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
filenamestr

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
filenamestr

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_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(filename)

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 = ()

ImageFileError

class nibabel.filebasedimages.ImageFileError

Bases: Exception

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.