Tutorials

PhysioMotion4D tutorials

Build animated medical USD workflows for NVIDIA Omniverse

Nine focused tutorials walk through CT segmentation, registration, statistical model fitting, high-resolution 4D reconstruction, and USD export. Each card links to implementation details, datasets, and the percent-cell Python script used to run the workflow.

01

Heart-Gated CT to Animated USD

Convert cardiac 4D CT frames into registered contours and an animated OpenUSD model.

Slicer-Heart-CT 02

CT Segmentation to VTK Surfaces

Segment one CT phase and export patient anatomy as VTK PolyData surfaces.

Slicer-Heart-CT 03

Create a PCA Shape Model

Build a statistical shape model from aligned cardiac meshes.

KCL-Heart-Model 04

Fit Statistical Model to Patient

Fit a PCA heart model to patient-specific anatomy for model-based reconstruction.

Tutorial 3 output 05

VTK Surface Series to Animated USD

Convert VTK meshes into a time-sampled USD scene for Omniverse playback.

Tutorial 2 output 06

Reconstruct High-Resolution 4D CT

Register respiratory CT phases and reconstruct a higher-resolution 4D volume series.

DirLab-4DCT 07

DirLab Lung-Lobe PCA Model

Build a surface PCA model from five lung lobes and fit it to all cases.

DirLab-4DCT 08

DirLab PCA Time-Series Propagation

Register respiratory phases with ANTs+ICON and propagate fitted meshes.

Tutorial 7 output 09

PhysicsNeMo Mesh Stage Model

Train a PhysicsNeMo MLP to predict lung-lobe meshes at requested stages.

Tutorial 8 output

Recommended Run Order

Tutorials are # %% percent-cell Python scripts. Each script defines its data and output paths near the top, using repository data/ and output/ directories by default. Edit those constants for tutorial exploration, or use the installed physiomotion4d-* CLI commands when you need command-line path arguments.

1. Run Tutorials 1 and 2 after preparing Slicer-Heart-CT data.

2. Run Tutorial 5 after Tutorial 2 because it consumes Tutorial 2 output.

3. Run Tutorial 3 after downloading KCL-Heart-Model.

4. Run Tutorial 4 after Tutorial 3 because it can consume the PCA model output.

5. Run Tutorial 6 after downloading DirLab-4DCT.

6. Run Tutorial 7 after downloading DirLab-4DCT.

7. Run Tutorial 8 after Tutorial 7 because it consumes fitted PCA meshes.

8. Run Tutorial 9 after Tutorial 8 because it trains from propagated meshes.

Tutorial 1: Heart-Gated CT to Animated USD

Script

tutorials/tutorial_01_heart_gated_ct_to_usd.py

Workflow

WorkflowConvertHeartGatedCTToUSD

Dataset

Slicer-Heart-CT, prepared before running the tutorial.

Run

python tutorials/tutorial_01_heart_gated_ct_to_usd.py

Outputs

Registered phase images, transformed contours, preview screenshots, and an animated USD model.

Tutorial 2: CT Segmentation to VTK Surfaces

Script

tutorials/tutorial_02_ct_to_vtk.py

Workflow

WorkflowConvertCTToVTK

Dataset

Slicer-Heart-CT, prepared before running the tutorial.

Run

python tutorials/tutorial_02_ct_to_vtk.py

Outputs

Segmentation artifacts, VTK PolyData surfaces, and preview screenshots.

Tutorial 3: Create a PCA Shape Model

Script

tutorials/tutorial_03_create_statistical_model.py

Workflow

WorkflowCreateStatisticalModel

Dataset

KCL-Heart-Model, downloaded manually.

Run

python tutorials/tutorial_03_create_statistical_model.py

Outputs

PCA model files, mean shape, and component diagnostics.

Tutorial 4: Fit Statistical Model to Patient

Script

tutorials/tutorial_04_fit_statistical_model_to_patient.py

Workflow

WorkflowFitStatisticalModelToPatient

Dataset

KCL-Heart-Model, downloaded manually.

Run

python tutorials/tutorial_04_fit_statistical_model_to_patient.py

Outputs

Patient-fitted statistical model surfaces and registration diagnostics.

Tutorial 5: VTK Surface Series to Animated USD

Script

tutorials/tutorial_05_vtk_to_usd.py

Workflow

WorkflowConvertVTKToUSD

Dataset

Output from Tutorial 2.

Run

python tutorials/tutorial_05_vtk_to_usd.py

Outputs

Time-sampled USD scene and conversion logs for Omniverse inspection.

Tutorial 6: Reconstruct High-Resolution 4D CT

Script

tutorials/tutorial_06_reconstruct_highres_4d_ct.py

Workflow

WorkflowReconstructHighres4DCT

Dataset

DirLab-4DCT, downloaded manually.

Run

python tutorials/tutorial_06_reconstruct_highres_4d_ct.py

Outputs

Registered respiratory phases, reconstructed high-resolution CT volumes, and preview screenshots.

Tutorial 7: DirLab Lung-Lobe PCA Model

Script

tutorials/tutorial_07_dirlab_pca_model.py

Workflow

WorkflowConvertCTToVTK, WorkflowCreateStatisticalModel, and WorkflowFitStatisticalModelToPatient

Dataset

DirLab-4DCT, downloaded manually.

Run

python tutorials/tutorial_07_dirlab_pca_model.py

Outputs

Five-lobe lung surface meshes, a surface PCA model, and PCA-fitted surfaces for every available case.

Tutorial 8: DirLab PCA Time-Series Propagation

Script

tutorials/tutorial_08_dirlab_pca_time_series.py

Workflow

RegisterTimeSeriesImages with registration_method='ants_icon' and TransformTools

Dataset

DirLab-4DCT plus Tutorial 7 fitted mesh outputs.

Run

python tutorials/tutorial_08_dirlab_pca_time_series.py

Outputs

Per-case ANTs+ICON transforms and one PCA-fitted lung-lobe surface for each DirLab respiratory phase.

Tutorial 9: PhysicsNeMo Mesh Stage Model

Script

tutorials/tutorial_09_physicsnemo_mesh_stage_model.py

Workflow

physicsnemo.models.mlp.FullyConnected trained on Tutorial 8 meshes.

Dataset

Tutorial 8 propagated PCA mesh outputs.

Run

python tutorials/tutorial_09_physicsnemo_mesh_stage_model.py

Outputs

Per-case PhysicsNeMo checkpoints, training metadata, loss histories, and a predicted PCA-fitted mesh at the requested normalized respiratory stage.

Dataset Notes

The repository-level tutorials/README.md has the most detailed dataset preparation notes. The tutorials are also exercised by tests/test_tutorials.py behind the --run-tutorials opt-in flag.