MONAI-Physio 2026.09.1

New

• SegmentNVSegmentCT: new segmentation class using NV-Segment-CT, with pretrained weights support (#144)
• registrar() / segmenter() factory methods on tutorial parameter classes — anatomy-tuned registrar/segmenter without hand-building RegisterImagesGreedy/segmenter instances (#145)
• tutorial_00_lung_demo.ipynb: self-contained lung-motion demo, downloads Chest-CT + pretrained PhysicsNeMo-MGN-Lung-Motion checkpoint, runs end-to-end with no prior tutorial dependency

Fixed

• workflow_convert_vtk_to_usd.py: mesh-path lookup now uses sanitized data_basename instead of raw usd_project_name
• Tutorial 3 doc: stale RegisterImagesGreedy() snippet corrected
• Lung tutorials 01–13 updated to use new factories; various fixes accompanying NV-Segment-CT integration
• pyproject.toml: dropped two dangling mypy overrides for removed tutorial_08/09_lung_all files

Docs

• Migration guide for 2026.09.0 API changes
• Tutorial 00 documented in docs/index.rst, docs/tutorials.rst, tutorials/README.md

Other

• Added restrict_deformation_field_to_normal_falloff_outside_mask for cardiac/respiratory slip-interface handling (Tutorial 13)

---

Notes

• migration_next.md empty for this cycle — no breaking API changes since 2026.09.0.
• This release was used for the Pre-MICCAI hands-on workshop.

---

What's Changed

• ENH: NV-Segment-CT, pretrained weights, lung tutorial fixes by @aylward in #144
• ENH: registrar/segmenter factories, Tutorial 00 by @aylward in #145
• ENH: Release 2026.09.1 by @aylward in #146

Full Changelog: 2026.09.0...2026.09.1

MONAI-Physio 2026.09.0

Highlights

• TCIA-4DLung is now the lung tutorials' primary dataset, replacing
  DirLab-4DCT, and downloads automatically with one CLI call
  (monai-physio-download-data TCIA-4DLung) instead of a manual DICOM
  download + conversion step. (#141)
• Physics-informed cardiac motion, tutorials 16-18, with a neo-Hookean
  loss term. (#126)
• Cohort-based evaluation and distributed training, plus tutorials
  14-15 and a new cookbook. (#123)

Enhancements

• Training now warns when it stalls. (#140)
• 4D CT reconstruction supports Mean/Max-over-time compositing, not just a
  single reference frame. (#132)
• Tutorials can point at custom data/output directories instead of the
  repo-relative defaults. (#125)
• Tetmesh quality is verified after fitting the statistical model to a
  patient. (#135)
• Physics-informed motion training is more robust (PhysicsNeMo fixes).
  (#138)
• GPU test run time reduced. (#127)

Breaking changes

See docs/developer/migration_2026.09.0.md for full before/after code and
automated-conversion scripts:

• Registration transform results renamed forward/inverse →
  fixed_to_moving_transform/moving_to_fixed_transform (asymmetric
  between image and PCA/ICP registration - read the table before
  find-replacing).
• WorkflowCreateStatisticalModel.inverse_transforms removed (unused,
  was doubling peak memory).
• Install extras collapsed to cuda12/cuda13/dev/dev_cuda12/
  dev_cuda13; all, physicsnemo, docs, test are gone, and the
  AI-surrogate packages are now base dependencies.
• physicsnemo_tools.py free functions moved onto a new
  PhysicsNemoTools class.
• The *_tools/*Tools module and class family renamed to
  process_*/Process* (ContourTools → ProcessContours, etc.);
  utils/rename_tools_to_process.py automates the migration.
• Project renamed PhysioTwin4D → MONAI Physio. (#133)

Fixes

• Nightly test failures from stale/old tests resolved. (#128)

Docs

• Installation procedure and docs refined. (#134)
• Docs updated for new tutorials and issue templates. (#131)
• data/TCIA-4DLung/README.md added (was a dangling link); every doc
  referencing TCIA-4DLung's download method updated.

Details

• Update installation.rst by @aylward in #122
• ENH: Cohort-based evaluation, distributed training, tutorials 14-15, cookbook by @aylward in #123
• DOC: Prefer API compatibility, log unavoidable breaks in a migration guide by @aylward in #124
• ENH: Allow data and output directories of tutorials to be specified by @aylward in #125
• ENH: address long run-time of GPU tests by @aylward in #127
• BUG: Address nightly failures due to stale/old tests by @aylward in #128
• ENH: Physics-informed cardiac motion with a neo-Hookean loss, tutorials 16-18 by @aylward in #126
• ENH: Enable reconstruction using Mean/Max over time by @aylward in #132
• DOC: Update docs for new tutorials, issues templates by @aylward in #131
• ENH: Rename the project from PhysioTwin4D to MONAI Physio by @aylward in #133
• ENH: Refined installation procedure and documentation by @aylward in #134
• ENH: Verify tetmesh quality after fit to patient by @aylward in #135
• ENH: Fixed naming of transforms to standard to/from by @aylward in #136
• ENH: Physics-informed motion training fixes - PhysicsNeMo robustness by @aylward in #138
• ENH: Rename tools modules and classes to process naming convention by @aylward in #139
• ENH: Warn when physics-informed motion training collapses to the trivial solution by @aylward in #140
• ENH: Switch lung tutorials to TCIA-4DLung and automate its download by @aylward in #141
• ENH: Release 2026.09.0 by @aylward in #142
• ENH: 2026.09.0 Migration Guide by @aylward in #143

Full Changelog: 2026.08.0...2026.09.0

PhysioTwin4D 2026.08.0

PhysioTwin4D 2026.08.0

First release with a complete, runnable end-to-end path: gated CT in, statistical
shape model built, PhysicsNeMo surrogate trained and inferred, motion scored
against acquired frames, result written to USD. The tutorial series was
renumbered to follow that path, and heart and lung are now parallel tracks
through the same 13 steps.

Highlights

• Movement evaluation and end-to-end inference. New WorkflowInferMovement
  and WorkflowEvaluateMovement push predicted displacements back into geometry
  and score them per-structure against acquired frames. Tutorials 11–13 chain
  the whole pipeline, ending with combined heart-and-lung motion in one USD stage.
• NV-Segment-CTMR segmentation backend. SegmentNVSegmentCTMRI bridges the
  NVIDIA CT/MRI bundle (MONAI VISTA3D) as an alternative to TotalSegmentator.
• PhysicsNeMo train/infer split. Training and inference are now separate
  module families (train_physicsnemo_*, infer_physicsnemo_*) with shared
  base classes, so inference no longer drags in the training stack.
• ICON finetuning promoted to a supported workflow. Checkpoints are
  validated on load, and Tutorial 02 scores its result by landmark error.
  Distance-map-driven variants added for both heart and lung.
• Per-organ tutorial parameters. Constants shared across a track now live in
  parameters_heart_ct_kcl.py, parameters_lung_ct_dirlab.py, and
  parameters_duke_heart_labelmaps.py instead of being duplicated per script.

New

Source modules

• segment_nv_segment_ct_mri.py — SegmentNVSegmentCTMRI
• train_physicsnemo_base.py / _mgn.py / _mlp.py
• infer_physicsnemo_base.py / _mgn.py / _mlp.py
• workflow_infer_movement.py — WorkflowInferMovement
• workflow_evaluate_movement.py — WorkflowEvaluateMovement
• workflow_create_mean_surface.py — WorkflowCreateMeanSurface
• workflow_finetune_icon_registration.py — WorkflowFinetuneICONRegistration

Tutorials — 29 scripts across steps 01–13, plus 3 parameter modules. New at
the end of the chain: 11 (evaluate PhysicsNeMo), 12 (end-to-end inference),
13 (heart and lung motion together).

Tests — 8 new test modules covering contour mesh extraction, the
registration base class, NV-Segment-CTMR, PhysicsNeMo train/infer, VTK-to-USD
conversion, mean-surface creation, and movement evaluation.

Utilities — utils/mp4_to_gif.py (bundled ffmpeg via imageio-ffmpeg) and
utils/patches/unigradicon_augment_identity.patch.

Breaking changes

• WorkflowFineTuneICONRegistration → WorkflowFinetuneICONRegistration;
  module workflow_fine_tune_icon_registration.py →
  workflow_finetune_icon_registration.py.
• WorkflowTrainPhysicsNeMoMGN / MLP → TrainPhysicsNeMoMGN / MLP in
  train_physicsnemo_mgn.py / _mlp.py.
• WorkflowInferPhysicsNeMoMGN / MLP → InferPhysicsNeMoMGN / MLP in
  infer_physicsnemo_mgn.py / _mlp.py.
• Tutorials renumbered. The *_byod_* scripts (08 fit-model-to-patients,
  09 train, 10 eval) are gone; their content lives in the numbered heart and
  lung tracks.
• Heart models are surfaces and are written as .vtp, not volumetric meshes.
• Pre-trained weights under tutorials/network_weights/physicsnemo_mgn_heart/
  removed from the repository; train via Tutorial 09 or fetch separately.
• monai>=1.4.0 is now required (monai.networks.nets.vista3d132,
  monai.apps.vista3d).
• unigradicon must come from the feat-add-finetuning branch — the PyPI
  release ships no unigradicon.finetuning. uv picks this up from
  [tool.uv.sources]; pip users must install it explicitly:
  pip install "unigradicon @ git+https://github.com/uncbiag/uniGradICON.git@feat-add-finetuning"
• API_MAP and utils/generate_api_map.py removed — use graphify instead.
• tests/test_experiments.py and the --run-experiments flag removed;
  experiments/ scripts are exploratory and not run as tests.
• Docs pages removed: isaac_for_healthcare.rst,
  cli_scripts/brain_vessel_modeling.rst, cli_scripts/lung_gated_ct.rst.

Dependencies and install

• Added: huggingface_hub>=0.24.0, einops>=0.6.1, pyacvd>=0.4.0.

• New all extra pulling in cuda13, dev, docs, physicsnemo, and test.

• torch-scatter compiles against torch without declaring it as a build
  dependency, so torch and setuptools must already be present. uv handles this
  via no-build-isolation-package; pip needs the flag:

  pip install "physiotwin4d[all]" setuptools
  pip install "physiotwin4d[physicsnemo]" --no-build-isolation
  
  

What's Changed

• ENH: Path to new, local winpython installation by @aylward in #99
• ENH: Update handling of torch-scatter and torch by @aylward in #100
• ENH: Pre-installing setuptools in nightly-health by @aylward in #101
• ENH: Add pre-installation of torch to nightly health check by @aylward in #102
• ENH: Adding badges to README.md for project health overview by @aylward in #103
• ENH: Add NV-Segment-CTMR segmentation backend by @aylward in #104
• DOC: Replace API_MAP with graphify and fix Sphinx warnings by @aylward in #105
• ENH: Provide tutorial on workflow_finetune_icon_registration by @aylward in #106
• ENH: Restructure tutorial series and split PhysicsNeMo train/infer by @aylward in #107
• ENH: Validate ICON finetune checkpoints and score tutorial 02 by land… by @aylward in #108
• ENH: Heart models are now surfaces, save as vtp by @aylward in #109
• ENH: Clean-up docs and add lighting to USD stages by @aylward in #110
• DOCS: Assets for tutorial 04 and statistics on repo by @aylward in #111
• ENH: Add data download instructions to readme quickstart by @aylward in #112
• DOCS: Update assets, stats, readme, getting started, and tutorials. by @aylward in #113
• ENH: Finalize README.md: quick start and Licensing description by @aylward in #114
• Update licensing information in README by @aylward in #115
• ENH: Disable AI running --run-slow tests since take too long by @aylward in #116
• ENH: Registration fixes by @aylward in #118
• ENH: Per-organ tutorial parameters and distance-map registration fixes by @aylward in #119
• ENH: Movement evaluation workflow and end-to-end tutorials 11-13 by @aylward in #120
• Release 2026.08.0 by @aylward in #121

Full Changelog: 2026.07.3...2026.08.0

PhysioTwin4D 2026.07.3

13 commits since 2026.07.2.

Highlights

PhysicsNeMo training and inference are now first-class workflows. Surrogate-model code that previously lived inside tutorial scripts is now library API: WorkflowTrainPhysicsNeMo{,MGN,MLP} and WorkflowInferPhysicsNeMo{,MGN,MLP} (plus physicsnemo_tools.py), exported from the package root and exposed as CLIs physiotwin4d-train-physicsnemo and physiotwin4d-infer-physicsnemo. Tutorials 9/10 shrank from ~2700 lines of duplicated logic to thin drivers. Training resumes from checkpoints. (#88, #89)

Combined heart + lung motion (Tutorial 11). Fuses cardiac motion from a trained MeshGraphNet applied to the patient heart with respiratory motion from Tutorial 1 lung transforms into a single animated 4D USD, split by anatomy label and painted with per-organ OmniSurface materials. Also emits 4D landmarks and 4D CT for the combined motion. Backed by the Heart_and_Lungs_Motion experiment scripts. (#90, #94)

Pretrained cardiac MGN weights ship with the repo. data/models/physicsnemo_mgn_heart/ (stage model, PCA model/means, shared edge features/index) tracked via Git LFS — run git lfs pull. (#95)

Enhancements

• Fit-to-patient works with non-contrast heart models. TotalSegmentator non-contrast heart segmentations are incomplete; registration to a statistical model now succeeds anyway. (#87)
• VTK-to-USD decoupled from file I/O. WorkflowConvertVTKToUSD takes in-memory PyVista/VTK meshes via input_meshes, with explicit usd_project_name / output_directory and optional time_codes / static_merge — replacing file-path input and regex-based time-series filename discovery. Entry point is process(), matching WorkflowConvertImageToUSD. Output format selectable: .usd, .usda, .usdc. times_per_second renamed frames_per_second throughout (including CLI --fps) for clarity. (#85)
• ct_to_vtk can save by label, by group, or combined. (#86)
• DownloadSlicerHeartCTData auto-splits the 4D sequence into per-frame slice_???.mha volumes via ConvertImage4DTo3D, skipping the split if they exist. Callers no longer need a separate conversion step. (#86)
• FixDirLab4DCTData added — reads DirLab .mhd, clips to the 4DCT HU range, writes .mha. DirLab data path updated. (#86, #87)
• Per-organ OmniSurface materials in usd_anatomy_tools: skin, airway, vein/artery, muscle, fat, cartilage, endocrine organs, oxygenation-coded heart chambers. enhance_meshes override matching is longest-substring-wins, so "kidney" covers kidney_left/kidney_right. (#90)
• New deformation-field utilities: TransformTools.smooth_deformation_field_transform and ContourTools.smooth_and_decimate_surface. The USD transform-visualization helpers (arrows/flowlines) were retired in the same pass. (#94)
• Lung USD FPS derived from the gated CT. (#88)
• SegmentAnatomyBase.create_anatomy_group_masks is now create_anatomy_group_labelmaps — the name matches what it returns. (#88)
• download_data CLI requires an explicit dataset argument, printing help otherwise, instead of silently defaulting to Slicer-Heart-CT. (#85)
• [physicsnemo] extra now also pulls torch-geometric>=2.5.0 and torch-scatter>=2.1.0 for the MGN path. On a custom NVIDIA PyTorch build with no matching wheel: pip install torch-scatter --no-build-isolation. (#88)

Tutorials reorganized

Renumbered and renamed; heart and lung variants now split at each stage. The MLP train/eval tutorials were dropped as low-priority (the MLP workflow classes remain).

#	File
01	tutorial_01_heart_gated_ct_to_usd.py, tutorial_01_lung_gated_ct_to_usd.py
02	tutorial_02_heart_ct_to_vtk.py, tutorial_02_lung_ct_to_vtk.py
03	tutorial_03_heart_vtk_to_usd.py
04	tutorial_04_heart_create_statistical_model.py
05	tutorial_05_heart_to_lung_fit_statistical_model_to_patient.py
06	tutorial_06_lung_reconstruct_highres_4d_ct.py
08	tutorial_08_byod_fit_model_to_patients.py
09	tutorial_09_byod_train_physicsnemo_mgn.py
10	tutorial_10_byod_eval_physicsnemo_mgn.py
11	tutorial_11_heart_and_lung_motion.py

(#88, #89, #93)

Removals

• netgen volume meshing dropped from the image-to-VTK path. netgen hung indefinitely on self-intersecting / non-manifold surfaces from real segmented anatomy (e.g. lung airways), and no practical preprocessing — image padding, fill_holes, morphological closing — reliably prevented it; fill_holes() itself carries a documented segfault risk. ContourTools.extract_mesh / save_meshes / save_combined_mesh, the mesh_target_reduction parameter, the "meshes" result key, CLI --mesh-target-reduction, VTU output, and the netgen-mesher dependency are all gone. (#86)

Bug fixes

• Windows py launcher resolved the wrong interpreter. A leftover jupytext #!/usr/bin/env python shebang on line 1 made py.exe search PATH for a bare python instead of using the active venv, breaking physiotwin4d imports. Removed from all 64 affected files. (#86)
• TotalSegmentator __main__ isolation fixed (Windows multiprocessing guard). (#89)
• sacrum (label 25) moved to the correct anatomy group, and body labels are no longer overwritten, so body_skin (133) survives. (#90)
• CHOP-Valve download directory structure corrected. (#92)
• Tutorials 5/9/10 evaluate the resumed run's output directory instead of OUTPUT_DIR. (#90)

Infrastructure

• Ruff runs through pre-commit so its version is pinned in one place; ruff-pre-commit bumped to v0.15.20. (#90)
• Pre-commit checks apply only to tracked files. (#97)
• Nightly health CI uses a local Python 3.13 install; interpreter path fixed. (#91, #96)
• .claude-plugin marketplace/plugin manifests and .cursor rules added; CLAUDE.md behavior guidelines restructured into numbered sections. (#90)

Full Changelog: https://github.com//physiotwin4d/compare/2026.07.2...2026.07.3

Itemizations

What's Changed

• ENH: Refactored VTK-to-USD class, workflow, and tutorial. by @aylward in #85
• ENH: Remove unreliable netgen meshing; fix py launcher and CT auto-convert by @aylward in #86
• ENH: Update fit-to-patient for non-contrast heart models by @aylward in #87
• ENH: Reorg tutorials and create PhysicsNeMo workflows by @aylward in #88
• ENH: Simplified naming of tutorials and updated their dirs by @aylward in #89
• ENH: Demo for combining heart and lung motion by @aylward in #90
• ENH: Fix path to python for nightly health CI by @aylward in #91
• ENH: Track physicsnemo_mgn_heart weights via Git LFS by @aylward in #95
• ENH: Fix directory structure for CHOP-Valve data by @aylward in #92
• ENH: Removed low-priority MLP training tutorial by @aylward in #93
• ENH: Produce 4D labelmap and CT images with lung and heart motion by @aylward in #94
• ENH: Update nightly runner to use a local install of python 3.13 by @aylward in #96
• ENH: Apply pre-commit checks only to tracked files by @aylward in #97
• ENH: Release 2026.07.3 by @aylward in #98

Full Changelog: 2026.07.2...2026.07.3

PhysioTwin4D 2026.07.2

PhysioTwin4D 2026.07.2

Added

• Automatic download support for CHOP-Valve4D via physiotwin4d-download-data / DataDownloadTools.DownloadCHOPValve4DData — fetches the PhysioTwin4D convenience release (VTK/ITK conversion of the original FEBio model) from GitHub. All three optional datasets (Slicer-Heart-CT, KCL-Heart-Model, CHOP-Valve4D) can now be fetched automatically; DirLab-4DCT remains manual (DIR-Lab distributes cases individually and may require registration).

Changed

• data/README.md restructured from a large, duplicated reference into a lightweight index (dataset table + provider + link); each dataset's own README.md (e.g. data/KCL-Heart-Model/README.md) is now the single source of truth for download commands, specs, and citations.

Fixed

• Corrected broken/incorrect links and claims accumulated in data/README.md and related docs: wrong Slicer-Heart-CT/Slicer-Heart-CT GitHub org (now SlicerHeart/SlicerHeart), stale "manual download" labels for datasets that already had downloaders, and an inaccurate .mhd/.raw format description for DirLab-4DCT (corrected to .mhd headers + .img raw volumes).
• Removed unreachable dead code (mypy unreachable errors) in vtk_to_usd/usd_utils.py's exhaustive DataType branching.

CI

• Nightly health / remote runner now pins Python 3.11.

What's Changed

• ENH: Add CHOP-Valve4D auto-download; restructure dataset docs by @aylward in #82
• ENH: Specify Python 3.11 for nightly health / remote runner by @aylward in #83
• ENH: Release 2026.07.2 by @aylward in #84

Full Changelog: 2026.07.1...2026.07.2

Data And PhysioTwin4D 2026.07.1

This is a documentation- and metadata-only patch release. No public API,
workflow, or CLI behavior changed.

Highlights

• Reframed the project description everywhere (README, pyproject.toml,
  package docstring, CLAUDE.md, AGENTS.md, Sphinx docs) around what
  PhysioTwin4D actually is: methods, workflows, tutorials, and a CLI for
  building personalized physiological digital twins — anatomic models plus
  AI surrogates, starting with cardiac/respiratory motion and expanding to
  electrophysiology, blood flow, and organ perfusion.
• Simplified README.md into a highlights page that points to the hosted
  docs site (https://project-monai.github.io/physiotwin4d/) instead of
  duplicating installation/CLI/API content inline.
• Consolidated docs/examples.rst into docs/tutorials.rst: tutorials are now
  the single source of runnable usage examples, each with an "Inner API
  usage" excerpt from the real tutorial script and an input/output preview
  (placeholder GIFs for now, tracked via Git LFS).
• Updated docs/architecture.rst to reflect the current class set (Greedy /
  Greedy+ICON registration, WorkflowFineTuneICONRegistration,
  SegmentChestTotalSegmentatorWithContrast, and others), the PhysicsNeMo
  AI-surrogate tutorial pipeline, and the accurate CLI command list.
• Removed stale docs (changelog.rst, PYPI_RELEASE_GUIDE.md) and fixed the
  docs CI workflow to fetch Git LFS assets before building, so tutorial
  preview images publish correctly.
• Refreshed statistics.md with current repo metrics.

No dependency, API, or CLI changes in this release.

What's Changed

• BUG: Avoid name collision when building docs on CI by @aylward in #73
• BUG: Nightly CI runner python accessed via py by @aylward in #75
• Eliminate tubetk by @aylward in #76
• ENH: Provide TotalSegmentatorWithContrast as a custom seg option by @aylward in #77
• ENH: Provides volumetric meshing. by @aylward in #78
• Rename/physiotwin4d by @aylward in #79
• ENH: Cleaned up infrastructure and documentation by @aylward in #80
• ENH: Release 2026.07.1 by @aylward in #81

Full Changelog: 2026.07.0...2026.07.1

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