ENH: AnatomyTaxonomy, USD pipeline hardening, tutorials + docs (#49)

* ENH: AnatomyTaxonomy, USD pipeline hardening, tutorials + docs

Replaces the per-organ flat dicts on SegmentAnatomyBase and USDAnatomyTools
with a shared AnatomyTaxonomy data type so new segmenters can register
custom groups via taxonomy.add_organ without subclassing either class.
Adds anatomy-type grouping to ConvertVTKToUSD's labeled output, ships
tutorials 07-09 (DirLab PCA + PhysicsNeMo), and fixes several USD-
pipeline issues that prevented clean rendering in Omniverse Kit.

Anatomy / segmentation
- AnatomyTaxonomy + AnatomyGroup (new). SegmentAnatomyBase owns one;
  subclasses populate via taxonomy.add_organ and call
  _finalize_other_group. Eight legacy *_mask_ids attributes and
  set_other_and_all_mask_ids removed; label_to_type delegates to the
  taxonomy. segment() now returns only the groups the segmenter
  registered (caller-checks contract; tests updated).
- SegmentHeartSimpleware: graceful fallback when ASCardio omits
  landmarks.csv; only the groups it actually populates are returned.

USD generation
- ConvertVTKToUSD: new segmenter= parameter groups labeled prims under
  /World/{basename}/{type}/{label} and materials under
  /World/Looks/{type}/{label}_material. Preserves cell-data primvars;
  new compute_von_mises_stress helper for 9-component stress tensors;
  framing camera with tight near-clip; stale USD-layer eviction;
  triangulation face-map propagated to uniform primvars so per-cell
  arrays survive quad-to-triangle splits.
- USDAnatomyTools: DEFAULT_RENDER_PARAMS promoted to a module-level
  constant so CLIs/tests can enumerate types without a stage; per-
  instance deep copy keeps mutations isolated; enhance_meshes now a
  single taxonomy loop with organ-level overrides as data instead of
  imperative carve-outs. MaterialBindingAPI.Apply() so Omniverse RTX
  consumes the binding (was rendering white).
- CLI convert_vtk_to_usd: ANATOMY_TYPES sourced from
  DEFAULT_RENDER_PARAMS (auto-syncs with future additions); "kidney"
  alias preserved.

Tutorials / experiments
- Tutorials 07-09 added (DirLab PCA lung-lobe model, time-series
  propagation, PhysicsNeMo mesh-stage training).
- Tutorials 02-09 gain if __name__ == "__main__" guards (Windows
  nnUNet spawn) matching tutorial_01; experiments gain the same
  guards plus Path(__file__)-anchored paths; valve scripts wire
  compute_von_mises_stress.
- notebook_utils.py removed (last consumers gone); experiment scripts
  and READMEs scrubbed of .ipynb references; test runner already on
  *.py glob.

Tests, docs, packaging
- New test_anatomy_taxonomy (12 tests); mask_ids / Simpleware
  assertions updated to the caller-checks contract; tutorial test
  harness rewritten.
- Segmentation .rst pages, developer/segmentation.rst, and developer/
  usd_generation.rst updated to document AnatomyTaxonomy, the
  type-grouped layout, von Mises helper, framing camera, and the
  three ways to register a new group's look.
- New CLI .rst pages, simpleware/greedy API pages, vtk_to_usd_lib
  page, data_download / test_tools utility pages; API_MAP.md
  regenerated.
- mypy: 7 errors fixed (Optional render-params indexing, redundant
  np.asarray casts, pyvista Plotter binding via Any cast,
  matplotlib colormap return typing). Full src/ tree clean.

Other
- data_download_tools.py extracted (was notebook_utils.py glue).
- pyproject.toml mypy overrides tightened.
- Stale baseline PNGs removed (regenerated by test_tools at runtime).

* COMP: Bump CI to Python 3.11.  3.10 is no longer supported.

* ENH: PR review fixes, save_3d_images split, USD utils, deps

save_3d_images: split the single basename argument into (directory,
basename); create the directory if needed. Propagated to all 7 callers
across src/, tests/, experiments/, data/Slicer-Heart-CT, and the
gated-CT workflow.

USDTools: move the module-level load_openusd_as_vtk and
_openusd_display_color helpers onto USDTools as load_usd_as_vtk and
_usd_display_color; update test_tools and test_vtk_to_usd_library
callers.

Tutorial outputs unified under TUTORIALS_DIR / "output" / ... so
tutorials 01/07/08/09 agree with tests/test_tutorials.py.

tutorial_01: drop the stray "test_mode = True" override so
TestTools.running_as_test() actually drives data_dir selection and
registration iteration count.

tutorial_08: validate phase_files, forward_transforms, and
inverse_transforms have equal length and raise ValueError on mismatch
before zipping so dropped frames surface instead of truncating
silently.

experiments/Heart-GatedCT_To_USD/3: move TestTools.running_as_test()
inside the __main__ guard so behavior matches the defensive
Windows-spawn comment.

vtk_to_usd/usd_utils.add_framing_camera: pick the camera offset axis
perpendicular to the stage up axis (+Y for Z-up stages, +Z otherwise)
so Z-up stages frame correctly.

Bump pyvista[all] floor: >=0.43.0 -> >=0.47.0.

Drop legacy Verity{SlicerHeartCT,KCLHeartModel}Data typo shims in
data_download_tools; current code only uses Verify* spellings.

docs/api/cli/index.rst: fix "an main() function" -> "a main() function".

docs/contributing.rst: drop the now-obsolete "If users might copy your
code..." paragraph.

docs/API_MAP.md regenerated.

* ENH: Enable offscreen rendering in github CI runners.

* ENH: No offscreen rendering on windows, disable certain tests

* ENH: Simplify results and baseline paths for tests

* BUG: Camera should point to center of bbox

* BUG: Ensure download goes to unique tmp file

* DOC: Cleanup doc mentions of notebook

* DOC: Remove reference to notebook/ipynb and emojis

* DOC: Minor doc fixes

Author: aylward

.agents/.gitignore

@@ -1 +1,2 @@
 settings.local.json
+.nicc*

.github/workflows/README.md

@@ -10,7 +10,7 @@ Runs on every push and pull request to main branches. Includes:
 
 - **unit-tests**: Cross-platform unit tests
   - Runs on Ubuntu and Windows
-  - Python 3.10, 3.11, and 3.12
+  - Python 3.11 and 3.12
   - Uses PyTorch CPU version to avoid GPU dependencies
   - Excludes slow tests and tests requiring external data
   - Generates coverage reports
@@ -83,7 +83,7 @@ The workflows use multiple caching layers to speed up builds:
 
 ### Important: GPU Tests Are Disabled by Default
 
-⚠️ **GPU tests do NOT run automatically** to prevent jobs from waiting indefinitely in the queue when no runner is available.
+**GPU tests do NOT run automatically** to prevent jobs from waiting indefinitely in the queue when no runner is available.
 
 To run GPU tests, you must either:
 1. **Manually trigger the workflow**: Go to Actions > CI > Run workflow

.github/workflows/ci.yml

@@ -30,7 +30,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest]
-        python-version: ['3.10', '3.11', '3.12']
+        python-version: ['3.11', '3.12']
 
     steps:
     - name: Checkout code
