Inheritance diagram for nipy.core.image.image:
This module defines the Image class, as well as functions that create Image instances and work on them:
Bases: object
The Image class provides the core object type used in nipy.
An Image represents a volumetric brain image and provides means for manipulating the image data. Most functions in the image module operate on Image 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)
>>> img = image.fromarray(np.zeros((21, 64, 64), dtype='int16'),
... 'kji', 'zxy')
Methods
affine() | |
axes() | |
coordmap | Class for affine transformation from domain to a range |
get_data() | Return data as a numpy array. |
ndim() | |
reference() | |
renamed_axes(**names_dict) | Return a new image with input (domain) axes renamed |
renamed_reference(**names_dict) | Return new image with renamed output (range) coordinates |
reordered_axes([order]) | Return a new Image with reordered input coordinates. |
reordered_reference([order]) | Return new Image with reordered output coordinates |
shape() |
Create an Image object from array and CoordinateMap object.
Images are most often created through the module functions load and fromarray.
Parameters : | data : array-like
coordmap : AffineTransform object
metadata : dict
|
---|
See also
Return data as a numpy array.
The file header structure for this image, if available. This interface will soon go away - you should use ``img.metadata[‘header’] instead.
Return a new image with input (domain) axes renamed
Axes renamed according to the input dictionary.
Parameters : | **names_dict : dict
|
---|---|
Returns : | newimg : Image
|
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)
Return new image with renamed output (range) coordinates
Coordinates renamed according to the dictionary
Parameters : | **names_dict : dict
|
---|---|
Returns : | newimg : Image
|
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)
Return a new Image with reordered input coordinates.
This transposes the data as well.
Parameters : | order : None, sequence, optional
|
---|---|
Returns : | r_img : object
|
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.]])
)
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
|
---|---|
Returns : | r_img : object
|
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.]])
)
Bases: object
This class just creates slice objects for image resampling
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]
x.__init__(...) initializes x; see help(type(x)) for signature
Create an image from a numpy array.
Parameters : | data : numpy array
innames : sequence
innames : sequence
coordmap : A CoordinateMap
|
---|---|
Returns : | image : An Image object |
See also
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
|
---|---|
Returns : | is_img : bool
|
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
Return generator to slice an image img over axis
Parameters : | img : Image instance axis : int or str
asarray : {False, True}, optional |
---|---|
Returns : | g : generator
|
Examples
>>> data = np.arange(24).reshape((4,3,2))
>>> img = fromarray(data, 'ijk', 'xyz')
>>> slices = list(iter_axis(img, 'j'))
>>> len(slices)
3
>>> slices[0].shape
(4, 2)
>>> slices = list(iter_axis(img, 'k', asarray=True))
>>> slices[1].sum() == data[:,:,1].sum()
True
Roll 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
axis : str or int
inverse : bool, optional
|
---|---|
Returns : | newimg : Image
|
Examples
>>> 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.coordmap
AffineTransform(
function_domain=CoordinateSystem(coord_names=('i', 'j', 'k', 'l'), name='', coord_dtype=float64),
function_range=CoordinateSystem(coord_names=('x', 'y', 'z', 't'), name='', coord_dtype=float64),
affine=array([[ 1., 0., 0., 0., 0.],
[ 0., 2., 0., 0., 0.],
[ 0., 0., 3., 0., 0.],
[ 0., 0., 0., 4., 0.],
[ 0., 0., 0., 0., 1.]])
)
>>> 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)
>>> im_t_first.coordmap
AffineTransform(
function_domain=CoordinateSystem(coord_names=('l', 'i', 'j', 'k'), name='', coord_dtype=float64),
function_range=CoordinateSystem(coord_names=('t', 'x', 'y', 'z'), name='', coord_dtype=float64),
affine=array([[ 4., 0., 0., 0., 0.],
[ 0., 1., 0., 0., 0.],
[ 0., 0., 2., 0., 0.],
[ 0., 0., 0., 3., 0.],
[ 0., 0., 0., 0., 1.]])
)
Subsample an image
Please don’t use this function, but use direct image slicing instead. That is, replace:
frame3 = subsample(im, slice_maker[:,:,:,3])
with:
frame3 = im[:,:,:,3]
Parameters : | img : Image slice_object: int, slice or sequence of slice :
|
---|---|
Returns : | img_subsampled: Image :
|
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])
>>> np.allclose(frame3.get_data(), im.get_data()[:,:,:,3])
True
Reorder reference and axes of img to match target_img.
Parameters : | img : Image target_img : Image axes : bool, optional
reference : bool, optional
|
---|---|
Returns : | newimg : Image
|
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)
>>>
>>> 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)
>>> im_unscrambled3.axes == im.axes
True
>>> im_unscrambled3.reference == im.reference
True
>>> im_unscrambled4 = synchronized_order(im_scrambled3, im, axes=False)
>>> im_unscrambled4.axes == im.axes
False
>>> im_unscrambled4.axes == im_scrambled3.axes
True
>>> im_unscrambled4.reference == im.reference
True