VBoussot/ImpactReg

IMPACT-Reg — Multimodal Medical Image Registration

Robust multimodal (MR / CT / CBCT) deformable registration presets, built with KonfAI. Alignment is driven by the IMPACT semantic similarity metric — deep features from pretrained segmentation / foundation models (MIND, TotalSegmentator, anatomix) — so cross-modality pairs align while the deformation stays smooth and physically plausible.

Each preset is a self-contained KonfAI app that writes one output: the DisplacementField on the fixed grid (Transform.h5, an ITK displacement field mapping a fixed point to its moving partner, in mm). impact-reg-konfai register derives the moved image from it, and ensembles presets by averaging their fields into one transform.

Versions

main follows the latest impact-reg-konfai. Since the 1.8.7 presets came back to main, impact-reg-konfai 1.8.6 and older cannot read it (their FireANTs presets need integrator_n): update to 1.8.7 or later, or pin this repository to 06efc39, the last commit for 1.8.6 (for example KONFAI_IMPACTREG_REPO=VBoussot/ImpactReg@06efc39). konfai-apps 1.8.7 and later resolve an unpinned reference to the tag of their own version, so they are not affected.

🧩 Presets

Preset	Pair	Engine	Description
Generic_Rigid	any	elastix	Rigid alignment (mutual information, multi-resolution)
Generic_Rigid_BSpline	any	elastix	Rigid, then B-spline deformable refinement
Elastix_IMPACT_Jacobian	CT/CBCT	elastix + IMPACT	A rigid (MI) stage, then a B-spline on early TS/M730 layers, differentiated through the network (Jacobian)
Elastix_IMPACT_Static	MR/CT	elastix + IMPACT	A rigid (MI) stage, then a B-spline on MIND and TS/M730 (last decoder layer at the coarse levels, segmentation head at the fine ones), features extracted once (Static)
ConvexAdam_Coarse	any	itk-impact (native)	Global coarse coupled-convex initialisation on MIND features
ConvexAdam_Composite	any	itk-impact (native)	The same coarse pass followed by the Adam refinement, in one app
ConvexAdam_IMPACT_CBCT	CT/CBCT	itk-impact (native)	The same pipeline on the second layer of TotalSegmentator MR (TS/M730)
ConvexAdam_IMPACT_MRCT	MR/CT	itk-impact (native)	The same pipeline on the last decoder layer of TS/M730 (soft Dice) and MIND, more regularised
FireANTs_SyN	any	FireANTs (native)	Rigid + Affine + deformable — SyN or Greedy via deformable_method (Riemannian Adam, GPU)
FireANTs_IMPACT	CT/CBCT	FireANTs + IMPACT	Rigid + Affine + SyN driven by the IMPACT deep-feature metric (multi-model, GPU)
FireANTs_Anatomix	any	FireANTs + IMPACT	The anatomix pipeline: anatomix + MIND features registered as feature volumes (Static), each reduced to its main components (GPU)
FireANTs_IMPACT_MRCT	MR/CT	FireANTs + IMPACT	Rigid + Affine + SyN on the last decoder layer of TS/M730 and MIND, extracted once and reduced to their main components (Static, GPU)

Inputs: Fixed, Moving, and optional FixedMask / MovingMask (restrict the metric region).

🚀 Usage

pip install impact-reg-konfai
# Register a moving image onto a fixed image (ensemble several presets by listing them):
impact-reg-konfai register ConvexAdam_Composite -f fixed.nii.gz -m moving.nii.gz -o ./Output --gpu 0

• Generic runner (single preset): konfai-apps infer VBoussot/ImpactReg:ConvexAdam_Composite -i fixed.nii.gz -i moving.nii.gz -o output/ writes the displacement field only.
• Interactive: SlicerImpactReg — a 3D Slicer extension driving these presets.

The ConvexAdam_* presets depend on itk-impact, whose wheels are built against torch 2.12: install it alongside (pip install impact-reg-konfai "torch==2.12.*"). An app's requirements never replace the torch already installed.

The FireANTs_* presets depend on fireants (installed at resolve time; a GPU is recommended, the CPU works but is slow). FireANTs is distributed under the FireANTs License v1.0 — this app calls its public API without copying its source, and ships its license and citation in each preset's NOTICE; please cite FireANTs if you use them. FireANTs_IMPACT and FireANTs_Anatomix additionally drive the deformable stage with the KonfAI IMPACT metric, fetching their feature models from VBoussot/impact-torchscript-models.

🩻 In 3D Slicer

SlicerImpactReg runs these presets on the volumes of a Slicer scene: fixed and moving images, optional masks, several presets ensembled in one run, the moved image and the transform loaded back into the scene, then an evaluation panel (MAE against a reference image, Dice against reference segmentations, TRE on paired landmarks) and an uncertainty map from the spread of the ensemble.

🎥 Walkthrough video (with captions) and its step-by-step tutorial, on an abdomen MRI/CT pair of the public SynthRAD2025 dataset.

