Metadata-Version: 2.4
Name: monai-physio
Version: 2026.9.0
Summary: Methods, workflows, tutorials, and CLI for creating personalized physiological digital twins from 3D/4D medical images
Author-email: "Stephen R. Aylward" <saylward@nvidia.com>
Maintainer-email: "Stephen R. Aylward" <saylward@nvidia.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/Project-MONAI/monai-physio
Project-URL: Documentation, https://project-monai.github.io/monai-physio/
Project-URL: Repository, https://github.com/Project-MONAI/monai-physio.git
Project-URL: Bug Tracker, https://github.com/Project-MONAI/monai-physio/issues
Project-URL: Author LinkedIn, https://www.linkedin.com/in/stephenaylward
Project-URL: Author Google Scholar, https://scholar.google.com/citations?user=u1UdL4oAAAAJ&hl
Keywords: medical-imaging,4d-ct,cardiac-imaging,lung-imaging,omniverse,usd,monai,segmentation,registration,deformable-registration,image-registration,model-registration,visualization,ai,deep-learning,totalsegmentator,ICON,ANTS,physiological-motion,4d-visualization,digital-twin,statistical-shape-model,physicsnemo,meshgraphnet
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: itk<6.0.0,>=5.3.0
Requires-Dist: nibabel>=4.0.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: pydicom>=2.4.0
Requires-Dist: pynrrd>=1.0.0
Requires-Dist: vtk>=9.2.0
Requires-Dist: monai>=1.4.0
Requires-Dist: torch>=2.0.0
Requires-Dist: transformers>=4.21.0
Requires-Dist: totalsegmentator>=2.0.0
Requires-Dist: huggingface_hub>=0.24.0
Requires-Dist: einops>=0.6.1
Requires-Dist: nvidia-physicsnemo>=2.0.0
Requires-Dist: torch-geometric>=2.5.0
Requires-Dist: torch-scatter>=2.1.0
Requires-Dist: antspyx>=0.6.1
Requires-Dist: icon-registration>=1.0.0
Requires-Dist: picsl-greedy>=0.0.12
Requires-Dist: scipy>=1.10.0
Requires-Dist: unigradicon>=1.0.0
Requires-Dist: pyvista[all]>=0.47.0
Requires-Dist: usd-core>=23.11
Requires-Dist: trimesh>=4.0.0
Requires-Dist: pyacvd>=0.4.0
Requires-Dist: ipykernel>=6.0.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: cuda13
Requires-Dist: cupy-cuda13x>=13.6.0; extra == "cuda13"
Requires-Dist: torch>=2.0.0; extra == "cuda13"
Requires-Dist: torchvision; extra == "cuda13"
Requires-Dist: torchaudio; extra == "cuda13"
Provides-Extra: cuda12
Requires-Dist: cupy-cuda12x>=13.6.0; extra == "cuda12"
Requires-Dist: torch<2.13,>=2.10; extra == "cuda12"
Requires-Dist: torchvision; extra == "cuda12"
Requires-Dist: torchaudio; extra == "cuda12"
Provides-Extra: dev
Requires-Dist: bumpver>=2023.0.0; extra == "dev"
Requires-Dist: jupytext>=1.16.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: pluggy>=1.2.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.0.0; extra == "dev"
Requires-Dist: coverage[toml]>=7.0.0; extra == "dev"
Requires-Dist: mypy>=2.1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: scipy-stubs<1.16.0.0,>=1.14.0.0; extra == "dev"
Requires-Dist: types-requests>=2.32.0.0; extra == "dev"
Requires-Dist: sphinx>=8.0.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=3.0.0; extra == "dev"
Requires-Dist: sphinx-autodoc-typehints>=3.0.0; extra == "dev"
Requires-Dist: sphinx-copybutton>=0.5.2; extra == "dev"
Requires-Dist: sphinx-tabs>=3.4.7; extra == "dev"
Requires-Dist: myst-parser>=4.0.0; extra == "dev"
Requires-Dist: docutils<0.22; extra == "dev"
Requires-Dist: linkify-it-py>=2.0.0; extra == "dev"
Requires-Dist: uc-micro-py>=1.0.1; extra == "dev"
Requires-Dist: markdown-it-py>=3.0.0; extra == "dev"
Requires-Dist: imageio-ffmpeg>=0.5.0; extra == "dev"
Provides-Extra: dev-cuda13
Requires-Dist: monai-physio[cuda13]; extra == "dev-cuda13"
Requires-Dist: monai-physio[dev]; extra == "dev-cuda13"
Provides-Extra: dev-cuda12
Requires-Dist: monai-physio[cuda12]; extra == "dev-cuda12"
Requires-Dist: monai-physio[dev]; extra == "dev-cuda12"
Dynamic: license-file

# MONAI Physio

[![CI](https://github.com/Project-MONAI/monai-physio/actions/workflows/ci.yml/badge.svg)](https://github.com/Project-MONAI/monai-physio/actions/workflows/ci.yml)
[![Documentation](https://github.com/Project-MONAI/monai-physio/actions/workflows/docs.yml/badge.svg)](https://github.com/Project-MONAI/monai-physio/actions/workflows/docs.yml)
[![Nightly Health](https://img.shields.io/endpoint?url=https://project-monai.github.io/monai-physio/status.json)](https://github.com/Project-MONAI/monai-physio/actions/workflows/nightly-health.yml)
[![codecov](https://codecov.io/gh/Project-MONAI/monai-physio/branch/main/graph/badge.svg)](https://codecov.io/gh/Project-MONAI/monai-physio)

[![PyPI version](https://img.shields.io/pypi/v/monai-physio.svg)](https://pypi.org/project/monai-physio/)
[![Python versions](https://img.shields.io/pypi/pyversions/monai-physio.svg)](https://pypi.org/project/monai-physio/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)

**A collection of methods, workflows, tutorials, and CLI tools for creating personalized physiological digital twins.**

MONAI Physio typically begins with a 3D medical image of a subject, extracts anatomic models from that image, and then uses AI surrogates to estimate the subject's physiological processes - initially focusing on cardiac and respiratory motion, and expanding to electrophysiology, blood flow, and organ perfusion. The package provides methods for forming these physiological AI surrogates and for finetuning the segmentation and registration AI methods that power them, with special emphasis on statistical shape models: they capture subject-specific characteristics that help determine subject-specific physiological function, and establish correspondence across subjects to aid AI surrogate generalization and simplify the application of traditional solvers.

MONAI Physio is not validated for clinical use. It is a research and
visualization toolkit, not a medical device, and must not be used for
diagnosis, treatment planning, or clinical decision-making.

## Documentation

**https://project-monai.github.io/monai-physio/** is the primary entry point
for users and contributors. Key sections:

- [Installation](https://project-monai.github.io/monai-physio/installation.html) and [Quickstart](https://project-monai.github.io/monai-physio/quickstart.html)
- [Tutorials](https://project-monai.github.io/monai-physio/tutorials.html) - runnable end-to-end workflows and their datasets
- [CLI & Scripts Guide](https://project-monai.github.io/monai-physio/cli_scripts/overview.html) - command-line tools for conversion, segmentation, registration, and USD workflows
- [API Reference](https://project-monai.github.io/monai-physio/api/index.html) - workflow, registration, segmentation, and USD classes
- [Developer Guides](https://project-monai.github.io/monai-physio/developer/architecture.html) - architecture, extension points, and implementation conventions
- [Contributing](CONTRIBUTING.md) and [Testing](https://project-monai.github.io/monai-physio/testing.html)
- [FAQ](https://project-monai.github.io/monai-physio/faq.html) and [Troubleshooting](https://project-monai.github.io/monai-physio/troubleshooting.html)
- [Issues](https://github.com/Project-MONAI/monai-physio/issues) and [Discussions](https://github.com/Project-MONAI/monai-physio/discussions)

## Highlights

- **Personalized digital twins**: build subject-specific anatomic models and physiological AI surrogates from 3D/4D medical images
- **Statistical shape models**: capture subject-specific anatomy and establish cross-subject correspondence, aiding AI surrogate generalization and simplifying traditional solver setup
- **Simplified workflows on industry-leading open-source tools**: ICON and Greedy for registration; MONAI with TotalSegmentator and Simpleware for segmentation; scikit-learn for statistical shape modeling; ITK for image processing; PyVista and OpenUSD/Omniverse for geometry manipulation; CuPy for accelerated computing; and PhysicsNeMo for AI surrogates
- **Extensible class hierarchy**: add new segmentation and registration methods, and extend to new data types, organs, and physiological processes, without reworking the workflow layer
- **Physiological motion**: cardiac and respiratory motion today, expanding to electrophysiology, blood flow, and organ perfusion
- **NVIDIA Omniverse as the simulation hub**: the end goal for simulation - a simulation-information hub and gateway to other engines (e.g., Ansys solvers), interactive simulations for treatment planning (e.g., Isaac Sim, Newton), visualization systems (e.g., AR/VR devices), and physical systems (e.g., robots via ROS)
- **CLI and Python API**: installed command-line tools and workflow classes for repeatable, scriptable pipelines

## Quick Start

### Install

```
uv pip install "monai-physio[cuda12]"
```

Installs entirely from prebuilt wheels. On CUDA 13 use `monai-physio[cuda13]`,
which additionally needs a CUDA toolkit and C++ toolchain to build
`torch-scatter`. See the
[installation guide](https://project-monai.github.io/monai-physio/installation.html)
for source installs, pip, and CPU-only.

### Download Tutorials

The tutorials are not installed by pip. They live in this repository.
Clone it to run them:

```
git clone https://github.com/Project-MONAI/monai-physio.git
```

### Download Tutorial Data

Tutorial 1 (heart) runs on the public Slicer-Heart 4D CT sample.  We provide
automated download for multiple datasets via a CLI, including the lung
tutorials' key dataset, TCIA-4DLung (a converted tutorial subset - the full
TCIA 4D-Lung collection remains a manual download), see
[data/TCIA-4DLung/README.md](data/TCIA-4DLung/README.md).

**IMPORTANT:** Run the download from the top level of the clone. The tutorials
resolve their inputs against the repository root, so downloading
elsewhere puts the data where they will not find it.

```
cd monai_physio
monai-physio-download-data Slicer-Heart-CT --directory data/Slicer-Heart-CT
```

### Run Tutorial 01: Gated CT to USD

```
python tutorials/tutorial_01_heart_gated_ct_to_usd.py
```

### Explore the Code

That tutorial builds the same workflow the Python API exposes:

```python
import itk
from pathlib import Path

from monai_physio import (
    RegisterImagesICON,
    SegmentChestTotalSegmentatorWithContrast,
    WorkflowConvertImageToUSD,
)

frame_files = sorted(Path("data/Slicer-Heart-CT").glob("slice_???.mha"))
time_series_images = [itk.imread(str(path)) for path in frame_files]

workflow = WorkflowConvertImageToUSD(
    time_series_images=time_series_images,
    reference_image=time_series_images[int(0.7 * len(time_series_images))],
    output_directory="./results",
    usd_project_name="cardiac_model",
    registration_method=RegisterImagesICON(),  # or RegisterImagesGreedy()
    segmentation_method=SegmentChestTotalSegmentatorWithContrast(),
)
results = workflow.process()
```

### Explore the CLIs

The Tutorial 01 workflow and many of the workflows in this toolkit are also
available as command-line tools but CLIs provide fewer options for
customization:

```bash
monai-physio-convert-image-to-usd cardiac_4d.nrrd --contrast --output-dir ./results
```

# Next Steps

See the [quickstart](https://project-monai.github.io/monai-physio/quickstart.html) and [tutorials](https://project-monai.github.io/monai-physio/tutorials.html) for full walkthroughs covering segmentation, registration, statistical shape modeling, and USD export.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) (also published at [project-monai.github.io/monai-physio/contributing.html](https://project-monai.github.io/monai-physio/contributing.html)) for code style, testing, IDE setup, and pull request conventions.

## License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

Additionally, NVIDIA Omniverse is distributed under its own custom license, which makes it
free for academic and commercial use.  https://docs.omniverse.nvidia.com/ov/latest/common/NVIDIA_Omniverse_License_Agreement.html

### Non-commercial Licenses (optional)
* NVIDIA Segment CT MRI AI weights (used in the SegmentNVSegmentCTMRI class,
are restricted from commercial use. https://github.com/NVIDIA-Medtech/NV-Segment-CTMR
* TotalSegmentator includes the optional use of some of their research-only models. Using those models assumes that you have
the appropriate license key install, otherwise an error occurs.   Those models can be disabled by calling ```set_has_academic_license(False)``` member function of the ```SegmentChestTotalSegmentator``` class.
