def __newFromFile(self, filename, loadmeta):
"""Open a NIfTI file.
:Parameters:
filename: str
Filename of the to be opened image file.
.. warning::
This is an internal method. Neither its availability nor its API is
guarenteed.
"""
# make sure filename is not unicode
try:
filename = str(filename)
except UnicodeEncodeError:
raise UnicodeError, \
"The filename must not contain unicode characters, since " \
"the NIfTI library cannot handle them."
# do not load image data!
self.__nimg = ncl.nifti_image_read(filename, 0)
if not self.__nimg:
raise RuntimeError, "Error while opening NIfTI file '%s'." % \
filename
# simply create extension interface since nifticlib took care of
# loading all extensions already
self.extensions = NiftiExtensions(self.raw_nimg)
# unpickle meta data if present
if loadmeta and 'pypickle' in self.extensions:
if self.extensions.count('pypickle') > 1:
warn("Handling more than one 'pypickle' extension is not "
"supported. Will continue using the first detected "
"extension.")
# unpickle meta data
self.meta = cPickle.loads(self.extensions['pypickle'])
# and remove the pickle extension to not confuse data integrity when
# users would add something to it manually, i.e. via
# self.extensions['pypickle']
self._removePickleExtension()
class NiftiFormat(object):
"""NIfTI header representation.
NIfTI header can be created by loading information from an existing NIfTI
file or by creating a matching NIfTI header for a ndarray.
In addition, a number of methods to manipulate the header information are
provided. However, this class is not able to write a NIfTI header back to
disk. Please refer to the NIfTIImage class for this functionality.
.. note::
Handling of NIfTI header extensions is provided by the
:class:`~nifti.extensions.NiftiExtensions` class (see its documentation
for more information). Access to an instance of this class is available
through the `NiftiFormat.extensions` attribute.
"""
#
# object constructors, destructors and generic Python interface
#
def __init__(self, source, header=None, loadmeta=False):
"""
The constructor decides whether to load a nifti image header from file
or create one from ndarray data, depending on the datatype of `source`.
:Parameters:
source: str | ndarray
If source is a string, it is assumed to be a filename and an
attempt will be made to open the corresponding NIfTI file.
Filenames might be provided as unicode strings. However, as the
underlying library does not support unicode, they must be
ascii-encodable, i.e. must not contain pure unicode characters.
In case of an ndarray the array data will be used for the to be
created nifti image and a matching nifti header is generated.
If an object of a different type is supplied as 'source' a
ValueError exception will be thrown.
header: dict
Additional header data might be supplied if image data is not loaded
from a file. However, dimensionality and datatype are determined
from the ndarray and not taken from a header dictionary.
"""
self.__nimg = None
# prepare empty meta dict
self.meta = {}
# placeholder for extensions interface
self.extensions = None
if type(source) == N.ndarray:
self.__newFromArray(source, header)
elif type(source) in (str, unicode):
self.__newFromFile(source, loadmeta)
else:
raise ValueError, \
"Unsupported source type. Only NumPy arrays and filename " \
+ "string are supported."
def __newFromArray(self, data, hdr=None):
"""Create a `nifti_image` struct from a ndarray.
:Parameters:
data: ndarray
Source ndarray.
hdr: dict
Optional dictionary with NIfTI header data.
.. warning::
This is an internal method. Neither its availability nor its API is
guarenteed.
"""
if hdr == None:
hdr = {}
# check array
if len(data.shape) > 7:
raise ValueError, \
"NIfTI does not support data with more than 7 dimensions."
# create template nifti header struct
niptr = ncl.nifti_simple_init_nim()
nhdr = ncl.nifti_convert_nim2nhdr(niptr)
# intermediate cleanup
ncl.nifti_image_free(niptr)
# convert virgin nifti header to dict to merge properties
# with supplied information and array properties
hdic = nhdr2dict(nhdr)
# copy data from supplied header dict
for k, v in hdr.iteritems():
hdic[k] = v
# finally set header data that is determined by the data array
# convert NumPy to nifti datatype
hdic['datatype'] = Ndtype2niftidtype(data)
# make sure there are no zeros in the dim vector
# especially not in #4 as FSLView doesn't like that
hdic['dim'] = [ 1 for i in hdic['dim'] ]
# set number of dims
hdic['dim'][0] = len(data.shape)
# set size of each dim (and reverse the order to match nifti format
# requirements)
for i, s in enumerate(data.shape):
hdic['dim'][len(data.shape)-i] = s
# set magic field to mark as nifti file
hdic['magic'] = 'n+1'
self._rebuildNimgFromHdrAndDict(nhdr, hdic)
def __newFromFile(self, filename, loadmeta):
"""Open a NIfTI file.
:Parameters:
filename: str
Filename of the to be opened image file.
.. warning::
This is an internal method. Neither its availability nor its API is
guarenteed.
"""
# make sure filename is not unicode
try:
filename = str(filename)
except UnicodeEncodeError:
raise UnicodeError, \
"The filename must not contain unicode characters, since " \
"the NIfTI library cannot handle them."
# do not load image data!
self.__nimg = ncl.nifti_image_read(filename, 0)
if not self.__nimg:
raise RuntimeError, "Error while opening NIfTI file '%s'." % \
filename
# simply create extension interface since nifticlib took care of
# loading all extensions already
self.extensions = NiftiExtensions(self.raw_nimg)
# unpickle meta data if present
if loadmeta and 'pypickle' in self.extensions:
if self.extensions.count('pypickle') > 1:
warn("Handling more than one 'pypickle' extension is not "
"supported. Will continue using the first detected "
"extension.")
# unpickle meta data
self.meta = cPickle.loads(self.extensions['pypickle'])
# and remove the pickle extension to not confuse data integrity when
# users would add something to it manually, i.e. via
# self.extensions['pypickle']
self._removePickleExtension()
def __del__(self):
# enforce del on extensions wrapper so Python GC doesn't try
# to free it up later on causing writes to freed memory.
del self.extensions
if self.__nimg:
ncl.nifti_image_free(self.__nimg)
def __str__(self):
lines = []
lines.append('extent' + str(self.extent))
lines.append('dtype(' \
+ nifti2numpy_dtype_map[self.raw_nimg.datatype] \
+ ')')
s = 'voxels('
s += 'x'.join(["%f" % d for d in self.voxdim])
if self.xyz_unit:
s += ' ' + self.getXYZUnit(as_string=True)
lines.append(s + ')')
if self.timepoints > 1:
s = "timepoints(%i, dt=%f" % (self.timepoints, self.rtime)
if self.time_unit:
s += ' ' + self.getTimeUnit(as_string=True)
s += ')'
lines.append(s)
if self.slope:
lines.append("scaling(slope=%f, intercept=%f)" \
% (self.slope, self.intercept))
if self.qform_code:
lines.append("qform(%s)" % self.getQFormCode(as_string=True))
lines.append("qform_orientation(%s)" \
% ', '.join(self.getQOrientation(as_string=True)))
if self.sform_code:
lines.append("sform(%s)" % self.getSFormCode(as_string=True))
lines.append("sform_orientation(%s)" \
% ', '.join(self.getSOrientation(as_string=True)))
if self.description:
lines.append("descr('%s')" % self.description)
if len(self.meta.keys()):
lines.append("meta(%s)" % str(self.meta.keys()))
return '<NIfTI:\n ' + ';\n '.join(lines) + ';\n>'
#
# converters
#
def asDict(self):
"""Returns the header data of the `NiftiImage` in a dictionary.
:Returns:
dict
The dictionary contains all NIfTI header information. Additionally,
it might also contain a special 'meta' item that contains the
meta data currently assigned to this instance.
.. note::
Modifications done to the returned dictionary do not cause any
modifications in the NIfTI image itself. Please use
:meth:`~nifti.format.NiftiFormat.updateFromDict` to apply
changes to the image.
.. seealso::
:meth:`~nifti.format.NiftiFormat.updateFromDict`,
:attr:`~nifti.format.NiftiFormat.header`
"""
# Convert nifti_image struct into nifti1 header struct.
# This get us all data that will actually make it into a
# NIfTI file.
nhdr = ncl.nifti_convert_nim2nhdr(self.raw_nimg)
# pass extensions as well
ret = nhdr2dict(nhdr, extensions=self.extensions)
if len(self.meta.keys()):
ret['meta'] = self.meta
return ret
def updateFromDict(self, hdrdict):
"""Update NIfTI header information.
Updated header data is read from the supplied dictionary. One cannot
modify dimensionality and datatype of the image data. If such
information is present in the header dictionary it is removed before
the update. If resizing or datatype casting are required one has to
convert the image data into a separate array and perform resize and
data manipulations on this array. When finished, the array can be
converted into a nifti file by calling the NiftiImage constructor with
the modified array as 'source' and the nifti header of the original
NiftiImage object as 'header'.
.. note::
If the provided dictionary contains a 'meta' item its content is
used to overwrite any potentially existing meta data.
dictionary.
The same behavior will be used for 'extensions'. If extensions
are defined in the provided dictionary all currently existing
extensions will be overwritten.
.. seealso::
:meth:`~nifti.format.NiftiFormat.asDict`,
:attr:`~nifti.format.NiftiFormat.header`
"""
# rebuild nifti header from current image struct
nhdr = ncl.nifti_convert_nim2nhdr(self.__nimg)
# remove settings from the hdrdict that are determined by
# the data set and must not be modified to preserve data integrity
if hdrdict.has_key('datatype'):
del hdrdict['datatype']
if hdrdict.has_key('dim'):
del hdrdict['dim']
self._rebuildNimgFromHdrAndDict(nhdr, hdrdict)
def vx2q(self, coord):
"""Transform a voxel's index into coordinates (qform-defined).
:Parameter:
coord: 3-tuple
A voxel's index in the volume fiven as three positive integers
(i, j, k).
:Returns:
vector
.. seealso::
:meth:`~nifti.format.NiftiFormat.setQForm`,
:meth:`~nifti.format.NiftiFormat.getQForm`
:attr:`~nifti.format.NiftiFormat.qform`
"""
# add dummy one to row vector
coord_ = N.r_[coord, [1.0]]
# apply affine transformation
result = N.dot(self.qform, coord_)
# return 3D coordinates
return result[0:-1]
def vx2s(self, coord):
"""Transform a voxel's index into coordinates (sform-defined).
:Parameter:
coord: 3-tuple
A voxel's index in the volume fiven as three positive integers
(i, j, k).
:Returns:
vector
.. seealso::
:meth:`~nifti.format.NiftiFormat.setSForm`,
:meth:`~nifti.format.NiftiFormat.getSForm`
:attr:`~nifti.format.NiftiFormat.sform`
"""
# add dummy one to row vector
coord_ = N.r_[coord, [1.0]]
# apply affine transformation
result = N.dot(self.qform, coord_)
# return 3D coordinates
return result[0:-1]
#
# private helpers
#
def _updateNimgFromArray(self, val):
"""Update all relevant items in the nimg struct to match a given
array's properties.
We can only savely modify the respective nimg items since the data
array is disconnected from the struct all the time.
.. warning::
This is an internal method. Neither its availability nor its API is
guarenteed.
"""
# convert dtype and store in struct
self.raw_nimg.datatype = Ndtype2niftidtype(val)
# wrap dims
dim = ncl.intArray_frompointer(self.raw_nimg.dim)
# make sure there are no zeros in the dim vector
# especially not in #4 as FSLView doesn't like that
target_dim = N.ones(7, dtype='int')
# reverse the array shape
target_dim[:len(val.shape)] = val.shape[::-1]
# set number of dims
dim[0] = len(val.shape)
# assign remaining dim vector
for i in range(7):
dim[i+1] = target_dim[i]
# expand dim vector
self.raw_nimg.ndim = dim[0]
self.raw_nimg.nx = dim[1]
self.raw_nimg.ny = dim[2]
self.raw_nimg.nz = dim[3]
self.raw_nimg.nt = dim[4]
self.raw_nimg.nu = dim[5]
self.raw_nimg.nv = dim[6]
self.raw_nimg.nw = dim[7]
def _rebuildNimgFromHdrAndDict(self, nhdr, hdic):
"""
.. warning::
This is an internal method. Neither its availability nor its API is
guarenteed.
"""
# first updated the header struct from the provided dictionary
# data
updateNiftiHeaderFromDict(nhdr, hdic)
# if no filename was set already (e.g. image from array) set a temp
# name now, as otherwise nifti_convert_nhdr2nim will fail
have_temp_filename = False
if not self.__nimg:
# we are creating from scratch
new_nimg = ncl.nifti_convert_nhdr2nim(nhdr, 'pynifti_none')
have_temp_filename = True
elif not self.filename:
# rebuild but no filename yet
self.__nimg.fname = 'pynifti_updateheader_temp_name'
self.__nimg.iname = 'pynifti_updateheader_temp_name'
new_nimg = ncl.nifti_convert_nhdr2nim(nhdr, 'pynifti_none')
have_temp_filename = True
else:
# recreate nifti image struct using current filename
new_nimg = ncl.nifti_convert_nhdr2nim(nhdr, self.filename)
if not new_nimg:
raise RuntimeError, \
"Could not create NIfTI image struct from header."
# rescue all extensions
if self.extensions:
# need to create a new extensions wrapper around the new
# nifti image struct
new_ext = NiftiExtensions(
new_nimg,
[ext for ext in self.extensions.iteritems()])
else:
# just create an empty wrapper
new_ext = NiftiExtensions(new_nimg)
# replace old image struct by new one
# be careful with memory leak (still not checked whether successful)
# assign the new image struct
self.__nimg = new_nimg
# and the extensions
self.extensions = new_ext
# reset filename if temp name was set
if have_temp_filename:
self.__nimg.fname = ''
self.__nimg.iname = ''
#
# merge new extensions
#
if hdic.has_key('extensions'):
# wipe current set of extensions
self.extensions.clear()
for e in hdic['extensions']:
self.extensions.append(e)
#
# assign new meta data
if hdic.has_key('meta'):
self.meta = hdic['meta']
def _removePickleExtension(self):
"""Remove the 'pypickle' extension from the raw NIfTI image struct.
Its content is expanded into the `meta` attribute in a NiftiImage
instance.
.. warning::
This is an internal method. Neither its availability nor its API is
guarenteed.
"""
if 'pypickle' in self.extensions:
del self.extensions['pypickle']
def updateQFormFromQuaternion(self):
"""Only here for backward compatibility."""
from warnings import warn
warn("The method has been renamed to " \
"NiftiFormat.__updateQFormFromQuaternion and should not be used " \
"in user code. This redirect will be removed with PyNIfTI 1.0.", \
DeprecationWarning)
self.__updateQFormFromQuaternion()
def __updateQFormFromQuaternion(self):
"""Recalculates the qform matrix (and the inverse) from the quaternion
representation.
.. warning::
This is an internal method. Neither its availability nor its API is
guarenteed.
"""
# recalculate qform
self.__nimg.qto_xyz = ncl.nifti_quatern_to_mat44 (
self.__nimg.quatern_b, self.__nimg.quatern_c, self.__nimg.quatern_d,
self.__nimg.qoffset_x, self.__nimg.qoffset_y, self.__nimg.qoffset_z,
self.__nimg.dx, self.__nimg.dy, self.__nimg.dz,
self.__nimg.qfac )
# recalculate inverse
self.__nimg.qto_ijk = \
ncl.nifti_mat44_inverse( self.__nimg.qto_xyz )
#
# getters and setters
#
def getVoxDims(self):
"""Returns a 3-tuple a voxel dimensions/size in (x,y,z).
.. seealso::
:meth:`~nifti.format.NiftiFormat.setVoxDims`,
:attr:`~nifti.format.NiftiFormat.voxdim`
"""
return (self.__nimg.dx, self.__nimg.dy, self.__nimg.dz)
def setVoxDims(self, value):
"""Set voxel dimensions/size.
The qform matrix and its inverse will be recalculated automatically.
:Parameter:
value: 3-tuple of floats
Have to be given in (x,y,z) order.
.. seealso::
:meth:`~nifti.format.NiftiFormat.getVoxDims`,
:attr:`~nifti.format.NiftiFormat.voxdim`
"""
if len(value) != 3:
raise ValueError, 'Requires 3-tuple.'
self.__nimg.dx = float(value[0])
self.__nimg.dy = float(value[1])
self.__nimg.dz = float(value[2])
self.__updateQFormFromQuaternion()
def setPixDims(self, value):
"""Set the pixel dimensions.
:Parameter:
value: sequence
Up to 7 values (max. number of dimensions supported by the
NIfTI format) are allowed in the sequence.
The supplied sequence can be shorter than seven elements. In
this case only present values are assigned starting with the
first dimension (spatial: x).
.. note::
Calling `setPixDims()` with a length-3 sequence equals calling
`setVoxDims()`.
.. seealso::
:meth:`~nifti.format.NiftiFormat.setVoxDims`,
:meth:`~nifti.format.NiftiFormat.getPixDims`,
:attr:`~nifti.format.NiftiFormat.pixdim`
"""
if len(value) > 7:
raise ValueError, \
'The Nifti format does not support more than 7 dimensions.'
pixdim = ncl.floatArray_frompointer( self.__nimg.pixdim )
for i, val in enumerate(value):
pixdim[i+1] = float(val)
# The nifticlib uses dimension deltas (dx, dy, dz, dt...) to store
# the pixdim values (in addition to the pixdim array). When
# saving the image to a file, the deltas are used, not the pixdims.
# The nifti_update_dims_from_array sync's the deltas with the pixdims.
# (It also syncs the dim array with it's duplicate scalar variables.)
ncl.nifti_update_dims_from_array(self.__nimg)
def getPixDims(self):
"""Returns the pixel dimensions on all 7 dimensions.
The function is similar to `getVoxDims()`, but instead of the 3d
spatial dimensions of a voxel it returns the dimensions of an image
pixel on all 7 dimensions supported by the NIfTI dataformat.
.. seealso::
:meth:`~nifti.format.NiftiFormat.getVoxDims`,
:meth:`~nifti.format.NiftiFormat.setPixDims`,
:attr:`~nifti.format.NiftiFormat.pixdim`
"""
return \
tuple([ ncl.floatArray_frompointer(self.__nimg.pixdim)[i]
for i in range(1,8) ] )
def getExtent(self):
"""Returns the shape of the dataimage.
:Returns:
tuple: Tuple with the size in voxel/timepoints.
The order of dimensions is (x,y,z,t,u,v,w). If the image has less
dimensions than 7 the return tuple will be shortened accordingly.
Please note that the order of dimensions is different from the tuple
returned by calling `NiftiImage.data.shape`!
.. seealso::
:meth:`~nifti.format.NiftiFormat.getVolumeExtent`,
:meth:`~nifti.format.NiftiFormat.getTimepoints`,
:attr:`~nifti.format.NiftiFormat.extent`
"""
# wrap dim array in nifti image struct
dims_array = ncl.intArray_frompointer(self.__nimg.dim)
dims = [ dims_array[i] for i in range(8) ]
return tuple( dims[1:dims[0]+1] )
def getVolumeExtent(self):
"""Returns the size/shape of the volume(s) in the image as a tuple.
:Returns:
tuple:
Either a 3-tuple or 2-tuple or 1-tuple depending on the available
dimensions in the image.
The order of dimensions in the tuple is (x [, y [, z ] ] ).
.. seealso::
:meth:`~nifti.format.NiftiFormat.getExtent`,
:attr:`~nifti.format.NiftiFormat.volextent`
"""
# it is save to do this even if self.extent is shorter than 4 items
return self.extent[:3]
def getTimepoints(self):
"""Returns the number of timepoints in the image.
In case of a 3d (or less dimension) image this method returns 1.
.. seealso::
:attr:`~nifti.format.NiftiFormat.timepoints`
"""
if len(self.extent) < 4:
return 1
else:
return self.extent[3]
def getRepetitionTime(self):
"""Returns the temporal distance between the volumes in a timeseries.
.. seealso::
:meth:`~nifti.format.NiftiFormat.setRepetitionTime`,
:attr:`~nifti.format.NiftiFormat.rtime`
"""
return self.__nimg.dt
def setRepetitionTime(self, value):
"""Set the repetition time of a NIfTI image (dt).
.. seealso::
:meth:`~nifti.format.NiftiFormat.getRepetitionTime`,
:attr:`~nifti.format.NiftiFormat.rtime`
"""
self.__nimg.dt = float(value)
def setSlope(self, value):
"""Set the slope attribute in the NIfTI header.
Setting the slope to zero, will disable scaling.
.. seealso::
:attr:`~nifti.format.NiftiFormat.slope`,
:attr:`~nifti.format.NiftiFormat.intercept`
"""
self.__nimg.scl_slope = float(value)
def setIntercept(self, value):
"""Set the intercept attribute in the NIfTI header.
The intercept is only considered for scaling in case of a non-zero
slope value.
.. seealso::
:attr:`~nifti.format.NiftiFormat.slope`,
:attr:`~nifti.format.NiftiFormat.intercept`
"""
self.__nimg.scl_inter = float(value)
def setDescription(self, value):
"""Set the description element in the NIfTI header.
:Parameter:
value: str
Description -- must not be longer than 79 characters.
.. seealso::
:attr:`~nifti.format.NiftiFormat.description`
"""
if len(value) > 79:
raise ValueError, \
"The NIfTI format only supports descriptions shorter than " \
"80 chars. (got length %i)" % len(value)
self.__nimg.descrip = value
def setXFormCode(self, xform, code):
"""Set the type of space described by the NIfTI transformations.
The NIfTI format defines five coordinate system types which are used
to describe the target space of a transformation (qform or sform).
Please note, that the last four transformation types are only available
in the NIfTI format and not when saving into ANALYZE.
'unkown', `NIFTI_XFORM_UNKNOWN`, 0:
Transformation is arbitrary. This is the ANALYZE compatibility
mode. In this case no *sform* matrix will be written, even when
stored in NIfTI and not in ANALYZE format. Additionally, only the
pixdim parts of the *qform* matrix will be saved (upper-left 3x3).
'scanner', `NIFTI_XFORM_SCANNER_ANAT`, 1:
Scanner-based anatomical coordinates.
'aligned', `NIFTI_XFORM_ALIGNED_ANAT`, 2:
Coordinates are aligned to another file's coordinate system.
'talairach', `NIFTI_XFORM_TALAIRACH`, 3:
Coordinate system is shifted to have its origin (0,0,0) at the
anterior commissure, as in the Talairach-Tournoux Atlas.
'mni152', `NIFTI_XFORM_MNI_152`, 4:
Coordinates are in MNI152 space.
:Parameters:
xform: 'qform' | 'q' | 'sform' | 's'
Which of the two NIfTI transformations to set.
code: str | `NIFTI_XFORM_CODE` | int (0..4)
The Transformation code can be specified either by a string, the
`NIFTI_XFORM_CODE` defined in the nifti1.h header file (accessible
via the `nifti.clib` module, or the corresponding integer value.
.. seealso::
:meth:`~nifti.format.NiftiFormat.setQFormCode`,
:meth:`~nifti.format.NiftiFormat.getQFormCode`,
:meth:`~nifti.format.NiftiFormat.setSFormCode`,
:meth:`~nifti.format.NiftiFormat.getSFormCode`,
:attr:`~nifti.format.NiftiFormat.qform_code`,
:attr:`~nifti.format.NiftiFormat.sform_code`
"""
if isinstance(code, str):
if not code in nifti_xform_map.keys():
raise ValueError, \
"Unknown xform code '%s'. Must be one of '%s'" \
% (code, str(nifti_xform_map.keys()))
code = nifti_xform_map[code]
else:
if not code in nifti_xform_map.values():
raise ValueError, \
"Unknown xform code '%s'. Must be one of '%s'" \
% (str(code), str(nifti_xform_map.values()))
if xform == 'qform' or xform == 'q':
self.raw_nimg.qform_code = code
elif xform == 'sform' or xform == 's':
self.raw_nimg.sform_code = code
else:
raise ValueError, "Unkown transformation '%s'" % xform
def setQFormCode(self, code):
"""Set the qform code.
.. note::
This is a convenience frontend for
:meth:`~nifti.format.NiftiFormat.setXFormCode`. Please see its
documentation for more information.
"""
self.setXFormCode('qform', code)
def getQFormCode(self, as_string = False):
"""Return the qform code.
By default NIfTI xform codes are returned, but if `as_string` is set to
true a string representation ala 'talairach' is returned instead.
.. seealso::
:meth:`~nifti.format.NiftiFormat.getQFormCode`,
:attr:`~nifti.format.NiftiFormat.qform_code`
"""
code = self.raw_nimg.qform_code
if as_string:
code = nifti_xform_inv_map[code]
return code
def getSFormCode(self, as_string = False):
"""Return the sform code.
By default NIfTI xform codes are returned, but if `as_string` is set to
true a string representation ala 'talairach' is returned instead.
.. seealso::
:meth:`~nifti.format.NiftiFormat.getSFormCode`,
:attr:`~nifti.format.NiftiFormat.sform_code`
"""
code = self.raw_nimg.sform_code
if as_string:
code = nifti_xform_inv_map[code]
return code
def setSFormCode(self, code):
"""Set the sform code.
.. note::
This is a convenience frontend for
:meth:`~nifti.format.NiftiFormat.setXFormCode`. Please see its
documentation for more information.
"""
self.setXFormCode('sform', code)
def getSForm(self):
"""Returns the sform matrix.
.. note::
The returned sform matrix is not bound to the object. Therefore it
cannot be successfully modified in-place. Modifications to the sform
matrix can only be done by setting a new sform matrix
.. seealso::
:meth:`~nifti.format.NiftiFormat.setSForm`,
:meth:`~nifti.format.NiftiFormat.setSFormCode`,
:meth:`~nifti.format.NiftiFormat.getSFormCode`,
:attr:`~nifti.format.NiftiFormat.sform`,
:attr:`~nifti.format.NiftiFormat.sform_inv`,
:attr:`~nifti.format.NiftiFormat.sform_code`
"""
return ncl.mat442array(self.__nimg.sto_xyz)
def setSForm(self, m, code='mni152'):
"""Sets the sform matrix.
The supplied value has to be a 4x4 matrix. The matrix elements will be
converted to floats. By definition the last row of the sform matrix has
to be (0,0,0,1). However, different values can be assigned, but will
not be stored when the NIfTI image is saved to a file.
The inverse sform matrix will be automatically recalculated.
:Parameters:
m: 4x4 ndarray
The sform matrix.
code: str | `NIFTI_XFORM_CODE` | int (0..4)
The type of the coordinate system the sform matrix is describing.
By default this coordinate system is assumed to be the MNI152
space. Please refer to the
:meth:`~nifti.format.NiftiFormat.setXFormCode` method for a
full list of possible codes and their meaning.
.. seealso::
:meth:`~nifti.format.NiftiFormat.getSForm`,
:meth:`~nifti.format.NiftiFormat.setSFormCode`,
:meth:`~nifti.format.NiftiFormat.getSFormCode`,
:attr:`~nifti.format.NiftiFormat.sform`,
:attr:`~nifti.format.NiftiFormat.sform_code`
"""
if m.shape != (4, 4):
raise ValueError, "SForm matrix has to be of size 4x4."
# make sure it is float
m = m.astype('float')
ncl.set_mat44( self.__nimg.sto_xyz,
m[0,0], m[0,1], m[0,2], m[0,3],
m[1,0], m[1,1], m[1,2], m[1,3],
m[2,0], m[2,1], m[2,2], m[2,3],
m[3,0], m[3,1], m[3,2], m[3,3] )
# recalculate inverse
self.__nimg.sto_ijk = \
ncl.nifti_mat44_inverse( self.__nimg.sto_xyz )
# set sform code, which decides how the sform matrix is interpreted
self.setXFormCode('sform', code)
def getInverseSForm(self):
"""Returns the inverse sform matrix.
.. note::
The inverse sform matrix cannot be modified in-place. One needs to
set a new sform matrix instead. The corresponding inverse matrix is
then re-calculated automatically.
.. seealso::
:meth:`~nifti.format.NiftiFormat.getSForm`,
:attr:`~nifti.format.NiftiFormat.sform`,
:attr:`~nifti.format.NiftiFormat.sform_inv`,
"""
return ncl.mat442array(self.__nimg.sto_ijk)
def getQForm(self):
"""Returns the qform matrix.
.. note::
The returned qform matrix is not bound to the object. Therefore it
cannot be successfully modified in-place. Modifications to the qform
matrix can only be done by setting a new qform matrix
.. seealso::
:meth:`~nifti.format.NiftiFormat.setQForm`,
:meth:`~nifti.format.NiftiFormat.setQFormCode`,
:meth:`~nifti.format.NiftiFormat.getQFormCode`,
:meth:`~nifti.format.NiftiFormat.getQuaternion`,
:meth:`~nifti.format.NiftiFormat.getQOffset`,
:meth:`~nifti.format.NiftiFormat.setQuaternion`,
:meth:`~nifti.format.NiftiFormat.setQOffset`,
:meth:`~nifti.format.NiftiFormat.setQFac`,
:attr:`~nifti.format.NiftiFormat.qform`,
:attr:`~nifti.format.NiftiFormat.qform_inv`,
:attr:`~nifti.format.NiftiFormat.qform_code`,
:attr:`~nifti.format.NiftiFormat.quatern`,
:attr:`~nifti.format.NiftiFormat.qoffset`,
:attr:`~nifti.format.NiftiFormat.qfac`
"""
return ncl.mat442array(self.__nimg.qto_xyz)
def getInverseQForm(self):
"""Returns the inverse qform matrix.
.. note::
The inverse qform matrix cannot be modified in-place. One needs to
set a new qform matrix instead. The corresponding inverse matrix is
then re-calculated automatically.
.. seealso::
:meth:`~nifti.format.NiftiFormat.getQForm`,
:attr:`~nifti.format.NiftiFormat.qform`,
:attr:`~nifti.format.NiftiFormat.qform_inv`,
"""
return ncl.mat442array(self.__nimg.qto_ijk)
def setQForm(self, m, code='scanner'):
"""Sets the qform matrix.
The supplied value has to be a 4x4 matrix. The matrix will be converted
to float.
The inverse qform matrix and the quaternion representation will be
automatically recalculated.
:Parameters:
m: 4x4 ndarray
The qform matrix.
code: str | `NIFTI_XFORM_CODE` | int (0..4)
The type of the coordinate system the qform matrix is describing.
By default this coordinate system is assumed to be the scanner
space. Please refer to the
:meth:`~nifti.format.NiftiFormat.setXFormCode` method for a
full list of possible codes and their meaning.
.. seealso::
:meth:`~nifti.format.NiftiFormat.getQForm`,
:meth:`~nifti.format.NiftiFormat.setQFormCode`,
:meth:`~nifti.format.NiftiFormat.getQFormCode`,
:meth:`~nifti.format.NiftiFormat.getQuaternion`,
:meth:`~nifti.format.NiftiFormat.getQOffset`,
:meth:`~nifti.format.NiftiFormat.setQuaternion`,
:meth:`~nifti.format.NiftiFormat.setQOffset`,
:meth:`~nifti.format.NiftiFormat.setQFac`,
:attr:`~nifti.format.NiftiFormat.qform`,
:attr:`~nifti.format.NiftiFormat.qform_inv`,
:attr:`~nifti.format.NiftiFormat.qform_code`,
:attr:`~nifti.format.NiftiFormat.quatern`,
:attr:`~nifti.format.NiftiFormat.qoffset`,
:attr:`~nifti.format.NiftiFormat.qfac`
"""
if m.shape != (4, 4):
raise ValueError, "QForm matrix has to be of size 4x4."
# make sure it is float
m = m.astype('float')
ncl.set_mat44( self.__nimg.qto_xyz,
m[0,0], m[0,1], m[0,2], m[0,3],
m[1,0], m[1,1], m[1,2], m[1,3],
m[2,0], m[2,1], m[2,2], m[2,3],
m[3,0], m[3,1], m[3,2], m[3,3] )
# recalculate inverse
self.__nimg.qto_ijk = \
ncl.nifti_mat44_inverse( self.__nimg.qto_xyz )
# update quaternions
( self.__nimg.quatern_b, self.__nimg.quatern_c, self.__nimg.quatern_d,
self.__nimg.qoffset_x, self.__nimg.qoffset_y, self.__nimg.qoffset_z,
self.__nimg.dx, self.__nimg.dy, self.__nimg.dz,
self.__nimg.qfac ) = \
ncl.nifti_mat44_to_quatern( self.__nimg.qto_xyz )
# set qform code, which decides how the qform matrix is interpreted
self.setXFormCode('qform', code)
def setQuaternion(self, value, code='scanner'):
"""Set Quaternion from 3-tuple (qb, qc, qd).
The qform matrix and it's inverse are re-computed automatically.
:Parameters:
value: length-3 sequence
qb, qc and qd quaternions.
code: str | `NIFTI_XFORM_CODE` | int (0..4)
The type of the coordinate system the corresponding qform matrix is
describing. By default this coordinate system is assumed to be the
scanner space. Please refer to the
:meth:`~nifti.format.NiftiFormat.setXFormCode` method for a
full list of possible codes and their meaning.
.. seealso::
:meth:`~nifti.format.NiftiFormat.getQForm`,
:meth:`~nifti.format.NiftiFormat.setQForm`,
:meth:`~nifti.format.NiftiFormat.setQFormCode`,
:meth:`~nifti.format.NiftiFormat.getQFormCode`,
:meth:`~nifti.format.NiftiFormat.getQuaternion`,
:meth:`~nifti.format.NiftiFormat.getQOffset`,
:meth:`~nifti.format.NiftiFormat.setQOffset`,
:meth:`~nifti.format.NiftiFormat.setQFac`,
:attr:`~nifti.format.NiftiFormat.qform`,
:attr:`~nifti.format.NiftiFormat.qform_inv`,
:attr:`~nifti.format.NiftiFormat.qform_code`,
:attr:`~nifti.format.NiftiFormat.quatern`,
:attr:`~nifti.format.NiftiFormat.qoffset`,
:attr:`~nifti.format.NiftiFormat.qfac`
"""
if len(value) != 3:
raise ValueError, 'Requires 3-tuple.'
self.__nimg.quatern_b = float(value[0])
self.__nimg.quatern_c = float(value[1])
self.__nimg.quatern_d = float(value[2])
self.__updateQFormFromQuaternion()
self.setXFormCode('qform', code)
def getQuaternion(self):
"""Returns a 3-tuple containing (qb, qc, qd).
.. seealso::
:meth:`~nifti.format.NiftiFormat.setQuaternion`,
:attr:`~nifti.format.NiftiFormat.qform`,
:attr:`~nifti.format.NiftiFormat.quatern`
"""
return( ( self.__nimg.quatern_b,
self.__nimg.quatern_c,
self.__nimg.quatern_d ) )
def setQOffset(self, value, code='scanner'):
"""Set QOffset from 3-tuple (qx, qy, qz).
The qform matrix and its inverse are re-computed automatically.
Besides reading it is also possible to set the qoffset by assigning
to the `qoffset` property.
:Parameters:
value: length-3 sequence
qx, qy and qz offsets.
code: str | `NIFTI_XFORM_CODE` | int (0..4)
The type of the coordinate system the corresponding qform matrix is
describing. By default this coordinate system is assumed to be the
scanner space. Please refer to the
:meth:`~nifti.format.NiftiFormat.setXFormCode` method for a
full list of possible codes and their meaning.
.. seealso::
:meth:`~nifti.format.NiftiFormat.getQOffset`,
:attr:`~nifti.format.NiftiFormat.qform`,
:attr:`~nifti.format.NiftiFormat.qoffset`
"""
if len(value) != 3:
raise ValueError, 'Requires 3-tuple.'
self.__nimg.qoffset_x = float(value[0])
self.__nimg.qoffset_y = float(value[1])
self.__nimg.qoffset_z = float(value[2])
self.__updateQFormFromQuaternion()
self.setXFormCode('qform', code)
def getQOffset(self):
"""Returns a 3-tuple containing (qx, qy, qz).
.. seealso::
:meth:`~nifti.format.NiftiFormat.setQOffset`,
:attr:`~nifti.format.NiftiFormat.qform`,
:attr:`~nifti.format.NiftiFormat.qoffset`
"""
return( ( self.__nimg.qoffset_x,
self.__nimg.qoffset_y,
self.__nimg.qoffset_z ) )
def setQFac(self, value, code='scanner'):
"""Set qfac (scaling factor of qform matrix).
The qform matrix and its inverse are re-computed automatically.
Besides reading it is also possible to set the qfac by assigning
to the `qfac` property.
:Parameters:
value: float
Scaling factor.
code: str | `NIFTI_XFORM_CODE` | int (0..4)
The type of the coordinate system the corresponding qform matrix is
describing. By default this coordinate system is assumed to be the
scanner space. Please refer to the
:meth:`~nifti.format.NiftiFormat.setXFormCode` method for a
full list of possible codes and their meaning.
.. seealso::
:attr:`~nifti.format.NiftiFormat.qform`,
:attr:`~nifti.format.NiftiFormat.qfac`
"""
self.__nimg.qfac = float(value)
self.__updateQFormFromQuaternion()
self.setXFormCode('qform', code)
def getQOrientation(self, as_string = False):
"""Returns to orientation of the i, j and k axis as stored in the
qform matrix.
By default NIfTI orientation codes are returned, but if `as_string` is
set to true a string representation ala 'Left-to-right' is returned
instead.
:Returns:
list
orientations fo the x, y and z axis respectively.
.. seealso::
:attr:`~nifti.format.NiftiFormat.qform`
"""
codes = ncl.nifti_mat44_to_orientation(self.__nimg.qto_xyz)
if as_string:
return [ ncl.nifti_orientation_string(i) for i in codes ]
else:
return codes
def getSOrientation(self, as_string = False):
"""Returns to orientation of the i, j and k axis as stored in the
sform matrix.
By default NIfTI orientation codes are returned, but if `as_string` is
set to true a string representation ala 'Left-to-right' is returned
instead.
:Returns:
list
orientations fo the x, y and z axis respectively.
.. seealso::
:attr:`~nifti.format.NiftiFormat.sform`
"""
codes = ncl.nifti_mat44_to_orientation(self.__nimg.sto_xyz)
if as_string:
return [ ncl.nifti_orientation_string(i) for i in codes ]
else:
return codes
def getXYZUnit(self, as_string = False):
"""Return 3D-space unit.
By default NIfTI unit codes are returned, but if `as_string` is set to
true a string representation ala 'mm' is returned instead.
.. seealso::
:meth:`~nifti.format.NiftiFormat.setXYZUnit`,
:attr:`~nifti.format.NiftiFormat.xyz_unit`
"""
code = self.__nimg.xyz_units
if as_string:
code = ncl.nifti_units_string(code)
return code
def setXYZUnit(self, value):
"""Set the unit of the spatial axes.
:Parameter:
value: int | str
The unit can either be given as a NIfTI unit code or as any of the
plain text abbrevations returned by
:meth:'~nifti.format.NiftiFormat.getXYZUnit`
.. seealso::
:meth:`~nifti.format.NiftiFormat.getXYZUnit`,
:attr:`~nifti.format.NiftiFormat.xyz_unit`
"""
# check for valid codes according to NIfTI1 standard
code = _checkUnit(value, valid_xyz_unit_codes)
self.raw_nimg.xyz_units = code
def getTimeUnit(self, as_string = False):
"""Return unit of temporal (4th) axis.
By default NIfTI unit codes are returned, but if `as_string` is set to
true a string representation ala 's' is returned instead.
.. seealso::
:meth:`~nifti.format.NiftiFormat.setTimeUnit`,
:attr:`~nifti.format.NiftiFormat.time_unit`
"""
code = self.__nimg.time_units
if as_string:
code = ncl.nifti_units_string(code)
return code
def setTimeUnit(self, value):
"""Set the unit of the temporal axis (4th).
:Parameter:
value: int | str
The unit can either be given as a NIfTI unit code or as any of the
plain text abbrevations returned by
:meth:'~nifti.format.NiftiFormat.getTimeUnit`
.. seealso::
:meth:`~nifti.format.NiftiFormat.getTimeUnit`,
:attr:`~nifti.format.NiftiFormat.time_unit`
"""
# check for valid codes according to NIfTI1 standard
code = _checkUnit(value, valid_time_unit_codes)
self.raw_nimg.time_units = code
def getFilename(self):
"""Returns the filename.
To distinguish ANALYZE from 2-file NIfTI images the image filename is
returned for ANALYZE images while the header filename is returned for
NIfTI files.
.. seealso::
:attr:`~nifti.format.NiftiFormat.filename`
"""
if self.__nimg.nifti_type == ncl.NIFTI_FTYPE_ANALYZE:
return self.__nimg.iname
else:
return self.__nimg.fname
#
# class properties
#
# read only
nvox = property(fget=lambda self: self.__nimg.nvox)
max = property(fget=lambda self: self.__nimg.cal_max)
min = property(fget=lambda self: self.__nimg.cal_min)
sform_inv = property(fget=getInverseSForm)
qform_inv = property(fget=getInverseQForm)
extent = property(fget=getExtent)
volextent = property(fget=getVolumeExtent)
timepoints = property(fget=getTimepoints)
raw_nimg = property(fget=lambda self: self.__nimg)
filename = property(fget=getFilename)
# read and write
slope = property(fget=lambda self: self.__nimg.scl_slope,
fset=setSlope)
intercept = property(fget=lambda self: self.__nimg.scl_inter,
fset=setIntercept)
voxdim = property(fget=getVoxDims, fset=setVoxDims)
pixdim = property(fget=getPixDims, fset=setPixDims)
description = property(fget=lambda self: self.__nimg.descrip,
fset=setDescription)
header = property(
fget=asDict, fset=updateFromDict,
doc="""Access to a dictionary version of the NIfTI header data.
.. note::
This property cannot be used like this::
nimg.header['something'] = 'new value'
Instead one has to get the header dictionary, modify
and later reassign it::
h = nimg.header
h['something'] = 'new value'
nimg.header = h
.. seealso::
:meth:`~nifti.format.NiftiFormat.asDict`,
:meth:`~nifti.format.NiftiFormat.updateFromDict`
""")
sform = property(fget=getSForm, fset=setSForm)
sform_code = property(fget=getSFormCode, fset=setSFormCode)
qform = property(fget=getQForm, fset=setQForm)
qform_code = property(fget=getQFormCode, fset=setQFormCode)
quatern = property(fget=getQuaternion, fset=setQuaternion)
qoffset = property(fget=getQOffset, fset=setQOffset)
qfac = property(fget=lambda self: self.__nimg.qfac, fset=setQFac)
rtime = property(fget=getRepetitionTime, fset=setRepetitionTime)
xyz_unit = property(fget=getXYZUnit, fset=setXYZUnit)
time_unit = property(fget=getTimeUnit, fset=setTimeUnit)
