NIPY logo

Site Navigation

NIPY Community

Table Of Contents

Previous topic

io.files

Next topic

labs.datasets.converters

This Page

io.nifti_ref

Module: io.nifti_ref

An implementation of the dimension info as desribed in

http://nifti.nimh.nih.gov/pub/dist/src/niftilib/nifti1.h

In particular, it allows one to take a (possibly 4 or higher-dimensional) AffineTransform instance and return a valid NIFTI 3-dimensional NIFTI AffineTransform instance.

Axes:

NIFTI files can have up to seven dimensions. We take the convention that the output coordinate names are (‘x+LR’,’y+PA’,’z+SI’,’t’,’u’,’v’,’w’) and the input coordinate names are (‘i’,’j’,’k’,’t’,’u’,’v’,’w’).

In the NIFTI specification, the order of the output coordinates (at least the first 3) are fixed to be LPS:(‘x+LR’,’y+PA’,’z+SI’) and their order is not allowed to change. If the output coordinates are RAS:(‘x+RL’,’y+AP’,’z+SI’), then the function ni_affine_pixdim_from_affine flips them to maintain NIFTI’s standard of LPS:(‘x+LR’,’y+PA’,’z+SI’) coordinates.

NIFTI has a ‘diminfo’ header attribute that optionally specifies that some of ‘i’, ‘j’, ‘k’ are renamed ‘frequency’, ‘phase’ or ‘axis’.

Functions

nipy.io.nifti_ref.affine_transform_from_array(affine, ijk, pixdim)

Generate a AffineTransform from an affine transform.

This is a convenience function to create a AffineTransform from image attributes. It assumes that the first three axes in the image (and therefore affine) are spatial (in ‘ijk’ in input and equal to ‘xyz’ in output), and appends the standard names for further dimensions (e.g. ‘l’ as the 4th in input, ‘t’ as the 4th in output).

Parameters :

affine : array

affine for affine_transform

ijk : sequence

sequence, some permutation of ‘ijk’, giving spatial axis ordering. These are the spatial input axis names

pixdim : sequence of floats

Pixdims for dimensions beyond 3.

Returns :

3daffine_transform : AffineTransform

affine transform corresponding to affine and ijk domain names with LPS range names

full_transform: ``AffineTransform`` :

affine transform corresponding to affine and ijk domain names for first 3 coordinates, diagonal with pixdim values beyond

Examples

>>> af_tr3d, af_tr = affine_transform_from_array(np.diag([2,3,4,1]), 'ijk', [])
>>> af_tr.function_domain.coord_names
('i', 'j', 'k')
>>> af_tr3d.function_domain.coord_names
('i', 'j', 'k')
>>> af_tr.function_range.coord_names
('x+LR', 'y+PA', 'z+SI')
>>> af_tr3d.function_range.coord_names
('x+LR', 'y+PA', 'z+SI')
>>> af_tr3d, af_tr = affine_transform_from_array(np.diag([2,3,4,1]), 'kij', [3.5])
>>> af_tr.function_domain.coord_names
('k', 'i', 'j', 't')
>>> af_tr.function_range.coord_names
('x+LR', 'y+PA', 'z+SI', 't')
>>> af_tr3d.function_domain.coord_names
('k', 'i', 'j')
>>> af_tr3d.function_range.coord_names
('x+LR', 'y+PA', 'z+SI')
>>> print af_tr3d
AffineTransform(
   function_domain=CoordinateSystem(coord_names=('k', 'i', 'j'), name='', coord_dtype=float64),
   function_range=CoordinateSystem(coord_names=('x+LR', 'y+PA', 'z+SI'), name='', coord_dtype=float64),
   affine=array([[ 2.,  0.,  0.,  0.],
                 [ 0.,  3.,  0.,  0.],
                 [ 0.,  0.,  4.,  0.],
                 [ 0.,  0.,  0.,  1.]])
)
>>> print af_tr
AffineTransform(
   function_domain=CoordinateSystem(coord_names=('k', 'i', 'j', 't'), name='product', coord_dtype=float64),
   function_range=CoordinateSystem(coord_names=('x+LR', 'y+PA', 'z+SI', 't'), name='product', coord_dtype=float64),
   affine=array([[ 2. ,  0. ,  0. ,  0. ,  0. ],
                 [ 0. ,  3. ,  0. ,  0. ,  0. ],
                 [ 0. ,  0. ,  4. ,  0. ,  0. ],
                 [ 0. ,  0. ,  0. ,  3.5,  0. ],
                 [ 0. ,  0. ,  0. ,  0. ,  1. ]])
)

FIXME: This is an internal function and should be revisited when the AffineTransform is refactored.

nipy.io.nifti_ref.ni_affine_pixdim_from_affine(affine_transform, strict=False)

Given a square affine_transform, return a new 3-dimensional AffineTransform and the pixel dimensions in dimensions greater than 3.

If strict is True, then an exception is raised if the affine matrix is not diagonal with positive entries in dimensions greater than 3.

If strict is True, then the names of the range coordinates must be LPS:(‘x+LR’,’y+PA’,’z+SI’) or RAS:(‘x+RL’,’y+AP’,’z+SI’). If strict is False, and the names are not either of these, LPS:(‘x+LR’,’y+PA’,’z+SI’) are used.

If the names are RAS:(‘x+RL’,’y+AA’,’z+SI’), then the affine is flipped so the result is in LPS:(‘x+LR’,’y+PA’,’z+SI’).

NIFTI images have the first 3 dimensions as spatial, and the remaining as non-spatial, with the 4th typically being time.

Parameters :

affine_transform : AffineTransform

Returns :

nifti_transform: `AffineTransform` :

A 3-dimensional or less AffineTransform

pixdim : ndarray(np.float)

The pixel dimensions greater than 3.

>>> outnames = CS((‘x+LR’,’y+PA’,’z+SI’) + (‘t’,)) :

>>> innames = CS([‘phase’, ‘j’, ‘frequency’, ‘t’]) :

>>> af_tr = AT(outnames, innames, np.diag([2,-2,3,3.5,1])) :

>>> print af_tr :

AffineTransform( :

function_domain=CoordinateSystem(coord_names=(‘x+LR’, ‘y+PA’, ‘z+SI’, ‘t’), name=’‘, coord_dtype=float64), function_range=CoordinateSystem(coord_names=(‘phase’, ‘j’, ‘frequency’, ‘t’), name=’‘, coord_dtype=float64), affine=array([[ 2. , 0. , 0. , 0. , 0. ],

[ 0. , -2. , 0. , 0. , 0. ], [ 0. , 0. , 3. , 0. , 0. ], [ 0. , 0. , 0. , 3.5, 0. ], [ 0. , 0. , 0. , 0. , 1. ]])

) :

>>> af_tr3dorless, p = ni_affine_pixdim_from_affine(af_tr) :

>>> print af_tr3dorless :

AffineTransform( :

function_domain=CoordinateSystem(coord_names=(‘x+LR’, ‘y+PA’, ‘z+SI’), name=’‘, coord_dtype=float64), function_range=CoordinateSystem(coord_names=(‘x+LR’, ‘y+PA’, ‘z+SI’), name=’‘, coord_dtype=float64), affine=array([[ 2., 0., 0., 0.],

[ 0., -2., 0., 0.], [ 0., 0., 3., 0.], [ 0., 0., 0., 1.]])

) :

>>> print p :

[ 3.5] :