ENH: New submodule for vtk_to_usd with correct colormap handling (#23)

Author: aylward

.cursor/rules/project-standards.mdc

@@ -0,0 +1,80 @@
+---
+description: PhysioMotion4D project standards and workflow preferences
+alwaysApply: true
+---
+
+# PhysioMotion4D Project Standards
+
+## File Operations
+
+**ALWAYS use git commands for file operations in this repository:**
+
+```bash
+# Moving files
+git mv old_path new_path
+
+# Deleting files
+git rm file_path
+
+# Renaming files
+git mv old_name.py new_name.py
+```
+
+❌ **Don't use**: `mv`, `rm`, `cp` directly
+✅ **Do use**: `git mv`, `git rm` to maintain git history
+
+## Documentation
+
+**Do NOT create extra documentation files** describing what was done:
+
+❌ **Don't create**:
+- `MIGRATION.md`
+- `CHANGES.md`
+- `UPDATE_SUMMARY.md`
+- `MODERNIZATION_*.md`
+- Similar meta-documentation files
+
+✅ **Do document**:
+- In-code docstrings
+- README files for new modules
+- Inline comments for complex logic
+- API documentation in existing docs
+
+## Backward Compatibility
+
+**Backward compatibility is NOT a priority** for this project:
+
+- Feel free to make breaking changes to improve code quality
+- Remove deprecated code without extensive migration paths
+- Update APIs for clarity and consistency
+- Prioritize modern, clean design over legacy support
+
+## Code Style
+
+- Use descriptive variable and function names
+- Add type hints to Python functions
+- Keep functions focused and small
+- Use `logging` module instead of `print` statements
+- Follow PEP 8 for Python code
+
+## Testing
+
+- Test new functionality with Jupyter notebooks in `experiments/`
+- Update existing tests when changing APIs
+- Use meaningful test names that describe what is being tested
+
+## Git Workflow
+
+**Do NOT stage files automatically:**
+
+❌ **Don't use**: `git add`, `git stage`
+✅ **Do use**: `git status` to show what changed
+✅ **User will**: Stage files themselves when ready
+
+The user prefers to review and stage changes manually.
+
+**Other git guidelines:**
+- Use `git rm` and `git mv` for file operations
+- Make atomic commits with clear messages
+- Don't commit large binary files (add to `.gitignore`)
+- Use `git status` to verify changes before committing

.pre-commit-config.yaml

@@ -37,4 +37,4 @@ repos:
         pass_filenames: false
         always_run: false
         files: ^(src/physiomotion4d/|tests/)
-        stages: [pre-push]
+        stages: [pre-push]

README.md

@@ -107,8 +107,16 @@ print(f"PhysioMotion4D version: {physiomotion4d.__version__}")
 - **Utility Classes**: Tools for data manipulation and conversion
   - `TransformTools`: Comprehensive transform manipulation utilities
   - `USDTools`: USD file manipulation for Omniverse integration
+  - `USDAnatomyTools`: Apply surgical materials to anatomy meshes
   - `ImageTools`: Medical image processing utilities
   - `ContourTools`: Mesh extraction and contour manipulation
+- **USD Conversion**: VTK to USD conversion for Omniverse visualization
+  - `ConvertVTKToUSD`: High-level converter for PyVista/VTK objects with colormap support
+  - `vtk_to_usd` module: File-based conversion library
+    - `VTKToUSDConverter`: Core converter with time-series support
+    - `read_vtk_file()`: Read VTK/VTP/VTU files into MeshData
+    - `ConversionSettings`: Configurable conversion parameters
+    - `MaterialData`: USD material definitions
 
 ### Key Dependencies
 
@@ -261,6 +269,80 @@ inverse_transform = results["inverse_transform"]  # Fixed to moving
 forward_transform = results["forward_transform"]  # Moving to fixed
 ```
 
+### VTK to USD Conversion
+
+PhysioMotion4D provides two APIs for converting VTK data to USD for NVIDIA Omniverse visualization:
+
+#### Option 1: High-Level ConvertVTKToUSD (for PyVista/VTK objects)
+
+```python
+from physiomotion4d import ConvertVTKToUSD
+import pyvista as pv
+
+# Load VTK data
+meshes = [pv.read(f"cardiac_frame_{i:03d}.vtp") for i in range(20)]
+
+# Convert to animated USD with anatomical labels
+converter = ConvertVTKToUSD(
+    data_basename='CardiacModel',
+    input_polydata=meshes,
+    mask_ids={1: 'ventricle', 2: 'atrium', 3: 'vessels'},
+    compute_normals=True
+)
+
+# Optional: Apply colormap visualization
+converter.set_colormap(
+    color_by_array='transmembrane_potential',
+    colormap='rainbow',
+    intensity_range=(-80.0, 20.0)
+)
+
+stage = converter.convert('cardiac_motion.usd')
+```
+
+#### Option 2: File-Based vtk_to_usd Library
+
+```python
+from physiomotion4d.vtk_to_usd import (
+    VTKToUSDConverter,
+    ConversionSettings,
+    MaterialData,
+    convert_vtk_file,
+)
+
+# Simple single-file conversion
+stage = convert_vtk_file('mesh.vtp', 'output.usd')
+
+# Advanced: Custom settings and materials
+settings = ConversionSettings(
+    triangulate_meshes=True,
+    compute_normals=True,
+    meters_per_unit=0.001,  # mm to meters
+    times_per_second=60.0,
+)
+
+material = MaterialData(
+    name="cardiac_tissue",
+    diffuse_color=(0.9, 0.3, 0.3),
+    roughness=0.4,
+)
+
+converter = VTKToUSDConverter(settings)
+stage = converter.convert_file('heart.vtp', 'heart.usd', material=material)
+
+# Time-series conversion
+files = ['frame_000.vtp', 'frame_001.vtp', 'frame_002.vtp']
+time_codes = [0.0, 0.1, 0.2]
+stage = converter.convert_sequence(files, 'animated.usd', time_codes=time_codes)
+```
+
+Features:
+- Automatic coordinate system conversion (RAS to Y-up)
+- Material system with UsdPreviewSurface
+- Preserves all VTK data arrays as USD primvars
+- Time-series animation support
+- Supports VTP, VTK, and VTU file formats
+
 ### Logging and Debug Control
 
 PhysioMotion4D provides standardized logging through the `PhysioMotion4DBase` class, which is inherited by workflow and registration classes.

data/CHOP-Valve4D/.gitignore

@@ -0,0 +1,2 @@
+Alterra*
+TPV*

data/KCL-Heart-Model/README.md

@@ -1,5 +1,17 @@
 # KCL Heart Model Dataset
 
+## ⚠️ Manual Download Required
+
+**This data is NOT automatically downloaded.** Users must manually download and preprocess the required files.
+
+### Required Files for PhysioMotion4D
+
+The following files must be present in this directory for VTK to USD conversion:
+- `average_surface.vtp` - Mean heart surface mesh (VTK PolyData format)
+- `average_mesh.vtk` - Mean heart volume mesh (VTK UnstructuredGrid format)
+
+These files can be generated from the KCL dataset using conversion tools provided in this directory.
+
 ## Overview
 
 This directory contains data from the King's College London (KCL) four-chamber heart model dataset, which provides a virtual cohort of adult healthy heart meshes derived from CT images.
@@ -74,4 +86,3 @@ For questions about the dataset, contact the original authors:
 - Pablo Lamata, King's College London
 
 For questions about SlicerSALT, contact: beatriz.paniagua@kitware.com
-