diff --git a/docs/_static/custom.css b/docs/_static/custom.css
index b20db8a..3d8eb22 100644
--- a/docs/_static/custom.css
+++ b/docs/_static/custom.css
@@ -333,11 +333,17 @@ dt.sig {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
gap: 1.15rem;
- margin: -4rem 0 2.25rem;
+ margin: 0 0 2.25rem;
position: relative;
z-index: 2;
}
+/* Only a grid that directly follows the hero rides up into its lower padding;
+ elsewhere (tutorials.rst) the grid follows body text and must not overlap it. */
+.pt4d-hero + .pt4d-card-grid {
+ margin-top: -4rem;
+}
+
.pt4d-card,
.pt4d-card:visited {
display: flex;
diff --git a/docs/assets/experiment_finetuning_landmark_results.png b/docs/assets/experiment_finetuning_landmark_results.png
deleted file mode 100644
index 7315b63..0000000
--- a/docs/assets/experiment_finetuning_landmark_results.png
+++ /dev/null
@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:2efbabf9c106e47d4bbb087b71401d60ba1763a0c6a9a53d067719b6d3bb3e5f
-size 14504
diff --git a/docs/assets/tutorial_08_lung.gif b/docs/assets/tutorial_08_lung.gif
new file mode 100644
index 0000000..0811432
--- /dev/null
+++ b/docs/assets/tutorial_08_lung.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a990d8ef57e463c57c5a8b2f5fed9c61c2bbf2cfde61e3e450f713fb89711141
+size 4443886
diff --git a/docs/installation.rst b/docs/installation.rst
index 7f85c33..58353c1 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -11,7 +11,7 @@ System Requirements
-------------------
* **Python**: 3.10, 3.11, or 3.12
-* **GPU**: NVIDIA GPU with CUDA 13 — recommended for production use; CPU-only PyPI installation is supported but will be slow and will emit a runtime warning
+* **GPU**: NVIDIA GPU with CUDA 13 — required for full capability and best performance; a CPU-only PyPI installation is a supported fallback, but it is slow, emits a runtime warning, and cannot run the AI-surrogate workflows
* **RAM**: 16GB minimum (32GB+ recommended for large datasets)
* **Storage**: 10GB+ for package and model weights
* **Visualization**: NVIDIA Omniverse (optional, for USD visualization)
@@ -26,6 +26,8 @@ PhysioTwin4D relies on several key packages:
* **Registration**: icon-registration, unigradicon
* **Visualization**: USD-core, PyVista
* **Segmentation**: TotalSegmentator
+* **AI surrogates**: PhysicsNeMo (``nvidia-physicsnemo``), torch-geometric,
+ torch-scatter - optional, installed with the ``[physicsnemo]`` extra
Installation Methods
====================
@@ -33,16 +35,29 @@ Installation Methods
Method 1: Install from PyPI (Recommended)
------------------------------------------
-The simplest way to install PhysioTwin4D is from PyPI.
+Install the ``[cuda13]`` extra. It enables every feature and gives the best
+performance:
-CPU-only PyPI install (evaluation / no GPU):
+.. code-block:: bash
+
+ uv pip install "physiotwin4d[cuda13]"
+
+The ``[cuda13]`` extra installs CuPy. In uv-managed source environments,
+PyTorch, torchvision, and torchaudio resolve from the CUDA 13.0 PyTorch wheel
+index. There is no need to install PyTorch separately.
+
+CPU-only fallback (evaluation, or no NVIDIA GPU available):
.. code-block:: bash
pip install physiotwin4d
-This works immediately. CuPy is absent, so a ``UserWarning`` is emitted at
-import time (visible by default in all standard Python runs):
+This works immediately but is a limited configuration: GPU acceleration is
+unavailable, segmentation and registration run slowly enough that the larger
+tutorials become impractical, and the AI-surrogate workflows behind the
+``[physicsnemo]`` extra need CUDA and cannot run at all. CuPy is absent, so a
+``UserWarning`` is emitted at import time (visible by default in all standard
+Python runs):
.. code-block:: text
@@ -51,16 +66,6 @@ import time (visible by default in all standard Python runs):
(pip alone will not select the correct CUDA wheel):
uv pip install 'physiotwin4d[cuda13]' # CUDA 13
-CUDA 13 install (recommended for production):
-
-.. code-block:: bash
-
- uv pip install "physiotwin4d[cuda13]"
-
-The ``[cuda13]`` extra installs CuPy. In uv-managed source environments,
-PyTorch, torchvision, and torchaudio resolve from the CUDA 13.0 PyTorch wheel
-index. There is no need to install PyTorch separately.
-
Method 2: Install from Source
------------------------------
@@ -99,22 +104,46 @@ For development or to get the latest features:
**Step 4: Install PhysioTwin4D**
-Default uv-managed source install:
+Install the ``[cuda13]`` extra for the full-capability source install:
.. code-block:: bash
- uv pip install -e "."
+ uv pip install -e ".[cuda13]"
-This uses the CUDA 13.0 PyTorch wheel index by default. To add CuPy for CUDA 13
-GPU acceleration:
+Without the extra:
.. code-block:: bash
- uv pip install -e ".[cuda13]"
+ uv pip install -e "."
+
+still uses the CUDA 13.0 PyTorch wheel index by default, but leaves out CuPy
+and the GPU acceleration that depends on it.
Optional Dependencies
=====================
+Everything at Once
+------------------
+
+The ``[all]`` extra pulls in every optional component — ``[cuda13]``,
+``[physicsnemo]``, ``[dev]``, ``[docs]`` and ``[test]`` — so every feature is
+enabled and every use of the platform is supported, from the AI-surrogate
+workflows to building the docs and running the full test suite:
+
+.. code-block:: bash
+
+ uv pip install "physiotwin4d[all]"
+
+It inherits the ``[physicsnemo]`` caveats: PyTorch and setuptools must already
+be installed, because ``torch-scatter`` compiles against torch when no matching
+wheel exists, and ``nvidia-physicsnemo`` requires Python >= 3.11. uv handles the
+build isolation automatically; with pip, install in two steps:
+
+.. code-block:: bash
+
+ pip install "physiotwin4d[cuda13]" setuptools
+ pip install "physiotwin4d[all]" --no-build-isolation
+
Development Tools
-----------------
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index 8d308ec..f40a396 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -58,16 +58,49 @@ Then fetch the sample datasets, again from the top level of the clone:
.. code-block:: bash
- # Tutorials 1, 3 and 4 (heart)
+ # Heart Tutorials 1, 3 and 4
physiotwin4d-download-data Slicer-Heart-CT --directory data/Slicer-Heart-CT
- # Tutorial 6 (heart)
+ # Heart Tutorial 6
physiotwin4d-download-data KCL-Heart-Model --directory data/KCL-Heart-Model
- # Tutorial 7 (lung)
+ # Lung Tutorial 7
physiotwin4d-download-data Chest-CT --directory data/Chest-CT
-``DirLab-4DCT`` is manual-only; see ``data/DirLab-4DCT/README.md``, and
+ # No tutorial - transcatheter pulmonary valve experiments only, >2 GB
+ physiotwin4d-download-data CHOP-Valve4D --directory data/CHOP-Valve4D
+
+Which dataset each tutorial needs:
+
+.. list-table::
+ :widths: 25 20 55
+ :header-rows: 1
+
+ * - Dataset
+ - Download
+ - Used by
+ * - ``Slicer-Heart-CT``
+ - CLI
+ - Heart Tutorials 1, 3, 4
+ * - ``DirLab-4DCT``
+ - Manual
+ - Lung Tutorials 1, 2, 3, 4, 6, 8, and Heart Tutorial 7
+ * - ``KCL-Heart-Model``
+ - CLI
+ - Heart Tutorial 6
+ * - ``Chest-CT``
+ - CLI
+ - Lung Tutorial 7
+ * - ``CHOP-Valve4D``
+ - CLI
+ - No tutorial - used by the valve experiments under ``experiments/``
+
+Tutorials 5, 9 and 10 need no dataset of their own: they consume the outputs of
+Tutorials 4, 8 and 9 respectively.
+
+``DirLab-4DCT`` is the one dataset with no automatic downloader: DIR-Lab
+distributes each case individually and may require registration, so download it
+by hand following ``data/DirLab-4DCT/README.md``. See
:doc:`cli_scripts/download_data` for every dataset's size and source.
Tutorial 1 needs only ``Slicer-Heart-CT``; with that dataset in place it runs
@@ -104,7 +137,7 @@ CUDA-capable GPU are required for practical runtime.
Command-Line Interface
----------------------
-The fastest way to process cardiac CT data is using the command-line interface:
+The same cardiac processing, packaged as a command for unattended runs:
.. code-block:: bash
@@ -267,8 +300,9 @@ See :doc:`cli_scripts/download_data` for sizes, source URLs, and directory
layouts for every dataset.
DirLab-4DCT data is manual-only; see ``data/DirLab-4DCT/README.md``. It drives
-the lung pipeline — Tutorials 2, 3, 6 (lung) and 8 — which then feeds the
-AI-surrogate Tutorials 9 and 10. Those two additionally require the optional
+the whole lung pipeline — Lung Tutorials 1, 2, 3, 4, 6 and 8, plus Heart
+Tutorial 7 — which then feeds the AI-surrogate Tutorials 9 and 10. Those two
+additionally require the optional
``physicsnemo`` extra (``pip install "physiotwin4d[physicsnemo]"``, plus
``torch-geometric`` for the MeshGraphNet); PhysicsNeMo itself requires
Python >= 3.11.
@@ -301,20 +335,26 @@ Next Steps
Now that you've completed your first workflow:
-* Explore :doc:`tutorials` for more runnable examples
-* Read detailed :doc:`cli_scripts/overview`
+* Work through :doc:`tutorials` — the primary guide to using and adapting the
+ toolkit
+* Read detailed :doc:`cli_scripts/overview` for unattended and production runs
* Learn about :doc:`api/segmentation/index` options
* Understand :doc:`api/registration/index` methods
* Check the :doc:`api/base` for advanced usage
.. important::
- **About CLI Commands and Experiments:**
+ **Where to learn the toolkit:**
- * **CLI Commands** ⭐ **PRIMARY RESOURCE** - Production-ready workflows with proper class usage
- (``physiotwin4d-convert-image-to-usd``, ``physiotwin4d-create-statistical-model``,
- ``physiotwin4d-fit-statistical-model-to-patient``).
- See ``src/physiotwin4d/cli/`` for implementation details.
+ * **tutorials/** - the primary resource. Each tutorial runs end-to-end on
+ downloadable data, shows the workflow classes in context, and closes with
+ the constants to change for your own scans. See :doc:`tutorials`.
+
+ * **CLI Commands** - the same workflows packaged as commands for unattended
+ and production runs (``physiotwin4d-convert-image-to-usd``,
+ ``physiotwin4d-create-statistical-model``,
+ ``physiotwin4d-fit-statistical-model-to-patient``). See
+ ``src/physiotwin4d/cli/`` for implementation details.
* **experiments/** - Research prototypes and design explorations. These demonstrate conceptual
approaches for adapting workflows to new anatomical regions and digital twin applications,
diff --git a/docs/tutorials.rst b/docs/tutorials.rst
index c1328a4..5c328e2 100644
--- a/docs/tutorials.rst
+++ b/docs/tutorials.rst
@@ -11,7 +11,7 @@ Tutorials
PhysioTwin4D tutorials
From a CT scan to an animated digital twin
- Ten numbered stages across 15 runnable, percent-cell Python scripts.
+ Ten numbered stages across 15 runnable Python scripts.
Each one drives the real workflow classes end-to-end on downloadable
data, shows what it produced, and ends with the handful of constants
to change so it runs on your own scans.
@@ -43,11 +43,13 @@ relative to the current working directory:
physiotwin4d-download-data KCL-Heart-Model --directory data/KCL-Heart-Model
physiotwin4d-download-data Chest-CT --directory data/Chest-CT
-That covers Tutorials 1, 3 (heart) and 4-7. ``DirLab-4DCT`` — used by
-Tutorials 2, 3 (lung), 6 (lung) and 8 — is **not** auto-downloaded: DIR-Lab
-distributes it manually and may require registration. See
-``data/DirLab-4DCT/README.md``, and :doc:`cli_scripts/download_data` for every
-dataset's size and source.
+That covers Heart Tutorials 1, 3, 4 and 6 (``Slicer-Heart-CT`` and
+``KCL-Heart-Model``) and Lung Tutorial 7 (``Chest-CT``). ``DirLab-4DCT`` — used
+by Lung Tutorials 1, 2, 3, 4, 6 and 8, and by Heart Tutorial 7 — is **not**
+auto-downloaded: DIR-Lab distributes each case individually and may require
+registration. Tutorials 5, 9 and 10 need no dataset of their own; they consume
+the outputs of Tutorials 4, 8 and 9. See ``data/DirLab-4DCT/README.md``, and
+:doc:`cli_scripts/download_data` for every dataset's size and source.
**3. Know where output lands.** Every tutorial writes to
``tutorials/output//`` and reuses what it finds there, so a
@@ -121,9 +123,10 @@ second run is cheap and later tutorials pick up earlier results automatically.
Recommended Run Order
=====================
-Tutorials are ``# %%`` percent-cell scripts: run them whole
-(``python tutorials/tutorial_01_heart_gated_ct_to_usd.py``) or cell by cell in
-VS Code or Cursor. Numbers 1, 4 and 5 are the fastest way to see the toolkit
+Tutorials are straightforward Python scripts: run one with
+``python tutorials/tutorial_01_heart_gated_ct_to_usd.py``, or open it in your
+editor and read it top to bottom. Numbers 1, 4 and 5 are the fastest way to see
+the toolkit
work end-to-end; 6 through 10 build the statistical-model and AI-surrogate
pipeline on top.
@@ -249,13 +252,6 @@ Preview
The held-out case scored per method — unregistered, Greedy, Greedy+ICON
with the stock weights, and with the finetuned weights.
- .. figure:: assets/experiment_finetuning_landmark_results.png
- :alt: Landmark error summary for stock and finetuned ICON weights
- :width: 90%
-
- Landmark target registration error over six held-out subjects, stock
- weights against finetuned.
-
Inner API usage
.. code-block:: python
@@ -652,12 +648,12 @@ Requirements
segmentation and one fit per case, plus one registration per phase per case.
Preview
- .. figure:: assets/example.gif
- :alt: Tutorial 8 output preview (capture pending)
- :width: 60%
+ .. figure:: assets/tutorial_08_lung.gif
+ :alt: Fitted lung shape model carried through every respiratory phase
+ :width: 90%
- Capture pending — running the tutorial writes
- ``ssm_surface_reference.png`` and ``ssm_surface_first_phase.png``.
+ The fitted shape-model surface propagated across the phases of a DIR-Lab
+ case.
Inner API usage
.. code-block:: python
diff --git a/experiments/README.md b/experiments/README.md
index ebd966e..4e347fa 100644
--- a/experiments/README.md
+++ b/experiments/README.md
@@ -273,20 +273,26 @@ Each subdirectory represents a different experimental domain:
### For Production Use, Consult:
-1. **CLI Commands** ⭐ **PRIMARY RESOURCE**
+1. **Tutorials in `tutorials/`** - the primary resource
+ - End-to-end runnable scripts on downloadable data
+ - Show the workflow classes in context, with the constants to change for
+ your own scans
+ - Documented at https://project-monai.github.io/physiotwin4d/tutorials.html
+
+2. **CLI Commands** - the same workflows packaged for unattended runs
- `physiotwin4d-convert-image-to-usd` - Complete heart-gated CT workflow
- `physiotwin4d-create-statistical-model` - Create PCA statistical shape model from sample meshes
- `physiotwin4d-fit-statistical-model-to-patient` - Model-to-patient registration
- Run with `--help` for all options and parameter specifications
- Tested on diverse datasets
-2. **CLI Implementation in `src/physiotwin4d/cli/`**
+3. **CLI Implementation in `src/physiotwin4d/cli/`**
- Production-ready workflow code
- Proper class usage patterns and parameter specifications
- Complete error handling and validation
- Python API usage examples
-3. **Main library documentation**
+4. **Main library documentation**
- API references and class documentation
- Architecture explanations
- Performance considerations
diff --git a/statistics.md b/statistics.md
index a8cad00..82d262e 100644
--- a/statistics.md
+++ b/statistics.md
@@ -38,9 +38,10 @@ This report summarizes development effort, code quality, and project maturity.
| **Markdown (repo-wide READMEs, guides)** | 35 files | 2,958 | 5.5% |
| **TOTAL** | **298 files** | **~53,400** | **100%** |
-All experiment and tutorial sources are plain `.py` files. Each uses `# %%`
-percent-cell markers so the same file can be executed end-to-end with
-`python