Skip to content

PhysioMotion4D 2026.5.8

Choose a tag to compare

View all tags
@aylward aylward released this 13 May 16:25
2026.05.8
d94ba02
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

PhysioMotion4D 2026.5.8 — Initial PyPI Release

PhysioMotion4D generates anatomic models with physiological motion in NVIDIA Omniverse from 4D medical images. This is the first beta release on PyPI; the package is ready for evaluation, research, and visualization workflows but is not validated for clinical use.

What's included

End-to-end pipeline

A complete 4D CT → USD pipeline composed of small, focused modules:

4D CT → segmentation → registration → contour extraction → USD export

All public classes inherit from PhysioMotion4DBase for unified logging and debug controls.

Workflows

  • WorkflowConvertHeartGatedCTToUSD — full cardiac CT → animated USD pipeline.
  • WorkflowCreateStatisticalModel — build a PCA statistical shape model from a population of meshes.
  • WorkflowFitStatisticalModelToPatient — fit a PCA model to a patient image or surface.

Segmentation

  • SegmentChestTotalSegmentator — AI-based chest segmentation via TotalSegmentator (nnUNetv2).
  • SegmentHeartSimpleware — wraps Simpleware ASCardio for cardiac segmentation (external license required).
  • SegmentAnatomyBase — extensible base class, now driven by the new AnatomyTaxonomy data type that both segmenters and renderers consume.

Registration

  • Image-to-image: RegisterImagesICON (deep-learning, GPU), RegisterImagesANTs (classical SyN), RegisterTimeSeriesImages (4D series).
  • Model-to-image / model-to-model: RegisterModelsPCA, RegisterModelsICP, RegisterModelsDistanceMaps.

VTK ↔ USD

  • High-level: ConvertVTKToUSD — the recommended entry point for experiments, CLIs, tutorials, and tests. Supports time-series animation, anatomical labeling, colormap visualization, automatic topology-change detection, and both surface and volumetric meshes.
  • Low-level: physiomotion4d.vtk_to_usd subpackage (advanced users only) — convert_vtk_file(), MeshData, ConversionSettings, MaterialData, MaterialManager, and an add_framing_camera() helper that authors a look-at camera respecting the stage up axis.
  • USDTools provides USD inspection, merging, and a load_usd_as_vtk() round-tripping helper.
  • USDAnatomyTools paints anatomy meshes with surgical-style materials driven by the shared AnatomyTaxonomy.

CLI commands

Seven installable console commands:

  • physiomotion4d-convert-ct-to-vtk
  • physiomotion4d-heart-gated-ct
  • physiomotion4d-convert-vtk-to-usd
  • physiomotion4d-create-statistical-model
  • physiomotion4d-fit-statistical-model-to-patient
  • physiomotion4d-reconstruct-highres-4d-ct
  • physiomotion4d-visualize-pca-modes

