NIPY logo

Site Navigation

NIPY Community

Table Of Contents

This Page

core.image.xyz_image

Module: core.image.xyz_image

Inheritance diagram for nipy.core.image.xyz_image:

Images that have orientations L/R, A/P, S/I, and that have the first three dimensions as spatial

Classes

XYZImage

class nipy.core.image.xyz_image.XYZImage(data, affine, axis_names, metadata={}, lps=True)

Bases: nipy.core.image.image.Image

The standard image for nipy, with XYZ output coordinates.

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

Attributes

metadata:

dictionary

Optional, user-defined, dictionary 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’).

xyz_transform:

XYZTransform

A CoordinateMap that relates all the spatial axes of the data to XYZ ‘xyz’ coordinates.

coordmap:

AffineTransform

Coordinate map describing the relationship between all coordinates and axis_names.

axes:

CoordinateSystem

CoordinateSystem for the axes of the data.

reference:

CoordinateSystem

CoordinateSystem for the reference space of the data.

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.

Examples

>>> data = np.empty((30,40,50))
>>> affine = np.diag([3,4,5,1])
>>> im = XYZImage(data, affine, 'ijk')
>>> im.reference
CoordinateSystem(coord_names=('x+LR', 'y+PA', 'z+SI'), name='world', coord_dtype=float64)
>>> im.axes
CoordinateSystem(coord_names=('i', 'j', 'k'), name='voxel', coord_dtype=float64)
>>> im.xyz_transform
XYZTransform(
   function_domain=CoordinateSystem(coord_names=('i', 'j', 'k'), name='voxel', coord_dtype=float64),
   function_range=CoordinateSystem(coord_names=('x+LR', 'y+PA', 'z+SI'), name='world', coord_dtype=float64),
   affine=array([[ 3.,  0.,  0.,  0.],
                 [ 0.,  4.,  0.,  0.],
                 [ 0.,  0.,  5.,  0.],
                 [ 0.,  0.,  0.,  1.]])
)

Methods

axes
coordmap
from_image
get_data
ndim
renamed_axes
renamed_reference
reordered_axes
reordered_reference
resampled_to_affine
resampled_to_img
shape
to_image
values_in_world
xyz_ordered
__init__(data, affine, axis_names, metadata={}, lps=True)

Creates a new nipy image with an affine mapping.

Parameters :

data : array

ndarray representing the data.

affine : 4x4 array

affine transformation to the reference coordinate system

axis_names : [string]

names of the axes in the coordinate system.

affine

4x4 Affine matrix

static axes()
static from_image(img)

Return an XYZImage from an Image with the same data.

The affine matrix is read off from the upper left corner of img.affine.

get_data()

Return data as a numpy array.

header

The file header structure for this image, if available. This interface will soon go away - you should use ``img.metadata[‘header’] instead.

static ndim()
reference

Reference space is always ‘world’ for XYZImage

renamed_axes(**names_dict)

Return new image with its axes renamed

Axes renamed according to the dictionary.

Parameters :

img : Image

names_dict : dict

Returns :

newimg : Image

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

Examples

>>> data = np.random.standard_normal((11,9,4))
>>> im = XYZImage(data, np.diag([3,4,5,1]), 'ijk')
>>> im_renamed = im.renamed_axes(i='slice')
>>> im_renamed.axes
CoordinateSystem(coord_names=('slice', 'j', 'k'), name='voxel', coord_dtype=float64)
renamed_reference(newnames, name='')
reordered_axes(order=None, name=None)

Return a new XYZImage whose axes have been reordered.

The reordering must be such that the first 3 coordinates remain the same.

Parameters :

order : sequence

Order to use, defaults to reverse. The elements can be integers, strings or 2-tuples of strings. If they are strings, they should be in self.axes.coord_names.

name : str, optional

Name of new function_domain, defaults to self.function_domain.name.

Returns :

im_reordered : XYZImage

reordered_reference(order)
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 : XYZTransform

Affine of the new grid.

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-neighbour interpolation is performed.

shape: tuple :

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

Returns :

resampled_image : XYZImage

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

Notes

The coordinate system of the output 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 : XYZImage

XYZImage onto the grid of which the data will be resampled.

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 : XYZImage

