Refactor: Reorganize statistical model workflows and standardize expe…

[aylward]

…riment naming

• Moves heart statistical model creation notebooks from data/KCL-Heart-Model to experiments/Heart-Create_Statistical_Model with sequential numbering.
• Renames experiment folders to use Title-Case with hyphens for consistency
  • Heart-Model_To_Patient → Heart-Statistical_Model_To_Patient
  • convert_vtk_to_usd_lib → Convert_VTK_To_USD.
• Removes outdated SlicerSALT documentation files and adds input_meshes directory structure.

[Copilot]

Pull request overview

This PR refactors the heart statistical shape model workflow away from SlicerSALT-specific artifacts into a fully in-repo, experiment-driven PCA pipeline, standardizes experiment naming, and improves the VTK→USD and registration tooling. It also enhances test infrastructure with experiment timing reports and adds stronger validation for generic array handling in the VTK-to-USD path.

Changes:

• Introduces a new Heart-Create_Statistical_Model experiment (with supporting data layout and docs), and renames/updates the downstream heart model–to–patient experiment to use an internally generated PCA JSON model.
• Tightens VTK→USD conversion by normalizing GenericArray data shapes, adding unit tests, and simplifying primvar handling; adds ANTs metric selection and distance-map behavior refinements in PCA and distance-map–based registrations.
• Extends the pytest infrastructure with per-test timing collection and summary reporting, and updates experiment test coverage and documentation to account for the expanded experiment set.

Reviewed changes