Tutorials and examples

  • Nine end-to-end tutorial scripts under tutorials/ covering each major workflow.
  • 35 percent-cell (# %%) experiment scripts under experiments/ for research and exploratory work.
  • All scripts run either as plain python <script>.py or interactively cell-by-cell in VS Code / Cursor — no Jupyter packages required.

Other quality-of-life features

  • Calendar versioning via bumpver.
  • Trusted-publishing release pipeline (GitHub Actions → PyPI, no token in repo).
  • Sphinx documentation at https://project-monai.github.io/physiomotion4d/.
  • Test suite with baseline regression comparison; Git LFS for binary baselines.

Installation

# CPU-only — works out of the box
pip install physiomotion4d

# CUDA 13 (recommended for production)
uv pip install "physiomotion4d[cuda13]"

The [cuda13] extra installs CuPy. In uv-managed source environments, PyTorch (torch, torchvision, torchaudio) resolves from the CUDA 13.0 wheel index automatically.

Compatibility

  • Python: 3.11 or 3.12
  • OS: Linux (Ubuntu 20.04+) and Windows 10/11
  • GPU (optional but recommended): NVIDIA GPU with CUDA 13 support (e.g. RTX 3090+) for AI segmentation, ICON registration, and reconstruction
  • Visualization: NVIDIA Omniverse, USD-aware viewers, or any OpenUSD-compatible 3D tool

Known limitations

  • Not validated for clinical use — diagnostic or treatment use is not supported.
  • Some tutorial datasets (DirLab-4DCT, KCL-Heart-Model, CHOP-Valve4D) must be downloaded manually; only Slicer-Heart-CT downloads automatically.
  • Headless rendering for tests on Windows hosted CI is disabled (no software OpenGL fallback). Linux runners use Xvfb + Mesa.
  • API may change between beta releases as the project stabilizes.

Documentation

License

Apache-2.0.

Acknowledgments

PhysioMotion4D builds on excellent open work: MONAI, DirLab, TotalSegmentator, Icon-Registration / UniGradICON, ITK, TubeTK, VTK / PyVista, OpenUSD, and ANTs.

Disclaimer: PhysioMotion4D is a research and visualization toolkit. It is not a medical device and must not be used for diagnosis, treatment planning, or clinical decision-making.

What's Changed

  • ENH: Initial commit to transfer files by @aylward in #1
  • ENH: Use logging in project classes. BUG: Fixed tests. by @aylward in #2
  • BUG: Remove line continuation in commands for windows compatibility by @aylward in #3
  • ENH: Disable GPU Tests on github workflows unless manually triggered. by @aylward in #4
  • STYLE: Enable ruff line length auto fix for comments by @aylward in #5
  • ENH: Update ICP and ICP_ITK to consistent API by @aylward in #6
  • STYLE: Disable ruff linting due to itk and vtk Optional requirements by @aylward in #7
  • BUG: Enable sufficient permissions for uploading pages by @aylward in #8
  • DOC:Improved doc organization. ENH:Workflows renamed by @aylward in #9
  • ENH: Update to modern style documentation by @aylward in #10
  • ENH: Use a simplified and unified doc build workflow by @aylward in #11
  • ENH: Initial workflow for register_heart_model by @aylward in #12
  • ENH: Clarify work is not limited to CT by @aylward in #14
  • ENH: Minor update to documentation to better explain role of experiments by @aylward in #15
  • BUG: Compatibility issue with docutils resolved by @aylward in #17
  • BUG: Disable nightly GPU workflows until GPU runner is available. by @aylward in #18
  • fix: link to slicer heart by @mhoeijm in #16
  • ENH: Reduced tools for style check, fixed style, experiments as tests by @aylward in #19
  • COMP: Remove warning during tests by defining xdist_group by @aylward in #20
  • ENH: Migrate CLI scripts to structured module and add highres 4D CT workflow by @aylward in #21
  • ENH: Remove '4d' naming convention across codebase by @aylward in #22
  • ENH: New submodule for vtk_to_usd with correct colormap handling by @aylward in #23
  • Refactor: Reorganize statistical model workflows and standardize expe… by @aylward in #24
  • ENH: Add Heart-Simpleware-Segmentation experiment and simpleware_medical module by @aylward in #25
  • ENH: image and transform baselines and experiment notebook testing by @aylward in #26
  • ENH: Refactor naming and add statistical model CLIs by @aylward in #27
  • ENH: Bump to cuda 13 and update cursor/vscode settings by @aylward in #28
  • ENH: Add method for flipping image and orientations. by @aylward in #29
  • ENH: Prepare notebooks for commit - script in utils by @aylward in #30
  • ENH: Simplify heart models for inter-patient consistency by @aylward in #31
  • ENH: Split VTK by type or connectivity. Greedy Registration by @aylward in #32
  • ENH: Provide consistent colormap use for Alterra and TPV25 valves by @aylward in #33
  • ENH: Add Claude Code project scaffolding and developer tooling by @aylward in #34
  • ENH: Add labelmap support to image registration pipeline by @aylward in #35
  • ENH: Add commit and simplify-staged Claude Code skills by @aylward in #36
  • FIX: Converting mm to voxels wrong for dilation in registration by @aylward in #37
  • MNT: Add cuda12 extra, update URLs to Project-MONAI, fix capitalization by @aylward in #38
  • ENH: Add nightly health dashboard and fix Windows GPU runner labels by @aylward in #39
  • FIX: Force javascript node24 and enablement:true for docs by @aylward in #40
  • ENH: Convert python notebooks to python scripts (with percent tags to define cells) by @aylward in #41
  • ENH: Disable enablement - manually enable doc deployment by @aylward in #42
  • Tests by @aylward in #43
  • ENH:VTK_To_USD and ConvertVTKToUSD consolidation by @aylward in #44
  • fix: scale VTK mm coordinates to meters when exporting to OpenUSD by @aylward in #45
  • ENH: Add low-level VTK-to-USD facade and clarify API boundary by @aylward in #46
  • Claude/add tutorials docs aa mpp by @aylward in #47
  • ENH: Prepare PhysioMotion4D beta docs and release infrastructure by @aylward in #48
  • ENH: AnatomyTaxonomy, USD pipeline hardening, tutorials + docs by @aylward in #49
  • Bump version 2026.05.07 -> 2026.05.8 by @aylward in #50

New Contributors

Full Changelog: https://github.com/Project-MONAI/physiomotion4d/commits/2026.05.8

Contributors

aylward and mhoeijm
Assets 2
Loading