PhysioMotion4D 2026.07.0

Enhancements

• Improved fit for PCA and labelmap-to-labelmap registration (#69), plus supporting image_tools additions.
• PhysicsNeMo tutorials updated to use cardiac data (#70).
• physicsnemo is now an optional dependency; AI-agent configs updated for consistency (#60).
• New "fine-tune ICON" experiments and longitudinal-registration ICON fine-tuning (#65, #62), and a restructured experiments/LongitudinalRegistration flow (1-initial_registration → 2-finetune_icon → 3-recon).
• Added an fps option to ConvertImageToUSD (#59).

Developer tooling

• Worktree creation no longer nests virtual environments (#61).

Breaking changes / API

• Workflows now take registrar/segmenter instances instead of string identifiers (#71). RegisterTimeSeriesImages and the workflows accept pre-constructed RegisterImagesBase / SegmentAnatomyBase objects; configure backend options (iterations, mass preservation, weights path, etc.) on the instance. Defaults are unchanged. New: RegisterImagesChain (run registrars in sequence, feeding each stage's forward_transform as the next stage's initial_forward_transform), RegisterImagesGreedyICON (named Greedy→ICON chain, replaces the "Greedy_ICON" string mode), and SegmentHeartSimplewareTrimmedBranches.
• Removed legacy registration method-name strings (#66). "ANTS" / "ANTS_ICON" / lowercase "greedy" are gone; use "Greedy" / "Greedy_ICON". Callers, tests, and tutorials updated.
• Standardized forward/inverse transform conventions (#63). New docs/developer/transform_conventions.rst codifies the rule that forward_transform warps the moving image onto the fixed grid while moving points/landmarks warp with inverse_transform (and PCA/model registration returns the opposite orientation). register_images_base now pre-warps the moving image onto the fixed grid for initial transforms (matching the ICON backend) rather than composing an ITK transform — this can change results for pipelines using an initial transform.

Bug fixes

• Fixed ACCESS_VIOLATION crashes and a NumPy shape bug in the 4D CT pipeline (#68): corrected (Nx,Ny,Nz)→(Nz,Ny,Nx) array shape in create_distance_map (was causing IndexError); replaced the intermittently-crashing TubeTK ResampleImage path on Windows with a standard ITK ResampleImageFilter isotropic helper; and deferred import-time CUDA library initialization that conflicted with TubeTK DLL loading.
• Use relative intra-package imports instead of absolute ones (#67), improving import robustness.

Merged PRs

• ENH: Add fps option to ConvertImageToUSD by @aylward in #59
• ENH: Upaded AI agents for consistency and make physicsnemo optional by @aylward in #60
• ENH: Longitudinal registration - ICON fine tuning by @aylward in #62
• ENH: worktree creation now avoids nested venv by @aylward in #61
• ENH: Standardize forward/inverse transform conventions in registration by @aylward in #63
• ENH: Experiment for Fine Tuning ICON by @aylward in #65
• ENH: Remove docstrings on itk.Image axis ordering. Remove ANTS option. by @aylward in #66
• fix: replace absolute intra-package imports with relative imports by @aylward in #67
• BUG:ACCESS_VIOLATION crashes and NumPy shape bug in 4D CT pipeline by @aylward in #68
• ENH: Improve fit for PCA and Labelmap_to_Labelmap registration by @aylward in #69
• ENH: Update physicsnemo tutorials to use cardiac data. by @aylward in #70
• ENH: accept registration/segmentation method instances in workflows by @aylward in #71
• ENH: Bump version 2026.05.9 -> 2026.07.0 by @aylward in #72

Full Changelog: 2026.05.9...2026.07.0

PhysioMotion4D 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...