Skip to content

PhysioTwin4D 2026.07.3

Choose a tag to compare

View all tags
@aylward aylward released this 25 Jul 16:05
· 49 commits to main since this release
2026.07.3
7275e00
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

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

Contributors

aylward
Assets 2
Loading