Programs · ANTs and ITK

antsAI

antsAI finds the linear transform that best aligns two images.

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

What it does

It starts from an initial alignment (centres of mass, principal axes, or the images’ geometric centres or centres of mass alone) and searches from many start points, over rotations about the principal axes and translations on a grid, each start point refined by a few conjugate-gradient iterations, with the Mattes, GC and MI metrics, None/Regular/Random sampling and masks, in 2D and 3D; or it aligns blobs (-b: ANTs’ multi-scale Laplacian-of-Gaussian blob detector, patch correlations, landmark fits; Blob alignment). fMRIPrep runs it in sMRIPrep’s brain extraction and in the BOLD reference’s skull-stripping (init_aff), without blobs.

Command line

text
larmorx ants antsAI ...

Everything after larmorx ants antsAI is the original’s command line: the arguments of ANTs 2.6.5’s antsAI, 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 antsAI ...

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.

Python

python
lx.ants.ai(
    fixed: Any,
    moving: Any,
    *,
    transform: AITransform = "Rigid",
    gradient_step: float = 0.1,
    metric: AIMetric = "Mattes",
    bins: int = 32,
    sampling: Sampling = "None",
    sampling_percentage: float = 1.0,
    align_principal_axes: bool = False,
    blobs: int | tuple[int, int] | None = None,
    search_factor: float = 20.0,
    arc_fraction: float = 1.0,
    translation_search_grid: tuple[float, Sequence[float]] | None = None,
    iterations: int = 0,
    convergence_threshold: float = 1e-6,
    convergence_window: int = 5,
    fixed_mask: Any = None,
    moving_mask: Any = None,
    dimension: int | None = None,
    random_seed: int | None = None,
    n_threads: int = 1,
    upstream_defects: UpstreamDefectsName = "fix",
) -> AIResult

Where AITransform is one of "Rigid", "Affine", "Similarity", "AlignGeometricCenters", "AlignCentersOfMass"; AIMetric is one of "Mattes", "GC", "MI"; Sampling is one of "None", "Regular", "Random"; UpstreamDefectsName is one of "fix", "reproduce".

The linear transform that best aligns moving to fixed, as antsAI (ANTs v2.6.5) finds it.

Returns an AIResult: transform (an ItkTransform, fixed to moving, read back from the file the port writes), start_points, values and best_value (the search’s start points and their metric values) and log (ANTs’ verbose output: Python always runs verbose).

python
import larmorx as lx

res = lx.ants.ai(
    "template.nii.gz", "t1w.nii.gz",
    transform="Affine", gradient_step=0.1,
    metric="Mattes", bins=32, sampling="Regular", sampling_percentage=0.25,
    search_factor=15, arc_fraction=0.1, translation_search_grid=(40, (0, 40, 40)),
    iterations=10, convergence_threshold=1e-6, convergence_window=10,
    fixed_mask="template_mask.nii.gz", random_seed=50495,
)
res.transform            # an ItkTransform (AffineTransform_double_3_3), fixed -> moving
res.start_points, res.best_value, res.values[:3]

Its result, AIResult, holds what ai returns.

