core.image.affine_image

Module: core.image.affine_image

Inheritance diagram for nipy.core.image.affine_image:

The base image interface.

AffineImage

class nipy.core.image.affine_image.AffineImage(data, affine, coord_sys, metadata=None)

Bases: nipy.core.image.image.Image

The affine image for nipy.

This object is a subclass of Image that assumes the first 3 coordinates are spatial.

Attributes

Metadata:

dictionnary

Optional, user-defined, dictionnary used to carry around extra information about the data as it goes through transformations. The Image class does not garanty consistency of this information as the data is modified.

_data:

Private pointer to the data.

Properties

Affine:

4x4 ndarray

Affine mapping from voxel axes to world coordinates (world coordinates are always forced to be ‘x’, ‘y’, ‘z’).

Spatial_coordmap:  

AffineTransform

Coordinate map describing the spatial coordinates (always forced to be ‘x’, ‘y’, ‘z’) and the coordinate axes with names axis_names[:3].

Coordmap:

AffineTransform

Coordinate map describing the relationship between all coordinates and axis_names.

Notes

The data is stored in an undefined way: prescalings might need to be applied to it before using it, or the data might be loaded on demand. The best practice to access the data is not to access the _data attribute, but to use the get_data method.

Methods

axes
coordmap
get_data
ndim
reference
renamed_axes
renamed_reference
reordered_axes
reordered_reference
resampled_to_affine
resampled_to_img
shape
values_in_world
xyz_ordered

__init__(data, affine, coord_sys, metadata=None)

Creates a new nipy image with an affine mapping.

Parameters:

data : ndarray

ndarray representing the data.

affine : 4x4 ndarray

affine transformation to the reference coordinate system

coord_system : string

name of the reference coordinate system.

affine

Returns the affine of the spatial coordmap which will always be a 4x4 matrix.

static axes()

get_data()

Return data as a numpy array.

header

The file header dictionary for this image. In order to update the header, you must first make a copy of the header, set the values you wish to change, then set the image header to the updated header.

static ndim()

static reference()

renamed_axes(**names_dict)

Return a new image with its axes renamed according to the dictionary.

Parameters:

img : Image

names_dict : dictionary

Returns:

newimg : Image

An Image with the same data, having its axes renamed.

>>> data = np.random.standard_normal((11,9,4)) :

>>> im = Image(data, AffineTransform.from_params(‘ijk’, ‘xyz’, np.identity(4), ‘domain’, ‘range’)) :

>>> im_renamed = im.renamed_axes(i=’slice’) :

>>> print im_renamed.axes :

CoordinateSystem(coord_names=(‘slice’, ‘j’, ‘k’), name=’domain’, coord_dtype=float64) :

renamed_reference(**names_dict)

Return a new image with its reference coordinates renamed according to the dictionary.

Parameters:

img : Image

names_dict : dictionary

Returns:

newimg : Image

An Image with the same data, having its reference coordinates renamed.

Examples

>>> data = np.random.standard_normal((11,9,4))
>>> im = Image(data, AffineTransform.from_params('ijk', 'xyz', np.identity(4), 'domain', 'range'))
>>> im_renamed_reference = im.renamed_reference(x='newx', y='newy')
>>> print im_renamed_reference.reference
CoordinateSystem(coord_names=('newx', 'newy', 'z'), name='range', coord_dtype=float64)

reordered_axes(order=None)

Return a new Image with its coordmap having reordered input coordinates. This transposes the data as well.

>>> cmap = AffineTransform.from_start_step('ijk', 'xyz', [1,2,3],[4,5,6], 'domain', 'range')
>>> cmap
AffineTransform(
   function_domain=CoordinateSystem(coord_names=('i', 'j', 'k'), name='domain', coord_dtype=float64),
   function_range=CoordinateSystem(coord_names=('x', 'y', 'z'), name='range', coord_dtype=float64),
   affine=array([[ 4.,  0.,  0.,  1.],
                 [ 0.,  5.,  0.,  2.],
                 [ 0.,  0.,  6.,  3.],
                 [ 0.,  0.,  0.,  1.]])
)
>>> im = Image(np.empty((30,40,50)), cmap)
>>> im_reordered = im.reordered_axes([2,0,1])
>>> im_reordered.shape
(50, 30, 40)
>>> im_reordered.coordmap
AffineTransform(
   function_domain=CoordinateSystem(coord_names=('k', 'i', 'j'), name='domain', coord_dtype=float64),
   function_range=CoordinateSystem(coord_names=('x', 'y', 'z'), name='range', coord_dtype=float64),
   affine=array([[ 0.,  4.,  0.,  1.],
                 [ 0.,  0.,  5.,  2.],
                 [ 6.,  0.,  0.,  3.],
                 [ 0.,  0.,  0.,  1.]])
)
>>> 

