ENH: Made tool naming more consistent with rest of code base

docs/api/physicsnemo/manifest.rst

@@ -45,33 +45,28 @@ decides which domain the model lives on.
 Reference
 =========
 
-These live in :mod:`monai_physio.physicsnemo_tools`, which is not re-exported
-from the top-level package - import it by module:
+:class:`PhysicsNemoTools` is re-exported from the top-level package;
+``SubjectManifest`` and ``PhaseEntry`` are not - import those by module:
 
 .. code-block:: python
 
-   from monai_physio.physicsnemo_tools import SubjectManifest, parse_manifest
+   from monai_physio import PhysicsNemoTools
+   from monai_physio.physicsnemo_tools import SubjectManifest
+
+   manifest = PhysicsNemoTools.parse_manifest(manifest_path)
 
 .. autoclass:: SubjectManifest
    :exclude-members: subject_id, fitted_reference_mesh, pca_coefficients, target_array, phases
 
 .. autoclass:: PhaseEntry
    :exclude-members: mesh, stage
 
-.. autofunction:: parse_manifest
-
-.. autofunction:: load_target_array
-
-.. autofunction:: load_pca_coefficients
-
 Supporting helpers
 ==================
 
-.. autofunction:: build_node_features
-
-.. autofunction:: mesh_to_edge_index
-
-.. autofunction:: compute_edge_features
+.. autoclass:: PhysicsNemoTools
+   :members: parse_manifest, load_target_array, load_pca_coefficients,
+             build_node_features, mesh_to_edge_index, compute_edge_features
 
 .. autoclass:: PhaseSampleDataset
    :members:

docs/api/usd/index.rst

@@ -58,10 +58,10 @@ Create Anatomical Scene
 .. code-block:: python
 
    from monai_physio import usd_anatomy_tools
-   
-   stage = usd_anatomy_tools.create_anatomical_stage()
-   usd_anatomy_tools.add_heart_model(stage, "heart.vtk")
-   usd_anatomy_tools.add_lungs_model(stage, "lungs.vtk")
+
+   stage = anatomy_tools.create_anatomical_stage()
+   anatomy_tools.add_heart_model(stage, "heart.vtk")
+   anatomy_tools.add_lungs_model(stage, "lungs.vtk")
    stage.Save()
 
 See Also

docs/developer/migration_next.md

@@ -191,6 +191,45 @@ uv pip install --torch-backend=auto monai-physio   # auto-detected PyTorch, no C
 not Python symbols; no code referenced `[physicsnemo]` or the other removed
 extras, so only install commands change.
 
+## `physicsnemo_tools.py` free functions - wrapped into `PhysicsNemoTools`
+
+**Change:** `physicsnemo_tools.py` had no class - it was free functions
+(`parse_manifest`, `load_target_array`, `build_node_features`,
+`mesh_to_edge_index`, `compute_edge_features`, `import_meshgraphnet`,
+`unwrap_model`, `uncompiled_state_dict`, `strip_compile_prefix`). Those are
+now `@staticmethod`s on a new `PhysicsNemoTools` class, so `parse_manifest(path)`
+becomes `PhysicsNemoTools.parse_manifest(path)`, etc. `distributed_context` is
+unaffected: it remains a top-level free function (`from monai_physio import
+distributed_context`), now implemented as a thin wrapper around
+`PhysicsNemoTools.distributed_context()`. `PhaseEntry`, `SubjectManifest`,
+`DistributedContext`, `PhaseSampleDataset` are unaffected -
+`from monai_physio import DistributedContext` still works.
+
+**Why:** grouping the PhysicsNeMo helpers under one class namespace matches
+the `*Tools` pattern used by every other utility module in the project
+(`ImageTools`, `ContourTools`, `TransformTools`, etc.), instead of being the
+only module exposing a flat set of free functions at import time.
+
+**Before**
+
+```python
+from monai_physio.physicsnemo_tools import parse_manifest
+
+manifest = parse_manifest(manifest_path)
+```
+
+**After**
+
+```python
+from monai_physio import PhysicsNemoTools
+
+manifest = PhysicsNemoTools.parse_manifest(manifest_path)
+```
+
+**Automated conversion:** `None needed` - the class is a thin wrapper, so a
+manual search-and-replace of `physicsnemo_tools.<function>(` ->
+`PhysicsNemoTools.<function>(` covers every call site.
+
 ## Entry template
 
 Append one section per breaking change, newest last, using this shape:

