multimodars 0.3.2__tar.gz → 0.3.4__tar.gz

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

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.3.4] - 2026-05-13
+
+### Changed
+- `align_three_point`, `align_manual` and `align_combined` are now all generic, taking either `PyGeometryPair` or `PyGeometry` as input
+- Test file added `test_intravascular.py` to demonstrate that same results with both
+
+## [0.3.3] - 2026-05-06
+
+### Added
+- `CITATION.cff` with full author list, ORCIDs, and preferred citation for JOSS/Zenodo archival.
+- Zenodo DOI badge added to README.
+
 ## [0.3.2] - 2026-05-05
 
 ### Added
@@ -14,14 +26,14 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Changed
 - `paper/paper.md` Performance section updated with quantified benchmark results and
-  corrected parallelisation description.
+  corrected parallelization description.
 
 ### Performance
-- Intra-pullback alignment (`search_range`) now parallelises over candidate rotation
+- Intra-pullback alignment (`search_range`) now parallelizes 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.
+  all cores: bruteforce scales 6.5× and optimized 4.2× from 2 to 16 cores (previously
+  ~1.4× for both). Combined algorithmic + parallelization gain reaches **38.5×** vs.
   brute-force at 2 cores.
 
 ## [0.3.1] - 2026-05-04

multimodars-0.3.4/CITATION.cff

@@ -0,0 +1,82 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata below."
+title: "multimodars: A Rust-powered toolkit for multi-modality cardiac image fusion and registration"
+version: 0.3.2
+date-released: 2026-05-05
+license: MIT
+repository-code: "https://github.com/yungselm/multimoda-rs"
+url: "https://multimoda-rs.readthedocs.io"
+
+authors:
+  - family-names: Stark
+    given-names: Anselm W.
+    orcid: "https://orcid.org/0000-0002-5861-3753"
+    affiliation: "Department of Cardiology, Inselspital, Bern University Hospital, University of Bern, Switzerland"
+  - family-names: Ilic
+    given-names: Marc
+    orcid: "https://orcid.org/0009-0000-6443-8739"
+    affiliation: "Department of Cardiology, Inselspital, Bern University Hospital, University of Bern, Switzerland"
+  - family-names: Mokhtari
+    given-names: Ali
+    orcid: "https://orcid.org/0009-0004-8864-6988"
+    affiliation: "Department of Cardiology, Inselspital, Bern University Hospital, University of Bern, Switzerland"
+  - family-names: Mohammadi Kazaj
+    given-names: Pooya
+    orcid: "https://orcid.org/0000-0003-2747-1489"
+    affiliation: "Department of Cardiology, Inselspital, Bern University Hospital, University of Bern, Switzerland"
+  - family-names: Gräni
+    given-names: Christoph
+    orcid: "https://orcid.org/0000-0001-6029-0597"
+    affiliation: "Department of Cardiology, Inselspital, Bern University Hospital, University of Bern, Switzerland"
+  - family-names: Shiri
+    given-names: Isaac
+    orcid: "https://orcid.org/0000-0002-5735-0736"
+    affiliation: "Department of Cardiology, Inselspital, Bern University Hospital, University of Bern, Switzerland"
+
+abstract: >
+  multimodars is a high-performance Python/Rust toolkit that registers and fuses
+  intravascular imaging (IVUS, OCT) with coronary CT angiography (CCTA) into unified
+  high-resolution 3D vessel models. It implements four alignment modes (full,
+  double-pair, single-pair, single) to support multi-state comparisons such as rest
+  vs. pharmacologic stress and pre- vs. post-intervention. The Rust backend (via
+  PyO3/maturin) parallelizes the multiscale angular search across all available cores,
+  achieving a combined 38.5x speedup over a Python brute-force baseline. Output
+  includes Wavefront OBJ/STL meshes, per-frame lumen metrics (minimum lumen area,
+  stenosis fraction, elliptic ratio), and optional interpolated deformation animations.
+
+keywords:
+  - Rust
+  - Python
+  - Cardiology
+  - Intravascular imaging
+  - CCTA
+  - Image Fusion
+  - Image registration
+  - IVUS
+  - OCT
+  - Coronary artery anomalies
+
+preferred-citation:
+  type: article
+  title: "multimodars: A Rust-powered toolkit for multi-modality cardiac image fusion and registration"
+  authors:
+    - family-names: Stark
+      given-names: Anselm W.
+      orcid: "https://orcid.org/0000-0002-5861-3753"
+    - family-names: Ilic
+      given-names: Marc
+      orcid: "https://orcid.org/0009-0000-6443-8739"
+    - family-names: Mokhtari
+      given-names: Ali
+      orcid: "https://orcid.org/0009-0004-8864-6988"
+    - family-names: Mohammadi Kazaj
+      given-names: Pooya
+      orcid: "https://orcid.org/0000-0003-2747-1489"
+    - family-names: Gräni
+      given-names: Christoph
+      orcid: "https://orcid.org/0000-0001-6029-0597"
+    - family-names: Shiri
+      given-names: Isaac
+      orcid: "https://orcid.org/0000-0002-5735-0736"
+  journal: "Journal of Open Source Software"
+  year: 2026

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

