Documentation/4.3/Modules/SurfaceToolbox

From Slicer Wiki
Jump to: navigation, search
Home < Documentation < 4.3 < Modules < SurfaceToolbox


For the latest Slicer documentation, visit the read-the-docs.



Introduction and Acknowledgements

  • Luca Antiga: Orobix Srl
  • Daniel Blezek: Mayo Clinic
  • Ron Kikinis, BWH
  • Steve Pieper, Isomics
  • Contact: Luca Antiga, luca.antiga@orobix.com


NA-MIC  
Isomics, Inc.  
Orobix  


Module Description

This module supports cleanup and optimization processes on surface models, namely

  • Decimation: topology-preserving reduction of surface triangles
  • Smoothing: surface regularization using a Laplacian filter or Taubin's [1] non-shrinking algorithm
  • Normals: generation of surface normals (for geometry algorithms or for improving visualization, since surface shading rendering needs normals to be defined on the surface)
  • Cleaner: merging of coincident points, removal of unused points (i.e. not used by any cell), treatment of degenerate cells
  • Connectivity: extraction of the largest connected portion of the surface model

The filters are arranged in a pipeline following the order in which they are listed above. Individual filters can be activated/deactivated by pressing/depressing the respective buttons. In case a filter needs parameters to be specified, a panel will be shown when the filter is activated.

Clicking Apply will run the filters in the pipeline and produce an output. Clicking on the Toggle Models button will toggle the visibility of the model before and after filtering.

Use Cases

The module is appropriate when a surface has been extracted (e.g. with the Model Maker module) but its appearance has to be improved.

This module supports various cleanup and optimization processes on surface models. For example, a noisy image data set can lead to models that have bumpy surfaces which do not accurately depict the actual anatomy of interest. In this case, the model can be smoothed to better approximate the actual surface.

Another application is to reduce the geometric complexity of surface models using decimation to reduce the file size or rendering time of the models.

Normals are used to improve the visual appearance of STL surfaces rendered as flat polygons due to a lack in normal information. Normals should also be recomputed after smoothing, since smoothing doesn't re-orient normals and shading depends on normal orientation. Activating Splitting, feature edges (i.e. seams in the surface) will be visually enhanced through the creation of a discontinuity in surface normal orientation producing a discontinuity in surface shading.

Connectivity can be employed after the extraction of an isosurface using Grayscale Model Maker, in order to get rid of tiny pieces of surface associated to noise with intensity greater than the isosurface level.

Surface obtained using Grayscale Model Maker
Filtered surface

Tutorials

N/A

Panels

SurfaceToolbox User Interface

Select the input and output models, and then enable the stages of the pipeline by selecting the buttons. Stages that include parameters will open up when they are enabled. Click apply to activate the pipeline and then click the Toggle button to compare the model before and after the operation.

    • Input Model: the input model
    • Output Model: the output model, i.e. the input model filtered through all the "Enabled" filters.
  • Decimation:
    • Enabled: enable topology-preserving surface decimation.
    • Target reduction: target percentage reduction in number of triangles (this target reduction may not be achieved depending on the constraints on the topology).
    • Boundary vertex deletion: allow deletion of points located on the boundary of the surface.
  • Smoothing:
    • Enabled: enable surface smoothing.
    • Smoothing method: choose between Laplace or Taubin [1] surface smoothing algorithms (while Taubin is a non-shrinking filter, Laplace will tend to shrink the surface under the effect of curvature).
    • Boundary smoothing: allow smoothing of points located on the boundary of the surface.
    • Laplace number of iterations: number of iterations set when the Laplace algorithm is selected.
    • Laplace relaxation factor: the factor by which a point moves towards the barycenter of its neighbors in the Laplace algorithm.
    • Taubin number of iterations: number of iterations set when the Taubin algorithm is selected.
    • Taubin passband: spatial frequency cutoff for the Taubin algorithm.
  • Normals:
    • Enabled: enable computation of consistently-oriented surface normals (advised after smoothing - smoothing algorithms only move points and do not update normals accordingly, so the surface might still look non-smooth after smoothing when Gouraud shading is used).
    • Flip normals: toggle direction of normals - the algorithm will do its best to orient the normals consistently "outwards" a surface, if the surface is orientable. This switch will make normals point "inwards"
    • Splitting: toggle splitting of surface when angle between the normals of two neighboring triangles is above the Feature angle. This improves the shading appearance of sharp edges but produces topological holes in the surface.
    • Feature angle: angle (in degrees) between two neighboring triangles beyond which the edge between the triangles is split.
  • Cleaner:
    • Enabled: enable cleaning (merging of coincident points, elimination of unused points, treatment of degenerate cells) of the surface.
  • Connectivity:
    • Enabled: enable extracting the largest connected portion of the surface and getting rid of the rest.
  • Toggle Models:
    • Clicked: toggle the visualization of the input or the output model, allowing to compare them and visualize the effect of filtering.
  • Apply:
    • Clicked: apply the pipeline of all Enabled filters to the input model and produce the output model.


References

[1] IBM tech report RC-20404 (#90237, dated 3/12/96) "Optimal Surface Smoothing as Filter Design" G. Taubin, T. Zhang and G. Golub

Information for Developers


The implementation isolates the module state in a class object defined in the setup method of the SurfaceToolboxWidget class.

A custom connect function, wrapping Qt's signal/slot connect, is defined within the setup method, allowing to concisely connect all signals originating from GUI controls to slots setting a variable in the state object in one line.

An updateGUI function is defined within the setup method, where controls take values from the state object. At the end of the setup method, self.updateGUI is set to the updateGUI function defined in setup. This allows updateGUI to close over (see closures), all widget objects instantiated in the setup method. This bypasses the need for making every widget an instance variable and having it connect to an instance method, achieving greater conciseness. An analogous technique is used for the onApply and onToggleModels functions, which are defined in the setup method body and then directly passed to the connect method of the respective widgets.

The SurfaceToolboxLogic class is in charge of executing the filtering pipeline. It is a stateless class, its applyFilters method takes the state defined in SurfaceToolboxWidget's setup method as an argument and configures the processing pipeline accordingly.

The module internally uses the following VTK filters:

vtkDecimatePro

vtkSmoothPolyDataFilter

vtkWindowedSincPolyDataFilter

vtkPolyDataNormals

vtkCleanPolyData