Programs · ANTs and ITK

antsApplyTransforms

antsApplyTransforms resamples an image onto the grid of a reference image through a chain of ITK transforms (linear transforms, displacement fields, B-spline transforms and composites of them), or writes the chain itself as one transform.

Original
ANTs 2.6.5
Command line
larmorx ants antsApplyTransforms
Python
lx.ants.apply_transforms
Ports
  • replica larmorx Apache-2.0 validated
Evidence
every comparison with ANTs
Source
made from docs/api/ants-apply-transforms.md and the code

What it does

Transform outputs says how it writes the chain. fMRIPrep runs it for the masks, references, tissue maps and segmentations it moves to the templates and the T1w, its confounds’ masks and its reports’ images.

Command line

text
larmorx ants antsApplyTransforms ...

Everything after larmorx ants antsApplyTransforms is the original’s command line: the arguments of ANTs 2.6.5’s antsApplyTransforms, as ANTs takes them. LARMORX’s own options stand between larmorx and the family ants, so they never meet the original’s (below):

text
larmorx
        [--n-threads N]
        [--implementation auto|replica|clean-room]
        [--upstream-defects fix|reproduce]
        ants antsApplyTransforms ...

From the next release. In 0.1.0rc1, set the variables instead: OMP_NUM_THREADS, LARMORX_IMPLEMENTATION (original for the clean room) and LARMORX_UPSTREAM_DEFECTS.

antsApplyTransforms's usage text, as the replica prints it
text
COMMAND:
     antsApplyTransforms (larmorx port of ANTs v2.6.5)
          Resamples an image through a chain of transforms onto a reference grid.

OPTIONS:
     -d, --dimensionality 3
     -e, --input-image-type 0/1/2/3/4/5/6
                            scalar/vector/tensor/time-series/multichannel/five-dimensional/physical-vector
                            (larmorx supports scalar and time-series)
     --time-index <index>   extract one volume of a time series
     -i, --input inputFileName
     -r, --reference-image imageFileName
     -o, --output warpedOutputFileName
                  [warpedOutputFileName,0]
     -n, --interpolation Linear
                         NearestNeighbor
                         MultiLabel[<sigma=imageSpacing>,<alpha=4.0>]
                         Gaussian[<sigma=imageSpacing>,<alpha=1.0>]
                         BSpline[<order=3>]
                         CosineWindowedSinc
                         WelchWindowedSinc
                         HammingWindowedSinc
                         LanczosWindowedSinc
                         GenericLabel[<interpolator=Linear>]
     -u, --output-data-type char/uchar/short/int/float/double/default
     -t, --transform transformFileName
                     [transformFileName,useInverse]
     -f, --default-value value
     --float 0/1
     -v, --verbose (0)/1
     -h
     --help

Python

python
lx.ants.apply_transforms(
    image: Any,
    reference: Any,
    transforms: TransformLike | Sequence[TransformLike] = (),
    *,
    invert: Sequence[bool] | None = None,
    interpolation: str = "linear",
    sigma: float | Sequence[float] | None = None,
    alpha: float | None = None,
    order: int = 3,
    time_series: bool | None = None,
    default_value: float = 0.0,
    dtype: Any = None,
    precision: Precision = "float64",
    n_threads: int = 1,
    upstream_defects: UpstreamDefectsName = "fix",
) -> Image

Where Precision is one of "float64", "float32"; UpstreamDefectsName is one of "fix", "reproduce".

Resample image onto the grid of reference through transforms (antsApplyTransforms).

Resamples image onto the grid of reference. Returns an lx.Image: float64 data (float32 with precision="float32") on the reference grid, plus a time axis for a series.

Precision. precision="float64" (the default) computes in double, as ANTs does by default; precision="float32" computes in single precision exactly as antsApplyTransforms --float 1 does: the image is read as float32, transform files are read as ITK’s float reader reads them (a text file’s numbers rounded once to float), points, transform arithmetic and continuous indices are float, and the result is float32. What is float and what stays double, step by step: ants-float.md.

