The ANTsPy library wraps the well-established C++ biomedical image processing framework ANTs. It includes blazing-fast reading and writing of medical images, algorithms for registration, segmentation, and statistical learning, as well as functions to create publication-ready visualizations.
If you are looking to train deep learning models on medical imaging datasets, you might be interested in ANTsPyNet which provides tools for training and visualizing deep learning models.
The easiest way to install ANTsPy is via the latest pre-compiled binaries from PyPI.
pip install antspyx
Because of limited storage space, pip binaries are not available for every combination of python version and platform. If we do not have releases for your platform on PyPI, you can check the Releases page for archived binaries.
In some scenarios, it can make sense to build from source. In general, you can build ANTsPy as you would any other Python package.
git clone https://github.com/antsx/antspy
cd antspy
python -m pip install .
Further details about installing ANTsPy or building it from source can be found in the Installation Tutorial.
Here is a basic overview of some of the things you can do with ANTsPy. The main functionality includes reading / writing images, basic and advanced image operations, segmentation, registration, and visualization.
You can read and write images of any format.
import ants
img = ants.image_read('path/to/image.nii.gz')
ants.image_write(img, 'path/to/image.nii.gz')
Printing to the console provides a great deal of metadata information about the image.
print(img)
ANTsImage
Pixel Type : float (float32)
Components : 1
Dimensions : (256, 256)
Spacing : (1.0, 1.0)
Origin : (0.0, 0.0)
Direction : [1. 0. 0. 1.]
Images can be operated on similar to numpy arrays - e.g., all math operations will work as expected.
img = ants.image_read(ants.get_data('r16'))
img2 = ants.image_read(ants.get_data('r64'))
img + img2
img - img2
img * img2
img / img2
img ** 2
You can also index images as you would a numpy array. Where possible, indexing an image will return an image with metadata intact.
img = ants.image_read(ants.get_data('mni')) # 3D image
img[:20,:20,:20] # 3D image
img[:,:,20] # 2D image
img[:,20,20] # 1D array
img[20,20,20] # sigle value
# setting works as well
img[:20,:20,:20] = 10
There is a large collection of advanced image operations that can be performed on images.
img = ants.image_read(ants.get_data('mni')) # 3D image
img = ants.smooth_image(img, 2)
img = ants.resample_image(img, (3,3,3))
img = ants.pad_image(img, pad_width=(4,4,4))
# chaining operations is possible
img = img.smooth_image(2).resample_image((3,3,3)).pad_image(pad_width=(4,4,4))
And if you ever need to convert to or from numpy, it is straight-forward to do so.
img = ants.image_read(ants.get_data('mni')) # 3D image
arr = img.numpy()
arr += 2
img2 = ants.from_numpy(arr)
Atropos is an example of a powerful three-class segmentation algorithm provided to you.
img = ants.image_read(ants.get_data("r16"))
mask = ants.get_mask(img)
result = ants.atropos(a=img, m='[0.2,1x1]', c='[2,0]', i='kmeans[3]', x=mask)
The full registration functionality of ANTs is available via the ants.registration
function.
fixed_image = ants.image_read(ants.get_ants_data('r16')).resample_image((60,60), 1, 0)
moving_image = ants.image_read(ants.get_ants_data('r64')).resample_image((60,60), 1, 0)
mytx = ants.registration(fixed_image, moving_image, type_of_transform = 'SyN' )
A diverse set of functions are available to flexibly visualize images, optionally with discrete or continuous overlays. The ants.plot
function will meet most needs.
img = ants.image_read(ants.get_data("mni")) # 3D image
ants.plot(img)
# with overlay
ants.plot(img, overlay = img > img.mean())
Resources for learning about ANTsPy can be found in the tutorials folder. A selection of especially useful tutorials is presented below.
- Basic overview [Link]
- Composite registrations [Link]
- Multi-metric registration [Link]
- Image math operations [Link]
- Wrapping ITK code [Link]
More tutorials can be found in the ANTs repository.
If you have a question, feature request, or bug report the best way to get help is by posting an issue on the GitHub page. We welcome any new contributions and ideas. If you want to add code, the best way to get started is by reading the contributors guide that runs through the structure of the project and how we go about wrapping ITK and ANTs code in C++.
The main references can be found at the main ANTs repo. A Google Scholar search also reveals plenty of explanation of methods and evaluation results by the community and by ourselves.