Module: Generate Surface ()

Description:

This module computes a triangular approximation of the interfaces between different regions or materials in a Label Field with either uniform or stacked coordinates. The resulting surfaces can be non-manifold surfaces, i.e., can contain edges belonging to more than two materials.

Depending on the dimensions of the input Label Image the resulting triangular surface may have a very large number of triangles. Therefore, it is often recommended to downsample the Label Image prior to using Generate Surface.

During resampling module Resample will create or update the probability information of the Label Image that Generate Surface can use to generate smoother surfaces. In this way, the loss of information caused by the resampling process will be partly compensated for.

Press the Apply button to start the surface computation.

References:

Connections:

Data [required]
Label Image from which the surface should be computed.

Ports:

Options

Compactify: If checked, a specialized post-processing edge-contraction technique is used to reduce the number of triangles in the resulting surface.

Minimum edge length: A non-zero value indicates that short edges of the final surface will be contracted in order to improve triangle quality as well as to decrease the number of triangles. The value entered into this text field indicates the minimal allowed edge length relative to the size of a unit grid cell. By default, values between 0 and 0.8 can be entered. Typically, a value of 0.4 already yields good results. However, note that intersections may be introduced during edge contraction. If you want to avoid this try to use the Simplification Editor. The editor applies some special strategies in order to ensure topological consistency.

Algorithm Mode [advanced]

This port selects if the surface generation uses multiple threads or not.
repetable: 1 thread is used. The result will always be the same on any computer.
fast: A maximum number of threads will be used. This can yield different outputs on different machines.

Border

Border

This option (default on) ensures that the resulting surfaces will be closed, even if some regions intersect the boundary of the Label Field. Closed surfaces are mandatory for subsequent tetrahedral grid generation. If unchecked, the surface will remain open where boundary voxels are assigned to a foreground material.

Settings

This port will only be visible, if Add Border has been selected.

If the option Adjust Coords is selected, points belonging to triangles adjacent to boundary voxels will be moved exactly onto the nearest boundary face of the bounding box. In this way the resulting surface appears to be sharply cut off at the boundaries. Adjust Coords is automatically selected, if Fit To Edges is checked (see below).

If option Extra Material is checked, an additional, pseudo material will be created outside the input lattice and named Exterior2. This is useful when using Surface View to select only those triangles lying on the boundary face of the bounding box.

If the option Create All Patches is unchecked (default), the label with value 0 (usually material Exterior, but can have other names) will be considered the exterior or background region. The surface between the background and the volume boundary is typically not of interest so that no triangle patches will be created with Exterior2 as outside and the background material as inside region. If the option Create All Patches is checked, the triangles for all patches, including those of patch <Background>/Exterior2 will be created. As a consequence, displaying the surface with module Surface View will show a closed box of the entire volume. This option is useful, for example, if the exterior region of the input label field is to be considered during finite element (FE) simulation because only then module Generate Tetra Grid will also create tetrahedrons for the background material.

If option Fit To Edges is selected, vertices close to the bounding box edge will be moved exactly into the edge so that the resulting surface exactly fits to the edges of the bounding box. This option is available only, if the Smoothing is set to None or Constrained Smoothing. Also, the option is available only, if the Adjust Coords is selected. Therefore, turning off Adjust Coords, turns off Fit To Edges automatically.

Smoothing

Smoothing

This port controls the way the module generates a smooth surface. Smoothing is necessary because the input Label Image consists of cuboid elements, voxels, that without correction would produce staircase-like surfaces.

can use a modified Gaussian filter on the Label Image to smooth the region boundaries and therefore slightly changes the labeling. In addition, Weights are computed denoting a voxel's probability of belonging to a particular region. The probability is 1 for voxels in the interior of a region and decreases towards the region boundary. Voxels near region boundaries are also assigned probabilities with respect to neighboring regions. This probability information is used during triangulation to make region boundaries appear smoother.

If set to None, no smoothing is performed and also no pre-computed sub-voxel weights are used. The resulting surface will show typical staircase-like artifacts.

If set to Existing Weights, pre-computed weights are used foe smoothing. Such weights are generated by modules Resample and Multi-Thresholding, or by the label smoothing filter of the Image Segmentation Editor. This option is displayed only if pre-computed weights are available.

The options Constrained Smoothing and Unconstrained Smoothing perform a label smoothing on-the-fly without modifying the input labels. Sub-voxel weights are then created as with the Segmentation Editor's label smoothing filter and used to create a smooth surface.

With Constrained Smoothing, the module ensures that thin regions will not vanish. It guarantees that any two voxel centers that have been labeled differently before the smoothing are separated by the generated surface afterwards. The extent of smoothing can be controlled with port Smoothing Extent.

Smoothing Extent

This port is only displayed if port Smoothing Type is set to Constrained Smoothing or Unconstrained Smoothing. It controls the size of the filter kernel and thus the extent of smoothing applied to the surface. The default is 5, cannot be larger than 9 and is a float variable. The larger this value, the smoother the surface will be, but also the more fine detail will be lost.

Figure 1: Left: smoothing extent set to 1. Right: smoothing extent set to 9.

Smooth Material

On default, the value of this port is None. If you change it to the name of a material, a smooth surface will be generated for the selected material. Otherwise, the surfaces of all materials will show some 'ridges' at contours incident on 3 or more materials.

Commands:

setInteractive
When the surface to generate is large, there is a warning to cancel the computation. To disable this warning, call this command with 0.

removeMaterialsIds
This command must be applied to the input label field (not to Generate Surface) like this: input_data removeMaterialsIds

Since Generate Surface internally reorganizes the input label field materials using their id (from bundle parameters). Materials without id in the input label field are appended to the rest of materials with a new id. This can cause some compatibility issues with projects saved with previous versions of . Use the command to restore the previous behavior where materials were considered in their storage order parameters, regardless of their id.