@@ -79,7 +79,9 @@ jobs:
           libxrender1 \
           libxext6 \
           libxrandr2 \
-          libxi6
+          libxi6 \
+          xvfb \
+          libosmesa6
         sudo apt-get clean
         sudo rm -rf /var/lib/apt/lists/*
 
@@ -99,13 +101,20 @@ jobs:
       run: |
         pip list
 
-    - name: Run unit tests (fast, no external data)
+    - name: Run unit tests (fast, no external data) - Ubuntu
+      if: matrix.os == 'ubuntu-latest'
+      run: |
+        xvfb-run -a --server-args="-screen 0 1024x768x24" \
+          pytest tests/ -v -m "not slow and not requires_data and not experiment" --cov=physiomotion4d --cov-report=xml --cov-report=term --cov-report=html
+
+    - name: Run unit tests (fast, no external data) - Windows
+      if: matrix.os == 'windows-latest'
       run: |
         pytest tests/ -v -m "not slow and not requires_data and not experiment" --cov=physiomotion4d --cov-report=xml --cov-report=term --cov-report=html
 
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v4
-      if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.10'
+      if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
         file: ./coverage.xml
@@ -115,7 +124,7 @@ jobs:
 
     - name: Upload coverage artifacts
       uses: actions/upload-artifact@v4
-      if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.10'
+      if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
       with:
         name: coverage-report-unit-tests
         path: htmlcov/
@@ -148,10 +157,10 @@ jobs:
         echo "Disk space after cleanup:"
         df -h
 
-    - name: Set up Python 3.10
+    - name: Set up Python 3.11
       uses: actions/setup-python@v5
       with:
-        python-version: '3.10'
+        python-version: '3.11'
         cache: 'pip'
         cache-dependency-path: pyproject.toml
 
@@ -185,7 +194,9 @@ jobs:
           libxrender1 \
           libxext6 \
           libxrandr2 \
-          libxi6
+          libxi6 \
+          xvfb \
+          libosmesa6
         sudo apt-get clean
         sudo rm -rf /var/lib/apt/lists/*
 
@@ -218,17 +229,20 @@ jobs:
 
     - name: Run USD conversion tests
       run: |
-        pytest tests/test_convert_vtk_to_usd_polymesh.py -v -m "not slow" --cov=physiomotion4d --cov-append --cov-report=xml
+        xvfb-run -a --server-args="-screen 0 1024x768x24" \
+          pytest tests/test_convert_vtk_to_usd_polymesh.py -v -m "not slow" --cov=physiomotion4d --cov-append --cov-report=xml
       continue-on-error: true
 
     - name: Run USD utility tests
       run: |
-        pytest tests/test_usd_merge.py tests/test_usd_time_preservation.py -v --cov=physiomotion4d --cov-append --cov-report=xml
+        xvfb-run -a --server-args="-screen 0 1024x768x24" \
+          pytest tests/test_usd_merge.py tests/test_usd_time_preservation.py -v --cov=physiomotion4d --cov-append --cov-report=xml
       continue-on-error: true
 
     - name: Run all integration tests
       run: |
-        pytest tests/ -v -m "not slow and not experiment and not requires_gpu"
+        xvfb-run -a --server-args="-screen 0 1024x768x24" \
+          pytest tests/ -v -m "not slow and not experiment and not requires_gpu"
       continue-on-error: true
 
     - name: Upload coverage to Codecov
@@ -345,10 +359,10 @@ jobs:
       with:
         lfs: true
 
-    - name: Set up Python 3.10
+    - name: Set up Python 3.11
       uses: actions/setup-python@v5
       with:
-        python-version: "3.10"
+        python-version: "3.11"
         cache: 'pip'
 
     - name: Install dev dependencies

.github/workflows/release.yml

@@ -32,7 +32,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
         with:
-          python-version: '3.10'
+          python-version: '3.11'
 
       - name: Install build tools
         run: |

CLAUDE.md

@@ -36,7 +36,7 @@ py -m pytest tests/ --ignore=tests/test_segment_chest_total_segmentator.py \
 # With coverage
 py -m pytest tests/ --cov=src/physiomotion4d --cov-report=html
 
-# Experiment notebook tests (very slow, opt-in)
+# Experiment script tests (very slow, opt-in)
 py -m pytest tests/ --run-experiments
 
 # Create missing baselines