vboussot/elastix_impact repository overview

⁠🐳 Usage

This Docker image provides a ready-to-use version of IMPACT⁠, a semantic similarity metric for multimodal medical image registration, implemented as a native metric in Elastix.

To use the container with your own data:

docker run --rm --gpus all \
  -v "./Data:/Data" \
  -v "./Out:/Out" \
  vboussot/elastix_impact

⁠📁 Required Folder Structure

The container expects the following files inside the Data/ directory:

• Data/Models/
  Must contain the TorchScript-exported models used by the IMPACT metric (e.g., TotalSegmentator, SAM2.1, etc.).
  👉 See Data/Models/README.md⁠ for model download instructions.

• Data/Fixed_image.mha and Data/Moving_image.mha The images used for registration. These files can be provided in either .mha or .nii.gz format.

• Data/ParameterMap.txt
  Elastix parameter file with the configuration for Impact.
  👉 See ParameterMaps/README.md⁠ for detailed configuration examples.

Optional files (for mask-based registration or evaluation):

• Data/Fixed_mask.mha and Data/Moving_mask.mha — binary masks to restrict metric computation.
• Data/Fixed_landmarks.txt and Data/Moving_landmarks.txt — optional landmarks for TRE evaluation.

Output results (transforms, logs) will be written to the mounted Out/ directory.

⁠📜 Example

To see a complete example of how to run a registration using this Docker setup, check:

👉 run_docker_impact_example.py⁠

⁠💡 Using GPU:

If you have a compatible GPU and the necessary toolkit (e.g., NVIDIA Docker support), it will be available inside the Docker container. You can select which GPU to use by setting the GPU parameter in the ParameterMap file ((Device 0), (Device 1), or (Device -1) to disable GPU usage). This enables the registration process to run on the GPU, significantly speeding up computation.

Without GPU / No Toolkit: If you don't have a GPU or the required toolkit, simply remove the --gpus all flag from the command. In this case, set (Device -1) in the Elastix parameter map to disable GPU usage and run the process on the CPU.

⁠🔗 Reference

If you use this software in your research, please cite: