Core

Images

ANTsImage

class ants.core.ants_image.ANTsImage(pixeltype='float', dimension=3, components=1, pointer=None, is_rgb=False, label_image=None)[source]
abs(axis=None)[source]

Return absolute value of image

apply(fn)[source]

Apply an arbitrary function to ANTsImage.

Parameters:

fn (python function or lambda) – function to apply to ENTIRE image at once

Returns:

image with function applied to it

Return type:

ANTsImage

argmax(axis=None)[source]

Return argmax along specified axis

argmin(axis=None)[source]

Return argmin along specified axis

argrange(axis=None)[source]

Return argrange along specified axis

astype(dtype)[source]

Cast & clone an ANTsImage to a given numpy datatype.

Map:

uint8 : unsigned char uint32 : unsigned int float32 : float float64 : double

clone(pixeltype=None)[source]

Create a copy of the given ANTsImage with the same data and info, possibly with a different data type for the image data. Only supports casting to uint8 (unsigned char), uint32 (unsigned int), float32 (float), and float64 (double)

Parameters:

dtype (string (optional)) –

if None, the dtype will be the same as the cloned ANTsImage. Otherwise, the data will be cast to this type. This can be a numpy type or an ITK type. Options:

’unsigned char’ or ‘uint8’, ‘unsigned int’ or ‘uint32’, ‘float’ or ‘float32’, ‘double’ or ‘float64’

Return type:

ANTsImage

copy(pixeltype=None)

Create a copy of the given ANTsImage with the same data and info, possibly with a different data type for the image data. Only supports casting to uint8 (unsigned char), uint32 (unsigned int), float32 (float), and float64 (double)

Parameters:

dtype (string (optional)) –

if None, the dtype will be the same as the cloned ANTsImage. Otherwise, the data will be cast to this type. This can be a numpy type or an ITK type. Options:

’unsigned char’ or ‘uint8’, ‘unsigned int’ or ‘uint32’, ‘float’ or ‘float32’, ‘double’ or ‘float64’

Return type:

ANTsImage

property direction

Get image direction

Return type:

tuple

flatten()[source]

Flatten image data

max(axis=None)[source]

Return max along specified axis

mean(axis=None)[source]

Return mean along specified axis

median(axis=None)[source]

Return median along specified axis

min(axis=None)[source]

Return min along specified axis

new_image_like(data)[source]

Create a new ANTsImage with the same header information, but with a new image array.

Parameters:

data (ndarray or py::capsule) – New array or pointer for the image. It must have the same shape as the current image data.

Return type:

ANTsImage

nonzero()[source]

Return non-zero indices of image

numpy(single_components=False)[source]

Get a numpy array copy representing the underlying image data. Altering this ndarray will have NO effect on the underlying image data.

Parameters:

single_components (boolean (default is False)) – if True, keep the extra component dimension in returned array even if image only has one component (i.e. self.has_components == False)

Return type:

ndarray

property origin

Get image origin

Return type:

tuple

range(axis=None)[source]

Return range tuple along specified axis

set_direction(new_direction)[source]

Set image direction

Parameters:

new_direction (numpy.ndarray or tuple or list) – updated direction for the image. should have one value for each dimension

Return type:

None

set_origin(new_origin)[source]

Set image origin

Parameters:

new_origin (tuple or list) – updated origin for the image. should have one value for each dimension

Return type:

None

set_spacing(new_spacing)[source]

Set image spacing

Parameters:

new_spacing (tuple or list) – updated spacing for the image. should have one value for each dimension

Return type:

None

property spacing

Get image spacing

Return type:

tuple

std(axis=None)[source]

Return std along specified axis

sum(axis=None, keepdims=False)[source]

Return sum along specified axis

to_file(filename)[source]

Write the ANTsImage to file

Parameters:

filename (string) – filepath to which the image will be written

to_filename(filename)

Write the ANTsImage to file

Parameters:

filename (string) – filepath to which the image will be written

unique(sort=False)[source]

Return unique set of values in image

view(single_components=False)[source]

Geet a numpy array providing direct, shared access to the image data. IMPORTANT: If you alter the view, then the underlying image data will also be altered.

Parameters:

single_components (boolean (default is False)) – if True, keep the extra component dimension in returned array even if image only has one component (i.e. self.has_components == False)

Return type:

ndarray

ANTsImage IO

ants.image_clone(image, pixeltype=None)[source]

Clone an ANTsImage

ANTsR function: antsImageClone

