RegionGrowing¶
- MLModule¶
genre
author
package
dll
definition
see also
keywords
segmentation,fill,3D,4D,thresholding
Purpose¶
The module RegionGrowing implements a fast threshold interval based 1D/2D/3D/4D region growing algorithm.
Usage¶
Specify a threshold interval and at least one seed point before starting.
Details¶
Starting with all seed points, the module segments all voxels that are
connected regarding the selected neighborhood relation (e.g., 3D-6 (x, y, z)), and
within the specified threshold interval [
Lower Threshold,Upper Threshold]
Tips¶
If you are using the
SoView2DMarkerEditorto generate the markers for the operation and plan to activate auto-update, you better activate “React on button release event only” in the SoView2DMarkerEditor-Panel in order to avoid that those release events get lost while the operator is checking the abort button.Although only 2D, 3D, and 4D growing is supported, you can technically perform a 2D, 3D, or 4D region growing on 5D-6D datasets. The operator uses the c- and u-coordinate of the volume it finds the markers in.
Be aware that the time used just to load the necessary input data can represent up to 90% of the total operation time. If you use input data with larger memory needs, you may notice that the segmentation of the same structure is significantly faster if it has a small extension in the z-dimension. This is due to the “per slice” nature of the algorithm. Because we load the entire slice into memory (which takes a little time) in the very moment we request a single voxel of it, the number of slices the structure intersects with is a significant factor of the total processing time.
See
Internal Accuracyon details about the module’s threshold accuracy and memory requirements.
Note that there is a macro wrapping this module: RegionGrowingMacro.
Windows¶
Default Panel¶
Input Fields¶
input0¶
- name: input0, type: Image¶
Input image.
inMarkerList¶
- name: inMarkerList, type: XMarkerList(MLBase), deprecated name: inputMarkersVol¶
Input marker list.
For accessing this object via scripting, see the Scripting Reference:
MLXMarkerListWrapper.
Output Fields¶
output0¶
- name: output0, type: Image¶
Segmentation result mask.
output1¶
- name: output1, type: Image¶
Masked input image.
Parameter Fields¶
Field Index¶
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Visible Fields¶
Module Status¶
- name: status, type: String, persistent: no¶
Shows information about the status of the module.
Abort¶
- name: abort, type: Trigger, deprecated name: stop¶
When pressed, the segmentation algorithm is stopped.
Update¶
- name: update, type: Trigger, deprecated name: go¶
When pressed, the module computes anew.
Clear¶
- name: clear, type: Trigger, deprecated name: flushMem¶
When pressed, the module invalidates its output images.
Update Mode¶
- name: autoUpdateMode, type: Enum, default: AutoClear¶
Defines the auto-update behavior of this module.
Values:
Title |
Name |
Deprecated Name |
Description |
|---|---|---|---|
Auto-Clear |
AutoClear |
AutoClearOnImageChange,Off |
Clears on input image change. |
Auto-Update |
AutoUpdate |
Updates on any input image or parameter change |
Lower Threshold¶
- name: lowerThreshold, type: Double, default: 0, deprecated name: Lower\_Threshold¶
Sets the lower threshold value.
Upper Threshold¶
- name: upperThreshold, type: Double, default: 600, deprecated name: Upper\_Threshold¶
Sets the upper threshold value.
Automatic (based on average seed value and threshold interval size)¶
- name: enableAutoThresholdInterval, type: Bool, default: FALSE, deprecated name: Auto\_Threshold,autoThreshold¶
If checked, an automatically generated threshold interval will be used instead of the manually set one. See
Threshold Interval Size [%]documentation on how this works.
Neighborhood Relation¶
- name: basicNeighborhoodType, type: Enum, default: BNBH_2D_4_XY, deprecated name: Basic\_Neighborhood\_Type¶
Defines the neighborhood relation that will be used during the growth process.
2D-neighborhood relations can also be used within 3D- and 4D-data, 3D-neighborhood relations can also be used in 4D-data.
By default, the growing will be performed in the x-y-plane, in other words, on a single slice.
If multiple seed points in multiple slices are selected, the growing will be performed on each of those slices (in that case be aware that the thresholds are global). However, it is possible to grow within the x-z or y-z-plane.
Values:
Title |
Name |
Deprecated Name |
Description |
|---|---|---|---|
2D-4-Neighborhood (x,y) |
BNBH_2D_4_XY |
2D-4-Neighborhood (x,y) |
Grows in 2D to four neighbors, i.e., from each point (X,Y,Z,T) to (X-1,Y,Z,T), (X+1,Y,Z,T) (X,Y-1,Z,T) and (X,Y+1,Z,T). |
3D-6-Neighborhood (x,y,z) |
BNBH_3D_6_XYZ |
3D-6-Neighborhood (x,y,z) |
Uses a 3D-6 Neighborhood, extending the 2D-4 neighborhood by looking at the direct neighbors in the Z-dimension (i.e., to (X,Y,Z-1,T), (X,Y,Z+1,T)). |
4D-8-Neighborhood (x,y,z,t) |
BNBH_4D_8_XYZT |
4D-8-Neighborhood (x,y,z,t) |
Uses a 4D-8 Neighborhood, extending the 3D-6 neighborhood by looking at the direct neighbors in the T-dimension (i.e., to (X,Y,Z,T-1), (X,Y,Z,T+1)). |
Extended Neighborhood Type¶
- name: extendedNeighborhoodType, type: Enum, default: ENBH_2D_4_XY, deprecated name: Extended\_Neighborhood\_Type¶
Defines the extended neighborhood type. The extended neighborhood allow:
to also look at diagonal neighbors (e.g., 2D-8 extends the 2D-4 neighborhood by all combinations of (x +/- 1, y +/- 1)),
to grow in 1D (e.g., 1D-2-Neighborhood (x) grows only in the x-dimension))
to grow in 2D or 3D, but selecting other fixed dimensions (e.g., 2D-4-Neighborhood (x,z) fixes the y-dimension instead of the z-dimension)
to exclude a certain growing direction (e.g., 3D-5-Neighborhood (x-, y, z) grows as 3D-6, but in the x-direction only to x-1 and not to x+1, whereas 3D-5-Neighborhood (x+, y, z) grows only to x+1)
Values:
Title |
Name |
Deprecated Name |
|---|---|---|
1D-2-Neighborhood (x) |
ENBH_1D_2_X |
1D-2-Neighborhood (x) |
1D-2-Neighborhood (y) |
ENBH_1D_2_Y |
1D-2-Neighborhood (y) |
1D-2-Neighborhood (z) |
ENBH_1D_2_Z |
1D-2-Neighborhood (z) |
2D-4-Neighborhood (x,y) |
ENBH_2D_4_XY |
2D-4-Neighborhood (x,y) |
2D-4-Neighborhood (x,z) |
ENBH_2D_4_XZ |
2D-4-Neighborhood (x,z) |
2D-4-Neighborhood (y,z) |
ENBH_2D_4_YZ |
2D-4-Neighborhood (y,z) |
2D-8-Neighborhood (x,y) |
ENBH_2D_8_XY |
2D-8-Neighborhood (x,y) |
2D-8-Neighborhood (x,z) |
ENBH_2D_8_XZ |
2D-8-Neighborhood (x,z) |
2D-8-Neighborhood (y,z) |
ENBH_2D_8_YZ |
2D-8-Neighborhood (y,z) |
3D-5-Neighborhood (x-,y,z) |
ENBH_3D_5_XmYZ |
3D-5-Neighborhood (x-,y,z) |
3D-5-Neighborhood (x+,y,z) |
ENBH_3D_5_XpYZ |
3D-5-Neighborhood (x+,y,z) |
3D-5-Neighborhood (x,y-,z) |
ENBH_3D_5_XYmZ |
3D-5-Neighborhood (x,y-,z) |
3D-5-Neighborhood (x,y+,z) |
ENBH_3D_5_XYpZ |
3D-5-Neighborhood (x,y+,z) |
3D-5-Neighborhood (x,y,z-) |
ENBH_3D_5_XYZm |
3D-5-Neighborhood (x,y,z-) |
3D-5-Neighborhood (x,y,z+) |
ENBH_3D_5_XYZp |
3D-5-Neighborhood (x,y,z+) |
3D-6-Neighborhood (x,y,z) |
ENBH_3D_6_XYZ |
3D-6-Neighborhood (x,y,z) |
3D-18-Neighborhood (x,y,z) |
ENBH_3D_18_XYZ |
3D-18-Neighborhood (x,y,z) |
3D-26-Neighborhood (x,y,z) |
ENBH_3D_26_XYZ |
3D-26-Neighborhood (x,y,z) |
4D-8-Neighborhood (x,y,z,t) |
ENBH_4D_8_XYZT |
4D-8-Neighborhood (x,y,z,t) |
4D-56-Neighborhood (x,y,z,t) |
ENBH_4D_56_XYZT |
4D-56-Neighborhood (x,y,z,t) |
4D-80-Neighborhood (x,y,z,t) |
ENBH_4D_80_XYZT |
4D-80-Neighborhood (x,y,z,t) |
Use additional seed point¶
- name: useAdditionalSeed, type: Bool, default: FALSE¶
If checked, an additional seed point can be specified on the module’s GUI.
Position¶
- name: additionalSeed, type: Vector6, default: 0 0 0 0 0 0¶
Sets the position of the additional seed point.
Type¶
- name: additionalSeedType, type: Integer, default: 0, minimum: 0¶
Sets the type of the additional seed point.
Interpretation¶
- name: additionalSeedCoordSystem, type: Enum, default: VoxelCoordinates¶
Defines how the position of the additional seed point is interpreted.
Values:
Title |
Name |
|---|---|
Voxel Coordinates |
VoxelCoordinates |
World Coordinates |
WorldCoordinates |
Incremental Updates¶
- name: incrementalUpdateMode, type: Enum, default: Smart¶
Defines the incremental update mode. Smart updates are most efficient, and there is usually no reason to switch away from it. See item help for details.
Values:
Title |
Name |
Description |
|---|---|---|
Disable |
Disable |
Do not allow incremental updates, compute from scratch every time. Should only be used when Smart updating turns out to be significantly slower. This might occur for some objects with a large surface-to-inner-voxels ratio. It is also the safest way to get consistent results, since the Smart mode requires correctly typed marker events to ensure consistency. |
Smart |
Smart |
The module tries to detect whether a parameter change allows an incremental update. The following situations provide consistent results using an incremental update:
All other (computation) parameter changes require complete recomputation. |
Force |
Force |
Force incremental updates every time, even if it is unsure whether the result will be consistent with the parameter. This mode can be useful if multiple objects corresponding to different threshold intervals in the same source images are to be segmented. Note that this might not work as expected when those objects are directly connected (with respect to the specified neighborhood relation). |
Use non-standard neighborhood relation¶
- name: useExtendedNBH, type: Bool, default: FALSE¶
If checked, the neighborhood relation is overwritten to be a non-standard one (might be slower!).
Calculate boundary overlap¶
- name: calcBoundaryOverlap, type: Bool, default: FALSE¶
If checked, the module computes 2D and 3D boundary overlaps over all slices in all time points (2D) or all time points (3D).
Max Boundary Overlap Percentage2D¶
- name: maxBoundaryOverlapPercentage2D, type: Double, persistent: no¶
Shows the maximum 2D boundary overlap of all slices in all time points.
Max Boundary Overlap Percentage3D¶
- name: maxBoundaryOverlapPercentage3D, type: Double, persistent: no, deprecated name: boundaryOverlapPercentage¶
Shows the maximum 3D boundary overlap of all time points.
Avg Boundary Overlap Percentage2D¶
- name: avgBoundaryOverlapPercentage2D, type: Double, persistent: no¶
Shows the 2D boundary overlap averaged over all slices and time points.
Avg Boundary Overlap Percentage3D¶
- name: avgBoundaryOverlapPercentage3D, type: Double, persistent: no¶
Shows the 3D boundary overlap averaged over all time points.
Specify Thresholds¶
- name: unitType, type: Enum, default: UnitTypeGrayValue¶
Defines the interpretation of the specified threshold values.
Values:
Title |
Name |
Deprecated Name |
|---|---|---|
as gray value |
UnitTypeGrayValue |
as gray value |
in Hounsfield units |
UnitTypeHounsfieldUnits |
in Hounsfield units |
Internal Accuracy¶
- name: internalAccuracy, type: Enum, default: Auto¶
Defines the threshold accuracy but also memory consumption. Using ‘Auto’ is the best choice most of the time.
Internally, the input image data is rescaled to an integer image on which the region growing is performed. This parameter can be used to specify the amount of bits that the module shall use to encode the image data.
This is the policy for the ‘Auto’ mode: 1. For integer input images, the smallest accuracy sufficient to capture the input image’s min/max range is used (e.g., [0, 63] → 6-bit, [0, 64] → 14-bit). 2. For float input images, it is not possible to automatically determine the required precision. Therefore, we use 30 bits for floats with 4 bytes (i.e., 32 bits) or less; otherwise, we use the maximum precision.
Thus, ‘Auto’ is usually best, but if you don’t need the accuracy and want to save memory (e.g., for floating-point images that only contain values of 0 and 1), it might be sometimes desirable to select a lower accuracy.
Values:
Title |
Name |
|---|---|
Auto-Detect |
Auto |
6 Bit |
6Bit |
14 Bit |
14Bit |
30 Bit |
30Bit |
60 Bit |
60Bit |
Auto-detect¶
- name: autoUpdateUnitType, type: Bool, default: FALSE¶
If checked, the unit type (value interpretation) is set automatically.
Unit Label¶
- name: unitLabel, type: String, persistent: no¶
Shows the unit of the values.
Number of Segmented Voxels¶
- name: numSegmentedVoxels, type: Integer, persistent: no, deprecated name: voxelCount¶
Shows the number of segmented voxels.
Volume of Segmented Area¶
- name: segmentedVolume_ml, type: Double, persistent: no, deprecated name: volumeCount¶
Shows the volume of segmented voxels in milliliters.
Overall Update Time¶
- name: growingTime, type: Double, persistent: no¶
Shows the time needed to compute the current result.
Number of Valid Seeds¶
- name: numValidSeeds, type: Integer, persistent: no, deprecated name: noSeeds¶
Shows the number of seed points.
Accepted Marker Type (All = -1)¶
- name: acceptedMarkerType, type: Integer, default: -1¶
Sets the integer value indicating the marker type that will be accepted as segmentation seeds.
This might be useful if you want to specify markers for different operations with a single marker list editor.
If -1 is used, all markers will be accepted.
Output is up to date¶
- name: outputValid, type: Bool, persistent: no¶
Shows whether the output is up-to-date.
Pos Fill Value¶
- name: posFillValue, type: Double, default: -1¶
Sets the positive gray value of the segmentation result.
If -1 is specified, the maximum gray value of the input image will be used.
/¶
- name: negFillValue, type: Double, default: 0¶
Sets the negative gray value of the segmentation result.
If -1 is specified, the minimum gray value of the input image will be used.
Invert result mask¶
- name: invertResult, type: Bool, default: FALSE¶
If checked, the segmentation result will be inverted.
That means that the object areas will be filled with the fill value for the non-segmented area and its environment will be filled with the fill value for the segmented area.
Furthermore, everything except the object will be put out on the second output (the object itself will be filled with the negative fill value).
Show outer object boundaries only¶
- name: showOuterBoundariesOnly, type: Bool, default: FALSE¶
If checked, only the outer object boundaries are shown.
Upper Volume Limit [ml]¶
- name: upperVolumeLimit_ml, type: Double, default: 100, deprecated name: maxVolume¶
Sets the upper volume limit in milliliters, applied if
Stop If Exceeded (NOTE: not exact)is enabled. SeeStop If Exceeded (NOTE: not exact)documentation for detailed information.
Stop If Exceeded (NOTE: not exact)¶
- name: enableUpperVolumeLimit, type: Bool, default: FALSE, deprecated name: maxVolumeEnabled¶
If checked, the region growing algorithm is stopped as soon as it is detected that the so far collected voxel volume exceeds the milliliter value set in
Upper Volume Limit [ml]. As the volume is only checked in certain intervals, the resulting volume will typically be somewhat larger than the exact limit.NOTE: The feature is only intended to prevent excessive processing time in the case of unwanted leakage. It cannot be reasonably used to prevent leakage, as the processing order of the voxels is basically unpredictable. Therefore, an exact restriction to the defined limit would not make sense from an algorithmic point of view, but only consume unnecessary processing time.
Threshold Interval Size [%]¶
- name: autoThresholdIntervalSizeInPercent, type: Double, default: 5, minimum: 0, maximum: 100, deprecated name: intervalSize¶
Sets a value for the automatic threshold generation.
The threshold generation is very simple and works as follows: The mean intensity value of all specified seed points will be computed. The upper/lower threshold is given as this mean value plus/minus the percentage specified in this field, multiplied with the maximum intensity value difference of the input image (maximum intensity value minus minimum intensity value).
Be aware that: 1. this procedure may lead to an empty segmentation result if multiple seed points with significantly varying intensity values were selected and the specified percentage is too low. 2. the threshold range depends on the seed point positions, the values at these position, and the input image’s image range (as detected from the properties, not the actual values!)