multimodars 0.3.0__tar.gz → 0.3.2__tar.gz

{multimodars-0.3.0 → multimodars-0.3.2}/.github/workflows/CI.yml

@@ -19,6 +19,31 @@ permissions:
   contents: read
 
 jobs:
+  notebook-tests:
+    name: Notebook tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.12.x
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+      - name: Install system dependencies
+        # pymeshlab loads MeshLab filter plugins as shared libraries at import time via
+        # load_default_plugins(). On bare Linux runners this requires libopengl0 to be
+        # present; without it the call silently fails (PyMeshLabException is caught in
+        # pymeshlab's __init__.py) and MeshSet is left with no filter methods, causing
+        # AttributeError on any filter call such as meshing_close_holes().
+        run: sudo apt-get install -y libopengl0
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[meshlab]'
+          pip install --group dev
+      - name: Run notebook tests
+        run: pytest --nbmake docs/notebooks/
+
   python-compat:
     name: Python ${{ matrix.python-version }} compatibility
     runs-on: ubuntu-latest
@@ -27,8 +52,8 @@ jobs:
       matrix:
         python-version: ['3.10', '3.11', '3.12', '3.13']
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install Rust
@@ -36,7 +61,8 @@ jobs:
       - name: Install Python deps
         run: |
           python -m pip install --upgrade pip
-          pip install -e .[test]
+          pip install -e .
+          pip install --group test
       - name: Run Python tests
         run: pytest
 
@@ -50,16 +76,17 @@ jobs:
           - runner: ubuntu-latest
             target: aarch64
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: 3.12.x
 
       - name: Install Python deps
         run: |
           python -m pip install --upgrade pip
-          pip install -e .[test,docs,maturin]
+          pip install -e .
+          pip install --group test
 
       - name: run Python tests
         run: pytest
@@ -102,14 +129,15 @@ jobs:
           - runner: ubuntu-latest
             target: armv7
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
         with:
           python-version: 3.12.x
       - name: Install Python deps
         run: |
           python -m pip install --upgrade pip
-          pip install -e .[test,docs,maturin]
+          pip install -e .
+          pip install --group test
       - name: run Python tests
         run: pytest
       - name: Format Python code
@@ -139,15 +167,16 @@ jobs:
           - runner: windows-latest
             target: x64
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
         with:
           python-version: 3.12.x
           architecture: ${{ matrix.platform.target }}
       - name: Install Python deps
         run: |
           python -m pip install --upgrade pip
-          pip install -e .[test,docs,maturin]
+          pip install -e .
+          pip install --group test
       - name: run Python tests
         run: pytest
       - name: Format Python code
@@ -179,14 +208,15 @@ jobs:
             target: aarch64
             arch: arm64
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
         with:
           python-version: 3.12.x
       - name: Install Python deps
         run: |
           python -m pip install --upgrade pip
-          pip install -e .[test,docs,maturin]
+          pip install -e .
+          pip install --group test
       - name: run Python tests
         run: pytest
       - name: Format Python code
@@ -210,7 +240,7 @@ jobs:
   sdist:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Build sdist
         uses: PyO3/maturin-action@v1
         with:

{multimodars-0.3.0 → multimodars-0.3.2}/.gitignore

@@ -5,7 +5,19 @@
 /paper/old
 .VSCodeCounter
 /test
-/examples
+examples/__pycache__/
+examples/logs/
+examples/data/output/
+examples/data/test/
+examples/data/logs/
+# generated/intermediate STL outputs in data root
+examples/data/all.stl
+examples/data/all_wall.stl
+examples/data/fixed_mesh.stl
+examples/data/prefixed_mesh.stl
+examples/data/lca.stl
+examples/data/rca.stl
+examples/data/aorta.stl
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

multimodars-0.3.2/.readthedocs.yaml

@@ -0,0 +1,19 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    rust: "latest"
+  jobs:
+    post_create_environment:
+      - "$READTHEDOCS_VIRTUALENV_PATH/bin/pip install maturin sphinx sphinx-rtd-theme sphinx-autodoc-typehints myst-nb plotly furo"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - method: pip
+      path: .

