Table Of Contents

Previous topic

core.reference.array_coords

Next topic

core.reference.coordinate_system

This Page

core.reference.coordinate_map

Module: core.reference.coordinate_map

Inheritance diagram for nipy.core.reference.coordinate_map:

CoordinateMaps map (transform) an image from an input space to an output space.

A CoordinateMap object contains all the details about an input CoordinateSystem, an output CoordinateSystem and the mappings between them. The mapping transforms an image from the input coordinate system to the output coordinate system. And the inverse_mapping performs the opposite transformation. The inverse_mapping can be specified explicity when creating the CoordinateMap or implicitly in the case of an Affine CoordinateMap.

Classes

Affine

class nipy.core.reference.coordinate_map.Affine(affine, input_coords, output_coords)

Bases: nipy.core.reference.coordinate_map.CoordinateMap

A class representing an affine transformation from an input coordinate system to an output coordinate system.

This class has an affine property, which is a matrix representing the affine transformation in homogeneous coordinates. This matrix is used to perform mappings, rather than having an explicit mapping function.

>>> inp_cs = CoordinateSystem('ijk')
>>> out_cs = CoordinateSystem('xyz')
>>> cm = Affine(np.diag([1, 2, 3, 1]), inp_cs, out_cs)
>>> cm.affine
array([[ 1.,  0.,  0.,  0.],
       [ 0.,  2.,  0.,  0.],
       [ 0.,  0.,  3.,  0.],
       [ 0.,  0.,  0.,  1.]])
>>> cm([1,1,1])
array([[ 1.,  2.,  3.]])
>>> icm = cm.inverse
>>> icm([1,2,3])
array([[ 1.,  1.,  1.]])
__init__(affine, input_coords, output_coords)

Return an CoordinateMap specified by an affine transformation in homogeneous coordinates.

Parameters:

affine : array-like

affine homogenous coordinate matrix

input_coords : CoordinateSystem

input coordinates

output_coords : CoordinateSystem

output coordinates

Notes

The dtype of the resulting matrix is determined by finding a safe typecast for the input_coords, output_coords and affine.

affine
The affine transform matrix of the Affine CoordinateMap.
copy()

Create a copy of the coordmap.

Returns:cm : CoordinateMap

Examples

>>> cm = Affine(np.eye(4), CoordinateSystem('ijk'), CoordinateSystem('xyz'))
>>> cm_copy = cm.copy()
>>> cm is cm_copy
False

Note that the matrix (affine) is not a pointer to the same data, it’s a full independent copy

>>> cm.affine[0,0] = 2.0
>>> cm_copy.affine[0,0]
1.0
static from_params(innames, outnames, params)

Create an Affine instance from sequences of innames and outnames.

Parameters:

innames : tuple of string

The names of the axes of the input coordinate systems

outnames : tuple of string

The names of the axes of the output coordinate systems

params : Affine, ndarray or (ndarray, ndarray)

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

Returns:

aff : Affine object instance

Notes

Precondition:len(shape) == len(names)
Raises valueerror:
 if len(shape) != len(names)
static from_start_step(innames, outnames, start, step)

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

Parameters:

innames : tuple of string

The names of the axes of the input coordinate systems

outnames : tuple of string

The names of the axes of the output coordinate systems

start : tuple of float

Start vector used in constructing affine transformation

step : tuple of float

Step vector used in constructing affine transformation

Returns:

cm : CoordinateMap

Notes

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

Examples

>>> cm = Affine.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(names)

Return an identity coordmap of the given shape.

Parameters:

names : tuple of string

Names of Axes in output CoordinateSystem

Returns:

cm : CoordinateMap

CoordinateMap with CoordinateSystem input and an identity transform, with identical input and output coords.

Examples

>>> cm = Affine.identity('ijk')
>>> cm.affine
array([[ 1.,  0.,  0.,  0.],
       [ 0.,  1.,  0.,  0.],
       [ 0.,  0.,  1.,  0.],
       [ 0.,  0.,  0.,  1.]])
>>> print cm.input_coords
name: 'input', coord_names: ('i', 'j', 'k'), coord_dtype: float64
>>> print cm.output_coords
name: 'output', coord_names: ('i', 'j', 'k'), coord_dtype: float64
inverse
Return the inverse coordinate map.
inverse_mapping
The inverse affine mapping from the Affine CoordinateMap.

CoordinateMap

class nipy.core.reference.coordinate_map.CoordinateMap(mapping, input_coords, output_coords, inverse_mapping=None)

Bases: object

A set of input and output CoordinateSystems and a mapping between them.

For example, the mapping may represent the mapping of an image from voxel space (the input coordinates) to real space (the output coordinates). The mapping may be an affine or non-affine transformation.

Attributes:

input_coords : CoordinateSystem

The input coordinate system.

output_coords : CoordinateSystem

The output coordinate system.

mapping : callable

A callable that maps the input_coords to the output_coords.

inverse_mapping : None or callable

A callable that maps the output_coords to the input_coords. Not all mappings have an inverse, in which case inverse_mapping is None.

Examples

>>> input_coords = CoordinateSystem('ijk', 'voxels')
>>> output_coords = CoordinateSystem('xyz', 'world')
>>> mni_orig = np.array([-90.0, -126.0, -72.0])
>>> mapping = lambda x: x + mni_orig
>>> inv_mapping = lambda x: x - mni_orig
>>> cm = CoordinateMap(mapping, input_coords, output_coords, inv_mapping)

Map the first 3 voxel coordinates, along the x-axis, to mni space:

>>> x = np.array([[0,0,0], [1,0,0], [2,0,0]])
>>> cm.mapping(x)
array([[ -90., -126.,  -72.],
       [ -89., -126.,  -72.],
       [ -88., -126.,  -72.]])
__init__(mapping, input_coords, output_coords, inverse_mapping=None)

Create a CoordinateMap given the input/output coords and mappings.

Parameters:

mapping : callable

The mapping between input and output coordinates

input_coords : CoordinateSystem

The input coordinate system

output_coords : CoordinateSystem

The output coordinate system

inverse_mapping : None or callable, optional

The optional inverse of mapping, with the intention being x = inverse_mapping(mapping(x)). If the mapping is affine and invertible, then this is true for all x. The default is None

Returns:

coordmap : CoordinateMap

copy()

Create a copy of the coordmap.

Returns:coordmap : CoordinateMap
input_coords
input coordinate system
inverse
Return a new CoordinateMap with the mappings reversed
inverse_mapping
The mapping from output_coords to input_coords
mapping
The mapping from input_coords to output_coords.
ndim
Number of dimensions of input and output coordinates.
output_coords
output coordinate system

Functions

nipy.core.reference.coordinate_map.compose(*cmaps)
Return the composition of two or more CoordinateMaps.
nipy.core.reference.coordinate_map.linearize(mapping, ndimin, step=1, origin=None, dtype=None)

Given a Mapping of ndimin variables, return the linearization of mapping at origin based on a given step size in each coordinate axis.

If not specified, origin defaults to np.zeros(ndimin, dtype=dtype).

Parameters:

mapping : callable

A function to linearize

ndimin : int

Number of input dimensions to mapping

step : scalar, optional

step size over which to calculate linear components. Default 1

origin : None or array, optional

Origin at which to linearize mapping. If None, origin is np.zeros(ndimin)

dtype : None or np.dtype, optional

dtype for return. Default is None. If dtype is None, and step is an ndarray, use step.dtype. Otherwise use np.float.

Returns:

C : array

Linearization of mapping in homogeneous coordinates, i.e. an array of size (ndimout+1, ndimin+1) where ndimout = mapping(origin).shape[0].

nipy.core.reference.coordinate_map.product(*cmaps)
Return the “topological” product of two or more CoordinateMaps.
nipy.core.reference.coordinate_map.reorder_input(coordmap, order=None)
Create a new coordmap with reversed input_coords. Default behaviour is to reverse the order of the input_coords. If the coordmap has a shape, the resulting one will as well.
nipy.core.reference.coordinate_map.reorder_output(coordmap, order=None)
Create a new coordmap with reversed output_coords. Default behaviour is to reverse the order of the input_coords.
nipy.core.reference.coordinate_map.replicate(coordmap, n, concataxis='concat')

Create a CoordinateMap by taking the product of coordmap with a 1-dimensional ‘concat’ CoordinateSystem

Parameters:
coordmap : CoordinateMap

The coordmap to be used

n : int

The number of tiems to concatenate the coordmap

concataxis : string

The name of the new dimension formed by concatenation