ENH: Refactor naming and add statistical model CLIs

[aylward]

• Rename heart_model_to_patient → fit_statistical_model_to_patient (workflow, CLI, docs: register_heart_model_to_patient → fit_statistical_model_to_patient)
• Rename segment_chest_base → segment_anatomy_base
• Add create_statistical_model CLI and workflow (+ docs)
• Add visualize_pca_modes CLI
• Update docs, API references, and dependent modules

[Copilot]

Pull request overview

This PR performs a comprehensive refactoring of the PhysioMotion4D codebase to improve naming consistency and adds new CLI tools for statistical shape model workflows. The changes rename WorkflowRegisterHeartModelToPatient to WorkflowFitStatisticalModelToPatient and SegmentChestBase to SegmentAnatomyBase to better reflect their general-purpose nature. Additionally, it introduces two new workflow classes and three new CLI commands for creating and working with PCA statistical shape models.

Changes:

• Renamed core classes and files to improve clarity: WorkflowRegisterHeartModelToPatient → WorkflowFitStatisticalModelToPatient, segment_chest_base.py → segment_anatomy_base.py
• Added new WorkflowCreateStatisticalModel class and CLI for building PCA models from sample meshes
• Added visualize_pca_modes CLI for interactive PCA mode visualization
• Refactored API to make PCA and mask-to-image registration opt-in features (breaking change with better API design)
• Added RegisterModelsPCA.from_pca_model() method to accept dict-based PCA models
• Enhanced boundary checking in contour_tools.py for points outside image bounds
• Updated all documentation, experiments, and examples to reflect the new naming

Reviewed changes

Copilot reviewed 42 out of 42 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
statistics.md	Updated file references to reflect renamed modules
workflow_fit_statistical_model_to_patient.py	Renamed class; refactored to make template_labelmap and patient_image optional; PCA and mask-to-image now opt-in
workflow_create_statistical_model.py	New workflow implementing full PCA statistical model creation pipeline
segment_anatomy_base.py	Renamed from segment_chest_base; added int16 cast fix for threshold image
segment_heart_simpleware.py	Updated import to use SegmentAnatomyBase
segment_chest_vista_3d.py	Updated import to use SegmentAnatomyBase
segment_chest_total_segmentator.py	Updated import to use SegmentAnatomyBase
segment_chest_ensemble.py	Updated import to use SegmentAnatomyBase
register_models_pca.py	Added from_pca_model() classmethod; fixed typos; removed unused instance variables
register_models_distance_maps.py	Changed default roi_dilation_mm from 10 to 20
physiomotion4d_base.py	Updated example class names in docstrings
image_tools.py	Added flip_image_to_identity_direction() method
contour_tools.py	Added boundary checking to skip out-of-bounds points
cli/visualize_pca_modes.py	New CLI for interactive PCA mode visualization with slider
cli/fit_statistical_model_to_patient.py	Renamed CLI; updated to use new opt-in API for PCA and mask-to-image
cli/create_statistical_model.py	New CLI for creating PCA statistical models
cli/init.py	Updated all exports with new CLI names
init.py	Updated imports and exports for renamed classes
pyproject.toml	Updated CLI entry points; added mypy ignore for sklearn (typo: "sklean")
experiments/README.md	Updated CLI command references throughout
experiments/Heart-*.ipynb	Updated notebooks to use renamed classes and new API patterns
experiments/Heart-Simpleware_Segmentation/README.md	Updated workflow class references
experiments/Heart-Create_Statistical_Model/README.md	Updated workflow class references
docs/*	Comprehensive documentation updates for renamed classes and new CLIs

---

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

[Copilot]

Pull request overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated 11 comments.

Comments suppressed due to low confidence (1)

docs/cli_scripts/fit_statistical_model_to_patient.rst:46

• This doc page still documents --template-labelmap and --patient-image as required for basic usage, but the CLI now allows omitting --patient-image (reference image is created from patient models) and only requires --template-labelmap when mask-to-image refinement is enabled. Please update the examples and the “Required Arguments” section to reflect the current CLI behavior (and document --mask-to-image as the trigger for requiring labelmap + IDs).

---

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