{multimodars-0.3.0 → multimodars-0.3.2}/CHANGELOG.md

@@ -3,6 +3,56 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.3.2] - 2026-05-05
+
+### Added
+- Benchmark suite (`benchmarks/`) with two scripts: `benchmark_bruteforce_stepsize.py`
+  (step-size scaling, `from_file_full`) and `benchmark_cpu_scaling.py` (core-count
+  scaling, `from_array_single`). Results saved to `benchmarks/results/`.
+- Benchmark documentation page (`docs/benchmark.rst`) with result figures and table,
+  linked in the ReadTheDocs table of contents.
+
+### Changed
+- `paper/paper.md` Performance section updated with quantified benchmark results and
+  corrected parallelisation description.
+
+### Performance
+- Intra-pullback alignment (`search_range`) now parallelises over candidate rotation
+  angles via `par_iter` instead of the point-rotation loop. The inner cost-function
+  loop is now sequential. This provides enough rayon tasks per frame step to saturate
+  all cores: bruteforce scales 6.5× and optimised 4.2× from 2 to 16 cores (previously
+  ~1.4× for both). Combined algorithmic + parallelisation gain reaches **38.5×** vs.
+  brute-force at 2 cores.
+
+## [0.3.1] - 2026-05-04
+
+### Added
+- Example data and Jupyter notebooks are now included directly in the repository under
+  `examples/` — no longer distributed as a release attachment. Both tutorials link to
+  the `examples/` directory and cross-reference the rendered notebook pages.
+- CCTA and intravascular Jupyter notebooks (`docs/notebooks/`) are now rendered and served
+  in the documentation via `myst-nb`, accessible as `:doc:` references from the tutorials.
+- Detailed explanation of the rolling-sphere and ray-casting labeling algorithms added to
+  the CCTA tutorial, including annotated figures.
+
+### Changed
+- README condensed: developer-setup section added, key workflow images included, installation
+  and quickstart sections tightened.
+- `plotly` added as a documentation dependency for interactive notebook figures.
+- Improved all print statements in the whole package.
+
+### Fixed
+- CI pipeline now correctly installs optional dependency groups required for the full test
+  suite.
+- Notebook tests no longer fail with `AttributeError: MeshSet has no attribute
+  'meshing_close_holes'` on bare Linux runners. pymeshlab silently skips plugin loading when
+  `libopengl0` is absent, leaving `MeshSet` with no filter methods; the CI now installs
+  `libopengl0` before the notebook test job runs.
+
+### Performance
+- Rust labeling step migrated to `par_iter()` for parallel vertex classification, reducing
+  wall time on large meshes.
+
 ## [0.3.0] - 2026-04-30
 
 ### Added

{multimodars-0.3.0 → multimodars-0.3.2}/Cargo.lock

@@ -191,6 +191,19 @@ version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3d7b894f5411737b7867f4827955924d7c254fc9f4d91a6aad6b097804b1018b"
 
+[[package]]
+name = "console"
+version = "0.15.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "054ccb5b10f9f2cbf51eb355ca1d05c2d279ce1804688d0db74b4733a5aeafd8"
+dependencies = [
+ "encode_unicode",
+ "libc",
+ "once_cell",
+ "unicode-width",
+ "windows-sys",
+]
+
 [[package]]
 name = "core2"
 version = "0.4.0"
@@ -298,6 +311,12 @@ version = "1.15.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
 
+[[package]]
+name = "encode_unicode"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34aa73646ffb006b8f5147f3dc182bd4bcb190227ce861fc4a4844bf8e3cb2c0"
+
 [[package]]
 name = "equator"
 version = "0.4.2"
@@ -575,6 +594,19 @@ dependencies = [
  "hashbrown",
 ]
 
