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 (MIND, TotalSegmentator, MRSegmentator). It plugs into an Elastix-based multi-resolution deformable pipeline to achieve robust cross-modality alignment while keeping deformations smooth and physically plausible.

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)
• 🧠 Semantic IMPACT metric on deep features from pretrained segmentation / foundation models
• 📐 Evaluation workflows against image, segmentation, and landmark references
• 🧾 Multi-format compatibility: supports all major medical image formats handled by ITK

🗂️ Available presets

Presets are resolved dynamically from the published preset database (PresetDatabase.json) and passed as the first positional argument(s). Current presets include generic rigid / rigid + BSpline strategies and IMPACT-driven deformable presets tuned per modality pair (MR/CT, CBCT/CT) and anatomy (generic, head & neck).

List the presets exposed by your installation with:

impact-reg-konfai register --help

🚀 Installation

From PyPI:

python -m pip install impact-reg-konfai

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

Evaluate a registration on any subset of modalities; the transform comes from a prior register:

impact-reg-konfai eval \
  --transform ./Output/P000/DVF.mha \
  -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

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

impact-reg-konfai uncertainty --dvf ./Output/P000/Ensemble/*.mha -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

📦 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.

📚 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