This guide details how to configure the cluster-installed version of ANTs in your user environment and how to use antsApplyTransforms to map images and atlases between spatial reference domains (e.g., native T1w space and MNI space).
1. System Installation Details
An updated build of ANTs (v2.5 equivalent, compiled with ITK v6 support) is available centrally on the cluster.
-
Installation Directory:
/lab_data/hawk/ANTs_v20261014/install/bin/ -
Version:
2.6.5(Compiled with ITK v6)
2. Environment Setup
ANTs is compiled C++ software and runs directly without requiring a Python or Conda environment. Add the binary path directly to your environment variables.
Add ANTs to your ~/.bashrc
Run the following commands in your cluster terminal:
Bash
echo 'export ANTSPATH=/lab_data/hawk/ANTs_v20261014/install/bin/' >> ~/.bashrc
echo 'export PATH=${ANTSPATH}:$PATH' >> ~/.bashrc
source ~/.bashrc
Verify the Installation
Confirm that the executable is correctly resolved in your PATH:
Bash
which antsRegistration
Expected Output:
Plaintext
/lab_data/hawk/ANTs_v20261014/install/bin/antsRegistration
3. Applying Transforms with antsApplyTransforms
Pipelines such as fMRIPrep generate spatial transformation files (.h5 or .txt) during preprocessing. You can use antsApplyTransforms to warp images or structural/functional atlases between spaces.
Basic Command Syntax
Bash
antsApplyTransforms \
--dimensionality 3 \
--input /path/to/input_atlas.nii.gz \
--reference-image /path/to/MNI_reference.nii.gz \
--output /path/to/output_atlas_in_MNI.nii.gz \
--transform /path/to/transform.h5 \
--interpolation GenericLabel
Key Parameter Definitions
-
--dimensionality 3: Specifies 3D image processing. -
--input: The source image or atlas you wish to transform. -
--reference-image: The target space image that defines the output grid, dimensions, and resolution (e.g., MNI template reference). -
--output: The output path for the transformed NIfTI file. -
--transform: The composite transformation matrix produced by registration pipelines (e.g., fMRIPrepfrom-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5).
4. Interpolation Guidelines
Choosing the correct interpolation mode is critical to prevent data distortion:
| Image Type | Recommended Interpolation | Reason |
| Discrete Atlases & Label Masks | GenericLabel or NearestNeighbor |
Prevents creation of non-existent label IDs (averaging) between integer region indices. |
| Continuous Structural / Functional Scans | Linear or BSpline |
Smoothly interpolates continuous voxel intensities (T1w, T2w, fMRI BOLD). |
5. Applying Inverse Transformations
To map an atlas or mask in reverse (e.g., transforming an atlas from MNI standard space back into native T1w space), invoke the inverse transform syntax by appending ,1 inside single quotes:
Bash
antsApplyTransforms \
--dimensionality 3 \
--input /lab_data/hawk/resources/neuroimaging/atlases/glasser/HCP-MMP1_on_MNI152NLin2009cAsym.nii.gz \
--reference-image /path/to/sub-01_T1w.nii.gz \
--output /path/to/sub-01_glasser_in_native.nii.gz \
--transform '[/path/to/from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5,1]' \
--interpolation GenericLabel
Note: Inverse transformations require a composite transform file that supports inversion. Ensure the transform direction matches your source and target spaces.