+[[package]]
+name = "indicatif"
+version = "0.17.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "183b3088984b400f4cfac3620d5e076c84da5364016b4f49473de574b2586235"
+dependencies = [
+ "console",
+ "number_prefix",
+ "portable-atomic",
+ "unicode-width",
+ "web-time",
+]
+
 [[package]]
 name = "indoc"
 version = "2.0.6"
@@ -617,6 +649,16 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "js-sys"
+version = "0.3.82"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b011eec8cc36da2aab2d5cff675ec18454fad408585853910a202391cf9f8e65"
+dependencies = [
+ "once_cell",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "lebe"
 version = "0.5.3"
@@ -711,13 +753,14 @@ dependencies = [
 
 [[package]]
 name = "multimodars"
-version = "0.3.0"
+version = "0.3.2"
 dependencies = [
  "anyhow",
  "approx",
  "crossbeam",
  "csv",
  "image",
+ "indicatif",
  "nalgebra",
  "pyo3",
  "rayon",
@@ -848,6 +891,12 @@ dependencies = [
  "autocfg",
 ]
 
+[[package]]
+name = "number_prefix"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "830b246a0e5f20af87141b25c173cd1b609bd7779a4617d6ec582abaf90870f3"
+
 [[package]]
 name = "once_cell"
 version = "1.21.3"
@@ -1341,6 +1390,12 @@ version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5a5f39404a5da50712a4c1eecf25e90dd62b613502b7e925fd4e4d19b5c96512"
 
+[[package]]
+name = "unicode-width"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
+
 [[package]]
 name = "unindent"
 version = "0.2.4"
@@ -1412,6 +1467,16 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "web-time"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "weezl"
 version = "0.1.11"
@@ -1428,6 +1493,79 @@ dependencies = [
  "safe_arch",
 ]
 
+[[package]]
+name = "windows-sys"
+version = "0.59.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
+dependencies = [
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
+dependencies = [
+ "windows_aarch64_gnullvm",
+ "windows_aarch64_msvc",
+ "windows_i686_gnu",
+ "windows_i686_gnullvm",
+ "windows_i686_msvc",
+ "windows_x86_64_gnu",
+ "windows_x86_64_gnullvm",
+ "windows_x86_64_msvc",
+]
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
+
 [[package]]
 name = "winnow"
 version = "0.7.13"

{multimodars-0.3.0 → multimodars-0.3.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "multimodars"
-version = "0.3.0"
+version = "0.3.2"
 edition = "2021"
 license = "MIT"
 readme = "README.md"
@@ -20,3 +20,4 @@ rayon = "1.7.1"
 crossbeam = "0.8.4"
 anyhow = "1.0.100"
 approx = "0.5"
+indicatif = "0.17"

multimodars-0.3.2/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: multimodars
+Version: 0.3.2
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: License :: OSI Approved :: MIT License
+Requires-Dist: numpy>=2.0.0,<3.0.0
+Requires-Dist: trimesh>=4.8.0
+Requires-Dist: scipy>=1.15.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: pymeshlab>=2023.12 ; extra == 'meshlab'
+Requires-Dist: pyglet<2 ; extra == 'viz'
+Provides-Extra: meshlab
+Provides-Extra: viz
+License-File: LICENSE
+Summary: A Rust-powered cardiac multi-image modality fusion package
+Author: Anselm W. Stark
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/yungselm/multimoda-rs
+Project-URL: Issues, https://github.com/yungselm/multimoda-rs/issues
+
+<p align="center">
+  <a href="https://github.com/yungselm/multimoda-rs">
+    <img
+      src="https://raw.githubusercontent.com/yungselm/multimoda-rs/main/media/multimoda-rs.jpg"
+      alt="multimoda-rs logo"
+    >
+  </a>
+</p>
+
+[![PyPI](https://img.shields.io/pypi/v/multimodars.svg)](https://pypi.org/project/multimodars)
+[![License](https://img.shields.io/pypi/l/multimodars.svg)](LICENSE)
+[![Docs](https://img.shields.io/readthedocs/multimoda-rs)](https://multimoda-rs.readthedocs.io)
+[![Tests and Build](https://github.com/yungselm/multimoda-rs/actions/workflows/CI.yml/badge.svg)](https://github.com/yungselm/multimoda-rs/actions/workflows/CI.yml)
+[![status](https://joss.theoj.org/papers/24992cb138d85b0bf08f01bc2b384a80/status.svg)](https://joss.theoj.org/papers/24992cb138d85b0bf08f01bc2b384a80)
+
+
+<figure class="epigraph" style="text-align: center; font-style: italic;">
+  <blockquote>
+    "One package to fuse them all."
+  </blockquote>
+  <figcaption>— <cite>The Lord of the Rings (probably)</cite></figcaption>
+</figure>
+
+---
+
+> 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](https://github.com/AI-in-Cardiovascular-Medicine/AIVUS-CAA) format) or raw NumPy arrays.
+
+## Installation
+
+```bash
+pip install multimodars
+```
+
+Optional extras:
+
+```bash
+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](https://multimoda-rs.readthedocs.io/en/latest/installation.html).
+
+## Quick Example
+
+Checkout our **[Documentation](https://multimod-rs.readthedocs.io/en/latest)** for in-depth explanations of the functionality and preloaded notebooks including 3D plots. Otherwise clone the repo to follow along the different examples:
+
+```python
+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,
+    aortic_ref_pt=(12.2605, -201.3643, 1751.0554),
+    upper_ref_pt=(11.7567, -202.1920, 1754.7975),
+    lower_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:
+
+![Dynamic lumen changes](https://raw.githubusercontent.com/yungselm/multimoda-rs/main/media/dynamic_lumen_changes.png)
+
+**2. Inter-pullback alignment** — registered pullbacks (rest vs. stress, diastole vs. systole) are aligned against each other to reveal stress-induced and pulsatile deformation:
+
+![Stress-induced diastolic lumen deformation](https://raw.githubusercontent.com/yungselm/multimoda-rs/main/docs/figures/animation_stress_induced_systolic_deformation.gif)
+
+**3. CCTA labeling** — the CCTA-derived geometry is automatically segmented by vessel region (aorta, RCA, LCA, intramural) to prepare it for fusion:
+
+![Initial CCTA labeling](https://raw.githubusercontent.com/yungselm/multimoda-rs/main/docs/figures/initial_labeling.jpg)
+
+**4. CCTA–morphing** — the labeled CCTA geometry is morphed along the centerline to match the high-resolution intravascular geometry:
+
+![CCTA scaling](https://raw.githubusercontent.com/yungselm/multimoda-rs/main/docs/figures/scaling.jpg)
+
+**5. CCTA/intravascular fusio** — the morphed CCTA geometry is stitched to the intravascular geometry, replacing a section with a high resolution verison:
+
+![CCTA fusion](https://raw.githubusercontent.com/yungselm/multimoda-rs/main/docs/figures/concept.jpg)
+
+## Documentation
+
+Full documentation — installation, step-by-step tutorials, interactive (preloaded) Jupyter notebooks, and API reference — is available at **[multimoda-rs.readthedocs.io](https://multimoda-rs.readthedocs.io)**.
+
+## License
+
+Distributed under the MIT License. See [LICENSE](LICENSE) for details.
+
+## Citation
+
+Please kindly cite the following paper if you use this repository.
+
+```
+@article{stark2025multimodars,
+  title     = {multimodars: A Rust-powered toolkit for multi-modality cardiac image fusion and registration},
+  author    = {Stark, Anselm W. and Ilic, Marc and Mokhtari, Ali and Mohammadi Kazaj, Pooya and Graeni, Christoph and Shiri, Isaac},
+  journal   = {arXiv preprint arXiv:2510.06241},
+  year      = {2025}
+}
+```
+
+Stark, Anselm W., Marc Ilic, Ali Mokhtari, Pooya Mohammadi Kazaj, Christoph Graeni, and Isaac Shiri. "multimodars: A Rust-powered toolkit for multi-modality cardiac image fusion and registration." arXiv preprint arXiv:2510.06241 (2025).
+