Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ diagnosis, treatment planning, or clinical decision-making.
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
- [Tutorials](https://project-monai.github.io/monai-physio/tutorials.html) - runnable end-to-end workflows and their datasets. Most numbered tutorials ship multiple organ/dataset variant scripts (heart, lung, duke_heart) that share the same workflow class, so you can see how to adapt a workflow to your own anatomy and data
- [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
Expand Down Expand Up @@ -146,5 +146,8 @@ free for academic and commercial use. https://docs.omniverse.nvidia.com/ov/late
### 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
* NVIDIA Segment CT AI weights (used in the SegmentNVSegmentCT class) are
released under the NVIDIA Open Model License Agreement, research use only,
not for clinical use. https://huggingface.co/nvidia/NV-Segment-CT
* 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.
1 change: 1 addition & 0 deletions docs/api/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ By Category
* :class:`~monai_physio.SegmentHeartSimpleware` - Simpleware cardiac segmentation
* :class:`~monai_physio.SegmentHeartSimplewareTrimmedBranches` - Simpleware with trimmed great vessels
* :class:`~monai_physio.SegmentNVSegmentCTMRI` - NV-Segment-CTMR, CT *and* MRI
* :class:`~monai_physio.SegmentNVSegmentCT` - NV-Segment-CT, CT only

**Image Registration**
* :class:`~monai_physio.RegisterImagesBase` - Base registration class
Expand Down
10 changes: 9 additions & 1 deletion docs/api/segmentation/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ MONAI Physio supports multiple segmentation approaches:
* **Simpleware**: Cardiac-focused segmentation (requires Simpleware Medical)
* **NV-Segment-CTMR**: Whole-body CT *and* MRI segmentation (345 structures,
non-commercial license)
* **NV-Segment-CT**: Whole-body CT-only segmentation (117 structures,
weights for research use only, not for clinical use)

All segmentation classes inherit from :class:`SegmentAnatomyBase` and provide consistent interfaces.

Expand All @@ -26,6 +28,7 @@ Quick Links
* :doc:`totalsegmentator` - TotalSegmentator implementation
* :doc:`simpleware` - Simpleware ASCardio cardiac segmentation
* :doc:`nv_segment_ct_mri` - NVIDIA NV-Segment-CTMR CT/MRI segmentation
* :doc:`nv_segment_ct` - NVIDIA NV-Segment-CT CT-only segmentation

Choosing a Method
=================
Expand All @@ -39,6 +42,9 @@ Choosing a Method
+------------------+------------------+------------------+------------------+
| NV-Segment-CTMR | Medium | Good | CT and MRI |
+------------------+------------------+------------------+------------------+
| NV-Segment-CT | Medium | Good | CT-only, |
| | | | research use |
+------------------+------------------+------------------+------------------+

Quick Start
===========
Expand All @@ -64,6 +70,7 @@ Module Documentation
totalsegmentator
simpleware
nv_segment_ct_mri
nv_segment_ct

Common Operations
=================
Expand Down Expand Up @@ -120,4 +127,5 @@ See Also

.. rubric:: Navigation

:doc:`../index` | :doc:`base` | :doc:`totalsegmentator` | :doc:`simpleware`
:doc:`../index` | :doc:`base` | :doc:`totalsegmentator` | :doc:`simpleware` |
:doc:`nv_segment_ct_mri` | :doc:`nv_segment_ct`
99 changes: 99 additions & 0 deletions docs/api/segmentation/nv_segment_ct.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
=============
NV-Segment-CT
=============

.. module:: monai_physio.segment_nv_segment_ct
.. currentmodule:: monai_physio

``SegmentNVSegmentCT`` runs NVIDIA's NV-Segment-CT model (a VISTA3D
derivative finetuned on CT scans) and groups its labelmap into the anatomy
masks used by MONAI Physio workflows. It covers 117 "segment everything"
classes (132 addressable via label prompt) and supports only automatic
(label-prompt) segmentation - there is no point-click interactive branch
exposed here.

.. warning::

The NV-Segment-CT *weights* are released under the NVIDIA Open Model
License Agreement (research use only, not for clinical use); the
surrounding bundle code is Apache 2.0. NV-Segment-CTMR's weights carry a
different restrictive license (NVIDIA OneWay Non-Commercial License) -
both models are research-use-only, just under different named terms, so
check the license text for your use case. Use
``SegmentChestTotalSegmentator`` if you need no license restriction at
all - its default task set is unrestricted; only its optional
``heartchambers_highres`` and ``tissue_4_types`` tasks
(``set_has_academic_license(True)``) require a TotalSegmentator academic
license.

Class Reference
===============

.. autoclass:: SegmentNVSegmentCT
:members:
:undoc-members:
:show-inheritance:

Basic Usage
===========

.. code-block:: python

import itk

from monai_physio import SegmentNVSegmentCT

image = itk.imread("chest_ct.nrrd")
segmenter = SegmentNVSegmentCT()

masks = segmenter.segment(image)

heart = masks["heart"]
lungs = masks["lung"]
labelmap = masks["labelmap"]

itk.imwrite(labelmap, "labelmap.nrrd", compression=True)

NV-Segment-CT is CT-only: unlike ``SegmentNVSegmentCTMRI`` there is no
``set_modality()`` call or MRI code path.

Returned Keys
=============

For this segmenter, ``segment()`` returns a dictionary with the following
keys:

* ``labelmap``
* ``heart``
* ``major_vessels``
* ``lung``
* ``bone``
* ``soft_tissue``
* ``other``

Label Ids
=========

Label ids are the model's own published class indices, used verbatim (see
``NV-Segment-CT/configs/label_dict.json`` in
https://github.com/NVIDIA-Medtech/NV-Segment-CTMR), which run to 132. For
example, 6 is the aorta and 115 the heart. The full group->id mapping is
available through the segmenter's ``taxonomy`` attribute
(``segmenter.taxonomy.labels_in_group("heart")``,
``segmenter.taxonomy.all_labels()``).

Operational Notes
=================

The first call to ``segment()`` downloads ~872 MB of model weights from
https://huggingface.co/nvidia/NV-Segment-CT into the Hugging Face cache
(override the destination with the ``model_cache_dir`` attribute). Inference
requires a CUDA GPU.

See Also
========

* :doc:`index`
* :doc:`nv_segment_ct_mri`
* :doc:`totalsegmentator`
* :doc:`../../tutorials`
4 changes: 3 additions & 1 deletion docs/architecture.rst
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ Data Flow
SegmentChestTotalSegmentator / SegmentChestTotalSegmentatorWithContrast
SegmentHeartSimpleware / SegmentHeartSimplewareTrimmedBranches
SegmentNVSegmentCTMRI (CT + MRI)
SegmentNVSegmentCT (CT only)
|
v
ProcessContours + ProcessTransforms
Expand Down Expand Up @@ -165,7 +166,8 @@ Component Boundaries
Segmentation classes produce anatomy masks or labelmaps from ITK images.
``SegmentAnatomyBase`` subclasses (``SegmentChestTotalSegmentator``,
``SegmentChestTotalSegmentatorWithContrast``, ``SegmentHeartSimpleware``,
``SegmentHeartSimplewareTrimmedBranches``, ``SegmentNVSegmentCTMRI``) share the
``SegmentHeartSimplewareTrimmedBranches``, ``SegmentNVSegmentCTMRI``,
``SegmentNVSegmentCT``) share the
same segment/taxonomy interface, so new segmentation methods or anatomy groups
slot in without touching the workflow layer.

