IMPACT-Reg-KonfAI

Fast and lightweight CLI for multimodal medical image registration using IMPACT-Reg presets within the KonfAI framework.

🧩 Overview

IMPACT-Reg-KonfAI is the command-line interface (CLI) for running IMPACT-Reg registration presets published in the VBoussot/ImpactReg Hugging Face repository, through the KonfAI deep learning framework.

IMPACT-Reg introduces a semantic similarity metric for multimodal registration, driven by deep features extracted from large pretrained segmentation and foundation models (TotalSegmentator, MIND, anatomix). The presets run it in three registration engines, elastix, ConvexAdam (through itk-impact) and FireANTs, beside intensity-based presets for pairs of the same modality.

A registration run combines:

• fixed and moving images
• one or more registration presets resolved from the published preset database (each preset is a KonfAI app)
• optional image, segmentation, or landmark references (with an optional mask) for evaluation

🧠 Features

• ⚡ Fast registration powered by KonfAI
• 🤗 Automatic preset, parameter-map, and model download from Hugging Face
• 🧩 Multi-preset ensembling (transforms averaged into a single displacement field)
• 📏 Large images: a pair too large for the memory is registered whole on a grid sized to fit, then refined on native tiles by the presets that declare a tile pass; the outputs are on the native fixed grid
• 🧠 Semantic IMPACT metric on deep features from pretrained segmentation / foundation models
• 📐 Evaluation workflows against image, segmentation, and landmark references
• 🧾 Multi-format compatibility: every format ITK reads, DICOM series, and OME-Zarr stores (the moved image comes back in the moving image's own format)

🗂️ Available presets

Each preset is a KonfAI app on VBoussot/ImpactReg, downloaded with its parameters and models on first use, and passed to register by name. List them with:

impact-reg-konfai list

Every deformable preset aligns the pair rigidly or affinely first, so a pair that starts centimetres apart needs no separate rigid run. impact-reg-konfai show NAME says what a preset runs, needs and tunes, and the presets page which one suits which pair, with the benchmark behind that advice.

Give the CT a body mask (--fixed-mask) whenever it shows what the other image does not: a table, a head rest, a field of view past the MRI's. A deformable stage otherwise pulls the moving image onto them.

🚀 Installation

From PyPI:

python -m pip install impact-reg-konfai

The ConvexAdam presets run on itk-impact, whose wheels are built against torch 2.12: install that torch alongside, python -m pip install impact-reg-konfai "torch==2.12.*". A preset's requirements never replace the torch you have. The first elastix preset downloads the elastix-IMPACT binary (and, when your torch is another version than the one it was built with, the matching LibTorch), the first FireANTs preset installs fireants; see Installation, caches and troubleshooting.

From source:

git clone https://github.com/fideus-labs/KonfAI.git
cd KonfAI
# konfai and konfai-apps must come from the same checkout: this app pins both to its own
# setuptools_scm version, which only exists on PyPI at a release tag.
python -m pip install -e . -e konfai-apps -e apps/impact_reg

⚙️ Usage

The CLI is organised into sub-commands, matching the registration workflow:

Register a moving image onto a fixed image (ensemble several presets by listing them):

impact-reg-konfai register <PRESET> [<PRESET_2> ...] -f fixed.nii.gz -m moving.nii.gz -o ./Output --gpu 0
# an MRI onto a CT, with the CT's body mask:
impact-reg-konfai register Elastix_IMPACT_Static -f ct.nii.gz -m mr.nii.gz --fixed-mask ct_body.nii.gz -o ./Output --gpu 0

Each case gets its transform, Output/P000/Transform.h5 (an ITK displacement field on the fixed grid mapping a fixed point to its moving partner, in mm), and the moving image resampled through it, Output/P000/Moved.<ext>. OME-Zarr stores go in and come out the same way:

impact-reg-konfai register FireANTs_SyN -f fixed.ome.zarr -m moving.ome.zarr -o ./Output --gpu 0

Evaluate a registration on any subset of modalities, always from the original moving data (the transform warps it); without --transform it scores the pair as it came:

impact-reg-konfai eval \
  --transform ./Output/P000/Transform.h5 \
  -f fixed.nii.gz -m moving.nii.gz --mask roi.nii.gz \
  --gt-fixed-seg fixed_seg.nii.gz --gt-moving-seg moving_seg.nii.gz \
  --gt-fixed-fid fixed.fcsv --gt-moving-fid moving.fcsv \
  -o ./Output --gpu 0

Warp a label map of the moving image onto the fixed one:

impact-reg-konfai apply --transform ./Output/P000/Transform.h5 -f fixed.nii.gz -i moving_labels.nii.gz --labels -o ./Output/P000

Estimate uncertainty from the per-preset displacement fields written by register:

impact-reg-konfai register <PRESET_1> <PRESET_2> -f fixed.nii.gz -m moving.nii.gz -o ./Output --gpu 0 --keep-fields
impact-reg-konfai uncertainty --dvf ./Output/P000/Ensemble/*.h5 -o ./Output/P000

register arguments

eval arguments (at least one modality required)

uncertainty arguments

See the full help of any sub-command with:

impact-reg-konfai register --help

📖 Documentation and tutorials

• How it works: the transform, the IMPACT features, the three engines.
• The presets: what each runs, which one for which pair, the benchmark.
• Parameters: what to tune when a registration falls short, with --set.
• Large images: native tiles, memory, disk.
• Evaluation: MAE, Dice, TRE, the Jacobian, ensembles and their spread.
• Installation, caches and troubleshooting, and architecture for contributors.
• Tutorials: seven runnable scripts, from a first registration to large images and ensembles, on public data with a known transform.

📏 Large images

A pair of any size is registered with no option to set. Each preset declares what a voxel costs it on the GPU and in RAM, and KonfAI sizes the run from the GPU memory free when it starts and from the RAM budget, whichever holds fewer voxels. A pair that fits is registered in one piece, at native resolution. A larger one runs in two passes:

1. Global pass: the whole preset runs on the pair resampled onto a grid coarse enough to fit, and its field comes back onto the native fixed grid.
2. Tile pass: the preset's deformable stage refines that result on native tiles, and the two fields are composed. Presets without a deformable stage worth refining locally stop after the global pass.

[ImpactReg] FireANTs_SyN: 257 x 665 x 887 voxels, more than the 19,636,779 it registers whole on this GPU: the preset
on the whole pair resampled to fit, then its deformable stage on native tiles of at most 17,705,407 voxels.

Everything around the presets is streamed, outputs included (.mha, .nii, .nii.gz, .nrrd, OME-Zarr). Pin --max-voxels for reproducible runs. SlicerImpactReg is not streamed: it loads the moved image and, for uncertainty, every preset's field whole. Details, disk and RAM: Large images.

⚡ Performance

Two mouse brains imaged by ExaSPIM light-sheet microscopy at the Allen Institute for Neural Dynamics (specimens 841260, fixed, and 823508, moving, from the public aind-open-data bucket), registered from OME-Zarr to OME-Zarr at three levels of their pyramid on one NVIDIA RTX PRO 5000 Blackwell Laptop GPU (24 GB), with at most 64 GB of RAM, in a fresh environment as pip installs it. The time is the whole register command, the moved image at native resolution included; the tiles are those of Large images, for a pair larger than what the preset registers whole.

Registration takes the correlation between the two brains, inside the fixed brain, from 0.27 to 0.65–0.70 with ConvexAdam_Composite and the FireANTs presets, and the Dice of the two brains from 0.71 to 0.94–0.95, at every size; Generic_Rigid alone reaches 0.52–0.54 (Dice 0.89), Generic_Rigid_BSpline 0.56–0.58 (0.91–0.92). At 40 µm, FireANTs_IMPACT and FireANTs_Anatomix would take about a hundred and a hundred and fifty tiles: at the time a tile takes them at 80 µm, some four and two hours, not run here. The process tree peaks under 17 GB of RAM at 80 µm and between 25 and 39 GB at 40 µm, where KonfAI streams what it resamples and composes within the memory it finds; the intermediates of a tiled run at 40 µm take up to 78 GB of disk, which register checks before it starts.

The elastix IMPACT presets compare TotalSegmentator features at 2 to 6 mm voxels, a scale made for human MRI/CT and CT/CBCT pairs, where a mouse brain is a few voxels across: they are not run here. How accurate each preset is on human MRI/CT, CBCT/CT, CT/CT and MRI/MRI pairs, on nine public datasets: the presets page.

📦 Notes

• Available presets are resolved dynamically from the published IMPACT-Reg preset database.
• Multiple presets can be provided in one command; their displacement fields are averaged into a single field.
• The wrapper orchestrates the preset KonfAI apps (model inference), then ensembles, evaluates, and estimates uncertainty on their outputs.
• SlicerImpactReg runs the same register from 3D Slicer, and KonfAI Studio from its assistant: konfai-mcp's run_app (action infer) on a preset runs register, and run_registration_evaluate runs eval.

📚 References

If you use IMPACT-Reg-KonfAI in your work, please cite KonfAI and the IMPACT-Reg paper.

• Boussot, V., Hémon, C., Nunes, J.-C., Dowling, J., Rouzé, S., Lafond, C., Barateau, A., & Dillenseger, J.-L. IMPACT-Reg: A Generic Semantic Loss for Multimodal Medical Image Registration.

• Boussot, V., & Dillenseger, J.-L. (2025). KonfAI: A Modular and Fully Configurable Framework for Deep Learning in Medical Imaging. arXiv preprint arXiv:2508.09823

🔗 Links

• 🤗 Model Hub: huggingface.co/VBoussot/ImpactReg
• 📦 PyPI Package: pypi.org/project/impact_reg_konfai
• 🧠 KonfAI Repository: github.com/fideus-labs/KonfAI
• 🧩 3D Slicer extension: github.com/vboussot/SlicerImpactReg