2026.05.9

PhysioMotion4D 2026.05.9

This release expands Bring Your Own Data workflows, generalizes image conversion beyond CT-specific naming, adds new segmentation and registration options, introduces a PhysicsNeMo tutorial, and improves release/docs maintenance.

Highlights

• Added BYOD DICOM, medical image, and VTK-to-USD tutorial documentation for 3D and 4D workflows.
• Added physiomotion4d-download-data CLI documentation and clearer demo data download guidance.
• Generalized CT-specific APIs and CLIs to image-oriented names:
  • WorkflowConvertImageToVTK
  • WorkflowConvertImageToUSD
  • physiomotion4d-convert-image-to-vtk
  • physiomotion4d-convert-image-to-usd
• Added ConvertImage4DTo3D support for vector 3D and 4D image inputs, with improved DICOM handling.
• Added HeartSimplewareTrimmedBranches as an explicit segmentation option for KCL heart model workflows.
• Added RegisterImagesICON.finetune() for cohort fine-tuning of UniGradICON weights.
• Added initial PhysicsNeMo tutorial support for mesh stage prediction.
• Improved docs navigation, clinical-use notices, version display, and tutorial/index pages.
• Updated bumpver configuration so version bumps no longer create local commits or tags automatically.

Breaking Or Behavior Changes

• Renamed CT-specific workflow/CLI surfaces to image-oriented names.
• Backend identifiers are now explicit documented values such as ChestTotalSegmentator, HeartSimpleware, HeartSimplewareTrimmedBranches, ANTS, and ICON.
• HeartSimpleware no longer implicitly trims branches. Use HeartSimplewareTrimmedBranches when trimmed branch behavior is required.

Testing And CI

• Added opt-in pytest flags for slow, GPU, Simpleware, experiment, and tutorial test buckets.
• Removed the old requires_data marker pattern; tests now use session fixtures that download required data.
• Updated GPU and slow-test workflows to pass the appropriate opt-in flags.
• Added workflow tests for segmentation dispatch and trimmed-branch defaults.

PhysioMotion4D 2026.5.8

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

• Home: https://project-monai.github.io/physiomotion4d/
• Quickstart, tutorials, CLI guide, API reference, developer guides are all linked from the documentation home.

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, updat...