longitudinal/REGISTRATION_BENCHMARK_RIGID.md

Registration Pipeline Benchmark — CT → T1c (M6)

Benchmarks six cross-modality registration pipelines — all rigid (6-DOF) — that align a head-and-neck CT to a tightly-cropped T1c MRI so the GTV can be warped onto the T1c (MR) native grid. This is the registration step of scripts/02_build_m6_dataset.py. The pairs are hard: different modality (CT Hounsfield vs MR intensity) and the patient is repositioned between the CT and MR sessions, so the inter-session head tilt can reach ~30°.

• Pipelines: src/registration_pipelines.py
• Benchmark harness: scripts/bench_registration.py
• Results: results/bench_registration/ (per-pipeline JSON, summary.json, summary.md, bench_registration.png)

Unified contract

Every pipeline returns a SimpleITK transform T such that

sitk.Resample(ct, t1c, T, sitk.sitkLinear)              # CT  onto the MR grid
sitk.Resample(tv,  t1c, T, sitk.sitkNearestNeighbor, 0) # GTV onto the MR grid

places the CT / GTV concentric with the MR head. In Resample's destination→source convention this T maps T1c → CT. Shared rules for every pipeline:

• No mask, no crop / pad: registration runs on the full input volumes exactly as given (no FixedMask / MovingMask, no head-box resampling, no padding).
• The T1c (MR) is always the fixed image (moving = CT) for every pipeline. (A CT clipped to a non-negative window reads as MR, so the T1c slot decides; both-CT pairs keep the given order.)
• Every transform is rigid (6-DOF) — Euler / rigid-matrix parameterizations per toolkit. No affine, no deformable.

All pipelines also use each toolkit's native automatic transform initialization (no manual centroid offset): elastix / impact use AutomaticTransformInitialization (CenterOfGravity), antspyx its default center-of-mass alignment, simpleitk starts from identity, niftyreg (reg_aladin) initializes from the image centres, synthmorph needs none. One consequence of the no-mask rule: the IMPACT metric only evaluates samples that map inside the moving buffer. With fixed=T1c the samples are drawn from the tight T1c head crop (fixed, ~220×220×150 mm) and map mostly inside the large CT head-neck FOV (moving, ~300×300×251 mm), so the gate rarely fires; the pipeline still sets RequiredRatioOfValidSamples 0.1 (vs the build default 0.25) as a safety override for the FOV mismatch — see the IMPACT section. The comparison is on each toolkit's native optimizer / metric / global-search capability.

The six pipelines

Listed alphabetically. All register on the full volumes (no head box, no mask, no crop / pad) and use each toolkit's native automatic transform initialization (no manual centroid offset): elastix / impact use elastix's AutomaticTransformInitialization (CenterOfGravity), antspyx uses its default center-of-mass alignment, simpleitk starts from identity, niftyreg initializes from the image centres, and synthmorph needs none (global deep method). All use fixed = T1c, moving = CT (shared rule above). niftyreg and synthmorph clip the CT (the moving image) to [0, 80] HU before registration (per the CT-clipping A/B below; clip_ct=None disables it).

#	pipeline	fixed / moving	init	metric	transform	status in this env
1	antspyx	T1c / CT	auto COM	Mattes MI (multi-res)	ANTs Rigid	✅ ran (main env; stochastic MI subsampling)
2	elastix	T1c / CT	auto CenterOfGravity	Mattes MI (32 bins)	EulerTransform rigid (5.x), ASGD, 3 resolutions	✅ ran (main env, in-process python API — no CLI)
3	impact	T1c / CT	auto CenterOfGravity	IMPACT semantic (MIND R1D2_3D L1 + TotalSegmentator M852/M850 deepest-layer Dice, per-level weighted, Static) + Mattes MI (w 0.4)	EulerTransform rigid, ASGD, 4 scales	✅ ran (Docker vboussot/elastix_impact + GPU — see IMPACT section)
4	niftyreg	T1c / CT	image centres	NCC block matching + trimmed least squares (symmetric)	reg_aladin -rigOnly, 3-level pyramid	✅ ran (Docker niftyreg:2.1.1-ubuntu, GPU -platf 1)
5	simpleitk	T1c / CT	identity	Mattes MI (32 bins)	Euler3D rigid, pyramid [4,2,1]	✅ ran
6	synthmorph	T1c / CT	none (global)	SynthMorph anatomy-aware contrast-invariant (deep, pretrained)	6-DOF rigid matrix	✅ ran (main env, Docker + GPU)

Benchmark budget (best-results settings): elastix and simpleitk run with MaximumNumberOfIterations = 2000 (per resolution / per pyramid level), with the sampler and metric left at their defaults (NumberOfSpatialSamples 5000, NumberOfHistogramBins 32). impact runs the MIND + TotalSegmentator static feature combination of the ImpactReg MR_CT_TS reference parameter map (per VBoussot/ImpactReg) as a rigid EulerTransform: 4 levels, per-level voxel sizes 6/3/2/2 mm (no image-resampling pyramid), per-level MaximumNumberOfIterations 400/300/200/200, NumberOfSpatialSamples 2000,

