Getting Started With ShapeWorks Studio
ShapeWorks Studio provides an all-in-one GUI based interface to the ShapeWorks toolkit. In Studio, you can Groom, Optimize and Analyze your data all within a single interface.
The splash screen provides access to recent projects and an option to create a new blank project.
The Data Module shows the project data table as well as user-defined/saved notes. This module enables you to add and remove shapes (segmentations and surface meshes) to your cohort for further analysis.
The Groom module provides options to preprocess/groom the input data. Options differ for binary segmentations and meshes. You also have the option of skipping grooming if your data is already prepped.
The Optimize module provides options for the particle-based optimization. After selecting options and clicking "Run Optimize", you can monitor the process of the optimization in real-time. Particle positions will be displayed on individual shapes as they progress where color encodes surface correspondences across different shapes in your cohort.
After optimization is complete, you may analyze the data in Studio using the Analysis module. There are several panels available in the Analysis Module.
The View panel contains all of the options for controlling the analyis viewer options.
The Group mode allows for group comparison to quantify and visualize population-level differences. Each
group_<value> column from the project can be selected and the differences between any two values (i.e., group identifiers) in the groups can be displayed by selecting the group values in the left and right dropdown boxes. A group difference display showing vectors and a colormap of distance can be shown using the "Diff -->" button.
The Samples tab of the view panel allows you to view all of the samples in your cohort, view a single sample by index, or view the median sample.
The PCA tab of the View panel shows reconstructed shapes (surface meshes) along PCA modes of variation. Modes of variations are shape parameters learned/discovered from your data that describes shape variations. You can control the location along the PCA mode with the Standard Deviation slider. The extent of this slider is configurable in Preferences. Values displayed:
Lambda - This shows the PCA loading of current position of the slider. The middle of the slider, at the mean value, will be 0. The extent of lambda is defined by the number of standard deviations of the slider as described above. At standard deviation of 1.0, it will be the square root of the mode's eigenvalue.
Eigenvalue - This shows the eigenvalue of the currently selected mode. This is a unitless measure of how much variance is explained by this mode. The modes are sorted in decreasing order of eigenvalue, corresponding to the most variance explained first.
The Metrics panel shows the Compactness, Specificity, and Generalization charts. These are interactive charts with hover menus and the ability to zoom, pan, etc.
See Shape Model Evaluation for more information about shape evaluation.
Surface Reconstruction Panel
The surface reconstruction panel provides options for the surface reconstruction method. There are three surface reconstruction methods available depending on the data you supply.
Legacy - If an older XML file with only particle files is supplied, then only this option is available. This is the fallback option since it requires only the particles.
Mesh Warping Based - Mesh warping based method that utilizes the mean mesh. You must have either meshes supplied or image based (distance transforms).
Distance Transform Based - Surface reconstruction based on distance transforms. Project must have distance transforms.
Below is an example of the difference in using this option.
Studio provides a number of preference options.
|Color Scheme||Base foreground and background colors for viewers|
|Orientation Marker Type||Medical, Triad, or None|
|Orientation Marker Corner||Upper Right, Upper Left, Lower Left, Lower Right|
|PCA Range||Number of standard deviations for PCA slider|
|Mesh Cache Enabled||Whether to use a cache of meshes|
|Mesh Cache Epsilon||Determination of how much different a mesh must be before it is considered a different mesh, for caching purposes|
|Mesh Cache Memory to Use||Percentage of phyisical memory to allow mesh cache to use|
|Mesh Parallel Reconstruction||Whether to use parallelized mesh reconstruction|
|Mesh Parallel Number of Threads||How many threads to use for parallelized mesh reconstruction|
|Log Location||A display of where the current log file is located|
At the bottom of the viewers are the controls for the viewers:
Each button has tooltips with descriptions. The controls from left to right are
- Autoview / reset view
- Glyph visibility with dropdown for glyph size and detail
- Isosurface visibility with dropdown for surface opacity (of each domain)
- View mode (original/groomed/reconstructed)
- Center (whether to center each object based on center of mass)
- Number of views in lightbox (1,2,4,9,16,25,36,49,64)
Additionally, when feature volumes or meshes with scalars are loaded, the extended panel will be displayed:
This adds the feature map / scalar selection and a checkbox to apply a uniform scale to all viewers, vs local scale for each. Additionally, the auto range can be turned off and specified range can be set.
The keyboard shortcuts are available from the Help -> Keyboard Shortcuts menu item.
As shown in the keyboard shortcuts panel, you can hover over a particle and press the '1' key. This will select this point on all viewers.
The selected point will become white and all other points will change to a color based on the distance to the chosen point.
To turn off this display, press '1' while hovering over something other than a particle.
Additionally, after selecting a point, you may select another point by pressing '2' while hovering. This will set the first point to white, the second point to yellow and the rest to black. This is an easy way to see how particlar particles vary and correspond across shapes.
Studio's file menu is shown below.
New Project- Create a new project
Open Project- Open a project from disk
Save Project- Save project to disk
Save Project As- Save a copy of the project to a new file
Import Shapes...- Import new shapes
Export- See export below
- Up to 4 recent projects are shown at the bottom
The File -> Export menu is shown below.
- Export Current Mesh - Export the current mesh as a VTK mesh file
- Export Mesh Scalars - Export the mesh scalars as a CSV file
- Export Eigenvectors - Export the PCA eigenvectors
- Export Eigenvalues - Export the PCA eigenvalues
- Export Variance Graph - Export the variance graph as a PNG file
- Export PCA Component Scores - Export the raw PCA component scores for each subject as a CSV file
- Export PCA Mode Points - Export the PCA mode points at each step of the PCA slider
ShapeWorks Studio and the
optimize are using a new project format based off of XLSX. The new spreadsheet format profiles a uniform, easy to edit, easy to organize way of inputing data into shapeworks for grooming, optimizing and analyzing data.
Users input shapes (either binary segmentations or meshes) in the first sheet (or data sheet) using special column names to indiate type:
|shape_<name>||An input shape (segmentation/mesh) with a given name.
* Specify multiple shape_<name> columns to input multiple anatomies for each subject
|group_<name>||An group column with categorical types|
|feature_<name>||A feature volume (such as an MRI or CT)|
Many other columns will be filled in automatically by the ShapeWorks tools.
A more complete example is provided in Examples/Studio/FeatureMap/feature_map_example.xlsx :
After completing groom and optimize steps, this worksheet will look like this:
There will also be new worksheets with parameters from those tools and other studio settings.