Transform order. As with -t, for each point of the output grid the first transform acts first. So [warp, affine] maps an output point x to affine(warp(x)). Equivalently, the image moves by the affine first, then the warp; that is ANTs’ “last transform is applied first”. apply_transforms_to_points maps points the same way.

Files and in-memory images. Paths are read as ITK reads them: ITK’s choice between qform and sform, and ITK’s rescaling of scaled integer data through float32. This is what makes the output match ANTs bit for bit. lx.Image objects, nibabel images and (array, affine) pairs are placed by their affine.

python
import larmorx as lx

# fMRIPrep's T1w → MNI (an .h5 composite: affine + warp), onto the 2 mm template grid
mni = lx.ants.apply_transforms(
    "sub-01_desc-preproc_T1w.nii.gz",
    "tpl-MNI152NLin2009cAsym_res-02_T1w.nii.gz",
    ["sub-01_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5"],
    interpolation="lanczos",
    n_threads=8,
)
mni.save("sub-01_space-MNI_T1w.nii.gz")

# A 4D BOLD series into T1w space, labels with GenericLabel
bold_t1 = lx.ants.apply_transforms(bold_path, t1w_path, [xfm_txt], interpolation="lanczos")
aseg = lx.ants.apply_transforms(aseg_path, boldref_path, [xfm_txt], interpolation="genericlabel", dtype="int16")

Its result, Image, holds a voxel array placed in world space by an affine.

Field Type What it holds
data np.ndarray
affine np.ndarray
header NiftiHeader | None
implementation Implementation | None

Options

Each row joins an option of the original’s command line with the Python argument that does the same. The rows are checked against the code at every test run: the options antsApplyTransforms accepts (crates/larmorx-ants/src/cli/apply_transforms.rs) and the arguments of lx.ants.apply_transforms (python/larmorx/ants/apply_transforms.py), whose defaults and descriptions are taken from it. Under each option, in grey, ANTs’s own help for it.

