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