Field Type What it holds
transform ItkTransform
start_points int | None
values list[tuple[int, float]]
best_value float | None
log str

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 antsAI accepts (crates/larmorx-ants/src/cli/ai.rs) and the arguments of lx.ants.ai (python/larmorx/ants/initializers.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 2/3, --dimensionality dimension None default: the fixed image’sANTs: “This option forces the image to be treated as a specified-dimensional image. If not specified, we try to infer the dimensionality from the input image.”
-m Mattes[f,m,bins,sampling,p], --metric fixed, moving, metric="Mattes", bins, sampling, sampling_percentage metric="Mattes", bins=32, sampling="None", sampling_percentage=1.0 GC[f,m,radius,...] (the third parameter is read but unused), MI[f,m,bins,...] (joint-histogram MI, smoothing variance 1); the images are read from -m whatever the metricANTs: “These image metrics are available: Mattes: Mattes mutual information (recommended), GC: global correlation, MI: joint histogram mutual information”
-t Rigid[step], --transform transform="Rigid", gradient_step=step transform="Rigid", gradient_step=0.1 Affine, Similarity; AlignGeometricCenters, AlignCentersOfMass (no step)ANTs: “Several transform options are available. For the rigid, affine, and similarity transforms, the gradientStep characterizes the gradient descent optimization and is scaled appropriately for each transform using the shift scales estimator. The other two transform types finds the simple translation transform which aligns the specified image feature. Note that the images are read from the similarity metric option although the metric isn’t actually used.”
-p 0/1, --align-principal-axes align_principal_axes False start from the principal axes’ rotation (Wahba’s problem)ANTs: “Boolean indicating alignment by principal axes. Alternatively, one can align using blobs (see -b option).”
-b n / -b [n,m], --align-blobs blobs=n / blobs=(n, m) blobs=None, blobs=None the initial transform from n blobs per image and up to m matched pairs (m = n by default); fewer than 3 blobs: ANTs’ error; -p is then ignored (Blob alignment)ANTs: “Boolean indicating alignment by a set of blobs. Alternatively, one can align using blobs (see -p option).”
-s [factor,arc] / -s factor, --search-factor search_factor (degrees), arc_fraction search_factor=20.0, arc_fraction=1.0 angles −180°·arc to 180°·arc in steps of factor, about each axisANTs: “Incremental search factor (in degrees) which will sample the arc fraction around the principal axis or default axis.”
-g [step,AxBxC], --translation-search-grid translation_search_grid=(step, (A, B, C)) None translations of the start points, in mm (ignored by Rigid/Similarity in 2D and Similarity in 3D in ANTs: ANTS-52)ANTs: “Translation search grid in mm, which will translate the moving image in each dimension in increments of the step size.”
-c [n,threshold,window] / -c n, --convergence iterations, convergence_threshold, convergence_window iterations=0, convergence_threshold=1e-6, convergence_window=5 defaults 0, 1e-6, 5 (the help says 10: ANTS-59); 0 iterations: the initial alignment onlyANTs: “Number of iterations.”
-x mask / -x [fixed,moving], --masks fixed_mask, moving_mask fixed_mask=None, moving_mask=None a mask that cannot be read is no maskANTs: “Image masks to limit voxels considered by the metric.”
-o out.mat, --output the result its transform; .mat, .txt, .tfm or an HDF5 name; Python reads the file backANTs: “Specify the output transform (output format an ITK .mat file). ”
--random-seed N / ANTS_RANDOM_SEED random_seed None default 1234; 0: ANTs from the clock, larmorx 121212ANTs: “Use a fixed seed for random number generation. The default fixed seed is overwritten by this value. The fixed seed can be any nonzero int value. If the specified seed is zero, the system time will be used.”
-v 1, --verbose the result its log, start_points, values and best_value: Python always runs verbose; errors are explained with or without -v (ANTS-45)ANTs: “Verbose output.”
-h, --help – the short and long menus, as ANTs prints themANTs: “Print the help menu (short version).”ANTs: “Print the help menu.”
ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS, NSLOTS n_threads 1 the result does not depend on it
LARMORX_UPSTREAM_DEFECTS upstream_defects= "fix" ANTS-52, -53, -55, -110, -111, -112, -114, ITK-18, -19, -60 (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 antsAI ...); lx.ants.ai 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
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.ai takes no implementation. The variable LARMORX_IMPLEMENTATION in 0.1.0rc1.
--upstream-defects fix|reproduce
upstream_defects="fix"
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: fixed.nii.gz (a synthetic head of 40 × 48 × 40 voxels of 4 mm), moving.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

# A rigid search from the centres of mass: 30-degree steps over the whole circle.
res = lx.ants.ai("fixed.nii.gz", "moving.nii.gz", transform="Rigid", search_factor=30,
                 random_seed=1)
res.transform.name  # -> 'Euler3DTransform_double_3_3'
bash
larmorx ants antsAI -d 3 -m Mattes[fixed.nii.gz,moving.nii.gz,32,Regular,0.25] -t Rigid[0.1] -s [30,1] -c 0 -o initialization.mat --random-seed 1

Ports

antsAI has one port: a replica.

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

The replica: status validated against antsAI itself (its record, 2026-10-28, standard tier: 132 cases, 76 pass, 52 rejected by both alike, 4 expected divergences): every compared case identical to ANTs 2.6.5 at one thread (exit status, standard output with every printed metric value, standard error, the transform file byte for byte), 75 of 76 against the unmodified binary, the other once glibc’s not-correctly-rounded cbrt is replaced by CORE-MATH’s (CLAUDE.md rule 5). fMRIPrep 25.2.6’s own init_aff command lines, with fMRIPrep’s seed, give fMRIPrep’s transforms within ANTs’ 8-thread band: all ten init_aff nodes of the five oracle runs (full tier) within 1.5e-9 of fMRIPrep’s files, nine of them within 1.3e-12.

Tier Cases Identical to the unmodified ANTs Identical with CORE-MATH Rejected by both Expected divergences Failures
standard (2026-10-28) 132 75 1 52 4 0
full (record, 2026-10-24) 144 86 1 53 4 0

“Rejected by both” includes the cases where ANTs aborts or crashes: everything ANTs printed before it stopped is identical, and larmorx then exits 1 with one more line. The expected divergences: two loops ANTs never finishes (larmorx refuses) and two clock-seeded runs (ANTS-58). ANTs’ own thread band (6 cases): up to 2e-13 in a transform parameter in five, and 0.137 in the BOLD reference of ds000005’s run 1 in the standard record of 2026-10-28; larmorx gives the one-thread result at any thread count.

On the data panel (record, 2026-10-26): all 36 antsAI nodes of the fourteen finished fMRIPrep oracle runs (the brain extraction’s init_aff in every run, the BOLD reference’s in 22 runs; the 3.5-year-old, the glioma, the stroke, 1.5 T, 7 T, multiband-8 and multi-echo among them), with fMRIPrep’s seed, and four images fMRIPrep never gives it (a FLAIR, a glioma’s T2w, an older adult’s T2w, the 7 T MP2RAGE, with sMRIPrep’s options): 40 of 40 identical to ANTs 2.6.5 at one thread (38 as built, 2 with CORE-MATH). Against fMRIPrep’s own transforms (ANTs 2.6.2 at 6 or 8 threads): 31 within 1e-8 in a parameter, five further, by up to 6.8 mm over a 100 mm cube. Those five are ANTs’ own spread above one thread: fMRIPrep’s ANTs at one thread gives exactly larmorx’s transform, and both ANTs builds at fMRIPrep’s thread count land, run to run, on fMRIPrep’s file, on the one-thread result or elsewhere (findings, “On the data panel”).

antsAI has one port, in pip install larmorx: the replica (crates/larmorx-ants, crates/larmorx-registration; Apache-2.0; Rust larmorx_ants::ai), translated from ANTs 2.6.5’s antsAI on ITK 5.4.5 (Apache-2.0). Results do not depend on threads. ANTs’ do, by about 1e-13 in a parameter (its metrics sum per work unit); larmorx always gives ANTs’ one-thread result. Random sampling is never repeatable in ANTs (its voxels are drawn from the clock, whatever the seed; so are Regular sampling’s perturbations with --random-seed 0, ANTS-58); larmorx seeds them from the seed.

Evidence

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

More in the repository

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