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 larmorx Apache-2.0 validated
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

text
larmorx ants antsAffineInitializer ImageDimension <Image1.ext> <Image2.ext> TransformOutput.mat Optional-SearchFactor Optional-Radian-Fraction Optional-bool-UsePrincipalAxes Optional-uint-UseLocalSearch Optional-Image1Mask

Everything 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):

text
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

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",
) -> ItkTransform

Where 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).

python
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 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.affine_initializer 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

# 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'
bash
larmorx ants antsAffineInitializer 3 fixed.nii.gz moving.nii.gz transform.mat 15 0.1 0 10

Ports

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: