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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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')