New XYZImage with the data resampled.

static shape()
to_image()

Return an Image with the same data as self.

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

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

Parameters :

x : number or array

x positions in world space, in other words milimeters

y : number or array

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

z : number or array

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 array

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

Returns an image with the affine diagonal, (optionally with positive entries), in the XYZ coordinate system.

Parameters :

positive : bool, optional

If True, also ensures that the diagonal entries are positive.

Notes

This may possibly transpose the data array.

If positive is True, this may involve creating a new array with data self.get_data()[::-1,::-1]

xyz_transform

Returns 3-dimensional XYZTransform

The same as self.coordmap if self.ndim == 3.

XYZTransform

class nipy.core.image.xyz_image.XYZTransform(affine, axis_names, lps=True)

Bases: nipy.core.reference.coordinate_map.AffineTransform

Affine transform with x, y, z being L<->R, P<->A, I<->S

That is, the X axis is left to right or right to left, the Y axis is anterior to posterior or posterior to anterior, and the Z axis is inferior to superior or superior to inferior.

Methods

from_params
from_start_step
identity
inverse
renamed_domain
renamed_range
reordered_domain
reordered_range
__init__(affine, axis_names, lps=True)

Initialize XYZTransform

Parameters :

affine : (4, 4) array-like

axis_names : sequence or str

sequence of voxel axis names. str is taken as list(str)

lps : bool, optional

whether the orientation is standard LPS

Examples

>>> xyz = XYZTransform(np.diag([3,4,5,1]), 'ijk')
>>> xyz
XYZTransform(
   function_domain=CoordinateSystem(coord_names=('i', 'j', 'k'), name='voxel', coord_dtype=float64),
   function_range=CoordinateSystem(coord_names=('x+LR', 'y+PA', 'z+SI'), name='world', coord_dtype=float64),
   affine=array([[ 3.,  0.,  0.,  0.],
                 [ 0.,  4.,  0.,  0.],
                 [ 0.,  0.,  5.,  0.],
                 [ 0.,  0.,  0.,  1.]])
)
static from_params(innames, outnames, params, domain_name='', range_name='')

Create AffineTransform from innames and outnames

Parameters :

innames : sequence of str or str

The names of the axes of the domain. If str, then names given by list(innames)

outnames : seqence of str or str

The names of the axes of the range. If str, then names given by list(outnames)

params : AffineTransform, array or (array, array)

An affine function between the domain and range. This can be represented either by a single ndarray (which is interpreted as the representation of the function in homogeneous coordinates) or an (A,b) tuple.

domain_name : str, optional

Name of domain CoordinateSystem

range_name : str, optional

Name of range CoordinateSystem

Returns :

aff : AffineTransform

Notes

Precondition :len(shape) == len(names)
Raises ValueError:
 if len(shape) != len(names)
static from_start_step(innames, outnames, start, step, domain_name='', range_name='')

New AffineTransform from names, start and step.

Parameters :

innames : sequence of str or str

The names of the axes of the domain. If str, then names given by list(innames)

outnames : seqence of str or str

The names of the axes of the range. If str, then names given by list(outnames)

start : sequence of float

Start vector used in constructing affine transformation

step : sequence of float

Step vector used in constructing affine transformation

domain_name : str, optional

Name of domain CoordinateSystem

range_name : str, optional

Name of range CoordinateSystem

Returns :

cm : CoordinateMap

Notes

len(names) == len(start) == len(step)

Examples

>>> cm = AffineTransform.from_start_step('ijk', 'xyz', [1, 2, 3], [4, 5, 6])
>>> cm.affine
array([[ 4.,  0.,  0.,  1.],
       [ 0.,  5.,  0.,  2.],
       [ 0.,  0.,  6.,  3.],
       [ 0.,  0.,  0.,  1.]])
static identity(coord_names, name='')

Return an identity coordmap of the given shape

Parameters :

coord_names : sequence of str or str

The names of the axes of the domain. If str, then names given by list(coord_names)

name : str, optional

Name of origin of coordinate system

Returns :

cm : CoordinateMap

CoordinateMap with CoordinateSystem domain and an identity transform, with identical domain and range.

Examples

