ENH: GPU Tutorial 4 meshing (~27x); split ProcessContours

.agents/agents/architecture.md

@@ -22,7 +22,9 @@ src/monai_physio/
   segment_chest_*.py          - TotalSegmentator, VISTA-3D, NIM, Ensemble
   register_images_*.py        - ICON, ANTs, Greedy, time-series wrappers
   register_models_*.py        - ICP, PCA, distance-map registerers
-  process_contours.py            - surface extraction from ITK masks
+  process_surface_mesh.py        - surface extraction from ITK masks
+  process_volumetric_mesh.py     - tetrahedral meshes from ITK masks
+  process_mesh_kernels.py        - GPU primitives for both mesh modules
   convert_vtk_to_usd.py       - high-level VTK→USD (in-memory, PyVista)
   vtk_to_usd/                 - file-based VTK→USD subpackage
   process_usd.py / process_usd_anatomy.py - USD stage utilities

.agents/agents/implementation.md

@@ -19,7 +19,7 @@ tutorials may require a GPU.
 4D CT → Segmentation → Registration → Contour Extraction → USD Export
 
 Key modules: `monai_physio_base.py`, `segment_chest_*.py`, `register_images_*.py`,
-`register_models_*.py`, `process_contours.py`, `convert_vtk_to_usd.py`, `vtk_to_usd/`,
+`register_models_*.py`, `process_surface_mesh.py`, `process_volumetric_mesh.py`, `convert_vtk_to_usd.py`, `vtk_to_usd/`,
 `workflow_*.py`. Use `graphify query "<question>"` to locate classes before
 searching manually.
 

.agents/agents/testing.md

@@ -32,7 +32,7 @@ to the project interpreter. If activation is impossible, use
 ```powershell
 python -m pytest tests/ -v                                        # fast, recommended (slow/GPU/etc auto-skipped)
 python -m pytest tests/test_contour_tools.py -v                   # single file
-python -m pytest tests/test_contour_tools.py::TestProcessContours -v # single class
+python -m pytest tests/test_process_surface_mesh.py::TestProcessSurfaceMesh -v # single class
 python -m pytest tests/ -v --run-slow                             # opt into slow tests
 # typical local GPU profile; CI adds --run-simpleware --run-tutorials
 python -m pytest tests/ -v --run-gpu --run-slow

.github/workflows/nightly-health.yml

@@ -115,11 +115,11 @@ jobs:
         # installed before ANY monai-physio extra is resolved, since
         # torch-scatter is now a base dependency and is pulled in immediately.
         #
-        # torch, torchvision, and torchaudio are all pinned to the pytorch-cu130
+        # torch and torchvision are both pinned to the pytorch-cu130
         # index here because the uv pip interface ignores tool.uv.sources.
-        # Pinning torch alone is not enough: the [cuda13] extra leaves the other
-        # two unconstrained, so they would resolve from PyPI and be built
-        # against a different CUDA runtime than torch. Installing all three up
+        # Pinning torch alone is not enough: the [cuda13] extra leaves
+        # torchvision unconstrained, so it would resolve from PyPI and be built
+        # against a different CUDA runtime than torch. Installing both up
         # front means [cuda13] finds them already satisfied. --index-url (not
         # --index) replaces PyPI for this command and matches the flag used in
         # .readthedocs.yaml; the pytorch index also serves the transitive deps.
@@ -132,7 +132,7 @@ jobs:
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
           python -m uv pip install setuptools wheel
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
-          python -m uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130
+          python -m uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu130
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
           python -c "import torch; print(f'build-time torch {torch.__version__} (CUDA {torch.version.cuda})')"
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

.pre-commit-config.yaml

@@ -12,24 +12,26 @@ repos:
       # Run the formatter
       - id: ruff-format
 
-  # Type checking with mypy
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v2.1.0
+  # Local hooks run from the active project venv
+  - repo: local
     hooks:
+      # Type checking with mypy. Runs in the project venv rather than an
+      # isolated hook env: the GPU modules are typed against the installed
+      # torch, warp and pyvista, which an isolated env would lack.
+      # Pass only the staged files pre-commit selects (via the files regex);
+      # do not scan whole src/ and tutorials/ trees, which would include
+      # untracked files.
       - id: mypy
-        # Pass only the staged files pre-commit selects (via the files regex);
-        # do not scan whole src/ and tutorials/ trees, which would include
-        # untracked files.
-        args: [--config-file=pyproject.toml]
-        additional_dependencies:
-          - types-setuptools
-          - scipy-stubs
-          - types-requests
+        name: mypy
+        entry: mypy
+        # pre-commit checks files in batches, so per-module config sections for
+        # files outside a batch would be reported as unused.
+        args: [--config-file=pyproject.toml, --no-warn-unused-configs]
+        language: system
+        types: [python]
         files: ^(src/|tutorials/)
 
-  # Local tests (optional - can be disabled if too slow)
-  - repo: local
-    hooks:
+      # Local tests (optional - can be disabled if too slow)
       - id: fast-unit-tests
         name: Run Fast Unit Tests
         entry: pytest tests/ -m "not slow" -v --maxfail=3

AGENTS.md

@@ -82,8 +82,8 @@ python -m pre_commit run --all-files
 python -m pytest tests/ -v
 
 # Single test file or test by name
-python -m pytest tests/test_contour_tools.py -v
-python -m pytest tests/test_contour_tools.py::test_extract_surface -v
+python -m pytest tests/test_process_surface_mesh.py -v
+python -m pytest tests/test_process_surface_mesh.py::TestProcessSurfaceMesh::test_extract_contours_from_heart_mask -v
 
 # Opt-in test buckets
 python -m pytest tests/ -v --run-slow

README.md

@@ -49,10 +49,11 @@ for users and contributors. Key sections:
 ### Install
 
 ```