Parameters:

  • image (ANTsImage) – image to clone

  • dtype (string (optional)) – new datatype for image

Return type:

ANTsImage

ants.image_header_info(filename)[source]

Read file info from image header

ANTsR function: antsImageHeaderInfo

Parameters:

filename (string) – name of image file from which info will be read

Return type:

dict

ants.image_read(filename, dimension=None, pixeltype='float', reorient=False)[source]

Read an ANTsImage from file

ANTsR function: antsImageRead

Parameters:

  • filename (string) – Name of the file to read the image from.

  • dimension (int) – Number of dimensions of the image read. This need not be the same as the dimensions of the image in the file. Allowed values: 2, 3, 4. If not provided, the dimension is obtained from the image file

  • pixeltype (string) – C++ datatype to be used to represent the pixels read. This datatype need not be the same as the datatype used in the file. Options: unsigned char, unsigned int, float, double

  • reorient (boolean | string) –

    if True, the image will be reoriented to RPI if it is 3D if False, nothing will happen if string, this should be the 3-letter orientation to which the

    input image will reoriented if 3D.

    if the image is 2D, this argument is ignored

Return type:

ANTsImage

ants.image_write(image, filename, ri=False)[source]

Write an ANTsImage to file

ANTsR function: antsImageWrite

Parameters:

  • image (ANTsImage) – image to save to file

  • filename (string) – name of file to which image will be saved

  • ri (boolean) –

    if True, return image. This allows for using this function in a pipeline:
    >>> img2 = img.smooth_image(2.).image_write(file1, ri=True).threshold_image(0,20).image_write(file2, ri=True)

    if False, do not return image

ants.make_image(imagesize, voxval=0, spacing=None, origin=None, direction=None, has_components=False, pixeltype='float')[source]

Make an image with given size and voxel value or given a mask and vector

ANTsR function: makeImage

Parameters:

  • shape (tuple/ANTsImage) – input image size or mask

  • voxval (scalar) – input image value or vector, size of mask

  • spacing (tuple/list) – image spatial resolution

  • origin (tuple/list) – image spatial origin

  • direction (list/ndarray) – direction matrix to convert from index to physical space

  • components (boolean) – whether there are components per pixel or not

  • pixeltype (float) – data type of image values

Return type:

ANTsImage

ants.from_numpy(data, origin=None, spacing=None, direction=None, has_components=False, is_rgb=False)[source]

Create an ANTsImage object from a numpy array

ANTsR function: as.antsImage

Parameters:

  • data (ndarray) – image data array

  • origin (tuple/list) – image origin

  • spacing (tuple/list) – image spacing

  • direction (list/ndarray) – image direction

  • has_components (boolean) – whether the image has components

Returns:

image with given data and any given information

Return type:

ANTsImage

ants.matrix_to_images(data_matrix, mask)[source]

Unmasks rows of a matrix and writes as images

ANTsR function: matrixToImages

Parameters:

  • data_matrix (numpy.ndarray) – each row corresponds to an image array should have number of columns equal to non-zero voxels in the mask

  • mask (ANTsImage) – image containing a binary mask. Rows of the matrix are unmasked and written as images. The mask defines the output image space

Return type:

list of ANTsImage types

Example

>>> import ants
>>> img = ants.image_read(ants.get_ants_data('r16'))
>>> msk = ants.get_mask( img )
>>> img2 = ants.image_read(ants.get_ants_data('r16'))
>>> img3 = ants.image_read(ants.get_ants_data('r16'))
>>> mat = ants.image_list_to_matrix([img,img2,img3], msk )
>>> ilist = ants.matrix_to_images( mat, msk )
ants.images_from_matrix(data_matrix, mask)

Unmasks rows of a matrix and writes as images

ANTsR function: matrixToImages

Parameters:

  • data_matrix (numpy.ndarray) – each row corresponds to an image array should have number of columns equal to non-zero voxels in the mask

  • mask (ANTsImage) – image containing a binary mask. Rows of the matrix are unmasked and written as images. The mask defines the output image space

Return type:

list of ANTsImage types

Example

>>> import ants
>>> img = ants.image_read(ants.get_ants_data('r16'))
>>> msk = ants.get_mask( img )
>>> img2 = ants.image_read(ants.get_ants_data('r16'))
>>> img3 = ants.image_read(ants.get_ants_data('r16'))
>>> mat = ants.image_list_to_matrix([img,img2,img3], msk )
>>> ilist = ants.matrix_to_images( mat, msk )
ants.image_list_to_matrix(image_list, mask=None, sigma=None, epsilon=0.5)

Read images into rows of a matrix, given a mask - much faster for large datasets as it is based on C++ implementations.

ANTsR function: imagesToMatrix

Parameters:

  • image_list (list of ANTsImage python:types) – images to convert to ndarray

  • mask (ANTsImage (optional)) – image containing binary mask. voxels in the mask are placed in the matrix

  • sigma (scaler (optional)) – smoothing factor

  • epsilon (scalar) – threshold for mask

Returns:

array with a row for each image shape = (N_IMAGES, N_VOXELS)

Return type:

ndarray

Example

>>> import ants
>>> img = ants.image_read(ants.get_ants_data('r16'))
>>> img2 = ants.image_read(ants.get_ants_data('r16'))
>>> img3 = ants.image_read(ants.get_ants_data('r16'))
>>> mat = ants.image_list_to_matrix([img,img2,img3])
ants.images_to_matrix(image_list, mask=None, sigma=None, epsilon=0.5)[source]

Read images into rows of a matrix, given a mask - much faster for large datasets as it is based on C++ implementations.

ANTsR function: imagesToMatrix

Parameters:

  • image_list (list of ANTsImage python:types) – images to convert to ndarray

  • mask (ANTsImage (optional)) – image containing binary mask. voxels in the mask are placed in the matrix

  • sigma (scaler (optional)) – smoothing factor

  • epsilon (scalar) – threshold for mask

Returns:

array with a row for each image shape = (N_IMAGES, N_VOXELS)

Return type:

ndarray

Example

>>> import ants
>>> img = ants.image_read(ants.get_ants_data('r16'))
>>> img2 = ants.image_read(ants.get_ants_data('r16'))
>>> img3 = ants.image_read(ants.get_ants_data('r16'))
>>> mat = ants.image_list_to_matrix([img,img2,img3])
ants.matrix_from_images(image_list, mask=None, sigma=None, epsilon=0.5)

Read images into rows of a matrix, given a mask - much faster for large datasets as it is based on C++ implementations.

ANTsR function: imagesToMatrix

Parameters:

  • image_list (list of ANTsImage python:types) – images to convert to ndarray

  • mask (ANTsImage (optional)) – image containing binary mask. voxels in the mask are placed in the matrix

  • sigma (scaler (optional)) – smoothing factor

  • epsilon (scalar) – threshold for mask

Returns:

array with a row for each image shape = (N_IMAGES, N_VOXELS)

Return type:

ndarray

Example

>>> import ants
>>> img = ants.image_read(ants.get_ants_data('r16'))
>>> img2 = ants.image_read(ants.get_ants_data('r16'))
>>> img3 = ants.image_read(ants.get_ants_data('r16'))
>>> mat = ants.image_list_to_matrix([img,img2,img3])

Transforms

ANTsTransform

class ants.core.ants_transform.ANTsTransform(precision='float', dimension=3, transform_type='AffineTransform', pointer=None)[source]
apply(data, data_type='point', reference=None, **kwargs)[source]

Apply transform to data

apply_to_image(image, reference=None, interpolation='linear')[source]

Apply transform to an image

Parameters:

  • image (ANTsImage) – image to which the transform will be applied

  • reference (ANTsImage) – target space for transforming image

  • interpolation (string) – type of interpolation to use

Returns:

list

Return type:

transformed vector

apply_to_point(point)[source]

Apply transform to a point

Parameters:

point (list/tuple) – point to which the transform will be applied

Returns:

list

Return type:

transformed point

Example

>>> import ants
>>> tx = ants.new_ants_transform()
>>> params = tx.parameters
>>> tx.set_parameters(params*2)
>>> pt2 = tx.apply_to_point((1,2,3)) # should be (2,4,6)
apply_to_vector(vector)[source]

Apply transform to a vector

Parameters:

vector (list/tuple) – vector to which the transform will be applied

Returns:

list

Return type:

transformed vector

property fixed_parameters

Get parameters of transform

invert()[source]

Invert the transform

property parameters

Get parameters of transform

set_fixed_parameters(parameters)[source]

Set parameters of transform

set_parameters(parameters)[source]

Set parameters of transform

ANTsTransform IO

ants.create_ants_transform(transform_type='AffineTransform', precision='float', dimension=3, matrix=None, offset=None, center=None, translation=None, parameters=None, fixed_parameters=None, displacement_field=None, supported_types=False)[source]

