NIPY logo

Site Navigation

NIPY Community

Table Of Contents

Previous topic

algorithms.statistics.utils

This Page

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 input (domain) axes renamed

Axes renamed according to the input dictionary.

Parameters :

**names_dict : dict

with keys being old names, and values being new names

Returns :

newimg : Image

An Image with the same data, having its axes 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 = 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 new image with renamed output (range) coordinates

Coordinates renamed according to the dictionary

Parameters :

**names_dict : dict

with keys being old names, and values being new names

Returns :

newimg : Image

An Image with the same data, having its output 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 reordered input coordinates.

This transposes the data as well.

Parameters :

order : None, sequence, optional

sequence of int (giving indices) or str (giving names) - expressing new order of coordmap output coordinates. None (the default) results in reversed ordering.

Returns :

r_img : object

Image of same class as self, with reordered output coordinates.

Examples

>>> 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 new Image with reordered output coordinates

New Image coordmap has reordered output coordinates. This does not transpose the data.

Parameters :

order : None, sequence, optional

sequence of int (giving indices) or str (giving names) - expressing new order of coordmap output coordinates. None (the default) results in reversed ordering.

Returns :

r_img : object

Image of same class as self, with reordered output coordinates.

Examples

>>> 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.