Programs · ANTs and ITK
antsAffineInitializer
antsAffineInitializer finds an affine transform that aligns two images.
- Original
- ANTs 2.6.5
- Command line
larmorx ants antsAffineInitializer- Python
lx.ants.affine_initializer- Ports
- replica
larmorxApache-2.0 validated
- replica
- Evidence
- every comparison with ANTs
- Source
- made from docs/api/ants-affine-initializer.md and the code
What it does
It aligns their
centres of mass (and, optionally, their principal axes), then takes the best start point of a
multi-start search over rotations about the fixed image’s principal axes, each refined by
conjugate-gradient iterations of Mattes mutual information on every 10th voxel (as many as the
eighth argument says, by default 20; ANTs always runs 20); in 2D, 3D and 4D (in 4D the initial
alignment only). niworkflows’ RobustMNINormalization runs it when it is given no initial
transform (fMRIPrep’s template registration).
Command line
larmorx ants antsAffineInitializer ImageDimension <Image1.ext> <Image2.ext> TransformOutput.mat Optional-SearchFactor Optional-Radian-Fraction Optional-bool-UsePrincipalAxes Optional-uint-UseLocalSearch Optional-Image1MaskEverything after larmorx ants antsAffineInitializer is the original’s command line: the arguments of ANTs 2.6.5’s antsAffineInitializer, 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 antsAffineInitializer ...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.affine_initializer(
fixed: Any,
moving: Any,
*,
search_factor: float = 10.0,
radian_fraction: float = 0.25,
principal_axes: bool = False,
local_search_iterations: int = 20,
fixed_mask: Any = None,
dimension: int | None = None,
n_threads: int = 1,
upstream_defects: UpstreamDefectsName = "fix",
) -> ItkTransformWhere UpstreamDefectsName is one of "fix", "reproduce".
An affine transform that aligns moving to fixed, as antsAffineInitializer (ANTs v2.6.5) finds it: the images’ centres of mass (and, with principal_axes, their principal axes) aligned, then the best of a multi-start search over rotations about the fixed image’s principal axes (2D and 3D; in 4D the alignment alone).
Returns the transform as an ItkTransform (the search’s best, fixed to moving).
import larmorx as lx
t = lx.ants.affine_initializer(
"tpl-MNI152NLin2009cAsym_res-01_T1w.nii.gz", "sub-01_T1w.nii.gz",
search_factor=15, radian_fraction=0.1, principal_axes=False,
)
t # ItkTransform('AffineTransform_double_3_3', 12 parameters, 3 fixed)Its result, ItkTransform, holds one transform as ITK stores it.
| Field | Type | What it holds |
|---|---|---|
name |
str |
|
parameters |
np.ndarray |
|
fixed_parameters |
np.ndarray |
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 antsAffineInitializer accepts (crates/larmorx-ants/src/cli/affine_initializer.rs) and the arguments of lx.ants.affine_initializer (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 argument (positional) | Python | Default | Notes |
|---|---|---|---|
1 ImageDimension |
dimension |
None |
default: the fixed image’s; std::stoi; any number but 2, 3, 4 runs as 2D in ANTs (ANTS-56; corrected, an error) |
2, 3 Image1, Image2 |
fixed, moving |
read as float images; a missing image, or one whose values sum to 0, aborts (zero image1 error) |
|
4 TransformOutput |
the result | the returned ItkTransform; written twice: the initial alignment, then the search’s best (.mat, .txt, .tfm, HDF5) |
|
5 SearchFactor |
search_factor |
10.0 |
degrees (×0.0174532925), atof; default 10 |
6 Radian-Fraction |
radian_fraction |
0.25 |
atof, clamped to [0.01, 1]; the angles run over [−π·f, π·f + step]; default 0.25 (π/4) |
7 UsePrincipalAxes |
principal_axes |
False |
std::stoi, non-zero is true; default false |
8 UseLocalSearch |
local_search_iterations |
20 |
each start point’s conjugate-gradient iterations, read with std::stoi (0: no local search; text, a negative value or one beyond int: an error); default 20. Not read by ANTs, which always runs 20 (ANTS-54, corrected; reproduce runs 20) |
9 Image1Mask |
fixed_mask |
None |
the metric’s fixed mask; one that cannot be read is no mask |
| fewer than 2 arguments | – | the usage on standard error, exit 0; 2 or 3 arguments abort (ANTS-57) | |
ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS, NSLOTS |
n_threads |
1 |
the result does not depend on it |
LARMORX_UPSTREAM_DEFECTS |
upstream_defects= |
"fix" |
ANTS-54, ANTS-56, ITK-19, ITK-21 (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 antsAffineInitializer ...); lx.ants.affine_initializer 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.affine_initializer 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
# niworkflows' call (15 0.1 0 10), with the local search's iterations as asked.
t = lx.ants.affine_initializer("fixed.nii.gz", "moving.nii.gz", search_factor=15,
radian_fraction=0.1, local_search_iterations=10)
t.name # -> 'AffineTransform_double_3_3'larmorx ants antsAffineInitializer 3 fixed.nii.gz moving.nii.gz transform.mat 15 0.1 0 10Ports
antsAffineInitializer has one port: a replica.
| Port | Package | Licence | Status | Records |
|---|---|---|---|---|
| replica | larmorx (built in) |
Apache-2.0 | validated | ants-affine-initializer |
The replica: status validated against antsAffineInitializer itself (its
record, 2026-10-28, standard tier): every compared
case identical to ANTs 2.6.5 at one thread (exit status, both streams, the transform file byte
for byte), including the usage, every abort and its messages, 2D, 3D and 4D, masks, oblique
grids and real images (the MNI template and fMRIPrep’s preprocessed T1w; full tier: fMRIPrep’s
own call in the template registration of all five oracle runs, on stand-ins for the masked
images nipype did not keep).
| Tier | Cases | Identical to the unmodified ANTs | Rejected by both | Expected divergences | Failures |
|---|---|---|---|---|---|
| standard | 41 | 26 | 13 | 2 | 0 |
| full (record) | 46 | 31 | 13 | 2 | 0 |
“Rejected by both” includes the aborts (everything ANTs printed before it stopped is
identical); the expected divergences are the two search factors whose loop never ends in ANTs.
ANTs’ own thread band (4 cases): up to 1.3e-6 in a parameter on the MNI template,
1e-15 on the phantoms; larmorx gives the one-thread result at any thread count. The
comparison runs larmorx with ANTs’ defects reproduced (reproduce); every case also runs in
larmorx’s default mode, where ANTS-54 and ITK-21 (Upstream defects)
are named exactly where they change the transform (the fix pass of each case).
On the data panel (record, 2026-10-26):
fMRIPrep’s own call in the template registration of all fourteen finished oracle runs (no node
of its own: niworkflows runs it inside register_template_wf/.../registration, with nipype’s
15 0.1 0 10), on the masked images remade exactly from each node’s recorded inputs
(larmorx_validation.parity.niworkflows_inputs; the 3.5-year-old, the glioma, the stroke, the
7 T MP2RAGE, the 1.5 T MPRAGE, the 82-year-old among them): 14 of
14 identical to the unmodified ANTs 2.6.5 at one thread, ANTs’ own band at 2 and 3 threads
6.5e-9 in a parameter. fMRIPrep did not keep the transform it made (at the node’s six or eight
threads); its effect is in the registration’s record.
antsAffineInitializer has one port, in pip install larmorx: the replica
(crates/larmorx-ants, crates/larmorx-registration; Apache-2.0; Rust
larmorx_ants::affine_initializer), translated from ANTs 2.6.5’s antsAffineInitializer on ITK
5.4.5 (Apache-2.0). Results do not depend on threads: larmorx gives ANTs’ one-thread result
at any thread count.
Evidence
How each of antsAffineInitializer’s ports was measured against ANTs, case by case: its evidence.
More in the repository
The API page docs/api/ants-affine-initializer.md holds what antsAffineInitializer shares with the page’s other programs: