CSOGenerateSmoothSurfaceFromSparseContours

MLModule
genre CSOModule
author MeVis Medical Solutions AG
package MeVisLab/Standard
dll MLCSOModules
definition MLCSOModules.def
see also CSOVoxelizeContours
keywords contour, spline, surface, interpolation, approximation, voxelize, rasterize

Purpose

The module CSOGenerateSmoothSurfaceFromSparseContours converts any number of CSOs to a mask image.

The CSOs can lie in parallel, orthogonal, or in any angle to each other. One CSO is sufficient, though.

Note that only closed CSOs are considered in the algorithm!

All existing CSOs are interpolated by computing a 3D implicit function that describes a surface, and this surface is scanned using a recursive marching-cubes algorithm. The resulting surface is rasterized to the output image and can also be filled. Additionally, the output mask can be rasterized with anti-aliasing.

Usage

Connect a CSOList and an image to the module, adjust the parameters and press Update.

Details

Internally, an algorithm is used which is described in the paper Shape Transformation Using Variational Implicit Functions by Greg Turk and James F. O’Brian. This algorithm constructs a 3D thin-plate spline function on behalf of the path points of the contours with the condition that the path points lie on the resulting surface. The resulting implicit distance function computes to 0 at these positions, and at points along the inward normal it computes to a set value other than 0 (-1 in this case).

This means that the accuracy of the module depends on the number of path points, but since the number of path points also reigns the number of parameters of the constructed implicit function, the speed of the module also depends on the number of path points.

With the implicit function constructed, a recursive marching-cube algorithm scans the surface. This algorithm is designed in a way that all unconnected surfaces are scanned. The resulting cells that were used for scanning the surface are sorted along the z-axis with a bucket sort for a fast slice-wise access. If the resulting mask image should be filled, a scan line algorithm is applied on the computed surface cells of each current slice. Note that surfaces can be clipped by the image’s extend. The filling algorithm can fill such clipped surfaces nevertheless.

If a filled mask should be generated, the surface voxels of the mask can be anti-aliased. In this case, an interpolated value between the background and the foreground value is computed on the base of how the surface really cuts the according cell of the marching cube algorithm. Note that using anti-aliasing is not recommended if the surface is not filled.

A more detailed description of the algorithm can be found in the paper Interactive 3D Medical Image Segmentation with Energy-Minimizing Implicit Functions by Heckel et al.

Tips

If the computation takes too long with a certain set of CSOs, try to convert the CSOs with the option Use only first CSO for start scanning checked.

If the CSOs are too dense, the resulting surface function may oscillate, leading to a very wrong surface and often multiple scans of this wrong surface. If the target image is large enough, this can even lead to a crash of MeVisLab. Consider this option a testing or debugging option, or check it if you are sure that only one connected mask results from the set of input CSOs (for a speed up because certain tests are omitted then).

Also, with very large CSOs, try to use only the seed points. Note, however, that the results may vary heavily if the CSOs are generated by a spline approximation where the seed points do not lie on the path of the approximated path points.

If the CSOs that are to be converted are generated by the CSOLiveWireProcessor or by the CSOIsoGenerator or CSOIsoProcessor without using any smoothing, the resulting spline surface may oscillate (forming ‘bubbles’). This is due to steep angles in the CSOs which causes the spline interpolation surface to take ‘detours’ to fit the path points that are left over after an internal point reduction process which is necessary to keep the total amount of considered points low (or otherwise the used matrix inversion fails due to a too large memory consumption).

In order to produce an acceptable result, try checking the option Use smoothing for path points which converts the path points (which may contain said steep angles) into a spline approximation which is generally much smoother and thus less prone to oscillation. That option may always be turned on, because the resulting surface does not differ much from a surface obtained from not-smoothed path points in case of the CSOs being smooth anyway. The resulting surface with using the internal spline approximation is just a little bit smaller than a surface without using that option.

Windows

Default Panel

../../../Modules/ML/MLCSOModules/mhelp/Images/Screenshots/CSOGenerateSmoothSurfaceFromSparseContours._default.png

Input Fields

input0

name: input0, type: Image

Input reference image. Can also be copied to the output.

inCSOList

name: inCSOList, type: CSOList(MLBase)

The CSOList that should be converted into a 3D mask.

For accessing this object via scripting see the Scripting Reference: MLCSOListWrapper.

Output Fields

output0

name: output0, type: Image

A mask image.

Parameter Fields

Visible Fields

Mode

name: updateMode, type: Enum, default: AutoClear

Defines how the module reacts to input changes.

Values:

Title Name Description
Off Off The module does not react to input changes.
Auto Update AutoUpdate The module computes anew if any input changes or if a valid notification is triggered.
Auto Clear AutoClear  

Auto apply

name: autoApply, type: Bool, default: FALSE

If checked, the module computes anew on a change of any field on the GUI.

Update

name: apply, type: Trigger

If pressed, the module computes anew.

Foreground

name: foregroundValue, type: Float, default: 4095

Sets the target object value if the CSOs are all set to use the module’s voxel write value (the default).

Background

name: backgroundValue, type: Float, default: 0

Sets the target background value if the input image should not be copied (Use image values).

Use image values

name: useImageValues, type: Bool, default: FALSE

If checked, the image’s values are written into the output image instead of the foreground values.

Fill

name: fillSurface, type: Bool, default: TRUE

If checked, the resulting surface is filled with the object values.

Copy input image

name: copyInputImage, type: Bool, default: FALSE

If checked, the background is filled with the input image’s values and the target object values are replacing those values.

Repaint

name: listenInteractionNotifications, type: Bool, default: FALSE

If checked, and the Mode is set to Auto Update, the module computes anew on repaint notifications.

Finishing

name: listenInteractionFinished, type: Bool, default: TRUE

If checked, and the Mode is set to Auto Update, the module computes anew on interaction finished notifications.

Margin

name: boundingBoxMargin, type: Integer, persistent: no

Sets an augmentation value for the voxel bounding box.

Start (startVoxelBoundingBox)

name: startVoxelBoundingBox, type: Vector3, persistent: no

Shows the upper front left corner position of the voxel bounding box.

End (endVoxelBoundingBox)

name: endVoxelBoundingBox, type: Vector3, persistent: no

Shows the lower rear right corner position of the voxel bounding box.

Start (startWorldBoundingBox)

name: startWorldBoundingBox, type: Vector3, persistent: no

Shows the upper front left corner of the bounding box in world coordinates.

End (endWorldBoundingBox)

name: endWorldBoundingBox, type: Vector3, persistent: no

Shows the lower rear right corner of the bounding box in world coordinates.

String

name: voxelBoundingBoxString, type: String, persistent: no

Shows the voxel bounding boxes start and end position as a string consisting of six 3D coordinates separated by a space.

Use Always Foreground Value Of Module

name: useAlwaysForegroundValueOfModule, type: Bool, default: FALSE

If checked, the voxel write mode of the CSO or CSOGroup are ignored and the foreground value of the module is used in any case.

Clear

name: clear, type: Trigger

If pressed, the output image is cleared.

Use anti aliasing

name: useAntiAliasing, type: Bool, default: TRUE

If checked, the target surface values are by using a linear interpolation scheme between the object and the background value.

Note that results may appear unsatisfying if this option is used with non-filled objects.

Quality

name: quality, type: Float, default: 0.5, minimum: 0, maximum: 1

Sets the quality and speed of the conversion. This value defines the portion of contour points used for computation. Thus, a low value means a low quality but a higher speed.

Use only first CSO for start scanning

name: useOnlyFirstCSOForStartScanning, type: Bool, default: FALSE

If checked, only the first CSO is used for start the scanning of the surface with the recursive marching cube algorithm.

Use only seed points

name: useOnlySeedPoints, type: Bool, default: FALSE

If checked, only the seed points are used to build the implicit function, otherwise the path points are used.

Resolve embedded CSOs

name: resolveEmbeddedCSOs, type: Bool, default: TRUE

If checked, the module determines the level of embedding of CSOs and treats inner CSOs by inverting their normals.

By checking this option, inner CSOs can lead to holes in the mask in simple cases. Since the mask is in 3D, not all levels of embedding can be resolved to full satisfaction.

Use smoothing for path points

name: useSplineApproximationSmoothing, type: Bool, default: FALSE

If checked, the path points are internally smoothed by converting them into a spline approximation. This parameter does not change the result if the module works on seed points only.

Additional point location

name: additionalPointLocation, type: Enum, default: Auto

Defines how the algorithm computes additional points (i.e., normals) for establishing the spline function.

Values:

Title Name Description
Inner Inner Additional points are generated inside the contours.
Outer Outer Additional points are generated outside the contours.
Auto Auto The side on which additional points are generated is automatically computed. Using this option is slower but can cope with self-intersecting contours.

Resolve intersections

name: resolveIntersections, type: Bool, default: TRUE

If checked, additional tests are performed for detecting self-intersections and the module resolves those issues automatically.

Strength (surface)

name: regularizationStrength, type: Float, default: 0, minimum: 0, maximum: 100

Sets the strength for regularization of contour points. The larger this value, the more the contour points are approximated instead of interpolated. Setting this parameter to a value >0 also increases the robustness of the algorithm.

Strength (normals)

name: regularizationStrength2, type: Float, default: 0, minimum: 0, maximum: 100

Sets the strength for regularization of normals. The larger this value, the more the normal of the surface in each contour point is approximated instead of interpolated. Setting this parameter to a value >0 also increases the robustness of the algorithm.

Inner Point Scale

name: innerPointScale, type: Float, default: 0.25, minimum: 0, maximum: 1

Sets a scale factor for the distance of additional point to the original points. This additional point represents the normal in the original point. If the contours are very narrow and the result yields errors, try a smaller value here. However, a too small value degenerates the result as well.

Maximum Number of Points

name: maxNumPoints, type: Integer, default: 10000, minimum: 0

Sets a limit to the number of points used for establishing the spline function.

The more points, the longer the module computes but the result is generally more precise.

Number of Threads

name: numThreads, type: Integer, default: 4, minimum: 1

Sets the number of threads for parallel computing. Currently only some parts of the algorithm are parallelized. Typically it does not make sense to set this value larger than 4.

Code Path

name: codePath, type: Enum, default: SSE3

Sets the code path used for evaluation of the implicit function. This mainly affects the voxelization step.

Values:

Title Name Description
Fpu FPU Uses the FPU for computation.
Sse3 SSE3 Uses the SSE3 instruction set for parallel computation (supported on all modern 64-Bit CPUs (particularly, since AMD Athlon 64 and Intel Pentium 4 Prescott).

Use logging

name: logging, type: Bool, default: FALSE

If checked, some internal states are written to the console.

Hidden Fields

isProcessing

name: isProcessing, type: Bool, persistent: no

done

name: done, type: Trigger, persistent: no

supportOpenCSOs

name: supportOpenCSOs, type: Bool, default: FALSE