-uv pip install "monai-physio[cuda12]"
+uv pip install "monai-physio[cuda12]" -f https://data.pyg.org/whl/torch-2.12.0+cu126.html
 ```
 
-Installs entirely from prebuilt wheels. On CUDA 13 use `monai-physio[cuda13]`,
+Installs entirely from prebuilt wheels; the `-f` option points uv at the PyG
+wheel index that hosts `torch-scatter`. On CUDA 13 use `monai-physio[cuda13]`,
 which additionally needs a CUDA toolkit and C++ toolchain to build
 `torch-scatter`. See the
 [installation guide](https://project-monai.github.io/monai-physio/installation.html)

data/test/README.md

@@ -43,7 +43,7 @@ Every subdirectory is created on demand by `tests/conftest.py` fixtures
 the first time a test needs them, and is `.gitignore`d - do not commit
 their contents. The subsets derived from another dataset are only built
 when that source dataset is present under the input root; otherwise the tests
-that need them skip, or fail if `--require-tutorial-data` was passed.
+that need them skip, or fail if `--require-tutorial-data` (or `--run-all`) was passed.
 
 The tutorials read these directories rather than the full datasets whenever
 `MONAI_PHYSIO_RUNNING_AS_TEST` is set, and write to the matching `test` subtree of

docs/api/utilities/image_conversion.rst

@@ -19,4 +19,4 @@ Module Reference
 
 .. rubric:: Navigation
 
-:doc:`process_contours` | :doc:`index` | :doc:`../index`
+:doc:`process_mesh_kernels` | :doc:`index` | :doc:`../index`

docs/api/utilities/index.rst

@@ -28,7 +28,9 @@ Quick Links
    * :doc:`process_labelmaps` - Labelmap to registration-mask conversion
    * :doc:`process_transforms` - Transform operations
    * :doc:`process_landmarks` - Landmark-based registration validation
-   * :doc:`process_contours` - Contour processing
+   * :doc:`process_surface_mesh` - Surface mesh extraction and processing
+   * :doc:`process_volumetric_mesh` - Tetrahedral mesh extraction and relaxation
+   * :doc:`process_mesh_kernels` - GPU mesh and distance-map primitives
    * :doc:`image_conversion` - 4D image to 3D time-series utilities
    * :doc:`process_tests` - Baseline / result comparison helpers
    * :doc:`download_data` - Optional dataset download helpers
@@ -43,7 +45,9 @@ Module Documentation
    process_labelmaps
    process_transforms
    process_landmarks
-   process_contours
+   process_surface_mesh
+   process_volumetric_mesh
+   process_mesh_kernels
    image_conversion
    process_tests
    download_data

docs/api/utilities/process_images.rst

@@ -15,4 +15,4 @@ Module Reference
 
 .. rubric:: Navigation
 
-:doc:`index` | :doc:`process_transforms` | :doc:`process_contours`
+:doc:`index` | :doc:`process_transforms` | :doc:`process_surface_mesh`

docs/api/utilities/process_landmarks.rst

@@ -25,4 +25,4 @@ See Also
 
 .. rubric:: Navigation
 
-:doc:`process_transforms` | :doc:`index` | :doc:`process_contours`
+:doc:`process_transforms` | :doc:`index` | :doc:`process_surface_mesh`

docs/api/utilities/process_mesh_kernels.rst

@@ -0,0 +1,18 @@
+====================================
+Mesh Kernels
+====================================
+
+.. currentmodule:: monai_physio
+
+GPU primitives shared by the surface and volumetric mesh tools: closest-point and inside/outside queries, tetrahedron quality, distance maps, blur and label-vote resampling.
+
+Module Reference
+================
+
+.. automodule:: monai_physio.process_mesh_kernels
+   :members:
+   :undoc-members:
+
+.. rubric:: Navigation
+
+:doc:`process_volumetric_mesh` | :doc:`index` | :doc:`image_conversion`

docs/api/utilities/process_surface_mesh.rst

@@ -0,0 +1,18 @@
+====================================
+Surface Mesh Tools
+====================================
+
+.. currentmodule:: monai_physio
+
+Surfaces from labelmaps and masks, surface remeshing, smoothing and combining, and conversions from surfaces back to images.
+
+Module Reference
+================
+
+.. automodule:: monai_physio.process_surface_mesh
+   :members:
+   :undoc-members:
+
+.. rubric:: Navigation
+
+:doc:`process_transforms` | :doc:`index` | :doc:`process_volumetric_mesh`

docs/api/utilities/process_transforms.rst

@@ -15,4 +15,4 @@ Module Reference
 
 .. rubric:: Navigation
 
-:doc:`process_images` | :doc:`index` | :doc:`process_contours`
+:doc:`process_images` | :doc:`index` | :doc:`process_surface_mesh`

docs/api/utilities/process_volumetric_mesh.rst

@@ -0,0 +1,18 @@
+====================================
+Volumetric Mesh Tools
+====================================
+
+.. currentmodule:: monai_physio
+
+Tetrahedral meshes filling a mask, their relaxation onto a surface, and the repair of inverted elements.
+
+Module Reference
+================
+
+.. automodule:: monai_physio.process_volumetric_mesh
+   :members:
+   :undoc-members:
+
+.. rubric:: Navigation
+
+:doc:`process_surface_mesh` | :doc:`index` | :doc:`process_mesh_kernels`

docs/api/workflows.rst

@@ -95,7 +95,6 @@ Image to VTK
    import itk
 
    from monai_physio import (
-       ProcessContours,
        SegmentChestTotalSegmentatorWithContrast,
        WorkflowConvertImageToVTK,
    )
@@ -109,7 +108,7 @@ Image to VTK
        anatomy_groups=["heart", "major_vessels"],
    )
 
-   ProcessContours.save_combined_surfaces(
+   WorkflowConvertImageToVTK.save_combined_surfaces(
        result["surfaces"],
        "./output/patient01_surfaces.vtp",
    )

docs/architecture.rst

@@ -31,7 +31,7 @@ Data Flow
    SegmentNVSegmentCT (CT only)
           |
           v
-   ProcessContours + ProcessTransforms
+   ProcessSurfaceMesh + ProcessVolumetricMesh + ProcessTransforms
           |
           v
    WorkflowConvertImageToVTK / ConvertVTKToUSD / WorkflowConvertVTKToUSD

docs/cli_scripts/byod_tutorials.rst

@@ -18,7 +18,7 @@ or the CPU-only variant:
 .. code-block:: bash
 
    # Recommended - CUDA 12.6, everything installs from prebuilt wheels
-   uv pip install "monai-physio[cuda12]"
+   uv pip install "monai-physio[cuda12]" -f https://data.pyg.org/whl/torch-2.12.0+cu126.html
 
    # CUDA 13 - same, but torch-scatter compiles from source
    uv pip install "monai-physio[cuda13]"

docs/conf.py

@@ -184,7 +184,6 @@ def __getattr__(cls, name):
 autodoc_mock_imports = [
     "torch",
     "torchvision",
-    "torchaudio",
     "monai",
     "totalsegmentator",
     "icon_registration",

docs/developer/architecture.rst

@@ -24,7 +24,7 @@ Architecture Diagram
       +--------------+-------------+-------------+
                          |
                          v
-               ProcessContours / ProcessTransforms
+     ProcessSurfaceMesh / ProcessVolumetricMesh / ProcessTransforms
                          |
                          v
               ConvertVTKToUSD / vtk_to_usd

docs/developer/core.rst

@@ -35,7 +35,9 @@ Class Boundaries
 * Registration classes estimate transforms.
 * Segmentation classes return ITK images or dictionaries of ITK masks.
 * ``ProcessTransforms`` applies transforms to images and PyVista contours.
-* ``ProcessContours`` creates and transforms VTK/PyVista surface data.
+* ``ProcessSurfaceMesh`` creates and transforms VTK/PyVista surface data;
+  ``ProcessVolumetricMesh`` builds and relaxes tetrahedral meshes; both run
+  their GPU work through ``ProcessMeshKernels``.
 * ``ProcessUSD`` and ``ProcessUSDAnatomy`` operate on USD stages and files.
 
 Public APIs should be documented in ``docs/api``.