Shapeworks Command Line Tools

The ShapeWorks software is an open-source distribution of a new method for constructing compact statistical point-based models of ensembles of similar shapes that does not rely on any specific surface parameterization. The method requires very little preprocessing or parameter tuning, and is applicable to a wide range of shape analysis problems, including nonmanifold surfaces and objects of arbitrary topology. The proposed correspondence point optimization uses an entropy-based minimization that balances the simplicity of the model (compactness) with the accuracy of the surface representations. The ShapeWorks software includes tools for preprocessing data, computing point-based shape models, and visualizing the results.

Table of Contents

• Aknowledgements
  
• Relevant Papers
  
• Requirements
  
• Building
  - Unix/OSX
  - Windows
  
• Running
  - ShapeWorksGroom
  - ShapeWorksRun
  - ShapeWorksView2
  
• Contact and Bug Reports
  

Aknowledgements

If you use ShapeWorks in work that leads to published research, we humbly ask that you add the following to the 'Acknowledgments' section of your paper: "This project was supported by the National Institute of General Medical Sciences of the National Institutes of Health under grant number P41GM103545."

Relevant Papers

The following selected papers give background on the methods used in ShapeWorks and a sample of the areas ShapeWorks has been applied:

J. Cates, P.T. Fletcher, M. Styner, H. Hazlett, R.T. Whitaker. "Particle-Based Shape Analysis of Multi-Object Complexes," In Proceedings of the 11th International Conference on Medical Image Computing and Computer Assisted Intervention (MICCAI '08), Lecture Notes In Computer Science (LCNS), pp. 477--485. 2008. ISBN: 978-3-540-85987-1

J. Cates, P.T. Fletcher, Z. Warnock, R.T. Whitaker. "A Shape Analysis Framework for Small Animal Phenotyping with Application to Mice with a Targeted Disruption of Hoxd11," In Proceedings of the 5th IEEE International Symposium on Biomedical Imaging (ISBI '08), pp. 512--516. 2008. DOI: 10.1109/ISBI.2008.4541045

K.B. Jones, M. Datar, S. Ravichandran, H. Jin, E. Jurrus, R.T. Whitaker, M.R. Capecchi. "Toward an Understanding of the Short Bone Phenotype Associated with Multiple Osteochondromas," In Journal of Orthopaedic Research, Vol. 31, No. 4, pp. 651--657. 2013.

M.D. Harris, M. Datar, R.T. Whitaker, E.R. Jurrus, C.L. Peters, A.E. Anderson. "Statistical Shape Modeling of Cam Femoroacetabular Impingement," In Journal of Orthopaedic Research, Vol. 31, No. 10, pp. 1620--1626. 2013.

Requirements

• Git (https://git-scm.com/)
• CMake 2.6+ (http://www.cmake.org/)
• Visualization ToolKit (VTK 6+ recommended) (http://www.vtk.org/) --built with Qt and Imaging support!
• Insight Toolkit (ITK 4.5+ recommended) (http://www.itk.org/)
• Qt 4.8.* (http://www.qt.io/developers/)
• Windows 7+, OSX 10.9+, and OpenSuse 13.1 Recommended. Other platforms may work, but are not officially supported.

Building

Unix and OSX

In a terminal: c++ mkdir shapeworks/build cd shapeworks/build cmake -DVTK_DIR=Path/To/Your/VTK/build -DITK_DIR=Path/To/Your/ITK/build -DCMAKE_BUILD_TYPE=Release ../src make

Windows

Open a Visual Studio (32 or 64 bit) Native Tools Command Prompt. Follow these commands: c++ mkdir C:\Path\To\shapeworks\build cd C:\Path\To\shapeworks\build cmake -G "NMake Makefiles" -DVTK_DIR="C:/Path/To/Your/VTK/build" -DITK_DIR="C:/Path/To/Your/ITK/build" -DCMAKE_BUILD_TYPE=Release ../src nmake NOTE Be sure to copy the Qt DLL files to the View2 Executable directory for the program to run.

Running

The original documentation is located in this repository under src/deprecated/documentation. You may read about the details of the algorithms there.

Here are the basic instructions/pipeline for using the Shapeworks Command Line Tools. You can follow the same steps for either the examples/torus or examples/mickey. Steps for the torus example are shown.

ShapeWorksGroom

c++ cd examples/torus ../../build/bin/ShapeWorksGroom torus.groom.xml isolate hole_fill center auto_crop antialias fastmarching blur This step may takes some time. Be sure that you are in the example directory (ie. examples/torus) when running the tools. Also be sure you are providing the actual path of the executable. This is for each step.

ShapeWorksRun

c++ ../../build/bin/ShapeWorksRun torus.run.xml

ShapeWorksView2

c++ ../../build/bin/ShapeWorksView2 The visualizer is called "View2" since a previous and outdated version uses the FLTK library, not needed for View2. You may also double click on the Executable. You will need to load the parameter file via a dialog box: examples/torus/torus.analysis.xml.
OSX Please note that if you run View2 from the command line, you will need to type the path to the package interior: c++ ../../build/bin/ShapeWorksView2.app/Contents/MaxOS/ShapeWorksView2

You Should have a Qt window pop up that looks similar to the one below.

Shape
Mean The Overall mean shows the average shape of the samples. Difference refers to the difference between two groups of samples, which is a feature that is not yet available.

Samples Here you select which sample to show in the viewer. Clicking Median will give you the median sample.

PCA This tab provides a way to visualize the shape standard deviations from the modes (eigen vector solutions from the statistical analysis.) You can select the mode and slide the standard deviation to show the respective shapes in the viewer. By clicking the "Animate" check, the slider will continuously slide back and forth to visualize the shapes. The respective eigen values and lambdas are displayed below the slider.

Regression This is another feature not yet available.

Visualization
Show Glyphs Toggle visualization of the correspondance point glyphs.

Show Surface Toggle visualization of the isosurface.

Neighborhood Size The neighborhood size (max vertex valence) used for isosurface reconstruction.

Spacing The spacing used for isosurface reconstruction.

Smoothing The smoothing amount for isosurface reconstruction.

Preferences (ctrl+,)
This window provides a number of options for display and meshing.

Color Scheme Select the Surface and background colors for the viewer.

Glyph Quality Select the quality of the spheres that represent correspondance points.

Glyph Size Select the size of the spheres that represent correspondance points.

Memory Cache To speed up mesh animation, you can cache the meshes into system memory to load as needed.

Memory to Use Select the amount of system memory to use for caching. Turn this down if your machine's memory is bogged down from the program.

Parallel Reconstruction Select the amount of threads to fire (up to system hardware core max) to run while building meshes. This speeds reconstruction, theoretically.

PCA Range This is the amount of standard deviation to reach on the +/- ends of the PCA Slider.

Number of PCA Steps This determines how many steps between +/- PCA Range to take for visualization.

Number of Regression Steps This feature is not currently available.

Restore Defaults Reset the preferences to the program defaults.

File Menu
There are a few Import/Export options under the File Menu. The details of these options are beyond the scope of this document.

Contact and Bug Reports

Please email any questions to Shapeworks-users@sci.utah.edu . If there problems or bugs, please report them using the issue tracker on GitHub. This includes feature requests. Feel free to add improvements using git pull requests.