Skip to content

ENH: Simplified naming of tutorials and updated their dirs #89

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aylward merged 7 commits into from
Jul 15, 2026
Merged

ENH: Simplified naming of tutorials and updated their dirs #89

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
02f1d90
ENH: Simplified naming of tutorials and updated their dirs
aylward Jul 15, 2026
d1bec38
ENH: Refactor tutorials to common style
aylward Jul 15, 2026
f2bfac3
ENH: Coderabbit
aylward Jul 15, 2026
065f974
ENH: Code Rabbit
aylward Jul 15, 2026
46c421b
BUG: Fix __main__ isolation for TotalSegmentator bug
aylward Jul 15, 2026
d85705d
ENH: Code Rabbit
aylward Jul 15, 2026
6fa109c
ENH: Resume physicsnemo training from checkpoints
aylward Jul 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions docs/architecture.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,29 +91,29 @@ Primary Workflows
AI Surrogate Workflows (PhysicsNeMo)
=====================================

The final tier of tutorials (``tutorials/tutorial_08cd`` through
``tutorial_10d``) turns a fitted statistical shape model into a trained AI
The final tier of tutorials (``tutorials/tutorial_08`` through
``tutorial_10``) turns a fitted statistical shape model into a trained AI
physiological surrogate, replacing the explicit per-phase registration solve
with a learned model at inference time:

``tutorial_08cd_byod_fit_model_to_patients.py``
``tutorial_08_byod_fit_model_to_patients.py``
Fits the cardiac PCA model to a patient (via
``WorkflowFitStatisticalModelToPatient``) and propagates the fitted mesh
through every gated phase using ICON-based registration
(``WorkflowReconstructHighres4DCT``), producing the per-phase mesh/surface
pairs used as AI surrogate training data.

``tutorial_09c_byod_train_physicsnemo_mgn.py`` /
``tutorial_09d_byod_train_physicsnemo_mlp.py``
``tutorial_09_byod_train_physicsnemo_mgn.py`` /
``tutorial_09_byod_train_physicsnemo_mlp.py``
Train a PhysicsNeMo surrogate — a graph-based ``MeshGraphNet`` via
``WorkflowTrainPhysicsNeMoMGN`` or a fully connected MLP via
``WorkflowTrainPhysicsNeMoMLP`` — on the Tutorial 8cd output to predict
``WorkflowTrainPhysicsNeMoMLP`` — on the Tutorial 8 output to predict
per-phase cardiac mesh deformation directly from the fitted SSM
coefficients. Requires the ``[physicsnemo]`` extra (and ``torch-geometric``
for the MeshGraphNet variant); Python >= 3.11.

``tutorial_10c_byod_eval_physicsnemo_mgn.py`` /
``tutorial_10d_byod_eval_physicsnemo_mlp.py``
``tutorial_10_byod_eval_physicsnemo_mgn.py`` /
``tutorial_10_byod_eval_physicsnemo_mlp.py``
Load a trained MeshGraphNet or MLP checkpoint (via
``WorkflowInferPhysicsNeMoMGN`` / ``WorkflowInferPhysicsNeMoMLP``) and
predict/score cardiac surfaces without running registration, i.e. the AI
Expand Down
34 changes: 17 additions & 17 deletions docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,8 @@
</section>

