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
larmorxApache-2.0 validated
- replica
- 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
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):
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
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
--helpPython
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",
) -> ImageWhere 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.
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 Nn_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|reproduceupstream_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.
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')larmorx ants antsApplyTransforms -d 3 -i t1w.nii.gz -r t1w.nii.gz -t identity -n LanczosWindowedSinc -o out.nii.gz --float 1Ports
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,
.h5files 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’sBSplinestage 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: