Ellipsoid: Basic Example
What and Where is the Use Case?
The ellipsoid dataset comprises of axis-aligned ellipsoids with varying radii along a single axis. 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 --use_case 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
(inExamples/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
(inExamples/Python/
). See Optimizing Shape Model for details about algorithmic parameters for optimizing the shape model. - Launches ShapeWorksStudio to visualize the use case results (i.e., optimized shape model and the groomed data) by calling functions in
AnalyzeUtils.py
(inExamples/Python/
).
If you wish to start with the optimization step using a previously groomed data, add --skip_grooming
tag.
$ python RunUseCase.py --use_case 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?.
- Isotropic Resampling: Binary segmentations in
ellipsoid/segmentations/
are resampled to have an isotropic voxel spacing using a user-defined spacing. This step could also be used to produce segmentations with smaller voxel spacing, and thereby reduce aliasing artifacts (i.e., staircase/jagged surface) due to binarization. - Apply Padding: Segmentations that touch the image boundary will have an artificial hole at that intersection. Segmentations are padded by adding a user-defined number of voxels along each image direction (rows, cols, and slices) to avoid introducing artificial holes.
- 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.
- 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).
- Rigid Alignment: All of the segmentations are then aligned to the selected reference using rigid alignment, which factors out the rotation and remaining translation.
- Cropping: The segmentations are cropped so that all of the samples are within the same bounding box.
- Distance Transform: Finally, the 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
ShapeWorksStudio 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?.