ANTs option Python Default Notes
-d 3, --dimensionality – 3D only for now
-i file, --input image path, lx.Image, nibabel image or (array, affine)
-r file, --reference-image reference only its grid is used
-o file, --output the result the returned image (its .save(path) writes it)
-o Linear[file,<invert=0>] (another function) lx.ants.combine_transforms(..., output="linear", invert_linear=...): Transform outputs
-o CompositeTransform[file] (another function) lx.ants.combine_transforms(..., output="composite"): Transform outputs
-o DisplacementField[file], -o [file,1] (another function) lx.ants.combine_transforms(..., output="displacement_field", reference=...): Transform outputs
-t file / -t [file,1], --transform transforms=[file], invert=[True] transforms=(), invert=None files or lx.transforms.read(...) lists: linear transforms, displacement fields, B-spline transforms (BSplineTransform_double_3_3, _float_3_3, as antsRegistration’s BSpline stage writes them) and composites of them; linear transforms only can be inverted (a field or a B-spline transform has no inverse: [file,1] fails, as in ANTs). Nothing is inverted by default, unlike ANTsPy, which inverts the first of [.mat, warp]
-t identity transforms=() () Transform files (.mat, .txt, .h5, warp .nii.gz; B-spline transforms included, as antsRegistration’s BSpline stage writes them) or ItkTransform lists, in -t order: for each point of the output grid the first transform is applied first, so [warp, affine] moves the image by the affine, then the warp, as -t warp -t affine does.
-n Linear, --interpolation interpolation="linear" "linear" default
-n NearestNeighbor interpolation="nearest" "linear" linear, nearest, bspline (order 0–5), gaussian and multilabel (sigma in mm, default the input spacing; alpha in sigmas, default 1 and 4), genericlabel, or a windowed sinc: lanczos, hamming, cosine, welch, blackman. ANTs’ names (LanczosWindowedSinc, …) work too.
-n BSpline[order] interpolation="bspline", order=3 interpolation="linear", order=3 orders 0–5
-n Gaussian[sigma,alpha] interpolation="gaussian", sigma=, alpha= interpolation="linear", sigma=None, alpha=None sigma in mm (one value or three); defaults: input spacing, 1
-n MultiLabel[sigma,alpha] interpolation="multilabel", sigma=, alpha= interpolation="linear", sigma=None, alpha=None alpha default 4 (ANTs ignores the command line’s, ANTS-33 in Upstream defects)
-n GenericLabel[Linear] interpolation="genericlabel" "linear" GenericLabel[NearestNeighbor] interpolates each label’s mask by nearest neighbour (ANTs ignores the parameter, ANTS-33)
-n LanczosWindowedSinc (and Cosine, Hamming, Welch, Blackman) interpolation="lanczos", "cosine", "hamming", "welch", "blackman" "linear" ANTs’ names are accepted too
-e 0 / -e 3, --input-image-type time_series=None/False/True None 4D images are resampled volume by volume by default; False with 4D is an error, as -e 0 is
--time-index t image.data[..., t]
-f value, --default-value default_value= 0.0 value outside the input
-u type, --output-data-type dtype= None char, uchar, short, int, float, double; default: the computation type (float64, or float32 with precision="float32"). Integers truncate toward zero; out-of-range values clamp (ANTs wraps them, ANTS-06 in Upstream defects; finding)
--float 1 precision="float32" "float64" single precision exactly as ANTs computes it (finding); --float 0 is "float64", the default
-z, --static-cast-for-R (command line only) accepted; it changes nothing the port writes
-v 1, --verbose –
-h, --help (command line only) ANTs’ help
ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS (or NSLOTS, as ITK reads them) n_threads=1 (0 = all CPUs) 1 the result does not depend on it
LARMORX_UPSTREAM_DEFECTS upstream_defects "fix" fix (default) or reproduce (Upstream defects)

LARMORX’s own options

From the next release. In 0.1.0rc1, set the variables instead: OMP_NUM_THREADS, LARMORX_IMPLEMENTATION (original for the clean room) and LARMORX_UPSTREAM_DEFECTS.

They stand between larmorx and ants on the command line (larmorx --n-threads 4 ants antsApplyTransforms ...); lx.ants.apply_transforms takes n_threads and upstream_defects as arguments, and the other is the command line’s only. Each one given wins over its environment variable, which keeps working.

Command line, then Python What it does
--n-threads N
n_threads=1
Worker threads (0 = all). The result does not depend on it. Default: every logical CPU on the command line (0), 1 in Python. The variable OMP_NUM_THREADS in 0.1.0rc1.
--implementation auto|replica|clean-room
(no Python argument)
The command line’s only: lx.ants.apply_transforms takes no implementation. The variable LARMORX_IMPLEMENTATION in 0.1.0rc1.
--upstream-defects fix|reproduce
upstream_defects="fix"
"fix" (the default) corrects ITK’s and ANTs’ defects: the floor of indices just below an integer (ITK-01), versors that fail to load in single precision (ITK-10), the dtype cast (ANTS-06); "reproduce" gives ANTs’ result, MultiLabel’s alpha ignored as ANTs ignores it (ANTS-33). An UpstreamDefectWarning names each defect that changed the result (docs/api/upstream-defects.md). The variable LARMORX_UPSTREAM_DEFECTS in 0.1.0rc1.

Examples

The tests run every example below (validation/tests/test_reference.py), each section in a new folder where these inputs are made first: t1w.nii.gz (a synthetic head of 40 × 48 × 40 voxels of 4 mm). The command lines run as python -m larmorx.

python
import larmorx as lx

