multimodars 0.4.0

A Rust-powered cardiac multi-image modality fusion package

"One package to fuse them all."

— The Lord of the Rings (probably)

---

A high‑performance, Rust‑accelerated toolkit for multi‑modality cardiac image fusion and registration ﮩ٨ـﮩﮩ٨ـ♡ﮩ٨ـﮩﮩ٨ـ.

---

Overview

multimoda-rs aligns and fuses diverse cardiac imaging modalities — IVUS, OCT and CCTA — into unified high-resolution 3D models. Originally developed to quantify dynamic lumen deformation in coronary artery anomalies (CAAs), it is equally applicable to longitudinal studies (e.g., pre/post-stenting) and general coronary artery disease workflows. The Rust backend parallelizes computationally intensive registration steps for speeds well beyond pure Python.

Key Features

• Intravascular Registration: align pullback sequences (rest/stress, diastole/systole) using Hausdorff distance on vessel contours and catheter centroids; four modes: full, double-pair, single-pair, single.
• Centerline Alignment: register intravascular geometries onto a CCTA-derived centerline via three-point landmark or manual rotation.
• CCTA Fusion: automatically label CCTA geometries by vessel region and morph them to match intravascular measurements.
• Flexible Input: accepts CSV files (AIVUS format) or raw NumPy arrays.

Installation

pip install multimodars

Optional extras:

pip install "multimodars[viz]"      # mesh visualisation (pyglet)
pip install "multimodars[meshlab]"  # MeshLab integration

For building from source or the full developer setup (tests, linting, docs), see the Installation guide.

Quick Example

Checkout our Documentation for in-depth explanations of the functionality and preloaded notebooks including 3D plots. Otherwise clone the repo to follow along the different examples:

import multimodars as mm
import numpy as np

# Align four intravascular phases (rest-dia, rest-sys, stress-dia, stress-sys)
rest, stress, dia, sys, _ = mm.from_file_full(
    "examples/data/ivus_rest",    # input_path_ab
    "examples/data/ivus_stress",  # input_path_cd
    write_obj=True,
    output_path_ab="output/rest",
    output_path_cd="output/stress",
    output_path_ac="output/diastole",
    output_path_bd="output/systole",
)

# Align geometry onto a CCTA-derived centerline
cl_raw = np.genfromtxt("examples/data/centerline_raw.csv", delimiter=",")
centerline = mm.numpy_to_centerline(cl_raw)
aligned_pair, cl_resampled = mm.align_three_point(
    centerline, rest,
    main_ref_pt=(12.2605, -201.3643, 1751.0554),
    counterclockwise_ref_pt=(11.7567, -202.1920, 1754.7975),
    clockwise_ref_pt=(15.6605, -202.1920, 1749.9655),
    write=True,
    output_dir="output/aligned",
)

Pipeline

1. Intrapullback alignment — frames within each pullback are co-registered to remove cardiac-motion artefacts, yielding clean diastolic and systolic geometries:

2. Inter-pullback alignment — registered pullbacks (rest vs. stress, diastole vs. systole) are aligned against each other to reveal stress-induced and pulsatile deformation:

3. CCTA labeling — the CCTA-derived geometry is automatically segmented by vessel region (aorta, RCA, LCA, intramural) to prepare it for fusion:

4. CCTA–morphing — the labeled CCTA geometry is morphed along the centerline to match the high-resolution intravascular geometry:

5. CCTA/intravascular fusio — the morphed CCTA geometry is stitched to the intravascular geometry, replacing a section with a high resolution verison:

Documentation

Full documentation — installation, step-by-step tutorials, interactive (preloaded) Jupyter notebooks, and API reference — is available at multimoda-rs.readthedocs.io.

License

Distributed under the MIT License. See LICENSE for details.

Citation

Please kindly cite the following paper if you use this repository.

@article{Stark2026, 
  doi = {10.21105/joss.10131}, 
  url = {https://doi.org/10.21105/joss.10131}, 
  year = {2026}, 
  publisher = {The Open Journal}, 
  volume = {11}, 
  number = {121}, 
  pages = {10131}, 
  author = {Stark, Anselm W. and Ilic, Marc and Mokhtari, Ali and Kazaj, Pooya Mohammadi and Gräni, Christoph and Shiri, Isaac}, 
  title = {multimodars: A Rust-powered toolkit for multi-modality cardiac image fusion and registration}, 
  journal = {Journal of Open Source Software} 
}

Stark et al., (2026). multimodars: A Rust-powered toolkit for multi-modality cardiac image fusion and registration. Journal of Open Source Software, 11(121), 10131, https://doi.org/10.21105/joss.10131.