Visualization

ants.plot(image, overlay=None, blend=False, alpha=1, cmap='Greys_r', overlay_cmap='turbo', overlay_alpha=0.9, vminol=None, vmaxol=None, cbar=False, cbar_length=0.8, cbar_dx=0.0, cbar_vertical=True, axis=0, nslices=12, slices=None, ncol=None, slice_buffer=None, black_bg=True, bg_thresh_quant=0.01, bg_val_quant=0.99, domain_image_map=None, crop=False, scale=False, reverse=False, title=None, title_fontsize=20, title_dx=0.0, title_dy=0.0, filename=None, dpi=500, figsize=1.5, reorient=True, resample=True)

Plot an ANTsImage.

Use mask_image and/or threshold_image to preprocess images to be be overlaid and display the overlays in a given range. See the wiki examples.

By default, images will be reoriented to ‘LAI’ orientation before plotting. So, if axis == 0, the images will be ordered from the left side of the brain to the right side of the brain. If axis == 1, the images will be ordered from the anterior (front) of the brain to the posterior (back) of the brain. And if axis == 2, the images will be ordered from the inferior (bottom) of the brain to the superior (top) of the brain.

ANTsR function: plot.antsImage

Parameters:

• image (ANTsImage) – image to plot

• overlay (ANTsImage) – image to overlay on base image

• cmap (string) – colormap to use for base image. See matplotlib.

• overlay_cmap (string) – colormap to use for overlay images, if applicable. See matplotlib.

• overlay_alpha (float) – level of transparency for any overlays. Smaller value means the overlay is more transparent. See matplotlib.

• axis (python:integer) – which axis to plot along if image is 3D

• nslices (python:integer) – number of slices to plot if image is 3D

• slices (list or tuple of python:integers) – specific slice indices to plot if image is 3D. If given, this will override nslices. This can be absolute array indices (e.g. (80,100,120)), or this can be relative array indices (e.g. (0.4,0.5,0.6))

• ncol (python:integer) – Number of columns to have on the plot if image is 3D.

• slice_buffer (python:integer) – how many slices to buffer when finding the non-zero slices of a 3D images. So, if slice_buffer = 10, then the first slice in a 3D image will be the first non-zero slice index plus 10 more slices.

• black_bg (boolean) –

  if True, the background of the image(s) will be black. if False, the background of the image(s) will be determined by the

  values bg_thresh_quant and bg_val_quant.

• bg_thresh_quant (float) –

  if white_bg=True, the background will be determined by thresholding the image at the bg_thresh quantile value and setting the background intensity to the bg_val quantile value. This value should be in [0, 1] - somewhere around 0.01 is recommended.

  • equal to 1 will threshold the entire image

  • equal to 0 will threshold none of the image

• bg_val_quant (float) –

  if white_bg=True, the background will be determined by thresholding the image at the bg_thresh quantile value and setting the background intensity to the bg_val quantile value. This value should be in [0, 1]

  • equal to 1 is pure white

  • equal to 0 is pure black

  • somewhere in between is gray

• domain_image_map (ANTsImage) – this input ANTsImage or list of ANTsImage types contains a reference image domain_image and optional reference mapping named domainMap. If supplied, the image(s) to be plotted will be mapped to the domain image space before plotting - useful for non-standard image orientations.

• crop (boolean) – if true, the image(s) will be cropped to their bounding boxes, resulting in a potentially smaller image size. if false, the image(s) will not be cropped

• scale (boolean or 2-tuple) – if true, nothing will happen to intensities of image(s) and overlay(s) if false, dynamic range will be maximized when visualizing overlays if 2-tuple, the image will be dynamically scaled between these quantiles

• reverse (boolean) – if true, the order in which the slices are plotted will be reversed. This is useful if you want to plot from the front of the brain first to the back of the brain, or vice-versa

• title (string) – add a title to the plot

• filename (string) – if given, the resulting image will be saved to this file

• dpi (python:integer) – determines resolution of image if saved to file. Higher values result in higher resolution images, but at a cost of having a larger file size

• resample (bool) – if true, resample image if spacing is very unbalanced.

Example

>>> import ants
>>> import numpy as np
>>> img = ants.image_read(ants.get_data('r16'))
>>> segs = img.kmeans_segmentation(k=3)['segmentation']
>>> ants.plot(img, segs*(segs==1), crop=True)
>>> ants.plot(img, segs*(segs==1), crop=False)
>>> mni = ants.image_read(ants.get_data('mni'))
>>> segs = mni.kmeans_segmentation(k=3)['segmentation']
>>> ants.plot(mni, segs*(segs==1), crop=False)

ants.surf(x, y=None, z=None, quantlimits=(0.1, 0.9), colormap='jet', grayscale=0.7, bg_grayscale=0.9, alpha=None, inflation_factor=0, tol=0.03, smoothing_sigma=0.0, rotation_params=(90, 0, 270), overlay_limits=None, filename=None, verbose=False)

Render a function onto a surface.

ANTsR function: antsrSurf

NOTE: the ANTsPy version of this function does NOT make a function call to ANTs, unlike the ANTsR version, so you don’t have to worry about paths.

Parameters:

• x (ANTsImage) – input image defining the surface on which to render

• y (ANTsImage) – input image list defining the function to render on the surface. these image(s) should be in the same space as x.

• z (ANTsImage) – input image list mask for each y function to render on the surface. these image(s) should be in the same space as y.

• quantlimits (tuple/list) – lower and upper quantile limits for overlay

• colormap (string) – one of: grey, red, green, blue, copper, jet, hsv, spring, summer, autumn, winter, hot, cool, overunder, custom

• alpha (scalar) – transparency vector for underlay and each overlay, default zero

• inflation_factor (python:integer) – number of inflation iterations to run

• tol (float) – error tolerance for surface reconstruction. Smaller values will lead to better surfaces, at the cost of taking longer. Try decreasing this value if your surfaces look very block-y.

• smoothing_sigma (scalar) – gaussian smooth the overlay by this sigma

• rotation_params (tuple/list/ndarray) – 3 Rotation angles expressed in degrees or a matrix of rotation parameters that will be applied in sequence.

• overlay_limits (tuple (optional)) – absolute lower and upper limits for functional overlay. this parameter will override quantlimits. Currently, this will set levels above overlayLimits[2] to overlayLimits[1]. Can be a list of length of y.

• filename (string) – prefix filename for output pngs

• verbose (boolean) – prints the command used to call antsSurf

Return type:

N/A

Example

>>> import ants
>>> ch2i = ants.image_read( ants.get_ants_data("ch2") )
>>> ch2seg = ants.threshold_image( ch2i, "Otsu", 3 )
>>> wm   = ants.threshold_image( ch2seg, 3, 3 )
>>> wm2 = wm.smooth_image( 1 ).threshold_image( 0.5, 1e15 )
>>> kimg = ants.weingarten_image_curvature( ch2i, 1.5  ).smooth_image( 1 )
>>> wmz = wm2.iMath("MD",3)
>>> rp = [(90,180,90), (90,180,270), (90,180,180)]
>>> ants.surf( x=wm2, y=[kimg], z=[wmz],
            inflation_factor=255, overlay_limits=(-0.3,0.3), verbose = True,
            rotation_params = rp, filename='/users/ncullen/desktop/surface.png')

ants.vol(volume, overlays=None, quantlimits=(0.1, 0.9), colormap='jet', rotation_params=(90, 0, 270), overlay_limits=None, magnification_factor=1.0, intensity_truncation=(0.0, 1.0), filename=None, verbose=False)

Render an ANTsImage as a volume with optional ANTsImage functional overlay. This function is beautiful, and runs very fast. It requires VTK.

ANTsR function: antsrVol

NOTE: the ANTsPy version of this function does NOT make a function call to ANTs, unlike the ANTsR version, so you don’t have to worry about paths.

Parameters:

• volume (ANTsImage) – base volume to render

• overlay (list of ANTsImages) – functional overlay to render on the volume image. These images should be in the same space

• colormap (string) –

  possible values:

  grey, red, green, blue, copper, jet, hsv, spring, summer, autumn, winter, hot, cool, overunder, custom

• rotation_params (tuple or collection of tuples or np.ndarray w/ shape (N,3)) –

  rotation parameters to render. The final image will be a stitch of each image from the given rotation params. e.g. if rotation_params = [(90,90,90),(180,180,180)], then the final

  stiched image will have 2 brain renderings at those angles

• overlay_limts –

• magnification_factor (float) – how much to zoom in on the image before rendering. If the stitched images are too far apart, try increasing this value. If the brain volume gets cut off in the image, try decreasing this value

• intensity_truncation (2-tuple of float) – percentile to truncate intensity of overlay

• filename (string) – final filename to which the final rendered volume stitch image will be saved this will always be a .png file

• verbose (boolean) – whether to print updates during rendering

Returns:

• - a numpy array representing the final stitched image.

• Effects

• ——-

• - saves a few png files to disk

Example

>>> import ants
>>> ch2i = ants.image_read( ants.get_ants_data("mni") )
>>> ch2seg = ants.threshold_image( ch2i, "Otsu", 3 )
>>> wm   = ants.threshold_image( ch2seg, 2, 2 )
>>> kimg = ants.weingarten_image_curvature( ch2i, 1.5  ).smooth_image( 1 )
>>> rp = [(90,180,90), (90,180,270), (90,180,180)]
>>> result = ants.vol( wm, [kimg], quantlimits=(0.01,0.99), filename='/users/ncullen/desktop/voltest.png')

ants.render_surface_function(surfimg, funcimg=None, alphasurf=0.2, alphafunc=1.0, isosurf=0.5, isofunc=0.5, smoothsurf=None, smoothfunc=None, cmapsurf='grey', cmapfunc='red', filename=None, notebook=False, auto_open=False)

Render an image as a base surface and an optional collection of other image.

ANTsR function: renderSurfaceFunction

NOTE: The ANTsPy version of this function is actually completely different than the ANTsR version, although they should produce similar results.

Parameters:

• surfimg (ANTsImage) – Input image to use as rendering substrate.

• funcimg (ANTsImage) – Input list of images to use as functional overlays.

• alphasurf (scalar) – alpha for the surface contour

• alphafunc (scalar) – alpha value for functional blobs

• isosurf (scalar) – intensity level that defines lower threshold for surface image

• isofunc (scalar) – intensity level that defines lower threshold for functional image

• smoothsurf (scalar (optional)) – smoothing for the surface image

• smoothfunc (scalar (optional)) – smoothing for the functional image

• cmapsurf (string) – color map for surface image

• cmapfunc (string) – color map for functional image

• filename (string) – where to save rendering. if None, will plot interactively

• notebook (boolean) – whether you’re in a jupyter notebook.

Return type:

N/A

Example

>>> import ants
>>> mni = ants.image_read(ants.get_ants_data('mni'))
>>> mnia = ants.image_read(ants.get_ants_data('mnia'))
>>> ants.render_surface_function(mni, mnia, alphasurf=0.1, filename='/users/ncullen/desktop/surffnc.png')