Ellipsoid: Basic Example

What and Where is the Use Case?

The ellipsoid dataset comprises of axis-aligned ellipsoids with varying radii along all three axes. This example is a stepping stone for the user to get familiar with the workflow of ShapeWorks.

The ellipsoid.py (in Examples/Python/) use case represents the standard use version of a shape modeling workflow using ShapeWorks. It includes the full pipeline for processed (i.e., groomed) as well as unprocessed data.

The use case is located at: Examples/Python/ellipsoid.py

Running the Use Case

To run the use case, run RunUseCase.py (in Examples/Python/) with proper tags. The tags control the type of input data and the optimization method. See Getting Started with Use Cases for the full list of tags.

  • --skip_grooming: to run the optimization on previously processed/groomed data
  • --use_single_scale: to use the single-scale optimization. Default is multi-scale optimization

To run the full pipeline with multi-scale:

$ cd /path/to/shapeworks/Examples/Python
$python RunUseCase.py ellipsoid 

This calls ellipsoid.py (in Examples/Python/) to perform the following.

  • Loads the ellipsoid dataset using a local version if it exists (i.e., previously downloaded); otherwise, the dataset is automatically downloaded from the ShapeWorks Data Portal.
  • Grooms the segmentations by calling data preprocessing functions in GroomUtils.py (in Examples/Python/). See Grooming Data for details about these preprocessing steps.
  • Optimizes particle distribution (i.e., the shape/correspondence model) by calling optimization functions in OptimizeUtils.py (in Examples/Python/). See Optimizing Shape Model for details about algorithmic parameters for optimizing the shape model.
  • Launches ShapeWorks Studio to visualize the use case results (i.e., optimized shape model and the groomed data) by calling functions in AnalyzeUtils.py (in Examples/Python/).

If you wish to start with the optimization step using a previously groomed data, add --skip_grooming tag.

$ python RunUseCase.py ellipsoid --skip_grooming

Grooming Data

The following preprocessing steps are only performed when you start with unprepped data, i.e., the tag --start_with_prepped_data is not used. For a description of the grooming tools and parameters, see: How to Groom Your Dataset?.

  1. Isotropic Resampling: Binary segmentations in ellipsoid/segmentations/ are resampled to have an isotropic voxel spacing.
  2. Center-of-Mass Alignment: This translational alignment step is performed before rigidly aligning the samples to a shape reference. This factors out translations to reduce the risk of misalignment and allow for a medoid sample to be automatically selected as the reference for rigid alignment.
  3. Reference Selection: The reference is selected by first computing the mean (average) distance transform of the segmentations, then selecting the sample closest to that mean (i.e., medoid).
  4. Rigid Alignment: All of the segmentations are then aligned to the selected reference using rigid alignment, which factors out the rotation and remaining translation.
  5. Bounding Box: The smallest region which fits all of the samples is found.
  6. Cropping: The segmentations are cropped to the size of the bounding box.
  7. Distance Transform: Finally, the smooth signed distance transform is computed, and the dataset is now ready for the optimize phase.

Optimizing Shape Model

Below are the default optimization parameters for this use case. For a description of the optimize tool and its algorithmic parameters, see: How to Optimize Your Shape Model. Note that use_shape_statistics_after parameter is not used when --use_single_scale tag is given to the RunUseCase.py (in Examples/Python/).

        "number_of_particles": 128,
        "use_normals": 1,
        "normal_weight": 10.0,
        "checkpointing_interval": 200,
        "keep_checkpoints": 0,
        "iterations_per_split": 2000,
        "optimization_iterations": 1000,
        "starting_regularization": 100,
        "ending_regularization": 10,
        "recompute_regularization_interval": 2,
        "domains_per_shape": 1,
        "domain_type": 'image',
        "relative_weighting": 10,
        "initial_relative_weighting": 0.01,
        "procrustes_interval": 0,
        "procrustes_scaling": 0,
        "save_init_splits": 0,
        "verbosity": 2
        "use_shape_statistics_after": 32

Analyzing Shape Model

ShapeWorks Studio visualizes/analyzes the optimized particle-based shape model by visualizing the mean shape, individual shape samples, and the shape modes of variations. For more information, see: How to Analyze Your Shape Model?.