Copilot reviewed 68 out of 68 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_vtk_to_usd_library.py	Adds GenericArray shape validation tests, a fixture to derive average_surface.vtp from average_mesh.vtk, and refactors multiple tests to use the shared kcl_average_surface fixture, aligning tests with the new data layout.
tests/test_experiments.py	Extends experiment test matrix to include Convert_VTK_To_USD and the new Heart-Create_Statistical_Model, renames the heart model–to–patient test to Heart-Statistical_Model_To_Patient, and wires these to the new experiment subdirectory names.
tests/conftest.py	Adds global test timing collection via pytest_runtest_logreport and a rich pytest_terminal_summary that separates regular vs. experiment tests, including duration stats and slowest-test ranking.
tests/README.md	Documents the new automatic test timing report feature so users understand the additional summary output produced after test runs.
tests/PARALLEL_EXECUTION_GUIDE.md	Updates commentary on xdist worker behavior to reflect the renamed Heart-Statistical_Model_To_Patient experiment.
tests/EXPERIMENT_TESTS_SUMMARY.md	Updates the experiment list, timeout table, total runtime estimate, and change log to cover the new experiments and increased overall runtime.
tests/EXPERIMENT_TESTS_GUIDE.md	Refreshes the experiment test invocation examples, available-test table, and FAQ to incorporate Convert_VTK_To_USD, Heart-Create_Statistical_Model, and the renamed heart statistical-model experiment.
src/physiomotion4d/workflow_register_heart_model_to_patient.py	Switches ICP alignment from the ITK-based class to RegisterModelsICP, rewires PCA registration to RegisterModelsPCA.from_json with the ICP-aligned template, simplifies PCA transform composition, and updates docstrings to match the new PCA JSON/model pipeline.
src/physiomotion4d/vtk_to_usd/usd_mesh_converter.py	Removes ad-hoc reshaping logic in _add_generic_arrays and assumes GenericArray.__post_init__ provides correctly shaped data, simplifying primvar chunking and logging.
src/physiomotion4d/vtk_to_usd/data_structures.py	Strengthens GenericArray.__post_init__ to normalize/validate 1D and 2D arrays (including reshaping flat multi-component arrays) and to reject invalid dimensionalities or component counts.
src/physiomotion4d/usd_tools.py	Clarifies error-handling intent in apply_colormap_from_primvar by documenting why failures clearing existing time samples are ignored.
src/physiomotion4d/transform_tools.py	Removes leftover debug print statements from convert_transform_to_displacement_field, reducing test and library noise.
src/physiomotion4d/segment_chest_vista_3d_nim.py	Makes the VISTA3D NIM HTTP call timeout-safe by passing a timeout to urlopen and converting socket timeouts into descriptive RuntimeErrors.
src/physiomotion4d/segment_chest_vista_3d.py	Avoids duplicating bundle_path in sys.path and wraps temporary disk I/O for HuggingFace segmentation in TemporaryDirectory for robust cleanup.
src/physiomotion4d/register_models_pca.py	Reorients the PCA registration class to consume a simple JSON model (eigenvalues + components) via from_json, introduces pre_pca_transform semantics, refactors distance-map interpolation state, and tweaks optimization bounds/iterations.
src/physiomotion4d/register_models_icp_itk.py	Adds a constructor docstring to clarify arguments and usage for the ITK-based ICP registrar; no behavioral changes.
src/physiomotion4d/register_models_distance_maps.py	Calls the updated create_distance_map API with sign/normalization parameters aligned to the new contour-tools semantics and explicitly sets the ANTs metric to "MeanSquares" in the mask-to-mask stage.
src/physiomotion4d/register_images_ants.py	Introduces a metric attribute with set_metric, and plumbs metric selection through to ants.registration via aff_metric/syn_metric depending on transform type.
src/physiomotion4d/physiomotion4d_base.py	Normalizes string log levels to ints on construction and when initializing the shared logger, making log_level type consistent across the library.
src/physiomotion4d/contour_tools.py	Reimplements create_distance_map using SignedMaurerDistanceMapImageFilter with options for sign, clipping, squaring, and normalization, and simplifies point rasterization into a binary image.
src/physiomotion4d/cli/register_heart_model_to_patient.py	Drops the obsolete --pca-group-key CLI option and corresponding wiring, matching the new PCA JSON schema that no longer uses group keys.
experiments/Reconstruct4DCT/reconstruct_4d_ct_class.ipynb	Updates execution metadata timestamps to reflect a fresh full run; functional cells are unchanged.
experiments/Reconstruct4DCT/reconstruct_4d_ct.ipynb	Sets quick_run = True to accelerate example execution and refreshes execution metadata from a recent run.
experiments/README.md	Adds detailed sections for the new Heart-Create_Statistical_Model and Heart-Statistical_Model_To_Patient experiments, clarifying their relationship and prerequisites, and updates the cardiac experiments list accordingly.
experiments/Lung-GatedCT_To_USD/Experiment_SubSurfaceScatter.ipynb	Refreshes execution metadata based on a new run; code and narrative remain the same.
experiments/Lung-GatedCT_To_USD/Experiment_SegReg.ipynb	Same as above: only execution metadata updated for reproducibility tracking.
experiments/Lung-GatedCT_To_USD/Experiment_CombineModels.ipynb	Same: execution metadata updated; logic unchanged.
experiments/Lung-GatedCT_To_USD/Experiment_ArrangeOnStage.ipynb	Same: execution metadata refreshed.
experiments/Lung-GatedCT_To_USD/2-paint_dirlab_models.ipynb	Same: metadata updates from a new end-to-end execution.
experiments/Lung-GatedCT_To_USD/1-make_dirlab_models.ipynb	Same: metadata updates; workflow unchanged.
experiments/Lung-GatedCT_To_USD/0-register_dirlab_4dct.ipynb	Same: refreshed execution timestamps.
experiments/Heart-VTKSeries_To_USD/1-heart_vtkseries_to_usd.ipynb	Same: metadata refresh after rerun.
experiments/Heart-VTKSeries_To_USD/0-download_and_convert_4d_to_3d.ipynb	Same: metadata refresh after rerun.
experiments/Heart-Statistical_Model_To_Patient/heart_model_to_patient.ipynb	Points the atlas labelmap and PCA JSON to the new on-disk structure produced by the create-statistical-model experiment and updates usage of transform_point to the new pre-PCA semantics.
experiments/Heart-Statistical_Model_To_Patient/heart_model_to_model_icp_itk.ipynb	Refreshes execution metadata for documentation/example purposes; computational flow is unchanged.
experiments/Heart-GatedCT_To_USD/test_vista3d_inMem.ipynb	Updates execution metadata and widget state reflecting a recent run of the in-memory VISTA3D test.
experiments/Heart-GatedCT_To_USD/test_vista3d_class.ipynb	Same: updated metadata and widget state.
experiments/Heart-GatedCT_To_USD/4-merge_dynamic_and_static_usd.ipynb	Same: updated execution metadata.
experiments/Heart-GatedCT_To_USD/3-transform_dynamic_and_static_contours.ipynb	Same: updated execution metadata for long-running transformation steps.
experiments/Heart-GatedCT_To_USD/2-generate_segmentation.ipynb	Same: refreshed metadata for the segmentation stage.
experiments/Heart-GatedCT_To_USD/1-register_images.ipynb	Same: updated metadata for the registration stage.
experiments/Heart-GatedCT_To_USD/0-download_and_convert_4d_to_3d.ipynb	Same: updated metadata for data-prep stage.
experiments/Heart-Create_Statistical_Model/README.md	New README describing the full PCA statistical shape-model creation workflow, data requirements, and its relationship to the downstream heart model–to–patient experiment.
experiments/Heart-Create_Statistical_Model/1-input_meshes_to_input_surfaces.ipynb	New notebook that reads the 20 KCL heart meshes, extracts surfaces via PyVista, and writes a normalized surface set plus an average surface into a dedicated experiment-local directory tree.
experiments/Heart-Create_Statistical_Model/.gitignore	Ignores the generated kcl-heart-model* outputs so experiment artifacts are not committed.
experiments/Convert_VTK_To_USD/convert_vtk_to_usd_using_class.ipynb	Cleans up imports to use the installed package (including ContourTools), re-roots data/output paths to the repository layout, and adds a small helper to create average_surface.vtp from average_mesh.vtk as needed.
experiments/Colormap-VTK_To_USD/colormap_vtk_to_usd.ipynb	Updates execution metadata to reflect a recent run of the colormap demonstration; code is unchanged.
data/README.md	Updates the KCL heart-model usage bullets to reference the new experiments and clarify that statistical model creation is the primary use case.
data/KCL-Heart-Model/input_meshes/README.md	Documents the expectation that files 01.vtk–20.vtk live in the input_meshes directory for the new experiment.
data/KCL-Heart-Model/input_meshes/.gitignore	Ignores the numbered .vtk files so local copies of the licensed dataset are not committed.
data/KCL-Heart-Model/group.csv	Removes an old SlicerSALT-specific PCA grouping CSV that is no longer used in the JSON-based PCA pipeline.
data/KCL-Heart-Model/README.md	Rewrites instructions around KCL data download and organization, removes SlicerSALT-dependent PCA instructions, and points users to the new Heart-Create_Statistical_Model experiment instead.
data/KCL-Heart-Model/6-create_template_mask.ipynb	Deletes an obsolete helper notebook for labelmap/template generation now superseded by the experiment workflow.
data/KCL-Heart-Model/5-run_slicersalt_population_analysis.md	Deletes SlicerSALT-specific population-analysis instructions that no longer match the new PCA path.
data/KCL-Heart-Model/4-surfaces_aligned_correspond_to_pca_inputs.ipynb	Deletes an older, custom PCA input-preparation notebook now replaced by the experiment pipeline.
data/KCL-Heart-Model/3-run_slicersalt_registration_based_correspondence.md	Deletes SlicerSALT registration-based correspondence instructions.
data/KCL-Heart-Model/2-input_surfaces_to_surfaces_aligned.ipynb	Removes an older ICP alignment notebook whose functionality is folded into the new experiment.
data/KCL-Heart-Model/1-input_meshes_to_input_surfaces.ipynb	Deletes the original mesh-to-surface conversion notebook in favor of the experiment-scoped replacement.
data/CHOP-Valve4D/.gitignore	Adds CT to the ignore list so raw CT data for the CHOP Valve4D dataset is not committed.
README.md	Updates the high-level experiment index to reflect the split between statistical-model creation and statistical-model–to–patient registration, and their respective notebook sets.
.cursor/rules/project-standards.mdc	Refines internal assistant guidelines around Markdown file creation, clarifying exceptions for README.md files, and adds Windows-specific guidance on using the py launcher.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

test_experiment_heart_statistical_model_to_patient relies on PCA model data produced by the Heart-Create_Statistical_Model experiment (as noted in the docstring), but this dependency is not enforced in the test itself. If a user runs only this test (or runs experiment tests in a different order), it will likely fail due to missing PCA outputs rather than clearly skipping or preparing its own inputs. Consider adding an explicit precondition check (e.g., verifying presence of the expected PCA JSON / output directory and skipping with a clear message when absent) or invoking the prerequisite workflow within this test so that it can be run in isolation.