• Mattes MI weight 0.4, CenterOfGravity auto-init, RequiredRatioOfValidSamples 0.1. antspyx, niftyreg and synthmorph keep their native defaults.

simpleitk has two budgets: --simpleitk-mode benchmark (single pyramid, identity start — the default, comparable to the other tools) and --simpleitk-mode production (the full multi-start tilt grid from 02_build_m6_dataset.py, now also on the full volumes per the no-crop rule, ~20× slower, the most robust but not used for the head-to-head).

Test cases

First 10 labeled M6 cases (--n-cases 10 --sample first), reproducible. 9 have a complete CT; 1 (m6_22GD5VL2_20230724) has an incomplete CT head and is reported as incomplete-CT for every pipeline (a data issue, not a pipeline failure).

m6_22GD5VL2_20230724  (incomplete CT)
m6_22IRRKU6_20240115  m6_23XIMO4M_20230222  m6_24V62QQM_20230223
m6_24V62QQM_20231017  m6_24V62QQM_20240820  m6_26TYQI3C_20221027
m6_2BBN5XA4_20250411  m6_2C4TKI6H_20240506  m6_2CDNN7BH_20240102

Metrics (identical for every pipeline)

Alignment is scored two ways, both as the registration's achieved metric read off as a standalone score: the intensity-based Mattes MI (mi_ct_mr) and the semantic ImpactLoss (impact_loss):

• mi_ct_mr — mean Mattes MI (nats) between the CT inverse-transformed into MR coordinates (the warped CT on the T1c grid) and the original MR, restricted to the MR head and each image percentile-binned independently (SimpleITK Mattes-MI style). Higher = the warped-CT and MR intensities are better in-sync = better aligned; it collapses toward 0 when the CT is rotated/translated away from the MR.
• impact_loss — the IMPACT semantic loss from vboussot/ImpactLoss (the metric family the impact pipeline registers with): a weighted L1 distance between the deep feature maps of the warped CT and the original MR extracted by the pretrained TotalSegmentator TS/M730.pt TorchScript model (two deepest layers, weights 1/1, no resampling), over the full co-registered volumes. The model standardizes intensity internally (per-image z-score), so both volumes go in raw and the score is invariant to affine intensity scaling. Lower = the two volumes carry more in-sync anatomy = better aligned; it rises when the CT is rotated/translated away from the MR.
• reg_wall_s — wall-clock registration time (excludes I/O + scoring).

Tables and plots report mi_ct_mr and impact_loss (plus registration time).

The production geometric QA is still computed per case and kept in the JSON (it drives dataset acceptance in 02_build_m6_dataset.py, but its summary numbers were found to correlate poorly with perceived alignment, so they are no longer reported in the tables/plots):

• skull_ring_gap_mm — march rays from the MR head center; the gap between the MR head silhouette boundary and the warped-CT skull ring (p97 of positive CT) at mid and low levels, plus the angular std. mid measures translational concentricity; std measures rotational concentricity.
• tv_nvox — warped GTV volume.
• accepted — the production acceptance rule of 02_build_m6_dataset.py (warped GTV non-empty and concentric with the head; aligned ⇔ |mid| ≤ 20 mm and std ≤ 12 mm — a small negative mid is fine: on full-volume registration the CT skull ring can land slightly inside the MR silhouette, which is equally concentric).

Results (10 cases, no clip)

Alignment is scored by the achieved Mattes MI (nats, warped-CT ~ MR over the MR head; higher = better) and the ImpactLoss semantic score (warped-CT ~ MR over the full volumes; lower = better), with the unclipped CT, so all rows are comparable on the same score scales. Full volumes, no mask / crop / pad, fixed = T1c / moving = CT (shared rule). niftyreg and synthmorph clip the CT (the moving image) to [0, 80] HU before registration (per the CT-clipping A/B below; clip_ct=None disables it); antspyx, elastix, impact and simpleitk register the CT as-is. niftyreg is the v2.1.1 Docker build on the GPU (-platf 1); impact runs the vboussot/elastix_impact Docker image on the GPU (see the IMPACT section). All six transforms are rigid (6-DOF).

pipeline	toolkit	registered	s/reg (med)	ImpactLoss (med/mean)	MI (med/mean, nats)
antspyx	ANTsPy 0.63	9	16.7	0.157 / 0.155	0.652 / 0.650
elastix	ITK-Elastix 0.25.4	9	11.7	0.157 / 0.156	0.646 / 0.638
impact	Docker vboussot/elastix_impact (Elastix 5.2 + IMPACT, rigid MIND+TS static config)	9	111.2	0.157 / 0.156	0.652 / 0.641
niftyreg	NiftyReg 2.1.1 (reg_aladin, Docker + CUDA)	9	15.4	0.166 / 0.170	0.292 / 0.338
simpleitk	SimpleITK 2.5.6	9	10.8	0.156 / 0.156	0.647 / 0.642
synthmorph	Docker SynthMorph (TensorFlow)	9	22.2	0.167 / 0.170	0.277 / 0.328

Per-case MI (nats, unclipped score; bold = best for the case). All rows are re-runs under the fixed = T1c / moving = CT convention (the shared rule); the CT-fixed-era numbers and the retired konfai-preset run are in the git history / archived JSONs. The impact column is the Docker rigid MIND+TS static config (the CT-fixed-era Docker run is archived in results/bench_registration/impact_docker_legacy.json).

case	antspyx	elastix	impact	niftyreg	simpleitk	synthmorph
m6_22GD5VL2_20230724	incomplete-CT	incomplete-CT	incomplete-CT	incomplete-CT	incomplete-CT	incomplete-CT
m6_22IRRKU6_20240115	0.648	0.644	0.645	0.292	0.647	0.277
m6_23XIMO4M_20230222	0.655	0.652	0.654	0.632	0.654	0.616
m6_24V62QQM_20230223	0.703	0.698	0.700	0.260	0.704	0.256
m6_24V62QQM_20231017	0.602	0.590	0.596	0.493	0.597	0.484
m6_24V62QQM_20240820	0.652	0.646	0.652	0.118	0.638	0.111
m6_26TYQI3C_20221027	0.718	0.650	0.658	0.609	0.670	0.590
m6_2BBN5XA4_20250411	0.577	0.577	0.572	0.069	0.579	0.061
m6_2C4TKI6H_20240506	0.645	0.638	0.639	0.233	0.636	0.231
m6_2CDNN7BH_20240102	0.655	0.650	0.655	0.340	0.652	0.323

Per-case ImpactLoss (semantic, unclipped score; bold = best (lowest) for the case):

case	antspyx	elastix	impact	niftyreg	simpleitk	synthmorph
m6_22GD5VL2_20230724	incomplete-CT	incomplete-CT	incomplete-CT	incomplete-CT	incomplete-CT	incomplete-CT
m6_22IRRKU6_20240115	0.1507	0.1508	0.1510	0.1656	0.1504	0.1664
m6_23XIMO4M_20230222	0.1565	0.1563	0.1564	0.1570	0.1564	0.1575
m6_24V62QQM_20230223	0.1466	0.1470	0.1469	0.1664	0.1467	0.1665
m6_24V62QQM_20231017	0.1520	0.1539	0.1534	0.1577	0.1532	0.1576
m6_24V62QQM_20240820	0.1566	0.1571	0.1567	0.1840	0.1585	0.1842
m6_26TYQI3C_20221027	0.1554	0.1620	0.1622	0.1623	0.1604	0.1620
m6_2BBN5XA4_20250411	0.1617	0.1612	0.1615	0.1847	0.1616	0.1856
m6_2C4TKI6H_20240506	0.1573	0.1579	0.1580	0.1754	0.1547	0.1757
m6_2CDNN7BH_20240102	0.1591	0.1590	0.1591	0.1734	0.1587	0.1741

Interpretation

• The top four are a statistical tie (median MI 0.646–0.652, median ImpactLoss 0.156–0.157): antspyx, impact, simpleitk and elastix all recover the gross offset on every case, including the two ~30° repositioned ones (m6_2BBN5XA4 0.572–0.579, m6_24V62QQM_20240820 0.638–0.652). The two alignment scores — an intensity histogram and a deep semantic one — agree on the ranking.
• IMPACT (Docker, rigid, T1c-fixed) is in the top tier at median MI 0.652 (0.6523) — best or within 0.006 of the best on 8 of 9 cases (m6_24V62QQM_20230223 0.700, m6_26TYQI3C 0.658 where it trails ANTsPy's 0.718). This is a large step up from the legacy CT-fixed Docker config (median 0.467, archived in impact_docker_legacy.json): the T1c-fixed direction fixes the sample-coverage problem the same way it fixed Elastix (the metric draws samples from the fixed T1c crop and evaluates them where they map into the large CT FOV, instead of the other way round; previously only ~14% of the samples were in-buffer at the auto-init). The m6_2BBN5XA4 ~30° tilt case that defeated every earlier IMPACT variant (0.223 CT-fixed Docker, 0.258 konfai preset) now registers at 0.572. Cost: the slowest of the six (~111 s/case, ~10× the intensity tools). Concentricity is comparable to the MI tools (4/9 accepted by the production rule).
• ImpactLoss corroborates the MI leaderboard from a different metric family. The top four cluster within 0.001 of each other on the median (0.1564–0.1571), and on every case the best (lowest) ImpactLoss belongs to one of them (antspyx 4/9, elastix 3/9, simpleitk 2/9, impact 0/9); niftyreg (0.1664) and synthmorph (0.1665) are clearly higher, and the gap widens on the hard cases (0.184–0.186 for the two tail tools vs 0.155–0.162 for the top four). A semantic score computed by pretrained segmentation features (not the registration's own objective) ranking the pipelines the same way the intensity score does is a strong check that the leaderboard is not an artifact of the MI scale.
• The grossly repositioned cases still separate the leaders from the tail. On m6_2BBN5XA4 / m6_24V62QQM_20240820 (~30° inter-session tilt) the top four hold 0.57–0.65, while niftyreg (0.069 / 0.118) and synthmorph (0.061 / 0.111) — the single-start block-matching and pretrained-MRI methods — lock onto local minima. This is exactly why production 02_build_m6_dataset.py uses a multi-start tilt grid.
• NiftyReg (reg_aladin) is second-from-bottom: single-start symmetric block matching is strong on moderate cases (m6_23XIMO4M 0.632; m6_26TYQI3C 0.609) but falls into the same tilt local minima (m6_2BBN5XA4 0.069, m6_24V62QQM_20240820 0.118). The v2.1.1 Docker build on the GPU (-platf 1) is ~15 s/case (vs ~4 min CPU for the conda 1.5.69 build). It clips the CT to [0,80] HU by default (per the A/B below) — neutral on the unclipped score scale (0.296→0.292 median).
• SynthMorph is weakest of the six on these cross-modality CT pairs (median 0.277 with its default CT clip; 0.241 unclipped): its rigid model is trained on brain MRI, so the ~30° tilt defeats it on the repositioned cases (0.06–0.11) even though it matches the intensity tools on the cleanest (m6_26TYQI3C 0.590). The [0,80] brain-window clip of the CT is its only genuine A/B win (+0.036 median, 7/9 cases), so it is the default. It needs no centroid init (global deep method).
• Speed (median wall, 3–4 cases in parallel, 24 threads, T1c-fixed): SimpleITK 10.8 s, elastix 11.7 s, NiftyReg 15.4 s (v2.1.1, GPU block matching), ANTs 16.7 s, SynthMorph 22.2 s (GPU forward pass), IMPACT 111.2 s (Docker, static feature mode, no backprop, 400/300/200/200 rigid ASGD iterations).
• Stochasticity: ANTs' Mattes-MI subsamples the image at random, so its per-case numbers carry run-to-run variance (this table is one draw); SimpleITK's MI (and registration) is deterministic at fixed thread count; the in-process Elastix ASGD is deterministic given its fixed seed; SynthMorph is deterministic; NiftyReg is deterministic on the CPU (conda 1.5.69) but shows small run-to-run variation on the GPU (v2.1.1, ~±0.01–0.05 MI on the weak cases). IMPACT in the Static config re-samples spatial coordinates every iteration, but the feature maps are deterministic given the pose. The earlier Jacobian-mode Docker experiments (archived in results/bench_registration/impact_*.json) resampled patches through the network each iteration, so their per-case numbers are one sample from a distribution — e.g. the MRSegmentator-only Jacobian configs reached 0.631 (500/2000) and 0.591 (2000/5000) at ~5×/~35× the Static cost, and the MIND+TS/MRSeg static variants 0.417/0.406 (~72/~37 s).

CT clipping A/B (--clip-ct 0 80)

Question: does clipping the CT to a brain window ([0, 80] HU — skull and air removed) before registration improve the result? The harness clips the CT before registration AND before scoring (percentile-binned MI is scale-free, so the A/B compares like for like). Same 10 cases, same budgets.

Median achieved MI (nats) and wall-clock (9 complete-CT cases):

pipeline	no clip	clip [0,80]	Δ (median MI)	clip wins (cases by MI)
antspyx	0.653 / 36.6 s	0.466 / 34.7 s	−0.186	0/9
elastix	0.517 / 6.0 s	0.425 / 5.9 s	−0.092	1/9
niftyreg	0.296 / 23.8 s	0.320 / 20.2 s	+0.024	5/9
simpleitk	0.651 / 10.6 s	0.436 / 11.1 s	−0.215	0/9
synthmorph	0.241 / 26.0 s	0.318 / 25.6 s	+0.077	5/9
impact	abort	abort	-	- (historical: at the time both aborted on the old 0.25 sample-validity gate; the gate is now 0.1, A/B to be re-done)

Verdict: no — clipping the CT to [0, 80] HU does not improve the result; do not clip.

• The headline alignment score drops for all three leading intensity pipelines: antspyx 0.653→0.466, simpleitk 0.651→0.436, elastix 0.517→0.425 (median nats; simpleitk and antspyx lose on all 9 cases, elastix on 8/9).
• The two weaker pipelines show small median-MI gains (niftyreg +0.024, synthmorph +0.077) but only mixed case-by-case (5/9), and their geometric QA does not support a real improvement.
• Geometric concentricity (skull-ring gap) is a wash: mean mid/std move by ~1–5 mm in either direction (niftyreg mid 23.6→18.1 the only clear gain; antspyx std 16.4→18.0 the clear loss). Production acceptance even falls (no-clip 4/4/2/4/2 → clip 1/0/1/0/2).
• Mechanism. Clipping is a saturating (non-invertible) intensity map: the skull atom (800+ HU → 80) removes the strongest intensity anchor (skull ↔ MR scalp) and compresses the CT rank distribution, so the percentile-binned MI between the warped CT and the MR is inherently lower for the same pose. The pose itself does not systematically degrade — the head is rigid, so skull-ring concentricity is its fingerprint, and that is unchanged. The MI drop is therefore mostly a score-scale effect, but it is exactly the score the benchmark reports, and there is no geometric benefit to pay it for.
• Scoring note: _skull_ring_gap tests the ring with >= p97 (not >) so the orientation gate and the gap QA also work on a clipped CT (where p97 sits exactly on the clipped-skull atom).
• Decision / adopted default. The pipelines were updated: niftyreg and synthmorph clip the CT to [0, 80] HU before registration (clip_ct=(0.0, 80.0) default, clip_ct=None disables it; MR inputs are never clipped); antspyx / elastix / simpleitk register the CT as-is. Re-checked on the unclipped score scale (the protocol used by the table above): synthmorph keeps a genuine gain (0.241→0.277 median, 7/9 cases), niftyreg is neutral (0.296→0.292; its apparent +0.024 above is mostly the clip-scoring effect). All rows of the main table are scored on the unclipped warped CT, so pipelines remain comparable.

Reproducing

# main env — SimpleITK + Elastix + ANTsPy + NiftyReg (niftyreg via Docker v2.1.1)
source /opt/conda/etc/profile.d/conda.sh && conda activate longitudinal-313
python scripts/bench_registration.py --pipelines "simpleitk elastix antspyx niftyreg" \
    --n-cases 10 --workers 4 --threads 24 --simpleitk-mode benchmark
# force the conda 1.5.69 CPU build: --niftyreg-backend conda

# impact (Docker vboussot/elastix_impact; GPU; ~110-120 s/case; see the IMPACT
# section). --impact-iters / --impact-samples override the reference map's
# per-level budget (one iters value for all levels)
python scripts/bench_registration.py --pipelines impact --n-cases 10 \
    --workers 3 --threads 24

# synthmorph (Docker, needs the pulled image; see the SynthMorph section)
python scripts/bench_registration.py --pipelines synthmorph --n-cases 10 \
    --workers 4 --threads 24

# A/B: does clipping the CT to a brain window help? (--clip-ct clips the CT
# for ALL pipelines, before registration and scoring; niftyreg/synthmorph
# already clip by default, so this only affects antspyx/elastix/simpleitk)
python scripts/bench_registration.py --n-cases 10 --workers 4 --threads 24 \
    --out-dir results/bench_reg_noclip
python scripts/bench_registration.py --n-cases 10 --workers 4 --threads 24 \
    --clip-ct 0 80 --out-dir results/bench_reg_clip0_80
python scripts/bench_registration.py --merge --out-dir results/bench_reg_noclip
python scripts/bench_registration.py --merge --out-dir results/bench_reg_clip0_80

# combine the per-pipeline JSONs accumulated across envs into one table + plot
python scripts/bench_registration.py --merge

Other flags: --sample random --seed 0 (reproducible random 10), --keys k1,k2,... (explicit cases), --n-cases N, --workers W, --threads T (also the OpenMP thread count for reg_aladin), --simpleitk-mode {benchmark,production}, --synthmorph-model {rigid,affine}, --synthmorph-gpu <int|-1>, --synthmorph-extent <int>, --impact-gpu <int|-1>, --impact-iters N (one MaximumNumberOfIterations value for all levels; default the reference map's 400/300/200/200), --impact-samples N (NumberOfSpatialSamples; default 2000), --out-dir <dir>, --qa-images / --qa-out <dir> (visual QA, below).

Visual QA images (checkerboard + color overlay)

--qa-images writes a checkreg-style PNG per (pipeline, case) to <out-dir>/qa/<pipeline>__<case>.png for eyeballing the alignment. Each image is a 3×2 grid: rows are the three orthogonal mid-slices through the head center (mid-axial, mid-coronal, mid-sagittal), and columns are:

• left — checkerboard blend: alternating blocks of the CT inverse-transformed into MR coordinates and the original MR; a clean registration gives a seamless mosaic, a misregistration shows hard edges at the block boundaries.
• right — additive color overlay: CT in red, MR in green. Structures that coincide blend to yellow; rotation/translation error appears as red/green fringing at the skull and brain edges.

The CT is shown in a brain window (L40/W80 = 0–80 HU) so the brain parenchyma is visible and comparable to the MR (the skull, ~800+ HU, clips to white); the MR uses a 2–98 % head window. The coronal and sagittal views are oriented superior-up to match the axial view.

The title carries the pipeline, case key and the achieved Mattes MI, so a glance tells you whether the visuals agree with the score. Generate for the available pipelines with:

source /opt/conda/etc/profile.d/conda.sh && conda activate longitudinal-313
python scripts/bench_registration.py \
    --pipelines "simpleitk elastix antspyx niftyreg" --n-cases 10 --qa-images
python scripts/bench_registration.py \
    --pipelines "synthmorph impact" --n-cases 10 --qa-images

(9 images each; the incomplete-CT case is skipped.)

SynthMorph pipeline (Docker) — one-time setup

The synthmorph pipeline runs the freesurfer/synthmorph image: SynthMorph (Hoffmann et al., IEEE TMI 2022), an anatomy-aware, acquisition-agnostic deep registration (TensorFlow VxmAffineFeatureDetector with the pretrained synthmorph.rigid.1.h5 weights). No skull-stripping or intensity preprocessing is needed: each volume is normalized to an isotropic 1-mm LIA network space internally. It is the second Docker-based pipeline and the only deep-learning one.

Prerequisites (check with RP.availability(); a missing piece raises PipelineUnavailable with the exact command):

# 1. Docker (with NVIDIA container toolkit so --gpus works)
docker --version

# 2. Pull the image (~11 GB, one-time)
docker pull freesurfer/synthmorph

No extra model assets: the rigid weights ship inside the image (/freesurfer/models).

How the adapter drives the image

1. Rigid matrix model, no init — register -m rigid on GPU when one is visible (auto-spread over the host GPUs by pid; --synthmorph-gpu -1 forces CPU). SynthMorph is a global deep method, so it recovers the gross inter-session offset on its own and needs no initial transform.
2. Read-back — the model estimates first→second, so the pair is passed as (fixed=T1c, moving=CT) and the -T LTA (a LINEAR_RAS_TO_RAS 4×4 in shared world space) is the T1c→CT contract transform directly; it is parsed into a SimpleITK AffineTransform and run through the usual fix_orientation gate.
3. GPU sharing — the container is run as the host uid (clean scratch removal, TF still reaches the GPU) with TF_FORCE_GPU_ALLOW_GROWTH set so concurrent benchmark workers can share a GPU.

NiftyReg pipeline — one-time setup

The niftyreg pipeline runs reg_aladin from the NiftyReg suite (KCL-BMEIS, the actively-maintained NiftyReg): symmetric block matching + trimmed least squares (Modat et al., J. Med. Img. 1(2) 024003, 2014). Instead of a histogram MI objective it matches 4-voxel image blocks by normalised cross-correlation at each level of a 3-level Gaussian pyramid and solves a robust (trimmed) least-squares for the rigid transform — a genuinely different algorithmic family, and cross-modality tolerant because NCC is invariant to intensity scaling.

Default backend: the official v2.1.1 release in Docker. The v2.x release binaries need GLIBC_2.34, which this host (Ubuntu 20.04, glibc 2.31) lacks, so the v2.1.1 Ubuntu zip is packaged in the niftyreg:2.1.1-ubuntu image (nvidia/cuda ubuntu22.04 base for the CUDA plugin). GPU runs use docker run --gpus all + -platf 1 -gpuid N and are ~20× faster than CPU; the v2.1.1 CUDA path supports linear interpolation only (-interp 1), so GPU runs use linear and CPU/conda runs use cubic (-interp 3) — the poses they recover on these cases agree to ~4 decimal places. The conda-forge build (1.5.69, CPU) remains the fallback when the Docker image is absent (--niftyreg-backend conda).

Prerequisites (check with RP.availability(); a missing piece raises PipelineUnavailable with the exact command):

# default: build the v2.1.1 Docker image (one-time)
docker build -t niftyreg:2.1.1-ubuntu niftyreg/   # from NiftyReg-Ubuntu-v2.1.1.zip

# fallback: conda-forge build (provides reg_aladin + reg_f3d, NiftyReg 1.5.69)
conda install -c conda-forge niftyreg

How the adapter drives the tool

1. Rigid 6-DOF, full volumes — reg_aladin -ref T1c -flo CT -rigOnly (the T1c is the reference/fixed image, the CT the floating/moving one; the CT is clipped to [0,80] HU first). Symmetric variant on by default, which matters: the non-symmetric mode drifts grossly on these repositioned pairs. -ln 3 pyramid, -maxit 15 TLS iterations per level (the tool's default of 5 is too coarse), -interp 1 (GPU) / -interp 3 (CPU) internal warping, default initialisation (image centres). GPU: --gpus all, -platf 1, -gpuid <auto by pid>; CPU/conda: -platf 0 (v2.1.1) or no -platf (1.5.69).
2. Read-back — the output affine (-aff) is a 4×4 row-major matrix, documented as Affine * Reference = Floating; the adapter parses it into a SimpleITK AffineTransform and runs it through the usual fix_orientation gate (skull-ring concentricity), which resolves the direction empirically rather than trusting the docs. Under -ref T1c -flo CT the file's affine comes out the other way, so the gate inverts it on the M6 cases (8/9 auto_inverted: True) to the contract transform (T1c→CT).

IMPACT pipeline (Docker vboussot/elastix_impact) — one-time setup

The impact pipeline runs the vboussot/elastix_impact image: Elastix 5.2 with the IMPACT semantic similarity metric (vboussot/ImpactLoss) as a native Elastix metric. The parameter map is the MIND + TotalSegmentator static feature combination of the MR_CT_TS reference map in the VBoussot/ImpactReg repo, with a rigid 6-DOF EulerTransform in place of the reference's RecursiveBSpline (its bending-energy penalty is zero for a rigid transform, so it is dropped) — i.e. the reference metric/budget, rigid-only, on the GPU.

Prerequisites (check with RP.availability(); a missing piece raises PipelineUnavailable with the exact command):

# 1. Docker (with NVIDIA container toolkit so --gpus works)
docker --version

# 2. Pull the image (~38 GB, one-time)
docker pull vboussot/elastix_impact

# 3. Feature models under the cache (the pipeline prints the exact
#    curl commands if any are missing):
#    data/impact_models/MIND/R1D2_3D.pt   (~15 KB)
#    data/impact_models/TS/M852.pt        (~200 MB)
#    data/impact_models/TS/M850.pt        (~200 MB)
#    (from HF VBoussot/impact-torchscript-models, or `sh
#     Data/Models/download_models.sh` from the ImpactLoss repo)

How the adapter drives the image

1. Full volumes, fixed=T1c (MR), moving=CT — the shared fixed-image rule: the metric draws its random spatial samples from the fixed buffer and evaluates them where they map inside the moving buffer. With the tight T1c head crop (~220×220×150 mm) as fixed, the samples map mostly inside the large CT head-neck FOV (~300×300×251 mm), so the RequiredRatioOfValidSamples 0.1 gate (build default 0.25) rarely fires.
2. Parameter map (the rigid MR_CT_TS reference config): (Metric "Impact" "AdvancedMattesMutualInformation") with weights 1.0 / 0.4; per level (coarse → fine) the MIND handcrafted descriptor (MIND/R1D2_3D.pt, L1, subset 32, layer mask "1") combined with TotalSegmentator TS/M852.pt (levels 0-1) / TS/M850.pt (levels 2-3, Dice, subset 64, deepest layers), layer weights 0.2/0.8, 0.3/0.7, 0.6/0.4, 0.7/0.3, at ImpactVoxelSize 6/3/2/2 mm (scaled to the moving spacing); Static mode (whole-image features, no backprop); no image-resampling pyramid (all-1 schedules — the scale is carried by ImpactVoxelSize, per the IMPACT docs); RandomCoordinate sampler; ASGD with per-level MaximumNumberOfIterations 400/300/200/200 and NumberOfSpatialSamples 2000; EulerTransform + AutomaticTransformInitialization (CenterOfGravity) + AutomaticScalesEstimation. A copy of the exact map is dumped to data/m6reg/impact/paramdump/ per run for inspection.
3. GPU auto-spread across the host GPUs by pid (docker run --gpus all, ImpactGPU = the worker's device; --impact-gpu -1 forces CPU and turns mixed precision off).
4. Read-back — the transform comes from Out/TransformParameters.0.itk.txt (an Euler3DTransform in the world physical frame; the full combination transform, with the auto-init folded in by elastix) and is direction-checked by fix_orientation against the skull ring (with fixed=T1c / moving=CT the gate keeps the file's transform, auto_inverted: False).
5. Intensity normalization happens inside the metric / models (no pipeline-side normalization): the MIND descriptor normalizes each 5-voxel neighbourhood to [0, 1] locally (modality-agnostic by construction); the segmentation models are standardized to zero mean / unit variance per the model card. Pre-normalizing the volumes would be an exact no-op for the z-scored models and would only corrupt the HU scale used by MI scoring and the QA brain-window images.

Notes / caveats

• The benchmark compares each toolkit in its native configuration: all register on the full volumes (no head box, no mask, no crop / pad) and use each toolkit's native automatic transform initialization (no manual centroid_offset) — elastix / impact AutomaticTransformInitialization (CenterOfGravity), antspyx's center-of-mass alignment, simpleitk identity, synthmorph none. Production uses --simpleitk-mode production's multi-start tilt grid, which raises SimpleITK's acceptance at ~20× the cost; that is out of scope for the head-to-head but is the config the dataset actually ships with.
• synthmorph is deterministic (one fixed pretrained model, no random subsampling), so its per-case numbers are stable run to run — unlike ANTs / IMPACT. Its low MI (median 0.277 with the default CT clip; 0.06–0.11 on the repositioned cases) is a genuine cross-modality / tilt weakness, not variance.
• fix_orientation (elastix/ants/impact/niftyreg/synthmorph) chooses between a transform and its inverse by skull-ring concentricity — a correctness gate that makes the result independent of each toolkit's transform-direction convention, so the fixed/moving swap is absorbed by the gate rather than re-derived per toolkit. Under the shared fixed=T1c / moving=CT rule the raw transforms come out in the contract direction for elastix (combination transform = fixed→moving), impact (its TransformParameters.0.itk.txt, the full combination Euler transform) and antspyx (ANTs forward transform) and synthmorph (the -T LTA, model estimates first→second) — completed runs report auto_inverted: False for those; niftyreg's -aff file comes out the other way and the gate inverts it (8/9 auto_inverted: True).
• SynthMorph specifics (Docker freesurfer/synthmorph, TensorFlow, GPU):
  • Cross-modality / tilt weakness. The rigid model is trained on brain MRI, so on these CT↔T1c pairs it recovers translation but is repeatedly defeated by the ~30° inter-session tilt (7/9 cases have std > 15 mm). It is a legitimate data point for how far a pretrained MRI deep model generalizes out-of-domain to CT — not a bug.
  • No centroid init needed. Being a global deep method it recovers the gross offset on its own; the -i initial-transform path is not used (which also sidesteps this image's float64/float32 bug on the -i code path).
  • GPU sharing. The container runs as the host uid with TF_FORCE_GPU_ALLOW_GROWTH so concurrent benchmark workers share a GPU.
• ~28 s/case (GPU: one pretrained forward pass), between SimpleITK (~11 s) / ANTs (~17 s) and IMPACT (~115 s, rigid docker config).
• NiftyReg specifics (conda-forge niftyreg 1.5.69, reg_aladin, symmetric block matching + TLS, CPU/OpenMP):
  • Different algorithmic family. No histogram MI objective: 4-voxel blocks are matched by normalised cross-correlation and the rigid transform is solved by a trimmed least squares, iterated per pyramid level (-ln 3 -maxit 15). NCC's scale invariance is what makes it cross-modality tolerant.
  • Symmetric mode matters. The default symmetric variant (optimising forward and backward transforms concurrently) is the robust one on these repositioned pairs; -noSym drifts grossly (gap std 45 mm on a clean case every other tool passes).
  • -maxit 5 (the tool default) is too coarse — on the clean case m6_26TYQI3C it reaches MI 0.41 vs 0.61 at 15 TLS iterations/level; 15 is the benchmark setting.
  • GPU is the default now (v2.1.1, -platf 1 via docker run --gpus all): ~20–25 s/case on the full volumes vs ~4 min CPU (120–440 s, -omp thread-bound) for the conda 1.5.69 build. --niftyreg-gpu -1 forces the CPU platform (-platf 0).
  • Version note. The upstream KCL-BMEIS release binaries (v2.x) need glibc ≥ 2.34; this host (Ubuntu 20.04, glibc 2.31) runs them in the niftyreg:2.1.1-ubuntu Docker image (nvidia/cuda ubuntu22.04 base; the CUDA plugin needs libcusolver.so.11, provided by the image). The conda-forge 1.5.69 build remains as the no-Docker fallback and gives essentially identical poses (MI matches to ±0.001 on the 10 cases).
• Elastix specifics (ITK-Elastix 0.25.4, elastix 5.3.1, in-process python API — no CLI binary involved):
  • Elastix 5.x renamed components vs the classic parameter files: the rigid 3D transform is EulerTransform (6-DOF, Rigid3DTransform is gone from the component set), the metric key is Metric (not ImageMetric), the random sampler is Random (not RandomSampler). The adapter uses the 5.x names and is not compatible with elastix ≤ 4.x parameter files.
  • AutomaticTransformInitialization "true" (CenterOfGravity) provides the start (no manual centroid_offset); AutomaticScalesEstimation sets the optimizer scales. An output directory is still set (SetOutputDirectory) for the C++ filter to run; the adapter uses a scratch dir under data/m6reg/elastix/itkelastix/.
  • WriteResultImage must be the string "false" (Python False); the default (absent) makes the filter raise "Could not read result image" after a successful registration.
• With fixed=T1c/moving=CT the combination transform is T1c→CT — the contract direction — so fix_orientation keeps it as-is (auto_inverted: False). The result is recovered by point-mapping (GetCombinationTransform().TransformPoint) into an affine — independent of elastix's Euler-angle parameterization — and wrapped in a SimpleITK AffineTransform(3).
  • Benchmark budget: MaximumNumberOfIterations 2000 per resolution (ASGD 2000/2000/2000 over 3 resolutions) with the sampler/metric at their defaults (NumberOfSpatialSamples 5000, NumberOfHistogramBins 32).
• IMPACT specifics (Docker vboussot/elastix_impact, Elastix 5.2 + IMPACT metric, GPU; rigid MIND+TS static config of the MR_CT_TS reference map):
  • Runs on M6 with the T1c-fixed direction + relaxed sample-validity gate. Full volumes, no mask, no crop / pad, fixed=T1c/moving=CT (the shared rule): the metric's samples (drawn from the tight T1c head crop) map mostly inside the large CT head-neck FOV, so the gate rarely fires. The map still sets RequiredRatioOfValidSamples 0.1 (build default 0.25) as a safety override — a genuinely diverging transform, <10% in-buffer, still aborts. The combination Euler transform comes out in the contract direction (completed runs report auto_inverted: False).
  • Auto init. AutomaticTransformInitialization (CenterOfGravity) aligns the intensity centroids (no manual translation); the reference map's GeometricalCenter start is too crude for the head+neck FOV mismatch.
  • Rigid, like every other pipeline. The reference map's RecursiveBSpline + bending-energy regularizer is replaced by a 6-DOF EulerTransform (the bending penalty is zero for a rigid transform).
  • History: single-init convergence. The semantic landscape has more local minima than Mattes-MI. The T1c-fixed direction fixes most of the hard cases (the repositioned m6_22IRRKU6 / m6_23XIMO4M now register as well as the MI tools do), but the single CenterOfGravity start on the ~30° tilt pair m6_2BBN5XA4 remains a weakness — a multi-start tilt grid (as production SimpleITK uses) would be the next step.
  • Stochastic. The config is Static mode: it re-samples spatial coordinates every iteration, but the feature maps are deterministic given the pose (see Stochasticity). The older Jacobian-mode configs (docker-era experiments, archived in results/bench_registration/impact_*.json) resampled patches through the network each iteration, so their per-case numbers are one sample from a distribution.
  • Models are under the data root, not the repo. The TorchScript feature models live in data/impact_models/ (MIND ~15 KB + TS ~200 MB each, from HF VBoussot/impact-torchscript-models); the pipeline raises with the exact curl commands if one is missing.
  • CPU fallback: --impact-gpu -1 (ImpactGPU -1, mixed precision off — much slower).