@@ -753,7 +753,7 @@ dependencies = [
 
 [[package]]
 name = "multimodars"
-version = "0.3.2"
+version = "0.3.4"
 dependencies = [
  "anyhow",
  "approx",

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

@@ -1,6 +1,6 @@
 [package]
 name = "multimodars"
-version = "0.3.2"
+version = "0.3.4"
 edition = "2021"
 license = "MIT"
 readme = "README.md"

{multimodars-0.3.2 → multimodars-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multimodars
-Version: 0.3.2
+Version: 0.3.4
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
@@ -36,7 +36,7 @@ Project-URL: Issues, https://github.com/yungselm/multimoda-rs/issues
 [![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)
-
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20051997.svg)](https://doi.org/10.5281/zenodo.20051997)
 
 <figure class="epigraph" style="text-align: center; font-style: italic;">
   <blockquote>
@@ -79,7 +79,7 @@ For building from source or the full developer setup (tests, linting, docs), see
 
 ## 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:
+Checkout our **[Documentation](https://multimoda-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

{multimodars-0.3.2 → multimodars-0.3.4}/README.md

@@ -12,7 +12,7 @@
 [![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)
-
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20051997.svg)](https://doi.org/10.5281/zenodo.20051997)
 
 <figure class="epigraph" style="text-align: center; font-style: italic;">
   <blockquote>
@@ -55,7 +55,7 @@ For building from source or the full developer setup (tests, linting, docs), see
 
 ## 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:
+Checkout our **[Documentation](https://multimoda-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

multimodars-0.3.4/ROADMAP.MD

@@ -0,0 +1,43 @@
+# Python package that has one purpose: Combining any intravascular image modality with CCTA meshes.
+
+# Hot fixes
+- [] Labeling doesn't work as expected especially for `from_file` variants
+
+# Optimizations
+- [] Optimize the ray intersection algorithm
+- [] Better parallelization strategy for frames alignment by processing in batches (frames only have to be aligned relative to each other not sequentially)
+
+# Mesh combination (v0.3.0)
+## New/improved features
+- [] "Smooth" the aortic ring of boundary points first, by projecting on plane to shift outliers
+- [] Write a more stable function to find intramural points on aorta (for now works with excluded RCA points)
+- [] Create an aortic and coronary wall with a consistent connection
+- [] Find bifurcation reference points automatically
+- [] `numpy_to_report` function that allows to read in lists for the four variables of interest (frame, phase, measurement_1, measurement_2)
+- [] write metadata to .obj files so they can be reconstructed completely to geometry/geometrypair
+
+## Fixes/Improvements
+- [] Write a more stable function to find intramural points on aorta (for now works with excluded RCA points)
+- [] Align algorithms only work with geometry pair not only geometry
+- [] fix centerline resampling
+
+## Investigate/check logic
+- [] When aligning geometry with wall has a rotation in the wall -> logic error for centerline alignment?
+
+# CCTA clinical assessment (v0.4.0)
+- [] automatically find the required reference points for anomalous 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
+
+# Miscellaneous
+- [] Integrate coverage measurement (`pytest-cov`) and upload reports to Coveralls or Codecov.
+- [] Add a coverage status badge to the README.
+
+# Centerline alignment module (v1.0.0)
+- [] Create Centerline directly from mesh
+
+# Myocardial Fusion v2.0.0
+- [] Read in LGE/T2 etc. from MRI and map onto CCTA myocardium
+- [] Read in Perfusion map from PET/SPECT and load onto CCTA myocardium
+- [] Calculate perfusion territories based on coronary anatomy

{multimodars-0.3.2 → multimodars-0.3.4}/benchmarks/BENCHMARK_PLAN.md

@@ -6,18 +6,18 @@ Two benchmarks to characterise the alignment performance of `multimodars`.
 
 | # | What | Function | Dataset |
 |---|------|----------|---------|
-| 1 | Bruteforce vs. optimised at varying step sizes | `from_file_full` | IVUS rest/stress |
+| 1 | Bruteforce vs. optimized at varying step sizes | `from_file_full` | IVUS rest/stress |
 | 2 | CPU-core scaling (parallelism) | `from_array_single` | OCT (280 frames) |
 
 Results land in `benchmarks/results/`.
 
 ---
 
-## Benchmark 1 — Bruteforce vs. Optimised: Step-Size Scaling
+## Benchmark 1 — Bruteforce vs. optimized: Step-Size Scaling
 
 ### Goal
 
-Quantify how bruteforce and optimised alignment scale as `step_rotation_deg` decreases
+Quantify how bruteforce and optimized alignment scale as `step_rotation_deg` decreases
 (i.e. as the rotation-search grid becomes finer).
 
 ### Setup
@@ -51,7 +51,7 @@ Corresponding number of rotation steps n = 180 / step (using the full ±90° ran
 
 - **Bruteforce**: exhaustively scores every rotation angle for every frame pair →
   wall time grows linearly with n\_steps (O(n)).
-- **Optimised**: coarse-to-fine hierarchical search → sub-linear in n\_steps,
+- **optimized**: coarse-to-fine hierarchical search → sub-linear in n\_steps,
   asymptotically O(log n).
 
 The plot axes are logarithmic so the two complexity classes appear as straight lines
@@ -64,8 +64,8 @@ with clearly different slopes.
 - x-axis (bottom): number of rotation steps; (top): step size in degrees
 - y-axis: median wall time (seconds)
 - Line 1: bruteforce (red ○–) + O(n) reference dashed line
-- Line 2: optimised (blue ■ --)
-- Right y-axis: speedup factor (bruteforce / optimised)
+- Line 2: optimized (blue ■ --)
+- Right y-axis: speedup factor (bruteforce / optimized)
 
 ---
 
@@ -110,7 +110,7 @@ a **separate subprocess** with the variable set before any import of `multimodar
 
 ### Expected behaviour
 
-- **Optimised**: near-linear speedup up to ~8 cores, then diminishing returns
+- **optimized**: near-linear speedup up to ~8 cores, then diminishing returns
   (Amdahl's law — serial fraction of the pipeline limits gains beyond that).
 - **Bruteforce**: also benefits from rayon frame-level parallelism, but expected
   to saturate earlier because the per-step work is less cache-friendly.
@@ -119,7 +119,7 @@ a **separate subprocess** with the variable set before any import of `multimodar
 
 `benchmarks/results/cpu_scaling.png` — two-panel figure:
 
-- Left panel: wall time (s) vs. CPU cores, two lines (bruteforce, optimised)
+- Left panel: wall time (s) vs. CPU cores, two lines (bruteforce, optimized)
 - Right panel: speedup relative to 1 core vs. CPU cores +
   ideal linear-speedup reference; same two lines
 

{multimodars-0.3.2 → multimodars-0.3.4}/benchmarks/benchmark_bruteforce_stepsize.py

@@ -1,4 +1,4 @@
-"""Benchmark 1: bruteforce vs. optimised alignment at varying step sizes.
+"""Benchmark 1: bruteforce vs. optimized alignment at varying step sizes.
 
 Tests from_file_full on the bundled IVUS rest/stress example data with
 step_rotation_deg in {5.0, 2.5, 1.0, 0.5, 0.1} degrees.
@@ -27,7 +27,7 @@ INPUT_AB = str(DATA_ROOT / "ivus_rest")
 INPUT_CD = str(DATA_ROOT / "ivus_stress")
 RESULTS_DIR = Path(__file__).parent / "results"
 
-STEP_SIZES: list[float] = [5.0, 2.5, 1.0, 0.5, 0.1, 0.05]
+STEP_SIZES: list[float] = [5.0, 2.5, 1.0, 0.5, 0.25, 0.1, 0.05]
 RANGE_DEG: float = 90.0
 REPEATS: int = 3
 
@@ -63,7 +63,7 @@ def _run_once(step: float, bruteforce: bool) -> float:
 
 
 def run_benchmark() -> dict[str, list[float]]:
-    results: dict[str, list[float]] = {"bruteforce": [], "optimised": []}
+    results: dict[str, list[float]] = {"bruteforce": [], "optimized": []}
 
     for step in STEP_SIZES:
         print(f"step={step:4.1f}°  bruteforce=True  ", end="", flush=True)
@@ -75,7 +75,7 @@ def run_benchmark() -> dict[str, list[float]]:
         print(f"step={step:4.1f}°  bruteforce=False ", end="", flush=True)
         times_opt = [_run_once(step, bruteforce=False) for _ in range(REPEATS)]
         med_opt = statistics.median(times_opt)
-        results["optimised"].append(med_opt)
+        results["optimized"].append(med_opt)
         speedup = med_bf / med_opt if med_opt > 0 else float("inf")
         print(f"{med_opt:.2f} s  (speedup {speedup:.1f}x)")
 
@@ -92,7 +92,7 @@ def plot_results(results: dict[str, list[float]]) -> None:
 
     n_steps_list = [_n_steps(s) for s in STEP_SIZES]
     bf_times = results["bruteforce"]
-    opt_times = results["optimised"]
+    opt_times = results["optimized"]
     speedups = [bf / opt for bf, opt in zip(bf_times, opt_times)]
 
     fig, (ax_main, ax_speedup) = plt.subplots(
@@ -116,7 +116,7 @@ def plot_results(results: dict[str, list[float]]) -> None:
         color="tab:blue",
         linewidth=2,
         markersize=7,
-        label="Optimised",
+        label="optimized",
     )
 
     # O(n) reference anchored at the first bruteforce point
@@ -137,7 +137,7 @@ def plot_results(results: dict[str, list[float]]) -> None:
     ax_main.set_xlabel("Number of rotation steps  (2 × range / step)", fontsize=12)
     ax_main.set_ylabel("Median wall time  (s)", fontsize=12)
     ax_main.set_title(
-        "Bruteforce vs. Optimised — Step-Size Scaling\n"
+        "Bruteforce vs. optimized — Step-Size Scaling\n"
         "from_file_full · IVUS rest/stress · range = 90°",
         fontsize=11,
     )
@@ -164,9 +164,9 @@ def plot_results(results: dict[str, list[float]]) -> None:
     ax_speedup.axhline(1.0, color="gray", linewidth=1, linestyle=":")
     ax_speedup.set_xscale("log")
     ax_speedup.set_xlabel("Number of rotation steps  (2 × range / step)", fontsize=12)
-    ax_speedup.set_ylabel("Speedup  (bruteforce / optimised)", fontsize=12)
+    ax_speedup.set_ylabel("Speedup  (bruteforce / optimized)", fontsize=12)
     ax_speedup.set_title(
-        "Speedup of Optimised over Bruteforce\n"
+        "Speedup of optimized over Bruteforce\n"
         "from_file_full · IVUS rest/stress · range = 90°",
         fontsize=11,
     )
@@ -190,7 +190,7 @@ def plot_results(results: dict[str, list[float]]) -> None:
 # ---------------------------------------------------------------------------
 
 if __name__ == "__main__":
-    print("=== Benchmark 1: Bruteforce vs. Optimised — Step-Size Scaling ===\n")
+    print("=== Benchmark 1: Bruteforce vs. optimized — Step-Size Scaling ===\n")
     results = run_benchmark()
     print("\nPlotting results …")
     plot_results(results)

{multimodars-0.3.2 → multimodars-0.3.4}/benchmarks/benchmark_cpu_scaling.py

@@ -1,4 +1,4 @@
-"""Benchmark 2: CPU-core scaling for optimised vs. bruteforce alignment.
+"""Benchmark 2: CPU-core scaling for optimized vs. bruteforce alignment.
 
 Tests from_array_single on the bundled OCT example dataset (280 frames) at
 varying RAYON_NUM_THREADS values (1 → 16 cores).
@@ -103,6 +103,7 @@ def _run_worker(n_cores: int, bruteforce: bool) -> list[float]:
         [sys.executable, "-c", script],
         capture_output=True,
         text=True,
+        encoding="utf-8",
     )
     if proc.returncode != 0 or not proc.stdout.strip():
         print(f"\n  [stdout] {proc.stdout.strip()[:600]}", file=sys.stderr)
@@ -122,7 +123,7 @@ def _run_worker(n_cores: int, bruteforce: bool) -> list[float]:
 
 
 def run_benchmark() -> dict[str, list[float]]:
-    results: dict[str, list[float]] = {"bruteforce": [], "optimised": []}
+    results: dict[str, list[float]] = {"bruteforce": [], "optimized": []}
 
     for n_cores in CORE_COUNTS:
         label_width = len(str(max(CORE_COUNTS)))
@@ -144,7 +145,7 @@ def run_benchmark() -> dict[str, list[float]]:
         )
         times_opt = _run_worker(n_cores, bruteforce=False)
         med_opt = statistics.median(times_opt)
-        results["optimised"].append(med_opt)
+        results["optimized"].append(med_opt)
         print(f"{med_opt:.2f} s")
 
     return results
@@ -159,7 +160,7 @@ def plot_results(results: dict[str, list[float]]) -> None:
     RESULTS_DIR.mkdir(parents=True, exist_ok=True)
 
     bf_times = results["bruteforce"]
-    opt_times = results["optimised"]
+    opt_times = results["optimized"]
 
     bf_speedup = [bf_times[0] / t for t in bf_times]
     opt_speedup = [opt_times[0] / t for t in opt_times]
@@ -186,7 +187,7 @@ def plot_results(results: dict[str, list[float]]) -> None:
         color="tab:blue",
         linewidth=2,
         markersize=7,
-        label="Optimised",
+        label="optimized",
     )
     ax_time.set_xlabel("CPU cores  (RAYON_NUM_THREADS)", fontsize=12)
     ax_time.set_ylabel("Median wall time  (s)", fontsize=12)
@@ -224,7 +225,7 @@ def plot_results(results: dict[str, list[float]]) -> None:
         color="tab:blue",
         linewidth=2,
         markersize=7,
-        label="Optimised",
+        label="optimized",
     )
     ax_speedup.set_xlabel("CPU cores  (RAYON_NUM_THREADS)", fontsize=12)
     ax_speedup.set_ylabel("Speedup  (relative to 1 core)", fontsize=12)

{multimodars-0.3.2 → multimodars-0.3.4}/multimodars/_processing.py

@@ -1005,7 +1005,7 @@ def from_array_single(
 
 def align_three_point(
     centerline: PyCenterline,
-    geometry_pair: PyGeometryPair,
+    geometry: PyGeometryPair | PyGeometry,
     aortic_ref_pt: tuple[float, float, float],
     upper_ref_pt: tuple[float, float, float],
     lower_ref_pt: tuple[float, float, float],
@@ -1016,20 +1016,19 @@ def align_three_point(
     output_dir: str = "output/aligned",
     contour_types: list[PyContourType] | None = None,
     case_name: str = "None",
-) -> tuple[PyGeometryPair, PyCenterline]:
-    """Align diastolic and systolic meshes to the centerline using three reference points.
+) -> tuple[PyGeometryPair | PyGeometry, PyCenterline]:
+    """Align a geometry (or geometry pair) to the centerline using three reference points.
 
-    Creates centerline-aligned meshes for a diastolic/systolic geometry pair
-    based on three anatomical reference points (aorta, upper section, lower
-    section).  Only works for elliptic vessels such as coronary artery
-    anomalies.
+    Creates centerline-aligned meshes based on three anatomical reference points
+    (aorta, upper section, lower section).  Only works for elliptic vessels such
+    as coronary artery anomalies.
 
     Parameters
     ----------
     centerline : PyCenterline
         Centerline of the vessel.
-    geometry_pair : PyGeometryPair
-        Diastolic/systolic geometry pair to align.
+    geometry : PyGeometryPair or PyGeometry
+        Single geometry or diastolic/systolic geometry pair to align.
     aortic_ref_pt : tuple of float
         ``(x, y, z)`` reference point at the aortic ostium.
     upper_ref_pt : tuple of float
@@ -1043,7 +1042,8 @@ def align_three_point(
     watertight : bool, optional
         Whether to write a watertight or shell mesh.  Default is ``True``.
     interpolation_steps : int, optional
-        Number of interpolation steps between phases.  Default is ``28``.
+        Number of interpolation steps between phases.  Only used when *geometry*
+        is a ``PyGeometryPair``.  Default is ``0``.
     output_dir : str, optional
         Output directory for aligned meshes.  Default is ``"output/aligned"``.
     contour_types : list of PyContourType, optional
@@ -1054,15 +1054,15 @@ def align_three_point(
 
     Returns
     -------
-    geom_pair : PyGeometryPair
-        Aligned geometry pair.
+    geometry : PyGeometryPair or PyGeometry
+        Aligned geometry, matching the type of the input.
     centerline : PyCenterline
         Resampled centerline.
 
     Examples
     --------
     >>> import multimodars as mm
-    >>> pair, cl = mm.align_three_point(
+    >>> result, cl = mm.align_three_point(
     ...     centerline,
     ...     geometry_pair,
     ...     (12.2605, -201.3643, 1751.0554),
@@ -1074,7 +1074,7 @@ def align_three_point(
         contour_types = _default_contour_types()
     return _align_three_point(
         centerline,
-        geometry_pair,
+        geometry,
         aortic_ref_pt,
         upper_ref_pt,
         lower_ref_pt,
@@ -1090,7 +1090,7 @@ def align_three_point(
 
 def align_manual(
     centerline: PyCenterline,
-    geometry_pair: PyGeometryPair,
+    geometry: PyGeometryPair | PyGeometry,
     rotation_angle: float,
     ref_point: tuple[float, float, float],
     write: bool = False,
@@ -1099,20 +1099,19 @@ def align_manual(
     output_dir: str = "output/aligned",
     contour_types: list[PyContourType] | None = None,
     case_name: str = "None",
-) -> tuple[PyGeometryPair, PyCenterline]:
-    """Align diastolic and systolic meshes to the centerline using a manual rotation angle.
+) -> tuple[PyGeometryPair | PyGeometry, PyCenterline]:
+    """Align a geometry (or geometry pair) to the centerline using a manual rotation angle.
 
-    Creates centerline-aligned meshes for a diastolic/systolic geometry pair
-    using an explicit rotation angle and a single reference point on the
-    centerline.  Only works for elliptic vessels such as coronary artery
-    anomalies.
+    Creates centerline-aligned meshes using an explicit rotation angle and a
+    single reference point on the centerline.  Only works for elliptic vessels
+    such as coronary artery anomalies.
 
     Parameters
     ----------
     centerline : PyCenterline
         Centerline of the vessel.
-    geometry_pair : PyGeometryPair
-        Diastolic/systolic geometry pair to align.
+    geometry : PyGeometryPair or PyGeometry
+        Single geometry or diastolic/systolic geometry pair to align.
     rotation_angle : float
         Rotation angle in radians to apply.
     ref_point : tuple of float
@@ -1122,7 +1121,8 @@ def align_manual(
     watertight : bool, optional
         Whether to write a watertight or shell mesh.  Default is ``True``.
     interpolation_steps : int, optional
-        Number of interpolation steps between phases.  Default is ``28``.
+        Number of interpolation steps between phases.  Only used when *geometry*
+        is a ``PyGeometryPair``.  Default is ``0``.
     output_dir : str, optional
         Output directory for aligned meshes.  Default is ``"output/aligned"``.
     contour_types : list of PyContourType, optional
@@ -1133,15 +1133,15 @@ def align_manual(
 
     Returns
     -------
-    geom_pair : PyGeometryPair
-        Aligned geometry pair.
+    geometry : PyGeometryPair or PyGeometry
+        Aligned geometry, matching the type of the input.
     centerline : PyCenterline
         Resampled centerline.
 
     Examples
     --------
     >>> import multimodars as mm
-    >>> pair, cl = mm.align_manual(
+    >>> result, cl = mm.align_manual(
     ...     centerline, geometry_pair, rotation_angle=1.57, ref_point=(1.0, 2.0, 3.0)
     ... )
     """
@@ -1149,7 +1149,7 @@ def align_manual(
         contour_types = _default_contour_types()
     return _align_manual(
         centerline,
-        geometry_pair,
+        geometry,
         rotation_angle,
         ref_point,
         write,
@@ -1163,7 +1163,7 @@ def align_manual(
 
 def align_combined(
     centerline: PyCenterline,
-    geom_pair: PyGeometryPair,
+    geometry: PyGeometryPair | PyGeometry,
     aortic_ref_pt: tuple[float, float, float],
     upper_ref_pt: tuple[float, float, float],
     lower_ref_pt: tuple[float, float, float],
@@ -1177,20 +1177,19 @@ def align_combined(
     output_dir: str = "output/aligned",
     contour_types: list[PyContourType] | None = None,
     case_name: str = "None",
-) -> tuple[PyGeometryPair, PyCenterline]:
-    """Align meshes using three reference points combined with Hausdorff distance refinement.
+) -> tuple[PyGeometryPair | PyGeometry, PyCenterline]:
+    """Align a geometry (or geometry pair) using three reference points and Hausdorff refinement.
 
-    Creates centerline-aligned meshes for a diastolic/systolic geometry pair
-    using three anatomical reference points for an initial orientation and a
-    set of additional points for Hausdorff distance-based fine-tuning of the
-    rotation.
+    Creates centerline-aligned meshes using three anatomical reference points
+    for an initial orientation and a set of additional points for
+    Hausdorff distance-based fine-tuning of the rotation.
 
     Parameters
     ----------
     centerline : PyCenterline
         Centerline of the vessel.
-    geom_pair : PyGeometryPair
-        Diastolic/systolic geometry pair to align.
+    geometry : PyGeometryPair or PyGeometry
+        Single geometry or diastolic/systolic geometry pair to align.
     aortic_ref_pt : tuple of float
         ``(x, y, z)`` reference point at the aortic ostium.
     upper_ref_pt : tuple of float
@@ -1212,7 +1211,8 @@ def align_combined(
     watertight : bool, optional
         Whether to write a watertight or shell mesh.  Default is ``True``.
     interpolation_steps : int, optional
-        Number of interpolation steps between phases.  Default is ``28``.
+        Number of interpolation steps between phases.  Only used when *geometry*
+        is a ``PyGeometryPair``.  Default is ``0``.
     output_dir : str, optional
         Output directory for aligned meshes.  Default is ``"output/aligned"``.
     contour_types : list of PyContourType, optional
@@ -1223,15 +1223,15 @@ def align_combined(
 
     Returns
     -------
-    geom_pair : PyGeometryPair
-        Aligned geometry pair.
+    geometry : PyGeometryPair or PyGeometry
+        Aligned geometry, matching the type of the input.
     centerline : PyCenterline
         Resampled centerline.
 
     Examples
     --------
     >>> import multimodars as mm
-    >>> pair, cl = mm.align_combined(
+    >>> result, cl = mm.align_combined(
     ...     centerline,
     ...     geometry_pair,
     ...     (12.2605, -201.3643, 1751.0554),
@@ -1244,7 +1244,7 @@ def align_combined(
         contour_types = _default_contour_types()
     return _align_combined(
         centerline,
-        geom_pair,
+        geometry,
         aortic_ref_pt,
         upper_ref_pt,
         lower_ref_pt,