# No transform (the identity), Lanczos interpolation, onto the image's own grid.
out = lx.ants.apply_transforms("t1w.nii.gz", "t1w.nii.gz", interpolation="lanczos")
out.data.dtype  # -> dtype('float64')
bash
larmorx ants antsApplyTransforms -d 3 -i t1w.nii.gz -r t1w.nii.gz -t identity -n LanczosWindowedSinc -o out.nii.gz --float 1

Ports

antsApplyTransforms has one port: a replica.

Port Package Licence Status Records
replica larmorx (built in) Apache-2.0 validated ants-apply-transforms

The replica: status validated against antsApplyTransforms itself (its record, 2026-10-22). The record covers 258 cases:

  • every interpolator;
  • every transform type and file format, .h5 files written by ITK (linear, inverted, float, six types in one composite, a dense group of nine affines, a float field) and by larmorx included, and B-spline transforms (antsRegistration’s BSpline stage output, A5 part 3: text, MATLAB and HDF5 files, float coefficients, inside composites and chains, the inverse refused);
  • awkward geometries, output types and time series;
  • real fMRIPrep derivatives;
  • all of them again with --float 1, ANTs’ single-precision pipeline;
  • the transform outputs, every form and format, and the errors around them.

All 258 agree (20 of them errors both programs report; 4 expected divergences, where ANTs crashes and larmorx refuses, ANTS-48). Of the 200 resampling cases compared, 185 are byte-identical to the unmodified ANTs program, among them all 102 --float 1 cases; the other 15 (two of them through fMRIPrep’s .h5 composite, one through a B-spline transform with Lanczos) differ only where ITK calls the platform’s exp, log, sin or cos (Gaussian and windowed sinc in double), by at most about 1e-15 relative (why). With correctly rounded maths preloaded into ANTs, all 200 are byte-identical. The 40 cases of B-spline transforms (A5 part 3: text, MATLAB and HDF5 files, float coefficients, composites, chains, interpolators, time series, --float 1, the transform outputs, and the inverses both programs refuse) all agree. The 46 transform-output cases (-o Linear[...], -o CompositeTransform[...], -o DisplacementField[...]) write ANTs’s files: text and MATLAB byte for byte, NIfTI fields bit for bit, HDF5 dataset for dataset. All 14 of fMRIPrep’s --float 1 outputs in the ds000005 oracle run are byte-identical to fMRIPrep’s own (stage record). Compared with ANTs’ defects reproduced (LARMORX_UPSTREAM_DEFECTS=reproduce); the record’s “D13 fix pass” lists what larmorx’s default changes.

On the data panel (record, 2026-10-26): every antsApplyTransforms node of the fourteen finished fMRIPrep oracle runs, each replayed from its own command line with its inputs (421 calls: masks, references, tissue maps and segmentations to the templates and the T1w, the confounds’ masks, the reports’ images; 179 through fMRIPrep’s .h5 composites, 166 with --float 1; Gaussian, MultiLabel, LanczosWindowedSinc, Linear and NearestNeighbor), and four calls fMRIPrep never makes (the 600-volume multiband-8 series to the T1w, the raw 7 T MP2RAGE to MNI, the stroke’s lesion mask to MNI, the 82-year-old’s FLAIR onto its T1w): 425 of 425 bit-identical with CORE-MATH, 329 to the unmodified ANTs, all 167 --float 1 calls among them (the others where ITK calls glibc’s exp, log, sin or cos in double).

antsApplyTransforms has one port, in pip install larmorx: the replica (Rust crates larmorx-ants, larmorx-interp, larmorx-transform, larmorx-io; Apache-2.0), translated from ANTs 2.6.5 on ITK 5.4.5. Its result does not depend on the thread count.

Evidence

How each of antsApplyTransforms’s ports was measured against ANTs, case by case: its evidence.

More in the repository

The API page docs/api/ants-apply-transforms.md holds what antsApplyTransforms shares with the page’s other programs: