ants.atropos(a, x, i='Kmeans[3]', m='[0.2,1x1]', c='[5,0]', priorweight=0.25, **kwargs)[source]

A finite mixture modeling (FMM) segmentation approach with possibilities for specifying prior constraints. These prior constraints include the specification of a prior label image, prior probability images (one for each class), and/or an MRF prior to enforce spatial smoothing of the labels. Similar algorithms include FAST and SPM. atropos can also perform multivariate segmentation if you pass a list of images in: e.g. a=(img1,img2).

ANTsR function: atropos

  • a (ANTsImage or list/tuple of ANTsImage python:types) – One or more scalar images to segment. If priors are not used, the intensities of the first image are used to order the classes in the segmentation output, from lowest to highest intensity. Otherwise the order of the classes is dictated by the order of the prior images.

  • x (ANTsImage) – mask image.

  • i (string) – initialization usually KMeans[N] for N classes or a list of N prior probability images. See Atropos in ANTs for full set of options.

  • m (string) – mrf parameters as a string, usually “[smoothingFactor,radius]” where smoothingFactor determines the amount of smoothing and radius determines the MRF neighborhood, as an ANTs style neighborhood vector eg “1x1x1” for a 3D image. The radius must match the dimensionality of the image, eg 1x1 for 2D and The default in ANTs is smoothingFactor=0.3 and radius=1. See Atropos for more options.

  • c (string) – convergence parameters, “[numberOfIterations,convergenceThreshold]”. A threshold of 0 runs the full numberOfIterations, otherwise Atropos tests convergence by comparing the mean maximum posterior probability over the whole region of interest defined by the mask x.

  • priorweight (scalar) – usually 0 (priors used for initialization only), 0.25 or 0.5.

  • kwargs (keyword arguments) – more parameters, see Atropos help in ANTs


segmentation: ANTsImage

actually segmented image

probabilityimageslist of ANTsImage types

one image for each segmentation class

Return type:

dictionary with the following key/value pairs


>>> import ants
>>> img = ants.image_read(ants.get_ants_data('r16'))
>>> img = ants.resample_image(img, (64,64), 1, 0)
>>> mask = ants.get_mask(img)
>>> ants.atropos( a = img, m = '[0.2,1x1]', c = '[2,0]',  i = 'kmeans[3]', x = mask )
>>> seg2 = ants.atropos( a = img, m = '[0.2,1x1]', c = '[2,0]', i = seg['probabilityimages'], x = mask, priorweight=0.25 )
ants.joint_label_fusion(target_image, target_image_mask, atlas_list, beta=4, rad=2, label_list=None, rho=0.01, usecor=False, r_search=3, nonnegative=False, no_zeroes=False, max_lab_plus_one=False, output_prefix=None, verbose=False)[source]

A multiple atlas voting scheme to customize labels for a new subject. This function will also perform intensity fusion. It almost directly calls the C++ in the ANTs executable so is much faster than other variants in ANTsR.

One may want to normalize image intensities for each input image before passing to this function. If no labels are passed, we do intensity fusion. Note on computation time: the underlying C++ is multithreaded. You can control the number of threads by setting the environment variable ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS e.g. to use all or some of your CPUs. This will improve performance substantially. For instance, on a macbook pro from 2015, 8 cores improves speed by about 4x.

ANTsR function: jointLabelFusion

  • target_image (ANTsImage) – image to be approximated

  • target_image_mask (ANTsImage) – mask with value 1

  • atlas_list (list of ANTsImage python:types) – list containing intensity images

  • beta (scalar) – weight sharpness, default to 2

  • rad (scalar) – neighborhood radius, default to 2

  • label_list (list of ANTsImage python:types (optional)) – list containing images with segmentation labels

  • rho (scalar) – ridge penalty increases robustness to outliers but also makes image converge to average

  • usecor (boolean) – employ correlation as local similarity

  • r_search (scalar) – radius of search, default is 3

  • nonnegative (boolean) – constrain weights to be non-negative

  • no_zeroes (boolean) – this will constrain the solution only to voxels that are always non-zero in the label list

  • max_lab_plus_one (boolean) – this will add max label plus one to the non-zero parts of each label where the target mask is greater than one. NOTE: this will have a side effect of adding to the original label images that are passed to the program. It also guarantees that every position in the labels have some label, rather than none. Ie it guarantees to explicitly parcellate the input data.

  • output_prefix (string) – file prefix for storing output probabilityimages to disk

  • verbose (boolean) – whether to show status updates



segmentation image


intensity image

probabilityimageslist of ANTsImage types

probability map image for each label

segmentation_numberslist of numbers

segmentation label (number, int) for each probability map

Return type:

dictionary w/ following key/value pairs


>>> import ants
>>> ref = ants.image_read( ants.get_ants_data('r16'))
>>> ref = ants.resample_image(ref, (50,50),1,0)
>>> ref = ants.iMath(ref,'Normalize')
>>> mi = ants.image_read( ants.get_ants_data('r27'))
>>> mi2 = ants.image_read( ants.get_ants_data('r30'))
>>> mi3 = ants.image_read( ants.get_ants_data('r62'))
>>> mi4 = ants.image_read( ants.get_ants_data('r64'))
>>> mi5 = ants.image_read( ants.get_ants_data('r85'))
>>> refmask = ants.get_mask(ref)
>>> refmask = ants.iMath(refmask,'ME',2) # just to speed things up
>>> ilist = [mi,mi2,mi3,mi4,mi5]
>>> seglist = [None]*len(ilist)
>>> for i in range(len(ilist)):
>>>     ilist[i] = ants.iMath(ilist[i],'Normalize')
>>>     mytx = ants.registration(fixed=ref , moving=ilist[i] ,
>>>         typeofTransform = ('Affine') )
>>>     mywarpedimage = ants.apply_transforms(fixed=ref,moving=ilist[i],
>>>             transformlist=mytx['fwdtransforms'])
>>>     ilist[i] = mywarpedimage
>>>     seg = ants.threshold_image(ilist[i],'Otsu', 3)
>>>     seglist[i] = ( seg ) + ants.threshold_image( seg, 1, 3 ).morphology( operation='dilate', radius=3 )
>>> r = 2
>>> pp = ants.joint_label_fusion(ref, refmask, ilist, r_search=2,
>>>                     label_list=seglist, rad=[r]*ref.dimension )
>>> pp = ants.joint_label_fusion(ref,refmask,ilist, r_search=2, rad=[r]*ref.dimension)
ants.kelly_kapowski(s, g, w, its=45, r=0.025, m=1.5, gm_label=2, wm_label=3, **kwargs)[source]

Compute cortical thickness using the DiReCT algorithm.

Diffeomorphic registration-based cortical thickness based on probabilistic segmentation of an image. This is an optimization algorithm.

  • s (ANTsimage) – segmentation image

  • g (ANTsImage) – gray matter probability image

  • w (ANTsImage) – white matter probability image

  • its (python:integer) – convergence params - controls iterations

  • r (scalar) – gradient descent update parameter

  • m (scalar) – gradient field smoothing parameter

  • gm_label (python:integer) – label for gray matter in the segmentation image

  • wm_label (python:integer) – label for white matter in the segmentation image

  • kwargs (keyword arguments) – anything else, see KellyKapowski help in ANTs

Return type:



>>> import ants
>>> img = ants.image_read( ants.get_ants_data('r16') ,2)
>>> img = ants.resample_image(img, (64,64),1,0)
>>> mask = ants.get_mask( img )
>>> segs = ants.kmeans_segmentation( img, k=3, kmask = mask)
>>> thick = ants.kelly_kapowski(s=segs['segmentation'], g=segs['probabilityimages'][1],
                                w=segs['probabilityimages'][2], its=45,
                                r=0.5, m=1)
ants.kmeans_segmentation(image, k, kmask=None, mrf=0.1)[source]

K-means image segmentation that is a wrapper around ants.atropos

ANTsR function: kmeansSegmentation

  • image (ANTsImage) – input image

  • k (python:integer) – integer number of classes

  • kmask (ANTsImage (optional)) – segment inside this mask

  • mrf (scalar) – smoothness, higher is smoother

Return type:



>>> import ants
>>> fi = ants.image_read(ants.get_ants_data('r16'), 'float')
>>> fi = ants.n3_bias_field_correction(fi, 2)
>>> seg = ants.kmeans_segmentation(fi, 3)
ants.fuzzy_spatial_cmeans_segmentation(image, mask=None, number_of_clusters=4, m=2, p=1, q=1, radius=2, max_number_of_iterations=20, convergence_threshold=0.02, verbose=False)[source]

Fuzzy spatial c-means for image segmentation.

Image segmentation using fuzzy spatial c-means as described in

Chuang et al., Fuzzy c-means clustering with spatial information for image segmentation. CMIG: 30:9-15, 2006.

  • image (ANTsImage) – Input image.

  • mask (ANTsImage) – Optional mask image.

  • number_of_clusters (python:integer) – Number of segmentation clusters.

  • m (float) – Fuzziness parameter (default=2).

  • p (float) – Membership importance parameter (default=1).

  • q (float) – Spatial constraint importance parameter (default=1). q = 0 is equivalent to conventional fuzzy c-means.

  • radius (python:integer or tuple) – Neighborhood radius (scalar or array) for spatial constraint.

  • max_number_of_iterations (python:integer) – Iteration limit (default=20).

  • convergence_threshold (float) – Convergence between iterations is measured using the Dice coefficient (default=0.02).

  • varbose (boolean) – Print progress.

Return type:

dictionary containing ANTsImage and probability images


>>> import ants
>>> image = ants.image_read(ants.get_ants_data('r16'))
>>> mask = ants.get_mask(image)
>>> fuzzy = ants.fuzzy_spatial_cmeans_segmentation(image, mask, number_of_clusters=3)
ants.label_geometry_measures(label_image, intensity_image=None)[source]

Wrapper for the ANTs funtion labelGeometryMeasures

ANTsR function: labelGeometryMeasures

  • label_image (ANTsImage) – image on which to compute geometry

  • intensity_image (ANTsImage (optional)) – image with intensity values

Return type:



>>> import ants
>>> fi = ants.image_read( ants.get_ants_data('r16') )
>>> seg = ants.kmeans_segmentation( fi, 3 )['segmentation']
>>> geom = ants.label_geometry_measures(seg,fi)
ants.prior_based_segmentation(image, priors, mask, priorweight=0.25, mrf=0.1, iterations=25)[source]

Spatial prior-based image segmentation.

Markov random field regularized, prior-based image segmentation that is a wrapper around atropos (see ANTs and related publications).

ANTsR function: priorBasedSegmentation

  • image (ANTsImage or list/tuple of ANTsImage python:types) – input image or image list for multivariate segmentation

  • priors (list/tuple of ANTsImage python:types) – list of priors that cover the number of classes

  • mask (ANTsImage) – segment inside this mask

  • prior_weight (scalar) – usually 0 (priors used for initialization only), 0.25 or 0.5.

  • mrf (scalar) – regularization, higher is smoother, a numerical value in range 0.0 to 0.2

  • iterations (python:integer) – maximum number of iterations. could be a large value eg 25.


segmentation: ANTsImage

actually segmented image

probabilityimageslist of ANTsImage types

one image for each segmentation class

Return type:

dictionary with the following key/value pairs


>>> import ants
>>> fi = ants.image_read(ants.get_ants_data('r16'))
>>> seg = ants.kmeans_segmentation(fi,3)
>>> mask = ants.threshold_image(seg['segmentation'], 1, 1e15)
>>> priorseg = ants.prior_based_segmentation(fi, seg['probabilityimages'], mask, 0.25, 0.1, 3)