reordered_reference(order=None)

Return a new Image with its coordmap having reordered output coordinates. This does not transpose the data.

>>> cmap = AffineTransform.from_start_step('ijk', 'xyz', [1,2,3],[4,5,6], 'domain', 'range')
>>> im = Image(np.empty((30,40,50)), cmap)
>>> im_reordered = im.reordered_reference([2,0,1])
>>> im_reordered.shape
(30, 40, 50)
>>> im_reordered.coordmap
AffineTransform(
   function_domain=CoordinateSystem(coord_names=('i', 'j', 'k'), name='domain', coord_dtype=float64),
   function_range=CoordinateSystem(coord_names=('z', 'x', 'y'), name='range', coord_dtype=float64),
   affine=array([[ 0.,  0.,  6.,  3.],
                 [ 4.,  0.,  0.,  1.],
                 [ 0.,  5.,  0.,  2.],
                 [ 0.,  0.,  0.,  1.]])
)

>>> 

resampled_to_affine(affine_transform, world_to_world=None, interpolation_order=3, shape=None)

Resample the image to be an affine image.

Parameters:

affine_transform : AffineTransform

Affine of the new grid.

XXX In the original proposal, it said something about “if only 3x3 it is assumed to be a rotation”, but this wouldn’t work the way the code was written becuase it was written as if affine was the affine of an AffineImage. So, if you input a “rotation matrix” that is assuming you have voxels of size 1.... This rotation can now be expressed with the world_to_world argument.

world_to_world: 4x4 ndarray, optional :

A matrix representing a mapping from the target’s (affine_transform) “world” to self’s “world”. Defaults to np.identity(4)

interpolation_order : int, optional

Order of the spline interplation. If 0, nearest-neighbour interpolation is performed.

shape: tuple :

Shape of the resulting image. Defaults to self.shape.

Returns:

resampled_image : nipy AffineImage

New nipy image with the data resampled in the given affine.

Notes

The coordinate system of the resampled_image is the world of affine_transform. Therefore, if world_to_world=np.identity(4), the coordinate system is not changed: the returned image points to the same world space.

resampled_to_img(target_image, world_to_world=None, interpolation_order=3)

Resample the image to be on the same grid than the target image.

Parameters:

target_image : AffineImage

Nipy image onto the grid of which the data will be resampled.

XXX In the proposal, target_image was assumed to be a matrix if it had no attribute “affine”. It now has to have a spatial_coordmap attribute.

world_to_world: 4x4 ndarray, optional

A matrix representing a mapping from the target’s “world” to self’s “world”. Defaults to np.identity(4)

interpolation_order : int, optional

Order of the spline interplation. If 0, nearest neighboor interpolation is performed.

Returns:

resampled_image : nipy_image

New nipy image with the data resampled.

XXX Since you’ve enforced the outputs always to be ‘x’,’y’,’z’ – EVERY image is embedded in the same coordinate system (i.e. ‘x’,’y’,’z’), but images can have different coordinate axes. The term “embedding” that was here in the proposal refers to something in the range of a function, not its domain. By adding a world_to_world transformation, i.e. a rotation or something, we now change the coordinate system of the resampled_image

static shape()

spatial_coordmap

Returns 3 dimensional AffineTransform, which is the same as self.coordmap if self.ndim == 3.

values_in_world(x, y, z, interpolation_order=3)

Return the values of the data at the world-space positions given by x, y, z

Parameters:

x : number or ndarray

x positions in world space, in other words milimeters

y : number or ndarray

y positions in world space, in other words milimeters. The shape of y should match the shape of x

z : number or ndarray

z positions in world space, in other words milimeters. The shape of z should match the shape of x

interpolation_order : int, optional

Order of the spline interplation. If 0, nearest neighboor interpolation is performed.

Returns:

values : number or ndarray

Data values interpolated at the given world position. This is a number or an ndarray, depending on the shape of the input coordinate.

xyz_ordered()

Returns an image with the affine diagonal and positive in its coordinate system.