docs/developer/usd_generation.rst

@@ -158,7 +158,7 @@ produced by ``TransformTools.convert_transform_to_usd_visualization`` and
 that already has a Camera does not produce a duplicate transform op.
 
 Anatomy Materials with USDAnatomyTools
-=======================================
+==========================================
 
 :class:`monai_physio.USDAnatomyTools` applies OmniSurface materials to
 labeled meshes after conversion. It reads :class:`AnatomyTaxonomy` from the

experiments/Heart-Create_Statistical_Model/2-input_surfaces_to_surfaces_aligned.py

@@ -12,10 +12,9 @@
 #
 
 # %%
-import itk
-
 from pathlib import Path
 
+import itk
 import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd

experiments/Heart-Create_Statistical_Model/3-registration_based_correspondence.py

@@ -17,15 +17,14 @@
 # - Mask-based approach focuses registration on the anatomical structures
 
 # %%
-import itk
+from pathlib import Path
 
+import itk
 import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd
 import pyvista as pv
 
-from pathlib import Path
-
 from monai_physio.contour_tools import ContourTools
 from monai_physio.register_models_distance_maps import RegisterModelsDistanceMaps
 

experiments/Heart-GatedCT-OptimizedLongitudinalRegistration/1-initial_registration.py

@@ -136,7 +136,7 @@ def landmark_rms_errors(
     landmarks, in sorted-name order.
     """
     errors: list[tuple[str, float]] = []
-    for name in fixed_landmarks.keys():
+    for name in fixed_landmarks:
         if name not in warped_landmarks:
             errors.append((name, float("nan")))
             continue

experiments/Heart-GatedCT_To_USD/2-generate_segmentation.py

@@ -40,7 +40,7 @@
         arr = itk.array_from_image(image)
         print(arr.shape)
         arr = np.where(arr == 0, -1000, arr)
-        for i in range(0, 21):
+        for i in range(21):
             print(f"Processing slice {i:03d}...")
             tmp_arr = itk.array_from_image(
                 itk.imread(

experiments/Heart_and_Lungs_Motion/0-heart_and_lungs_beating_heart.py

@@ -109,9 +109,9 @@ def _ensure_mgn_inference_assets(
     edge_index_file = model_dir / "shared_edge_index.pt"
     edge_feats_file = model_dir / "shared_edge_features.pt"
     if not edge_index_file.exists() or not edge_feats_file.exists():
-        edge_index = pnt.mesh_to_edge_index(mean_surface)
+        edge_index = pnt.PhysicsNemoTools.mesh_to_edge_index(mean_surface)
         coords = np.asarray(mean_surface.points, dtype=np.float32)
-        edge_feats = pnt.compute_edge_features(coords, edge_index)
+        edge_feats = pnt.PhysicsNemoTools.compute_edge_features(coords, edge_index)
         torch.save(edge_index, str(edge_index_file))
         torch.save(edge_feats, str(edge_feats_file))
 

experiments/Lung-GatedCT_To_USD/1-make_dirlab_models.py

@@ -6,8 +6,8 @@
 import pyvista as pv
 from data_dirlab_4d_ct import DataDirLab4DCT
 
-from monai_physio.contour_tools import ContourTools
 from monai_physio import ConvertVTKToUSD
+from monai_physio.contour_tools import ContourTools
 from monai_physio.segment_chest_total_segmentator import SegmentChestTotalSegmentator
 
 # Defensive: today this script only reads `seg.all_mask_ids`, but if anyone

src/monai_physio/__init__.py

@@ -52,10 +52,9 @@
         stacklevel=2,
     )
 
+# Data processing utilities
 from .anatomy_taxonomy import AnatomyGroup, AnatomyTaxonomy
 from .contour_tools import ContourTools
-
-# Data processing utilities
 from .convert_image_4d_to_3d import ConvertImage4DTo3D
 from .convert_vtk_to_usd import ConvertVTKToUSD
 from .data_download_tools import DataDownloadTools
@@ -73,7 +72,7 @@
 
 # Base classes
 from .monai_physio_base import MONAIPhysioBase
-from .physicsnemo_tools import DistributedContext, distributed_context
+from .physicsnemo_tools import DistributedContext, PhysicsNemoTools, distributed_context
 from .register_images_ants import RegisterImagesANTS
 
 # Registration classes
@@ -152,6 +151,7 @@
     # Base classes
     "MONAIPhysioBase",
     "MovementGroundTruth",
+    "PhysicsNemoTools",
     "RegisterImagesANTS",
     # Registration classes
     "RegisterImagesBase",

src/monai_physio/contour_tools.py

@@ -6,7 +6,8 @@
 
 import logging
 import os
-from typing import Optional, Sequence, cast
+from collections.abc import Sequence
+from typing import Optional, cast
 
 import itk
 import numpy as np
@@ -758,7 +759,7 @@ def trim_tetrahedra_to_surface(
     def repair_inverted_tetrahedra(
         self,
         tetrahedra: pv.UnstructuredGrid,
-        max_iterations: int = 20,
+        max_iterations: int = 100,
     ) -> pv.UnstructuredGrid:
         """Relax the nodes of any inverted or degenerate tetrahedron.
 
@@ -828,13 +829,20 @@ def volumes(points: np.ndarray) -> np.ndarray:
                 if len(neighbor_points):
                     points[node] = neighbor_points.mean(axis=0)
 
-        still_bad = int(np.sum(volumes(points) <= 0.0))
+        final_volumes = volumes(points)
+        still_bad_mask = final_volumes <= 0.0
+        still_bad = int(np.sum(still_bad_mask))
         if still_bad:
+            details = "; ".join(
+                f"cell {cell_id} (nodes {connectivity[cell_id].tolist()}): "
+                f"volume={final_volumes[cell_id]:.3e}"
+                for cell_id in np.nonzero(still_bad_mask)[0]
+            )
             raise ValueError(
                 f"{still_bad} of {len(connectivity)} tetrahedra are still "
                 f"inverted or degenerate after {max_iterations} repair "
-                "passes; the fitted mesh needs a real re-fit, not just "
-                "smoothing."
+                f"passes ({details}); the fitted mesh needs a real re-fit, "
+                "not just smoothing."
             )
 
         self.log_warning(

src/monai_physio/convert_vtk_to_usd.py

@@ -235,7 +235,7 @@ def from_files(
         mask_ids: Optional[dict[int, str]] = None,
         segmenter: Optional[SegmentAnatomyBase] = None,
         log_level: int | str = logging.INFO,
-    ) -> "ConvertVTKToUSD":
+    ) -> ConvertVTKToUSD:
         """Create a converter by loading VTK files from disk.
 
         Accepts .vtk (legacy), .vtp (PolyData), and .vtu (UnstructuredGrid) files.
@@ -462,7 +462,7 @@ def set_colormap(
         color_by_array: Optional[str] = None,
         colormap: str = "plasma",
         intensity_range: Optional[tuple[float, float]] = None,
-    ) -> "ConvertVTKToUSD":
+    ) -> ConvertVTKToUSD:
         """
         Configure colormap for visualization.
 
@@ -495,7 +495,7 @@ def compute_von_mises_stress(
         self,
         stress_array_name: str = "stress",
         output_name: str = "von_mises_stress",
-    ) -> "ConvertVTKToUSD":
+    ) -> ConvertVTKToUSD:
         """Add a scalar von Mises stress array derived from a 9-component
         stress tensor on every input mesh.
 
@@ -875,9 +875,9 @@ def _vtk_to_mesh_data(
 
         # Extract surface if needed
         if self.convert_to_surface and not isinstance(vtk_mesh, pv.PolyData):
-            if isinstance(vtk_mesh, pv.UnstructuredGrid):
-                vtk_mesh = vtk_mesh.extract_surface(algorithm="dataset_surface")
-            elif hasattr(vtk_mesh, "extract_surface"):
+            if isinstance(vtk_mesh, pv.UnstructuredGrid) or hasattr(
+                vtk_mesh, "extract_surface"
+            ):
                 vtk_mesh = vtk_mesh.extract_surface(algorithm="dataset_surface")
             elif hasattr(vtk_mesh, "extract_geometry"):
                 vtk_mesh = vtk_mesh.extract_geometry()