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
larmorxApache-2.0 validated
- replica
- 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
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):
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
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",
) -> AIResultWhere 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).
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 Nn_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|reproduceupstream_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.
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'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 1Ports
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: