core.image.xyz_image¶

Module: `core.image.xyz_image`¶

Inheritance diagram for nipy.core.image.xyz_image:

The base image interface.

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, an Image with

XYZ output coordinates.

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

Attributes

metadata:

metadata:	dictionary 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.

dictionary

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

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

Parameters:	data : ndarray ndarray representing the data. affine : 4x4 ndarray affine transformation to the reference coordinate system axis_names : [string] names of the axes in the coordinate system.

data : ndarray

ndarray representing the data.

affine : 4x4 ndarray

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 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()¶

reference¶: Reference space is always ‘world’ for XYZImage

renamed_axes(**names_dict)¶

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

Parameters:

Parameters:	img : Image names_dict : dictionary
Returns:	newimg : Image An Image with the same data, having its axes renamed.

img : Image

names_dict : dictionary

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')
>>> print im_renamed.axes
CoordinateSystem(coord_names=('slice', 'j', 'k'), name='voxel', coord_dtype=float64)

renamed_reference(newnames, name='')¶

reordered_axes(order=None)¶

Return a new XYZImage whose axes have been reordered. The reordering must be such that the first 3 coordinates remain the same.

Parameters:

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: string, optional : Name of new function_domain, defaults to self.function_domain.name.

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: string, optional :

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

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:

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.

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:

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.

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 the values of the data at the world-space positions given by x, y, z

Parameters:

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.

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

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

Parameters:

Parameters:	positive : bool, optional If True, also ensures that the diagonal entries are positive.

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, which is 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

An AffineTransform with either LPS:(‘x+LR’, ‘y+PA’, ‘z+SI’) or RAS:(‘x+RL’, ‘y+AP’, ‘z+SI’) output coordinates.

Methods

`from_params`
`from_start_step`
`identity`
`inverse`
`renamed_domain`
`renamed_range`
`reordered_domain`
`reordered_range`

__init__(affine, axis_names, lps=True)¶

>>> 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 an AffineTransform instance from sequences of innames and outnames.

Parameters:

Parameters:	innames : `tuple` of `string` The names of the axes of the domain. outnames : `tuple` of `string` The names of the axes of the range. params : AffineTransform, ndarray or (ndarray, ndarray) 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 : `string` Name of domain CoordinateSystem range_name : `string` Name of range CoordinateSystem
Returns:	aff : AffineTransform object instance

innames : tuple of string

The names of the axes of the domain.

outnames : tuple of string

The names of the axes of the range.

params : AffineTransform, ndarray or (ndarray, ndarray)

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

Name of domain CoordinateSystem

range_name : string

Name of range CoordinateSystem

Returns:

aff : AffineTransform object instance

Notes

Raises valueerror:
Precondition:	`len(shape) == len(names)`
	`if len(shape) != len(names)`

static from_start_step(innames, outnames, start, step, domain_name='', range_name='')¶

Create an AffineTransform instance from sequences of names, start and step.

Parameters:

Parameters:	innames : `tuple` of `string` The names of the axes of the domain. outnames : `tuple` of `string` The names of the axes of the range. start : `tuple` of `float` Start vector used in constructing affine transformation step : `tuple` of `float` Step vector used in constructing affine transformation domain_name : `string` Name of domain CoordinateSystem range_name : `string` Name of range CoordinateSystem
Returns:	cm : CoordinateMap

innames : tuple of string

The names of the axes of the domain.

outnames : tuple of string

The names of the axes of the range.

start : tuple of float

Start vector used in constructing affine transformation

step : tuple of float

Step vector used in constructing affine transformation

domain_name : string

Name of domain CoordinateSystem

range_name : string

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:

Parameters:	coord_names : `tuple` of `string` Names of Axes in domain CoordinateSystem name : `string` Name of origin of coordinate system
Returns:	cm : CoordinateMap `CoordinateMap` with CoordinateSystem domain and an identity transform, with identical domain and range.

coord_names : tuple of string

Names of Axes in domain CoordinateSystem

name : string

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.]])
>>> print cm.function_domain
CoordinateSystem(coord_names=('i', 'j', 'k'), name='somewhere', coord_dtype=float64)
>>> print cm.function_range
CoordinateSystem(coord_names=('i', 'j', 'k'), name='somewhere', coord_dtype=float64)

inverse()¶: Return the inverse affine transform, when appropriate, or None.

renamed_domain(newnames, name='')¶: Create a new AffineTransform with the coordinates of function_domain renamed.

renamed_range(newnames, name='')¶

reordered_domain(order=None)¶

Create a new AffineTransform with the coordinates of function_domain reordered. Default behaviour is to reverse the order of the coordinates.

Parameters:

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.

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.

reordered_range(order, name='')¶

Function¶

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

Take an xyz_img and flip its world from LPS / RAS to RAS / LPS.

>>> 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.]])
)
>>> print np.allclose(ras_im.get_data(), lps_im.get_data())
True
>>> print ras_im.metadata == lps_im.metadata
True
>>> 
>>> print flip(ras_im) == lps_im
True
>>> 

Site Navigation

NIPY Community

Table Of Contents

This Page

core.image.xyz_image¶

Module: `core.image.xyz_image`¶

Classes¶

`XYZImage`¶

`XYZTransform`¶

Function¶

Navigation

Site Navigation

NIPY Community

Table Of Contents

This Page

Search mailing list archive

Search this site

core.image.xyz_image¶

Module: core.image.xyz_image¶

Classes¶

XYZImage¶

XYZTransform¶

Function¶

Navigation

Module: `core.image.xyz_image`¶

`XYZImage`¶

`XYZTransform`¶