<section class="pt4d-card-grid" aria-label="Tutorial cards">
<a class="pt4d-card" href="tutorials.html#tutorial-1a-heart-gated-ct-to-animated-usd">
<span class="pt4d-card__number">1a</span>
<a class="pt4d-card" href="tutorials.html#tutorial-1-heart-gated-ct-to-animated-usd">
<span class="pt4d-card__number">01</span>
<h2>Heart-Gated CT to Animated USD</h2>
<p>Convert cardiac 4D CT frames into registered contours and an animated OpenUSD model.</p>
<span class="pt4d-card__meta">Slicer-Heart-CT</span>
Expand All @@ -40,41 +40,41 @@
<p>Convert VTK meshes into a time-sampled USD scene for Omniverse playback.</p>
<span class="pt4d-card__meta">Tutorial 2 output</span>
</a>
<a class="pt4d-card" href="tutorials.html#tutorial-4a-create-a-pca-shape-model">
<span class="pt4d-card__number">4a</span>
<a class="pt4d-card" href="tutorials.html#tutorial-4-create-a-pca-shape-model">
<span class="pt4d-card__number">04</span>
<h2>Create a PCA Shape Model</h2>
<p>Build a statistical shape model from aligned cardiac meshes.</p>
<span class="pt4d-card__meta">KCL-Heart-Model</span>
</a>
<a class="pt4d-card" href="tutorials.html#tutorial-5a-fit-statistical-model-to-patient">
<span class="pt4d-card__number">5a</span>
<a class="pt4d-card" href="tutorials.html#tutorial-5-fit-statistical-model-to-patient">
<span class="pt4d-card__number">05</span>
<h2>Fit Statistical Model to Patient</h2>
<p>Fit a PCA heart model to patient-specific anatomy for model-based reconstruction.</p>
<span class="pt4d-card__meta">Tutorial 4a output</span>
<span class="pt4d-card__meta">Tutorial 4 output</span>
</a>
<a class="pt4d-card" href="tutorials.html#tutorial-6-reconstruct-high-resolution-4d-ct">
<span class="pt4d-card__number">06</span>
<h2>Reconstruct High-Resolution 4D CT</h2>
<p>Register respiratory CT phases and reconstruct a higher-resolution 4D volume series.</p>
<span class="pt4d-card__meta">DirLab-4DCT</span>
</a>
<a class="pt4d-card" href="tutorials.html#tutorial-8cd-fit-the-cardiac-ssm-and-propagate-through-gated-phases">
<span class="pt4d-card__number">8cd</span>
<a class="pt4d-card" href="tutorials.html#tutorial-8-fit-the-cardiac-ssm-and-propagate-through-gated-phases">
<span class="pt4d-card__number">08</span>
<h2>Fit the Cardiac SSM and Propagate Through Gated Phases</h2>
<p>Fit a PCA heart model to the reference phase and propagate it to every gated phase with ICON registration.</p>
<span class="pt4d-card__meta">Bring your own cardiac data</span>
</a>
<a class="pt4d-card" href="tutorials.html#tutorial-9c-9d-train-a-physicsnemo-cardiac-stage-model">
<span class="pt4d-card__number">9cd</span>
<a class="pt4d-card" href="tutorials.html#tutorial-9-train-a-physicsnemo-cardiac-stage-model">
<span class="pt4d-card__number">09</span>
<h2>Train a PhysicsNeMo Cardiac Stage Model</h2>
<p>Train a PhysicsNeMo MeshGraphNet (9c) or MLP (9d) to predict cardiac meshes at requested stages.</p>
<span class="pt4d-card__meta">Tutorial 8cd output</span>
<p>Train a PhysicsNeMo MeshGraphNet or MLP to predict cardiac meshes at requested stages.</p>
<span class="pt4d-card__meta">Tutorial 8 output</span>
</a>
<a class="pt4d-card" href="tutorials.html#tutorial-10c-10d-predict-and-evaluate-cardiac-surfaces">
<span class="pt4d-card__number">10cd</span>
<a class="pt4d-card" href="tutorials.html#tutorial-10-predict-and-evaluate-cardiac-surfaces">
<span class="pt4d-card__number">10</span>
<h2>Predict and Evaluate Cardiac Surfaces</h2>
<p>Load a Tutorial 9c/9d checkpoint and predict cardiac surfaces at gated phases or caller-specified stages.</p>
<span class="pt4d-card__meta">Tutorial 9c / 9d output</span>
<p>Load a Tutorial 9 checkpoint and predict cardiac surfaces at gated phases or caller-specified stages.</p>
<span class="pt4d-card__meta">Tutorial 9 output</span>
</a>
</section>

Expand Down
18 changes: 9 additions & 9 deletions docs/quickstart.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ The ``tutorials/`` directory contains eleven end-to-end scripts covering nine
major workflows (Tutorials 9 and 10 each have MeshGraphNet and MLP variants).
Each script is a ``# %%`` percent-cell Python script that exercises
the workflow classes directly. Run as a regular file
(``python tutorials/tutorial_01a_...py``) or cell-by-cell in VS Code or Cursor.
(``python tutorials/tutorial_01_...py``) or cell-by-cell in VS Code or Cursor.

See :doc:`tutorials` for the NVIDIA-styled tutorial card index, dataset
requirements, script paths, and workflow details.
Expand All @@ -41,9 +41,9 @@ tutorials:

.. code-block:: bash

python tutorials/tutorial_01a_heart_gated_ct_to_usd.py
python tutorials/tutorial_01_heart_gated_ct_to_usd.py

python tutorials/tutorial_02_ct_to_vtk.py
python tutorials/tutorial_02_heart_ct_to_vtk.py

Tutorial paths are defined near the top of each script. To use different paths,
edit the script constants or use the installed ``physiotwin4d-*`` CLI commands.
Expand All @@ -52,16 +52,16 @@ recommended run order.

Recommended run order:

1. Tutorials 1a and 2 first, after downloading Slicer-Heart-CT data.
1. Tutorials 1 and 2 first, after downloading Slicer-Heart-CT data.
2. Tutorial 3 after Tutorial 2 (consumes Tutorial 2 output).
3. Tutorial 4a after downloading KCL-Heart-Model.
4. Tutorial 5a after Tutorial 4a because it can consume Tutorial 4a output.
3. Tutorial 4 after downloading KCL-Heart-Model.
4. Tutorial 5 after Tutorial 4 because it can consume Tutorial 4 output.
5. Tutorial 6 after downloading DirLab-4DCT (manual).
6. Tutorial 8cd after preparing your own cardiac gated CT, labelmaps, KCL volume
6. Tutorial 8 after preparing your own cardiac gated CT, labelmaps, KCL volume
PCA model, and ICON weights (bring-your-own-data).
7. Tutorial 9c and/or 9d after Tutorial 8cd because they train from its fitted
7. Tutorial 9 (MGN and/or MLP) after Tutorial 8 because they train from its fitted
meshes.
8. Tutorial 10c and/or 10d after Tutorial 9c / 9d because they evaluate the
8. Tutorial 10 (MGN and/or MLP) after Tutorial 9 because they evaluate the
trained checkpoints.

Prerequisites
Expand Down
Loading
Loading