ENH: Refactor naming and add statistical model CLIs (#27)

* ENH: Refactor naming and add statistical model CLIs

- 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

* ENH: Enable clipping top of heart when using Simpleware

* ENH: Initial version of trimming heart models to base rep.

* BUG: Address copilot and mypy (import-not-found) errors

Author: aylward

README.md

@@ -88,13 +88,14 @@ print(f"PhysioMotion4D version: {physiomotion4d.__version__}")
 
 - **Workflow Classes**: Complete end-to-end pipeline processors
   - `WorkflowConvertHeartGatedCTToUSD`: Heart-gated CT to USD processing workflow
-  - `WorkflowRegisterHeartModelToPatient`: Model-to-patient registration workflow
+  - `WorkflowCreateStatisticalModel`: Create PCA statistical shape model from sample meshes
+  - `WorkflowFitStatisticalModelToPatient`: Model-to-patient registration workflow
 - **Segmentation Classes**: Multiple AI-based chest segmentation implementations
   - `SegmentChestTotalSegmentator`: TotalSegmentator-based segmentation
   - `SegmentChestVista3D`: VISTA-3D model-based segmentation
   - `SegmentChestVista3DNIM`: NVIDIA NIM version of VISTA-3D
   - `SegmentChestEnsemble`: Ensemble segmentation combining multiple methods
-  - `SegmentChestBase`: Base class for custom segmentation methods
+  - `SegmentAnatomyBase`: Base class for custom segmentation methods
 - **Registration Classes**: Multiple registration methods for different use cases
   - Image-to-Image Registration:
     - `RegisterImagesICON`: Deep learning-based registration using Icon algorithm
@@ -156,21 +157,42 @@ physiomotion4d-heart-gated-ct cardiac.nrrd \
 
 For Python API usage and advanced customization, see the examples below or refer to the CLI implementation in `src/physiomotion4d/cli/`.
 
+#### Create Statistical Model
+
+Build a PCA statistical shape model from sample meshes aligned to a reference:
+
+```bash
+# From a directory of sample meshes
+physiomotion4d-create-statistical-model \
+    --sample-meshes-dir ./input_meshes \
+    --reference-mesh average_mesh.vtk \
+    --output-dir ./pca_output
+
+# With custom PCA components
+physiomotion4d-create-statistical-model \
+    --sample-meshes-dir ./meshes \
+    --reference-mesh average_mesh.vtk \
+    --output-dir ./pca_output \
+    --pca-components 20
+```
+
+Outputs: `pca_mean_surface.vtp`, `pca_mean.vtu` (if reference is volumetric), and `pca_model.json`.
+
 #### Heart Model to Patient Registration
 
 Register a generic heart model to patient-specific data:
 
 ```bash
 # Basic registration
-physiomotion4d-register-heart-model \
+physiomotion4d-fit-statistical-model-to-patient \
     --template-model heart_model.vtu \
     --template-labelmap heart_labelmap.nii.gz \
     --patient-models lv.vtp rv.vtp myo.vtp \
     --patient-image patient_ct.nii.gz \
     --output-dir ./results
 
 # With PCA shape fitting
-physiomotion4d-register-heart-model \
+physiomotion4d-fit-statistical-model-to-patient \
     --template-model heart_model.vtu \
     --template-labelmap heart_labelmap.nii.gz \
     --patient-models lv.vtp rv.vtp myo.vtp \
@@ -203,7 +225,7 @@ final_usd = processor.process()
 ### Python API - Model to Patient Registration
 
 ```python
-from physiomotion4d import WorkflowRegisterHeartModelToPatient
+from physiomotion4d import WorkflowFitStatisticalModelToPatient
 import pyvista as pv
 import itk
 
@@ -213,7 +235,7 @@ patient_surfaces = [pv.read("lv.stl"), pv.read("rv.stl")]
 reference_image = itk.imread("patient_ct.nii.gz")
 
 # Initialize and run workflow
-workflow = WorkflowRegisterHeartModelToPatient(
+workflow = WorkflowFitStatisticalModelToPatient(
     moving_mesh=model_mesh,
     fixed_meshes=patient_surfaces,
     fixed_image=reference_image
@@ -352,13 +374,13 @@ PhysioMotion4D provides standardized logging through the `PhysioMotion4DBase` cl
 
 ```python
 import logging
-from physiomotion4d import WorkflowRegisterHeartModelToPatient, PhysioMotion4DBase
+from physiomotion4d import WorkflowFitStatisticalModelToPatient, PhysioMotion4DBase
 
 # Control logging level globally for all classes
 PhysioMotion4DBase.set_log_level(logging.DEBUG)
 
 # Or filter to show logs from specific classes only
-PhysioMotion4DBase.set_log_classes(["WorkflowRegisterHeartModelToPatient", "RegisterModelsPCA"])
+PhysioMotion4DBase.set_log_classes(["WorkflowFitStatisticalModelToPatient", "RegisterModelsPCA"])
 
 # Show all classes again
 PhysioMotion4DBase.set_log_all_classes()
@@ -436,7 +458,7 @@ Advanced registration between generic anatomical models and patient-specific dat
 - **`heart_model_to_model_registration_pca.ipynb`**: PCA-based statistical shape model registration
 - **`heart_model_to_patient.ipynb`**: Complete model-to-patient registration workflow
 
-Uses the `WorkflowRegisterHeartModelToPatient` class for three-stage registration:
+Uses the `WorkflowFitStatisticalModelToPatient` class for three-stage registration:
 1. ICP-based rough alignment
 2. Mask-to-mask deformable registration
 3. Optional PCA-constrained shape fitting

docs/api/index.rst

@@ -76,10 +76,11 @@ By Category
 
 **Workflows**
    * :class:`~physiomotion4d.WorkflowConvertHeartGatedCTToUSD` - Heart CT to USD
-   * :class:`~physiomotion4d.WorkflowRegisterHeartModelToPatient` - Heart model registration
+   * :class:`~physiomotion4d.WorkflowCreateStatisticalModel` - Create PCA statistical shape model
+   * :class:`~physiomotion4d.WorkflowFitStatisticalModelToPatient` - Heart model registration
 
 **Segmentation**
-   * :class:`~physiomotion4d.SegmentChestBase` - Base segmentation class
+   * :class:`~physiomotion4d.SegmentAnatomyBase` - Base segmentation class
    * :class:`~physiomotion4d.SegmentChestTotalSegmentator` - TotalSegmentator
    * :class:`~physiomotion4d.SegmentChestVista3D` - VISTA-3D model
    * :class:`~physiomotion4d.SegmentChestVista3DNIM` - VISTA-3D NIM

docs/api/segmentation/base.rst

@@ -9,7 +9,7 @@ Abstract base class for all segmentation methods.
 Class Reference
 ===============
 
-.. autoclass:: SegmentChestBase
+.. autoclass:: SegmentAnatomyBase
    :members:
    :undoc-members:
    :show-inheritance:
@@ -18,7 +18,7 @@ Class Reference
 Overview
 ========
 
-:class:`SegmentChestBase` provides the foundation for all segmentation implementations in PhysioMotion4D. It defines the common interface and shared functionality that all segmentation methods must implement.
+:class:`SegmentAnatomyBase` provides the foundation for all segmentation implementations in PhysioMotion4D. It defines the common interface and shared functionality that all segmentation methods must implement.
 
 **Key Responsibilities**:
    * Define standard segmentation interface
@@ -87,17 +87,17 @@ These methods are provided by the base class:
 Creating Custom Segmentation Classes
 =====================================
 
-To create a new segmentation method, inherit from :class:`SegmentChestBase`:
+To create a new segmentation method, inherit from :class:`SegmentAnatomyBase`:
 
 Basic Implementation
 --------------------
 
 .. code-block:: python
 
-   from physiomotion4d import SegmentChestBase
+   from physiomotion4d import SegmentAnatomyBase
    import numpy as np
    
-   class CustomSegmentator(SegmentChestBase):
+   class CustomSegmentator(SegmentAnatomyBase):
        """Custom segmentation implementation."""
        
        def __init__(self, param1=None, verbose=False):
@@ -150,7 +150,7 @@ With Custom Post-Processing
 
 .. code-block:: python
 
-   class CustomSegmentator(SegmentChestBase):
+   class CustomSegmentator(SegmentAnatomyBase):
        """Segmentator with custom post-processing."""
        
        def post_process(self, labelmap):
@@ -243,7 +243,7 @@ Validate that required structures are present:
 
 .. code-block:: python
 
-   class ValidatingSegmentator(SegmentChestBase):
+   class ValidatingSegmentator(SegmentAnatomyBase):
        """Segmentator with validation."""
        
        def segment(self, image_path):
@@ -268,7 +268,7 @@ Track segmentation progress for long operations:
 
 .. code-block:: python
 
-   class ProgressSegmentator(SegmentChestBase):
+   class ProgressSegmentator(SegmentAnatomyBase):
        """Segmentator with progress tracking."""
        
        def segment(self, image_path):

docs/api/segmentation/index.rst

@@ -16,7 +16,7 @@ PhysioMotion4D supports multiple segmentation approaches:
 * **VISTA-3D NIM**: NVIDIA Inference Microservice version
 * **Ensemble**: Combine multiple methods for improved accuracy
 
-All segmentation classes inherit from :class:`SegmentChestBase` and provide consistent interfaces.
+All segmentation classes inherit from :class:`SegmentAnatomyBase` and provide consistent interfaces.
 
 Quick Links
 ===========

docs/api/workflows.rst

@@ -49,7 +49,7 @@ Heart Gated CT to USD
 Heart Model to Patient Registration
 ------------------------------------
 
-.. autoclass:: WorkflowRegisterHeartModelToPatient
+.. autoclass:: WorkflowFitStatisticalModelToPatient
    :members:
    :undoc-members:
    :show-inheritance:
@@ -67,9 +67,9 @@ Heart Model to Patient Registration
 
 .. code-block:: python
 
-   from physiomotion4d import WorkflowRegisterHeartModelToPatient
+   from physiomotion4d import WorkflowFitStatisticalModelToPatient
    
-   workflow = WorkflowRegisterHeartModelToPatient(
+   workflow = WorkflowFitStatisticalModelToPatient(
        model_file="heart_template.vtk",
        patient_image="patient_ct.nrrd",
        output_directory="./registration_results",
@@ -221,7 +221,7 @@ Combine multiple workflows:
    heart_result = heart_workflow.process()
    
    # Second workflow: Register model
-   registration_workflow = WorkflowRegisterHeartModelToPatient(
+   registration_workflow = WorkflowFitStatisticalModelToPatient(
        model_file=heart_result['model'],
        patient_image=patient_ct,
        output_directory="./registration_output"

docs/architecture.rst

@@ -31,7 +31,7 @@ Core Components
 
 2. **Segmentation Module**
 
-   * Base class: :class:`SegmentChestBase`
+   * Base class: :class:`SegmentAnatomyBase`
    * Implementations: TotalSegmentator, VISTA-3D, Ensemble
 
 3. **Registration Module**

docs/cli_scripts/create_statistical_model.rst

@@ -0,0 +1,102 @@
+====================================
+Create Statistical Model
+====================================
+
+Overview
+========
+
+The ``physiomotion4d-create-statistical-model`` command-line tool builds a PCA
+(Principal Component Analysis) statistical shape model from a sample of meshes
+aligned to a reference mesh. This mirrors the pipeline in the
+Heart-Create_Statistical_Model experiment notebooks.
+
+The workflow:
+
+1. **Extract surfaces** from sample and reference meshes
+2. **ICP alignment**: Affine align each sample surface to the reference surface
+3. **Deformable registration**: ANTs SyN to establish dense correspondence
+4. **Correspondence**: Build aligned shapes with reference topology
+5. **PCA**: Compute mean shape and principal components
+
+Outputs written to the output directory:
+
+* ``pca_mean_surface.vtp`` — Mean shape as a surface (PolyData)
+* ``pca_mean.vtu`` — Reference volume mesh in mean space (only if reference is volumetric)
+* ``pca_model.json`` — PCA model (eigenvalues, components) for use with
+  :class:`physiomotion4d.WorkflowFitStatisticalModelToPatient` or
+  :class:`physiomotion4d.RegisterModelsPCA`
+
+Installation
+============
+
+The script is installed with PhysioMotion4D:
+
+.. code-block:: bash
+
+   pip install physiomotion4d
+
+Quick Start
+===========
+
+Basic Usage
+-----------
+
+Create a PCA model from a directory of sample meshes and a reference mesh:
+
+.. code-block:: bash
+
+   physiomotion4d-create-statistical-model \
+       --sample-meshes-dir ./input_meshes \
+       --reference-mesh average_mesh.vtk \
+       --output-dir ./pca_output
+
+Explicit Sample List
+--------------------
+
+Provide sample mesh paths explicitly instead of a directory:
+
+.. code-block:: bash
+
+   physiomotion4d-create-statistical-model \
+       --sample-meshes 01.vtk 02.vtk 03.vtu 04.vtp \
+       --reference-mesh average_mesh.vtk \
+       --output-dir ./pca_output
+
+With Custom Parameters
+----------------------
+
+.. code-block:: bash
+
+   physiomotion4d-create-statistical-model \
+       --sample-meshes-dir ./meshes \
+       --reference-mesh average_mesh.vtk \
+       --output-dir ./pca_output \
+       --pca-components 20
+
+Command-Line Arguments
+======================
+
+Required Arguments
+------------------
+
+``--sample-meshes-dir DIR`` or ``--sample-meshes PATH [PATH ...]``
+   Either a directory containing sample mesh files (``.vtk``, ``.vtu``, ``.vtp``)
+   or a list of paths to sample meshes. One of these is required.
+
+``--reference-mesh PATH``
+   Path to the reference mesh. Its surface is used as the alignment target for
+   all samples.
+
+``--output-dir DIR``
+   Output directory. Writes ``pca_mean_surface.vtp``, ``pca_mean.vtu`` (if
+   reference is volumetric), and ``pca_model.json``.
+
+Optional Arguments
+------------------
+
+``--pca-components N``
+   Number of PCA components to retain (default: 15).
+
+See :class:`physiomotion4d.WorkflowCreateStatisticalModel` for the full API and
+additional parameters (e.g. ``reference_spatial_resolution``,
+``reference_buffer_factor``) that can be exposed in future CLI versions.

…s/cli_scripts/heart_model_to_patient.rst …pts/fit_statistical_model_to_patient.rstdocs/cli_scripts/heart_model_to_patient.rst renamed to docs/cli_scripts/fit_statistical_model_to_patient.rst docs/cli_scripts/heart_model_to_patient.rst renamed to docs/cli_scripts/fit_statistical_model_to_patient.rst

@@ -5,7 +5,7 @@ Heart Model to Patient Registration
 Overview
 ========
 
-The ``physiomotion4d-register-heart-model`` command-line tool registers generic anatomical heart models to patient-specific imaging data and surface models. This workflow enables:
+The ``physiomotion4d-fit-statistical-model-to-patient`` command-line tool registers generic anatomical heart models to patient-specific imaging data and surface models. This workflow enables:
 
 * Patient-specific anatomical modeling from generic templates
 * Multi-stage registration combining ICP, PCA, and deformable methods
@@ -38,7 +38,7 @@ Register a generic heart model to patient data:
 
 .. code-block:: bash
 
-   physiomotion4d-register-heart-model \
+   physiomotion4d-fit-statistical-model-to-patient \
        --template-model heart_model.vtu \
        --template-labelmap heart_labelmap.nii.gz \
        --patient-models lv.vtp rv.vtp myo.vtp \
@@ -52,7 +52,7 @@ Include statistical shape model fitting:
 
 .. code-block:: bash
 
-   physiomotion4d-register-heart-model \
+   physiomotion4d-fit-statistical-model-to-patient \
        --template-model heart_model.vtu \
        --template-labelmap heart_labelmap.nii.gz \
        --patient-models lv.vtp rv.vtp myo.vtp \
@@ -82,7 +82,7 @@ Required Arguments
 ``--output-dir DIR``
    Output directory for results
 
-See :class:`physiomotion4d.WorkflowRegisterHeartModelToPatient` for API documentation.
+See :class:`physiomotion4d.WorkflowFitStatisticalModelToPatient` for API documentation.
 
 Template Labelmap Configuration
 --------------------------------
@@ -141,7 +141,7 @@ Example 1: Basic Registration
 
 .. code-block:: bash
 
-   physiomotion4d-register-heart-model \
+   physiomotion4d-fit-statistical-model-to-patient \
        --template-model heart_model.vtu \
        --template-labelmap heart_labelmap.nii.gz \
        --patient-models lv.vtp rv.vtp myo.vtp \
@@ -153,7 +153,7 @@ Example 2: PCA-Based Registration
 
 .. code-block:: bash
 
-   physiomotion4d-register-heart-model \
+   physiomotion4d-fit-statistical-model-to-patient \
        --template-model heart_model.vtu \
        --template-labelmap heart_labelmap.nii.gz \
        --patient-models lv.vtp rv.vtp \