From 1ac0266873ee8ea4fbcec98f39de1ae2d8107ac9 Mon Sep 17 00:00:00 2001 From: Stephen Aylward Date: Wed, 5 Aug 2026 21:11:07 -0400 Subject: [PATCH] DOCS: Update assets, stats, readme, getting started, and tutorials. --- docs/_static/custom.css | 8 ++- ...experiment_finetuning_landmark_results.png | 3 - docs/assets/tutorial_08_lung.gif | 3 + docs/installation.rst | 69 +++++++++++++------ docs/quickstart.rst | 68 ++++++++++++++---- docs/tutorials.rst | 38 +++++----- experiments/README.md | 12 +++- statistics.md | 9 +-- tutorials/README.md | 5 +- ...torial_08_lung_fit_model_to_4d_patients.py | 1 + 10 files changed, 147 insertions(+), 69 deletions(-) delete mode 100644 docs/assets/experiment_finetuning_landmark_results.png create mode 100644 docs/assets/tutorial_08_lung.gif 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