>>> cm = AffineTransform.identity('ijk', 'somewhere')
>>> cm.affine
array([[ 1.,  0.,  0.,  0.],
       [ 0.,  1.,  0.,  0.],
       [ 0.,  0.,  1.,  0.],
       [ 0.,  0.,  0.,  1.]])
>>> cm.function_domain
CoordinateSystem(coord_names=('i', 'j', 'k'), name='somewhere', coord_dtype=float64)
>>> cm.function_range
CoordinateSystem(coord_names=('i', 'j', 'k'), name='somewhere', coord_dtype=float64)
inverse()

Return inverse affine transform or None if not invertible

renamed_domain(newnames, name='')

New AffineTransform with function_domain renamed

Parameters :

newnames : dict

A dictionary whose keys are integers or are in mapping.function_domain.coord_names and whose values are the new names.

Returns :

newmapping : AffineTransform

A new AffineTransform with renamed function_domain.

Examples

>>> affine_domain = CoordinateSystem('ijk')
>>> affine_range = CoordinateSystem('xyz')
>>> affine_matrix = np.identity(4)
>>> affine_mapping = AffineTransform(affine_domain, affine_range, affine_matrix)
>>> new_affine_mapping = affine_mapping.renamed_domain({'i':'phase','k':'freq','j':'slice'})
>>> new_affine_mapping.function_domain
CoordinateSystem(coord_names=('phase', 'slice', 'freq'), name='', coord_dtype=float64)
>>> new_affine_mapping = affine_mapping.renamed_domain({'i':'phase','k':'freq','l':'slice'})
Traceback (most recent call last):
   ...
ValueError: no domain coordinate named l
renamed_range(newnames, name='')
reordered_domain(order=None)

New AffineTransform with function_domain reordered

Default behaviour is to reverse the order of the coordinates.

Parameters :

order : sequence

Order to use, defaults to reverse. The elements can be integers, strings or 2-tuples of strings. If they are strings, they should be in mapping.function_domain.coord_names.

Returns :

newmapping :AffineTransform :

A new AffineTransform with the coordinates of function_domain reordered.

Examples

>>> input_cs = CoordinateSystem('ijk')
>>> output_cs = CoordinateSystem('xyz')
>>> cm = AffineTransform(input_cs, output_cs, np.identity(4))
>>> cm.reordered_domain('ikj').function_domain
CoordinateSystem(coord_names=('i', 'k', 'j'), name='', coord_dtype=float64)
reordered_range(order, name='')

Function

nipy.core.image.xyz_image.flip(xyz_img)

Flip world of xyz_img from LPS / RAS to RAS / LPS.

Parameters :

xyz_img : XYZImage

Returns :

f_img : XYZImage

image with flipped world

Examples

>>> data = np.random.standard_normal((30,40,50,5))
>>> metadata = {'name':'John Doe'}
>>> lps_im = XYZImage(data, np.diag([3,4,5,1]), 'ijkt', metadata)
>>> lps_im.xyz_transform
XYZTransform(
   function_domain=CoordinateSystem(coord_names=('i', 'j', 'k'), name='voxel', coord_dtype=float64),
   function_range=CoordinateSystem(coord_names=('x+LR', 'y+PA', 'z+SI'), name='world', coord_dtype=float64),
   affine=array([[ 3.,  0.,  0.,  0.],
                 [ 0.,  4.,  0.,  0.],
                 [ 0.,  0.,  5.,  0.],
                 [ 0.,  0.,  0.,  1.]])
)
>>> ras_im = flip(lps_im)
>>> ras_im.xyz_transform
XYZTransform(
   function_domain=CoordinateSystem(coord_names=('i', 'j', 'k'), name='voxel', coord_dtype=float64),
   function_range=CoordinateSystem(coord_names=('x+RL', 'y+AP', 'z+SI'), name='world', coord_dtype=float64),
   affine=array([[-3.,  0.,  0.,  0.],
                 [ 0., -4.,  0.,  0.],
                 [ 0.,  0.,  5.,  0.],
                 [ 0.,  0.,  0.,  1.]])
)
>>> np.allclose(ras_im.get_data(), lps_im.get_data())
True
>>> ras_im.metadata == lps_im.metadata
True
>>> 
>>> flip(ras_im) == lps_im
True