multimodars 0.2.3__tar.gz → 0.3.0__tar.gz

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

@@ -226,7 +226,7 @@ jobs:
     name: Release
     runs-on: ubuntu-latest
     if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
-    needs: [linux, musllinux, windows, macos, sdist]
+    needs: [linux, musllinux, windows, macos, sdist, python-compat]
     permissions:
       id-token: write
       contents: write

multimodars-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,52 @@
+repos:
+  - repo: local
+    hooks:
+      # - id: pytest
+      #   name: Run pytest
+      #   entry: pytest
+      #   language: system
+      #   types: [python]
+      #   pass_filenames: false
+        
+      - id: rust-fmt
+        name: Rust format
+        entry: cargo fmt --all
+        language: system
+        types: [rust]
+        pass_filenames: false
+
+      - id: rust-clippy
+        name: Rust clippy
+        entry: cargo clippy --all-targets --all-features -- -D warnings
+        language: system
+        types: [rust]
+        pass_filenames: false
+
+      # - id: rust-test
+      #   name: Rust unit tests
+      #   entry: cargo test --lib # --quiet
+      #   language: system
+      #   types: [rust]
+      #   pass_filenames: false
+
+      - id: python-black
+        name: Black formatting
+        entry: black
+        language: system
+        types: [python]
+        require_serial: true
+        args: [--quiet, --target-version, py312]
+
+      - id: python-ruff
+        name: Ruff linting
+        entry: ruff check
+        language: system
+        types: [python]
+        args: [--fix]
+
+      - id: python-mypy
+        name: Mypy type checking
+        entry: mypy multimodars --ignore-missing-imports
+        language: system
+        types: [python]
+        pass_filenames: false

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

@@ -3,6 +3,61 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.3.0] - 2026-04-30
+
+### Added
+- `stitch_ccta_to_intravascular()`: fuses an aligned intravascular `PyGeometry` with a CCTA
+  trimesh by triangulating a patch between the open boundary ring of the CCTA mesh and the
+  proximal/distal contour of the intravascular geometry. Supports two boundary-ring alignment
+  modes (`"nearest_iv"` and `"highest_z"`) for proximal and distal ends independently.
+- `fix_and_remesh_stitched_mesh()`: repairs the stitched surface (non-manifold edges/vertices,
+  open holes) and applies isotropic remeshing via `pymeshlab`. Requires the optional
+  `multimodars[meshlab]` extra.
+- `manual_hole_fill()`: flat-fills remaining open holes in a trimesh after automatic repair.
+- `remove_labeled_points_from_mesh()`: deletes one or more labeled vertex regions from the mesh, remaps faces, and returns the open boundary ring as `"boundary_points"` for downstream stitching.
+- `keep_labeled_points_from_mesh()`: retains only the vertices of a specified labeled region,
+  discarding all others.
+- `sync_results_to_mesh()`: refreshes all coordinate lists in the results dictionary after
+  `scale_region_centerline_morphing()` moves vertices, keeping labels consistent with the
+  updated mesh.
+- `find_aortic_wall_scaling()`: computes the optimal radial scaling factor for the aortic wall
+  region by minimising the distance to the first intravascular frame whose lumen elliptic ratio
+  drops below 1.3 (transition from intramural to free-segment lumen).
+- `export_section_stl()`: exports the full mesh or a labeled sub-region (`"all"`, `"aorta"`,
+  `"rca"`, `"lca"`) as an STL file.
+- `plot_results_key()`: opens an interactive 3-D trimesh scene visualising selected labeled
+  regions with colour coding (yellow = aorta, blue = RCA, green = LCA, red = removed/intramural,
+  cyan = proximal, magenta = distal, orange = anomalous).
+- Tests for all new CCTA functions.
+- `mypy` added to pre-commit hooks for static type checking.
+
+### Changed
+- Rust-side CCTA STL reader (`src/ccta/io/input.rs`) removed; mesh I/O is now handled
+  entirely via Python `trimesh`, eliminating the `stl_io` dependency.
+- `pymeshlab` and `pyglet` are now optional dependencies; the core package installs without
+  them. Install extras with `pip install 'multimodars[meshlab]'`.
+- Debug-plot helpers moved to a dedicated `ccta.debug_plots` module.
+- CCTA Python module refactored into focused sub-modules (`labeling`, `manipulating`,
+  `fixing_functions`, `debug_plots`).
+- Parameter order updated in several CCTA API calls for consistency.
+- `diastole` argument removed from functions where it was not used.
+- Labeling of aorta boundary points improved to avoid incorrect assignment at mesh edges.
+- Type stubs updated and extended to cover all new public functions.
+- Clippy lints applied across the Rust codebase (non-breaking).
+
+### Fixed
+- 3-D area and elliptic ratio calculation corrected for non-planar contours.
+- Mesh face normals corrected after stitching to ensure consistent outward orientation.
+
+### Documentation
+- CCTA tutorial completely rewritten to cover the full stitching workflow:
+  `remove_labeled_points_from_mesh` → `stitch_ccta_to_intravascular` →
+  `fix_and_remesh_stitched_mesh` → Taubin smoothing → `export_section_stl` → re-labeling.
+- Intravascular tutorial reviewed and completed: section numbering corrected (1–7),
+  CSV-vs-numpy workflow note added, column descriptions with units added to data tables,
+  Sphinx cross-references added throughout, `translate()` tuple-argument bug fixed.
+
+
 ## [0.2.3] - 2026-03-06
 
 ### Added

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

