core.image.image

Module: core.image.image

Inheritance diagram for nipy.core.image.image:

This module defines the Image class, as well as two functions that create Image instances.

fromarray : create an Image instance from an ndarray

Classes

Image

class nipy.core.image.image.Image(data, coordmap, metadata={})

Bases: object

The BaseImage class provides the core object type used in nipy. An BaseImage represents a volumetric brain image and provides means for manipulating the image data. Most functions in the image module operate on BaseImage objects.

Notes

Images can be created through the module functions. See nipy.io for image IO such as load and save

Examples

>>> from nipy.core.image import image
>>> from nipy.testing import anatfile
>>> from nipy.io.api import load_image
>>> img = load_image(anatfile)

>>> import numpy as np
>>> img = image.fromarray(np.zeros((21, 64, 64), dtype='int16'),
...                       'kji', 'zxy')

Methods

affine
axes
coordmap
get_data
ndim
reference
renamed_axes
renamed_reference
reordered_axes
reordered_reference
shape

__init__(data, coordmap, metadata={})

Create an Image object from array and CoordinateMap object.

Images are most often created through the module functions load and fromarray.

Parameters:

data : A numpy.ndarray

coordmap : An AffineTransform object

metadata : dictionary

See also

load

load Image from a file

save

save Image to a file

fromarray

create an Image from a numpy array

static affine()

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

>>> 

static shape()

SliceMaker

class nipy.core.image.image.SliceMaker

Bases: object

This class just creates slice objects to be used in resampling images. It only has a __getitem__ method that returns its argument.

XXX Wouldn’t need this if there was a way XXX to do this XXX subsample(img, [::2,::3,10:1:-1]) XXX XXX Could be something like this Subsample(img)[::2,::3,10:1:-1]

__init__()

x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Functions

nipy.core.image.image.fromarray(data, innames, outnames, coordmap=None)

Create an image from a numpy array.

Parameters:

data : numpy array

A numpy array of three dimensions.

innames : sequence

a list of input axis names

innames : sequence

a list of output axis names

coordmap : A CoordinateMap

If not specified, an identity coordinate map is created.

Returns:

image : An Image object

See also

load

function for loading images

save

function for saving images

nipy.core.image.image.is_image(obj)

Returns true if this object obeys the Image API

This allows us to test for something that is duck-typing an image.

For now an array must have a ‘coordmap’ attribute, and a callable ‘__array__’ attribute.

Parameters:

obj : object

object for which to test API

Returns:

is_img : bool

True if object obeys image API

Examples

>>> from nipy.testing import anatfile
>>> from nipy.io.api import load_image
>>> img = load_image(anatfile)
>>> is_image(img)
True
>>> class C(object): pass
>>> c = C()
>>> is_image(c)
False

nipy.core.image.image.rollaxis(img, axis, inverse=False)

Roll the specified axis backwards, until it lies in the first position.

It also reorders the reference coordinates by the same ordering. This is done to preserve a diagonal affine matrix if image.affine is diagonal. It also makes it possible to unambiguously specify an axis to roll along in terms of either a reference name (i.e. ‘z’) or an axis name (i.e. ‘slice’).

Parameters:

img : Image

Image whose axes and reference coordinates are to be reordered by rolling.

axis : str or int

Axis to be rolled, can be specified by name or as an integer.

inverse : bool, optional

If inverse is True, then axis must be an integer and the first axis is returned to the position axis.

Returns:

newimg : An Image with reordered axes and reference coordinates.

>>> data = np.zeros((30,40,50,5)) :

>>> affine_transform = AffineTransform.from_params(‘ijkl’, ‘xyzt’, np.diag([1,2,3,4,1])) :

>>> im = Image(data, affine_transform) :

>>> im_t_first = rollaxis(im, ‘t’) :

>>> np.diag(im_t_first.affine) :

array([ 4., 1., 2., 3., 1.]) :

>>> im_t_first.shape :

(5, 30, 40, 50) :

nipy.core.image.image.subsample(img, slice_object)

Subsample an image.

Parameters:

img: Image :

slice_object: int, slice or [slice] :

An object representing a numpy ‘slice’.

Returns:

img_subsampled: Image :

An Image with data img.get_data()[slice_object] and an appropriately corrected CoordinateMap.

Examples

>>> from nipy.io.api import load_image
>>> from nipy.testing import funcfile
>>> from nipy.core.api import subsample, slice_maker
>>> im = load_image(funcfile)
>>> frame3 = subsample(im, slice_maker[:,:,:,3])
>>> from nipy.testing import funcfile, assert_almost_equal
>>> assert_almost_equal(frame3.get_data(), im.get_data()[:,:,:,3])

nipy.core.image.image.synchronized_order(img, target_img, axes=True, reference=True)

Take an Image, and reorder its reference and axes to match target_img.

Parameters:

img : Image

target_img : Image

axes : bool, optional

If True, synchronize the order of the axes.

reference : bool, optional

If True, synchronize the order of the reference coordinates.

Returns:

newimg : Image

An Image satisfying newimg.axes == target.axes (if axes == True), newimg.reference == target.reference (if reference == True).

Examples

>>> data = np.random.standard_normal((3,4,7,5))
>>> im = Image(data, AffineTransform.from_params('ijkl', 'xyzt', np.diag([1,2,3,4,1])))
>>> im_scrambled = im.reordered_axes('iljk').reordered_reference('txyz')
>>> im == im_scrambled
False
>>> im_unscrambled = synchronized_order(im_scrambled, im)
>>> im == im_unscrambled
True
>>> 

>>> # the images don't have to be the same shape
>>> 
>>> data2 = np.random.standard_normal((3,11,9,4))
>>> im2 = Image(data, AffineTransform.from_params('ijkl', 'xyzt', np.diag([1,2,3,4,1])))
>>> 
>>> im_scrambled2 = im2.reordered_axes('iljk').reordered_reference('xtyz')
>>> im_unscrambled2 = synchronized_order(im_scrambled2, im)
>>> 
>>> print im_unscrambled2.coordmap == im.coordmap
True
>>> 
>>> # or have the same coordmap
>>> 
>>> data3 = np.random.standard_normal((3,11,9,4))
>>> im3 = Image(data3, AffineTransform.from_params('ijkl', 'xyzt', np.diag([1,9,3,-2,1])))
>>> 
>>> im_scrambled3 = im3.reordered_axes('iljk').reordered_reference('xtyz')
>>> im_unscrambled3 = synchronized_order(im_scrambled3, im)
>>> 
>>> print im_unscrambled3.axes == im.axes
True
>>> print im_unscrambled3.reference == im.reference
True
>>> im_unscrambled4 = synchronized_order(im_scrambled3, im, axes=False)
>>> print im_unscrambled4.axes == im.axes
False
>>> print im_unscrambled4.axes == im_scrambled3.axes
True
>>> print im_unscrambled4.reference == im.reference
True