On that pair, rigidly aligned by the challenge, the ensemble of ConvexAdam_Composite, FireANTs_Anatomix and Elastix_IMPACT_Static brings the mean Dice of eight organs from 0.65 to 0.83 and their landmark error from 11.2 to 6.1 mm. The time, Dice and landmark error of each preset are in the SlicerImpactReg README.

⚡ Performance & VRAM

Measured with impact-reg-konfai register on nine public datasets (Learn2Reg's AbdomenMRCT, ThoraxCBCT, AbdomenCTCT and OASIS, Lung250M-4B, BraTS-Reg and three SynthRAD2025 tasks: MR/CT, CBCT/CT, CT/CT and MR/MR pairs of 6 to 33 million voxels), one case at a time on an NVIDIA RTX PRO 5000 Blackwell Laptop GPU (24 GB). The time is the whole call, start-up, model loading and writing included; the VRAM is the peak of its processes, PyTorch's cache included, so a preset that finds a free card fills more of it than it needs.

Preset	Time per case	Peak VRAM
Generic_Rigid	6 s to 13 s	1.8 to 5.6 GB
Generic_Rigid_BSpline	8 s to 20 s	1.8 to 5.6 GB
Elastix_IMPACT_Static	53 s to 2 min	1.9 to 12.8 GB
Elastix_IMPACT_Jacobian	4 min to 6 min	2.1 to 5.4 GB
ConvexAdam_Coarse	20 s to 2 min	1.8 to 8.0 GB
ConvexAdam_Composite	20 s to 2 min	2.0 to 9.4 GB
ConvexAdam_IMPACT_CBCT	26 s to 56 s	6.8 to 17.3 GB
ConvexAdam_IMPACT_MRCT	24 s to 47 s	7.9 to 23.0 GB
FireANTs_SyN	22 s to 4 min	6.4 to 20.5 GB
FireANTs_IMPACT	62 s to 24 min	16.2 to 23.3 GB
FireANTs_Anatomix	31 s to 5 min	10.7 to 22.9 GB
FireANTs_IMPACT_MRCT	57 s to 11 min	9.9 to 21.2 GB

How accurate each preset is on each pair, and which one to start from: the presets page.

🧩 Large volumes

A pair that fits the device registers whole. A larger one is registered at its native resolution, in tiles, by impact-reg-konfai register and by SlicerImpactReg, which runs it. Each preset states what one voxel costs it on the GPU, whole and in a tile (vram_bytes_per_voxel and tiling in its app.json); on the CPU the same figures are read against half the RAM left:

1. The preset (Prediction.yml, patch mode: resample) runs once on the whole pair, which KonfAI resamples onto a grid just coarse enough to fit and whose field it brings back onto the native fixed grid: rigid, affine and deformable stay one global registration.
2. The moving image goes through that result onto the native fixed grid, streamed.
3. The preset's deformable stage alone (Prediction_tile.yml) refines it on native tiles, blended over their overlap with a cosine window. KonfAI cuts the tiles (patch mode: tile) to what the device holds, sized before the run. A tile the fixed mask does not reach gets a zero field without running.
4. The two fields are composed on the native grid.

Generic_Rigid, ConvexAdam_Coarse, ConvexAdam_IMPACT_MRCT and the two elastix IMPACT presets stop after step 1: their result is resampled onto the native grid. The elastix IMPACT features are computed at their model's own voxel size, a few millimetres: registered again on native tiles, they added deformation rather than detail (on an abdomen MRI/CT pair, Elastix_IMPACT_Static missed the organ landmarks by 12.2 mm that way, 10.0 mm global only, 9.2 mm whole).

On two ExaSPIM mouse brains at 80 µm (257 × 665 × 887 voxels), FireANTs_SyN then reaches a correlation of 0.68 in 6 min 19 s on a 24 GB GPU, where cutting the pair into patches that each fit their own rigid and affine gave 0.62 in 16 min 24 s.

Every Prediction.yml leaves its patch free (patch_size: [0, 0, 0], mode: resample) and is never cut: with --max-voxels 0, or through the generic konfai-apps infer, KonfAI resamples a pair that runs out of memory onto a coarser grid and runs it again whole. --patch-size forces a size. The elastix + IMPACT presets also retry their IMPACT features on smaller patches by themselves when the whole image does not fit the GPU.

🔗 Links & Citation

• 🧠 KonfAI: github.com/vboussot/KonfAI
• 📦 PyPI: impact_reg_konfai
• 🩻 Slicer: SlicerImpactReg
• 📄 Paper: KonfAI — arXiv:2508.09823
• 🧬 anatomix (used by FireANTs_Anatomix): github.com/neel-dey/anatomix — Dey et al., AnatomiX: Anatomy-Aware Multimodal Registration, 2024 (MIT). See FireANTs_Anatomix/NOTICE.
• 🔥 FireANTs (used by the FireANTs_* presets): github.com/rohitrango/FireANTs — Jena et al., FireANTs: Adaptive Riemannian Optimization for Multi-Scale Diffeomorphic Registration, Nature Communications, 2024. See FireANTs_SyN/NOTICE for the full citation and license.