@@ -161,12 +161,6 @@ version = "1.23.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5c76a5792e44e4abe34d3abf15636779261d45a7450612059293d1d2cfc63422"
 
-[[package]]
-name = "byteorder"
-version = "1.5.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
-
 [[package]]
 name = "byteorder-lite"
 version = "0.1.0"
@@ -390,15 +384,6 @@ dependencies = [
  "miniz_oxide",
 ]
 
-[[package]]
-name = "float-cmp"
-version = "0.10.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b09cf3155332e944990140d967ff5eceb70df778b34f77d8075db46e4704e6d8"
-dependencies = [
- "num-traits",
-]
-
 [[package]]
 name = "getrandom"
 version = "0.3.4"
@@ -726,7 +711,7 @@ dependencies = [
 
 [[package]]
 name = "multimodars"
-version = "0.2.3"
+version = "0.3.0"
 dependencies = [
  "anyhow",
  "approx",
@@ -737,7 +722,6 @@ dependencies = [
  "pyo3",
  "rayon",
  "serde",
- "stl_io",
  "toml",
 ]
 
@@ -1255,16 +1239,6 @@ version = "1.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
 
-[[package]]
-name = "stl_io"
-version = "0.10.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "da63e75b86345156b191c021b3ce2a13b973941ecdb8c70d6f00cbbfe0076ed7"
-dependencies = [
- "byteorder",
- "float-cmp",
-]
-
 [[package]]
 name = "syn"
 version = "2.0.104"

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

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

{multimodars-0.2.3 → multimodars-0.3.0}/PKG-INFO

@@ -1,25 +1,30 @@
 Metadata-Version: 2.4
 Name: multimodars
-Version: 0.2.3
+Version: 0.3.0
 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: pyglet<2
+Requires-Dist: scipy>=1.15.0
 Requires-Dist: sphinx>=8.0,<9.0 ; extra == 'docs'
 Requires-Dist: sphinx-rtd-theme ; extra == 'docs'
 Requires-Dist: sphinx-autodoc-typehints ; extra == 'docs'
 Requires-Dist: myst-parser ; extra == 'docs'
 Requires-Dist: maturin>=1.7,<2.0 ; extra == 'docs'
 Requires-Dist: furo ; extra == 'docs'
+Requires-Dist: pymeshlab>=2023.12 ; extra == 'meshlab'
 Requires-Dist: pytest>=9.0.2 ; extra == 'test'
 Requires-Dist: pytest-cov ; extra == 'test'
 Requires-Dist: ruff ; extra == 'test'
 Requires-Dist: black ; extra == 'test'
+Requires-Dist: mypy ; extra == 'test'
+Requires-Dist: pyglet<2 ; extra == 'viz'
 Provides-Extra: docs
+Provides-Extra: meshlab
 Provides-Extra: test
+Provides-Extra: viz
 License-File: LICENSE
 Summary: A Rust-powered cardiac multi-image modality fusion package
 Author: Anselm W. Stark

multimodars-0.3.0/ROADMAP.MD

@@ -0,0 +1,90 @@
+# Python package that has one purpose: Combining any intravascular image modality with CCTA meshes.
+
+# Centerline alignment module
+(- [] Create Centerline directly from mesh) (v1.0.0)
+
+# Mesh combination (v0.3.0)
+- [] Write a more stable function to find intramural points on aorta (for now works with excluded RCA points)
+- [] fix centerline resampling
+- [] Create an aortic and coronary wall with a consistent connection
+
+# CCTA clinical assessment (v0.4.0)
+- [] automatically find the required reference points for alignment
+- [] automatically assess lumen area, minor-, major axis, mla, intramural length etc. from the CCTA mesh.
+- [] return hausdorff distances per point between aligned ivus mesh and ccta mesh.
+- [] function to automatically assign wall thickness to ccta and combined ivus/ccta mesh
+- [] helper function to automatically export only certain points on mesh (e.g. RCA or LCA)
+- [] function to combine anomalous section only with the distal part
+
+# Miscellaneous
+- [] Improve print statements in the whole package
+
+# Prepublish checklist (JOSS review feedback — open until resolved):
+
+## Data & archival
+- [] Upload example data (`examples.zip`) to a persistent archive (Zenodo or similar) with a DOI.
+  Upload the source code snapshot there as well, either in the same record or a separate one linked from the paper.
+  Leave open until the DOI is minted and cited in the paper/README.
+- [] Clarify whether the sample data (repo + examples.zip) is real human data or synthetic data.
+  If real, add a statement on ethical approval / data-use conformity per JOSS policy
+  (https://joss.readthedocs.io/en/latest/policies.html#joss-policies).
+
+## Dependencies / packaging
+- [] Add `scipy` as an explicit runtime dependency in `pyproject.toml` (required by `mm.label_geometry()`).
+- [] Convert `optional-dependencies` groups that are not user-facing extras (docs, test, dev)
+  to PEP 735 `dependency-groups` so they are not shipped with the package on PyPI.
+  Move notebook runtime deps (`trimesh`, `plotly`, `scipy`, `nbformat`, `ipykernel`) into a
+  `[dependency-groups.dev]` group so `uv` installs them automatically during development.
+
+## Examples / notebooks
+- [] Include the `examples/` folder (with data) directly in the repository so users can clone
+  and run without a separate download, and so CI can execute the notebooks as tests.
+- [] Fix `ivus_to_centerline.ipynb`: create `output/` and `output/unprocessed/` directories
+  on-the-fly with `os.makedirs(..., exist_ok=True)` so the notebook does not error on a fresh clone.
+- [] Add a unit test that runs the example notebook end-to-end (e.g. using `nbmake` or `pytest-notebook`)
+  so regressions are caught automatically.
+
+## Performance claim
+- [] Provide reproducible code + sample data for the performance claim in the paper (lines 102-104):
+  "Empirical performance on a 16-core CPU: an OCT pullback with 280 frames and a rotation search range
+  of ±3° (final accuracy 0.01°) saw alignment time reduced from 150 s to 18 s with the optimized
+  multiscale search."
+  Add a benchmark script or notebook to `examples/` so the claim can be independently reproduced.
+
+## Documentation — Tutorial Intravascular
+- [x] Section "1. Workflow csv files": add column descriptions with units after the data table,
+  and add header names to the first data table — done (frame_index, x (mm), y (mm), z (mm)
+  headers present; "Column descriptions:" bullet block added).
+- [x] Section "1. Workflow csv files": add `:func:` / `:class:` Sphinx cross-references —
+  done throughout section 2 and the rest of the tutorial.
+- [x] Section "3. Workflow numpy arrays": explain how CSV and numpy workflows differ — done via
+  `.. note:: **CSV vs. numpy workflow** …` block at the top of section 3.
+- [x] Fix section numbering — done: sections run 1–7 with no duplicates.
+- [x] Section "6. Utility functions / to_array": clarify Returns block — done with prose
+  descriptions and typed bullet list per return type; `:func:` cross-reference present.
+- [x] Fix `translate((0.0, 1.0, 2.0))` tuple bug — done: all three call-sites use positional
+  args `translate(0.0, 1.0, 2.0)`.
+- [] Fix remaining undefined variables in tutorial snippets (reviewer: "cannot be run due to
+  undefined variables"):
+  - `stress` (section 6, to_array snippet, line ~392) — only defined if the user followed the
+    `from_file_full` path; breaks on the `singlepair` path.  Change to `rest` or add a note.
+  - `cl_resampled` (section 6, to_array snippet, line ~394) — variable returned in section 4
+    is named `resampled_cl`; rename to match.
+  - `results["rca_points"]` (section 4, align_combined code block, line ~358) — `results` is
+    never defined in this tutorial.  Add an inline comment: `# from mm.label_geometry() — see
+    CCTA tutorial` and a placeholder assignment above the block.
+  - `geometry` (section 5, to_obj code block, line ~374) — undefined at that point; replace
+    with `aligned` (returned from align_combined in section 4).
+
+## Documentation — general
+- [] Consider converting tutorials to Jupyter notebooks rendered via `nbsphinx` or `myst-nb`
+  so outputs are visible, results are verifiable, and documentation build failures reveal
+  broken code early. (Non-blocking suggestion from reviewer crnh / richardkoehler.)
+- [] Cite the case-report paper in the Research impact statement (it is cited elsewhere but
+  not in that section).
+
+## CI / quality
+- [] Integrate coverage measurement (`pytest-cov`) and upload reports to Coveralls or Codecov.
+- [] Add a coverage status badge to the README.
+- [] Add `mypy` to pre-commit hooks.
+- [] Add `scipy` to pre-commit / lint hooks.

multimodars-0.3.0/docs/api/adjust_ccta.rst

@@ -0,0 +1,9 @@
+Adjust CCTA
+===========
+
+.. autofunction:: multimodars.ccta.labeling.label_geometry
+.. autofunction:: multimodars.ccta.labeling.label_anomalous_region
+.. autofunction:: multimodars.ccta.manipulating.scale_region_centerline_morphing
+.. autofunction:: multimodars.ccta.manipulating.find_distal_and_proximal_scaling
+.. autofunction:: multimodars.ccta.manipulating.find_aorta_scaling
+.. autofunction:: multimodars.ccta.debug_plots.compare_centerline_scaling

{multimodars-0.2.3 → multimodars-0.3.0}/docs/conf.py

@@ -3,12 +3,13 @@ import sys
 import re
 
 try:
-    import multimodars
+    import multimodars  # noqa: F401
 except ImportError:
     from unittest.mock import MagicMock
 
     sys.modules["multimodars"] = MagicMock()
 
+
 # Get the version from Cargo.toml
 def get_version():
     with open(os.path.join("..", "Cargo.toml"), "r") as f:
@@ -19,6 +20,7 @@ def get_version():
         return match.group(1)
     return "0.0.0"
 
+
 # Add project to path
 sys.path.insert(0, os.path.abspath(".."))
 sys.path.insert(0, os.path.abspath("../src"))
@@ -62,12 +64,4 @@ autodoc_default_options = {
     "special-members": "__init__",
 }
 autodoc_typehints = "description"
-
-# Workaround for PyO3 modules
-try:
-    import multimodars
-except ImportError:
-    from unittest.mock import MagicMock
-
-    sys.modules["multimodars"] = MagicMock()
-    print("Warning: multimodars module not found, using mocks for documentation")
+numfig = True

multimodars-0.3.0/docs/index.rst

@@ -0,0 +1,82 @@
+.. multimodars documentation master file, created by
+   sphinx-quickstart on Wed Jul 23 22:38:42 2025.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+
+Welcome to multimodars documentation!
+=====================================
+
+*multimodars: A Rust-powered cardiac multi-image modality fusion package.*
+
+.. warning::
+   
+   Not intended for clinical use.
+
+This package aims to combine different cardiac imaging modalities to combined 3D models. A particular focus is on the fusion of intravascular 
+imaging (either intravascular ultrasound [IVUS] or optical coherence tomography [OCT]) with a 3D geometry created from computed coronary tomography angiography (CCTA).
+
+The main functionalities are organized into two major categories:
+
+1. **Intravascular Alignment**: This category addresses the co-registration of intravascular frames through translation and rotation to minimize the distance between adjacent frames.
+   This approach is particularly useful for correcting misalignments introduced by cardiac motion during intravascular image acquisition. It further encompasses the alignment of
+   separate intravascular pullbacks (e.g., acquired under rest and stress conditions) as well as the co-registration of systolic and diastolic frames within the same pullback.
+
+2. **CCTA-Intravascular Fusion**: This category covers the fusion of intravascular frames with a three-dimensional geometry reconstructed from coronary computed tomography angiography (CCTA).
+   This is particularly valuable for generating high-resolution three-dimensional models of coronary arteries by combining the high spatial resolution of intravascular imaging with the
+   three-dimensional geometry provided by CCTA. Functionalities in this category include the anatomical labeling of CCTA geometries based on centerlines, the registration of intravascular
+   frames onto a centerline, and the subsequent fusion of the resulting geometry with the CCTA reconstruction.
+
+Intravascular image data are accepted either as CSV files following the output format of
+`AIVUS <https://github.com/AI-in-Cardiovascular-Medicine/AIVUS-CAA>`_, an open-source tool for automated intravascular ultrasound analysis,
+or directly as NumPy arrays, affording greater flexibility for integration with custom pipelines.
+
+Table of Contents
+-----------------
+
+.. toctree::
+   :hidden:
+
+   Home <self>
+
+.. toctree::
+   :maxdepth: 2
+
+   installation
+   Intravascular Alignment Tutorial <tutorial_intravascular>
+   CCTA Intravascular Fusion Tutorial <tutorial_ccta>
+   api/index
+   changelog
+
+License
+-------
+
+This package is covered by the open source `MIT License <https://github.com/yungselm/multimoda-rs/blob/main/LICENSE>`_.
+
+Developers
+----------
+
+ - `Anselm Stark <https://github.com/yugnselm>`_:sup:`1,2`
+ - `Marc Ilic <https://github.com/cicram>`_:sup:`1,2`
+ - `Ali Mokthari <https://github.com/alimokh91>`_:sup:`1,2`
+ - `Pooya Mohammadi Kazaj <https://github.com/pooya-mohammadi>`_:sup:`1,2`
+ - `Isaac Shiri <https://github.com/Isaacshiri>`_:sup:`1`
+
+:sup:`1`\ Department of Cardiology, Inselspital, Bern University Hospital, University of Bern, Switzerland
+:sup:`2`\ Graduate School for Cellular and Biomedical Sciences, University of Bern, Bern, Switzerland
+
+Contributing
+------------
+We'd welcome your contributions to multimodars. Please read the
+`contributing guidelines <https://github.com/yungselm/multimoda-rs/blob/main/CONTRIBUTING.md>`_ on how to contribute to ``multimodars``.
+
+Changelog
+---------
+
+* :doc:`changelog`
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`