Expand Down
3 changes: 3 additions & 0 deletions docs/assets/tutorial_15_lung.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
32 changes: 28 additions & 4 deletions docs/cli_scripts/download_data.rst
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,10 @@ Supported Datasets
Physio GitHub release. See ``data/TCIA-4DLung/README.md`` for the
data source, the full-collection manual download, and required
citation.
* - ``PhysicsNeMo-MGN-Lung-Motion``
- Pretrained PhysicsNeMo MeshGraphNet checkpoint for lung motion, from
the MONAI Physio GitHub release. Used by Lung Tutorial 10 and later
when skipping Tutorial 9's training.

Basic Usage
===========
Expand All @@ -51,12 +55,13 @@ Options

.. code-block:: bash

monai-physio-download-data [Slicer-Heart-CT|KCL-Heart-Model|CHOP-Valve4D|Chest-CT|TCIA-4DLung] [--directory DIRECTORY]
monai-physio-download-data [Slicer-Heart-CT|KCL-Heart-Model|CHOP-Valve4D|Chest-CT|TCIA-4DLung|PhysicsNeMo-MGN-Lung-Motion] [--directory DIRECTORY]

``data_name``
Dataset to download. One of ``Slicer-Heart-CT``, ``KCL-Heart-Model``,
``CHOP-Valve4D``, ``Chest-CT``, or ``TCIA-4DLung``. Required - omitting
it prints help and exits.
``CHOP-Valve4D``, ``Chest-CT``, ``TCIA-4DLung``, or
``PhysicsNeMo-MGN-Lung-Motion``. Required - omitting it prints help and
exits.

``--directory``
Directory where the dataset is stored. Defaults to ``data/<data_name>``.
Expand Down Expand Up @@ -131,6 +136,22 @@ the download entirely once any case's phase volumes are already present -
this is a converted tutorial subset; see ``data/TCIA-4DLung/README.md`` for
how to obtain the full TCIA 4D-Lung collection manually.

For ``PhysicsNeMo-MGN-Lung-Motion``, the command downloads, extracts, and
reuses:

.. code-block:: text

tutorials/network_weights/physicsnemo_mgn_lung_motion/mgn_stage_model.pt
tutorials/network_weights/physicsnemo_mgn_lung_motion/ (other epoch
checkpoints and metadata)

The command uses
:meth:`monai_physio.download_data.DownloadData.DownloadPhysicsNeMoMGNLungMotionData`,
which fetches ``physicsnemo_mgn_lung_motion.zip`` from the MONAI Physio
GitHub release and skips the download once ``mgn_stage_model.pt`` is
already present. Unlike every other dataset, its default ``--directory`` is
``tutorials/network_weights``, not ``data/<data_name>``.

See Also
========

Expand All @@ -142,7 +163,10 @@ See Also
individually and may require registration, so it is manual-only, see
``data/DirLab-4DCT/README.md``. ``Duke-Heart-4DLabelmaps``, which drives the
ten ``duke_heart`` variants, is being released soon; see
``data/Duke-Heart-4DLabelmaps/README.md``.
``data/Duke-Heart-4DLabelmaps/README.md``. ``PhysicsNeMo-MGN-Lung-Motion``
is the pretrained-checkpoint shortcut for Lung Tutorial 10 (and everything
downstream of it: 11-14), letting a reader skip running Tutorial 9's
training themselves.
* :doc:`byod_tutorials`
* :doc:`heart_gated_ct`
* :doc:`overview`
39 changes: 39 additions & 0 deletions docs/developer/migration_next.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Migration Guide - Unreleased

Breaking changes committed since the last release, and how to update code that
depends on them.

MONAI Physio prefers compatibility: public APIs are broken only when the change
is generally beneficial to future users. When a break is unavoidable, the
project does **not** ship deprecation shims or removed-symbol stubs. Instead,
substantial changes ship with code that automates the conversion, and every
break is recorded here in the commit that introduces it.

At release time this file is renamed `migration_<version>.md` and a fresh
`migration_next.md` is started for the next cycle.

## Entry template

Append one section per breaking change, newest last, using this shape:

````markdown
## <symbol, module, or CLI flag> - <one-line summary>

**Change:** what moved, was renamed, or changed signature.

**Why:** the benefit to future users that justified the break.

**Before**

```python
old_call(argument)
```

**After**

```python
new_call(argument, required_option="value")
```

**Automated conversion:** `<path to script or CLI>`, or `None needed`.
````
Loading
Loading