ANTsPy Documentation

ANTsPy provides several specialized segmentation algorithms within the ants module. Depending on your data and requirements, you can use different approaches:

• Atropos: A multi-atlas segmentation tool.
• Joint Label Fusion: Combines multiple segmentations into a single consensus segmentation.
• Kelly Kapowski: A specific segmentation method (likely for brain structures).
• K-means Segmentation: Standard unsupervised clustering-based segmentation.
• Fuzzy Spatial C-means Segmentation: A fuzzy clustering approach that accounts for spatial information.
• Prior-based Segmentation: Uses anatomical priors to guide the segmentation process.

All these functions are accessible via the ants namespace.

ANTsPy uses specific S4 classes to manage complex data structures. Understanding these is essential for interacting with the API correctly:

• antsImage-class: Represents an image.
• antsMatrix-class: An S4 class used to hold an antsMatrix imported from ITK types.
• antsRegion-class: An S4 class used to hold a region of an antsImage.

ANTsPy follows Pythonic naming conventions, diverging from the original ANTsR (R) versions in two main ways:

1. Snake Case: Camel case used in ANTsR is converted to underscore case (e.g., resampleImage becomes resample_image).
2. Namespace usage: Prefixes like ants or antsr are removed from function names because they are accessed via the ants namespace (e.g., antsImageRead becomes ants.image_read).

This example demonstrates the core workflow in ANTsPy, including image I/O, basic arithmetic, advanced processing, NumPy conversion, segmentation, registration, and plotting.

import ants

# read / write images
img = ants.image_read('path/to/image.nii.gz')
ants.image_write(img, 'path/to/image.nii.gz')

# basic operations
img + img2
img - img2
img[:20,:20,:20] # indexing returns an image

# advanced operations
img = ants.smooth_image(img, 2)
img = ants.resample_image(img, (3,3,3))
img.smooth_image(2).resample_image((3,3,3)) # chaining

# convert to or from numpy
arr = img.numpy()
img2 = ants.from_numpy(arr * 2)

# segmentation
result = ants.atropos(a=img, m='[0.2,1x1]', c='[2,0]', i='kmeans[3]', x=ants.get_mask(img))

# registration
result = ants.registration(fixed_image, moving_image, type_of_transform = 'SyN' )

# plotting
ants.plot(img, overlay = img > img.mean())

For active development of the Python codebase, use an 'editable' installation. This allows you to modify Python code without needing to reinstall the package.

Note: This method will not recompile C++ code (ANTsPy, ANTs, or ITK). If you modify C++ files, you must recompile.

git clone https://github.com/ANTsX/ANTsPy.git
cd ANTsPy
pip install -e .

ANTsPy is an optimized and validated medical imaging library for Python. To begin using the library, you can refer to the following resources:

• Installation: Follow the official Installation instructions.
• Examples: Explore ANTsX examples for practical usage patterns.
• Support: Visit the ANTsPy GitHub repository for bug reports, support, and contributions.

Standard Docker builds are tested on Ubuntu Linux (amd64). For cross-platform builds targeting multiple architectures (e.g., amd64, ppc64le, arm64), use docker buildx with QEMU emulation.

# Standard build for amd64
cd ANTsPy
docker build -t antspy:latest .

# Cross-platform build using buildx
# 1. Enable QEMU emulation
docker run --rm --privileged aptman/qus -s -- -p ppc64le aarch64

# 2. Create and use a buildx builder
docker buildx create --name moc_builder --use

# 3. Build for multiple platforms and push
docker buildx build --pull --build-arg j=6 -t dockeruser/antspy:latest --platform linux/amd64,linux/ppc64le,linux/arm64 --push .

# 4. Cleanup
docker buildx rm
docker run --rm --privileged aptman/qus -- -r

You can install ANTsPy by cloning the repository and using pip. You can install the current state of the repository, or target a specific version using a tag or commit hash.

# Option 1: Clone and install locally
git clone https://github.com/ANTsX/ANTsPy.git
cd ANTsPy
pip install .

# Option 2: Install directly via git URL
pip install git+https://github.com/ANTsX/ANTsPy.git

# Option 3: Install a specific version (tag or commit hash)
pip install git+https://github.com/ANTsX/ANTsPy.git@${antspyx_version}

The easiest way to install ANTsPy is using pre-compiled binaries.

Using pip:

pip install antspyx

Using conda:

conda install conda-forge::antspyx

Note for macOS users: If you encounter compatibility issues where pip attempts to compile from source instead of using binaries, you can disable compatibility checks by setting the environment variable SYSTEM_VERSION_COMPAT=0.

Note for Windows users: You must have a compatible Microsoft Visual C++ Redistributable installed.