Create and initialize an ANTsTransform

ANTsR function: createAntsrTransform

Parameters:

  • transform_type (string) – type of transform(s)

  • precision (string) – numerical precision

  • dimension (python:integer) – spatial dimension of transform

  • matrix (ndarray) – matrix for linear transforms

  • offset (tuple/list) – offset for linear transforms

  • center (tuple/list) – center for linear transforms

  • translation (tuple/list) – translation for linear transforms

  • parameters (ndarray/list) – array of parameters

  • fixed_parameters (ndarray/list) – array of fixed parameters

  • displacement_field (ANTsImage) – multichannel ANTsImage for non-linear transform

  • supported_types (boolean) – flag that returns array of possible transforms types

Return type:

ANTsTransform or list of ANTsTransform types

Example

>>> import ants
>>> translation = (3,4,5)
>>> tx = ants.create_ants_transform( type='Euler3DTransform', translation=translation )
ants.new_ants_transform(precision='float', dimension=3, transform_type='AffineTransform', parameters=None)[source]

Create a new ANTsTransform

ANTsR function: None

Example

>>> import ants
>>> tx = ants.new_ants_transform()
ants.read_transform(filename, precision='float')[source]

Read a transform from file

ANTsR function: readAntsrTransform

Parameters:

  • filename (string) – filename of transform

  • precision (string) – numerical precision of transform

Return type:

ANTsTransform

Example

>>> import ants
>>> tx = ants.new_ants_transform(dimension=2)
>>> tx.set_parameters((0.9,0,0,1.1,10,11))
>>> ants.write_transform(tx, '~/desktop/tx.mat')
>>> tx2 = ants.read_transform('~/desktop/tx.mat')
ants.write_transform(transform, filename)[source]

Write ANTsTransform to file

ANTsR function: writeAntsrTransform

Parameters:

  • transform (ANTsTransform) – transform to save

  • filename (string) – filename of transform (file extension is “.mat” for affine transforms)

Return type:

N/A

Example

>>> import ants
>>> tx = ants.new_ants_transform(dimension=2)
>>> tx.set_parameters((0.9,0,0,1.1,10,11))
>>> ants.write_transform(tx, '~/desktop/tx.mat')
>>> tx2 = ants.read_transform('~/desktop/tx.mat')
ants.transform_from_displacement_field(field)[source]

Convert deformation field (multiChannel image) to ANTsTransform

ANTsR function: antsrTransformFromDisplacementField

Parameters:

field (ANTsImage) – deformation field as multi-channel ANTsImage

Return type:

ANTsImage

Example

>>> import ants
>>> fi = ants.image_read(ants.get_ants_data('r16') )
>>> mi = ants.image_read(ants.get_ants_data('r64') )
>>> fi = ants.resample_image(fi,(60,60),1,0)
>>> mi = ants.resample_image(mi,(60,60),1,0) # speed up
>>> mytx = ants.registration(fixed=fi, moving=mi, type_of_transform = ('SyN') )
>>> vec = ants.image_read( mytx['fwdtransforms'][0] )
>>> atx = ants.transform_from_displacement_field( vec )

Metrics

ANTsMetric

class ants.core.ants_metric.ANTsImageToImageMetric(metric)[source]

ANTsImageToImageMetric class

set_fixed_image(image)[source]

Set Fixed ANTsImage for metric

set_fixed_mask(image)[source]

Set Fixed ANTsImage Mask for metric

set_moving_image(image)[source]

Set Moving ANTsImage for metric

set_moving_mask(image)[source]

Set Fixed ANTsImage Mask for metric

ANTsMetric IO

ants.new_ants_metric(dimension=3, precision='float', metric_type='MeanSquares')[source]
ants.create_ants_metric(fixed, moving, metric_type='MeanSquares', fixed_mask=None, moving_mask=None, sampling_strategy='regular', sampling_percentage=1)[source]
Parameters:

metric_type (string) –

which metric to use options:

MeanSquares MattesMutualInformation ANTSNeighborhoodCorrelation Correlation Demons JointHistogramMutualInformation

Example

>>> import ants
>>> fixed = ants.image_read(ants.get_ants_data('r16'))
>>> moving = ants.image_read(ants.get_ants_data('r64'))
>>> metric_type = 'Correlation'
>>> metric = ants.create_ants_metric(fixed, moving, metric_type)
ants.supported_metrics()[source]