DOCS: Update assets, stats, readme, getting started, and tutorials.

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;

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,23 +26,38 @@ 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
 ====================
 
 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
 -----------------
 

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,

docs/tutorials.rst

@@ -11,7 +11,7 @@ Tutorials
      <p class="pt4d-kicker">PhysioTwin4D tutorials</p>
      <h1>From a CT scan to an animated digital twin</h1>
      <p>
-       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/<tutorial_name>/`` 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

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

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 <script>.py` or stepped through cell-by-cell in VS Code / Cursor.
+All experiment and tutorial sources are plain `.py` files run with
+`python <script>.py`. Experiment scripts additionally carry `# %%` percent-cell
+markers, so they can be stepped through cell-by-cell in VS Code / Cursor;
+tutorials are straightforward top-to-bottom scripts.
 
 ### Core Module Highlights (Python Source)
 
@@ -187,7 +188,7 @@ subject-specific characterization and cross-subject correspondence - to
 estimate a subject's physiological processes, currently cardiac and
 respiratory motion. It is built on top of established medical imaging, AI/ML,
 and 3D graphics libraries with a small, focused public API and a
-percent-cell-script example/tutorial layout that runs both interactively and
+plain-Python-script example/tutorial layout that runs both interactively and
 unattended.
 
 ---

tutorials/README.md

@@ -47,9 +47,8 @@ notes on running them against your own data.
 
 ## Running a Tutorial
 
-Each tutorial is a standalone percent-cell Python script (`# %%`) that can be
-run cell-by-cell in VS Code or Cursor, or executed end-to-end as a regular
-Python script. Paths are defined near the top of each script. By default, data
+Each tutorial is a standalone, straightforward Python script, executed
+end-to-end. Paths are defined near the top of each script. By default, data
 is read from the repository `data/` directory and outputs are written under
 `tutorials/output/<tutorial_name>/`.