Purpose

The module ConnectedComponentsMacro performs a connected component analysis on 2D / 3D gray scale or vector images.

It comprises most of the functionality of the deprecated/removed ConnectedComponents module.

Usage

Connect an input image, select a Neighborhood Relation Used and press Update.

Depending on your parameterization, the output image now contains for example

  1. a label image where all interconnected non-background voxels are labeled with the same image value (Output Selection = “All Filtered”, Output Image Values = “Rank”)
  2. a mask of selected clusters only (Output Selection = “Selected By Coordinates”), where the selection comes from the markers in inMarkerList
  3. a mask of the largest cluster only (default, Output Selection = “Largest”, Output Image Values = “FixedValue”)
  4. an image where all clusters have the integer or float value stating their volume (Output Selection = “All Filtered”, Output Image Values = “VolumeInMilliliters”)

Details

When to use this module as a replacement for the deprecated/removed ``ConnectedComponents`` module

Use it if your package allows it and if you do not use more than one of the outputs of the old ConnectedComponents modules. Otherwise, it is better to reimplement the functionality using a custom combination of ComputeConnectedComponents, FilterConnectedComponents and ConnectedComponentsToImage modules.

Depending on your deployment, you may have access to the module ConnectedComponentsPortingHelper which can help in the transition. However, in cases where you are sure what the original module did, a manual replacement is even easier.

Windows

Default Panel

../../../Projects/ConnectedComponentsMacro/Modules/mhelp/Images/Screenshots/ConnectedComponentsMacro._default.png

Input Fields

inImage

name: inImage, type: Image, deprecated name: input0

Image to be processed. A grayscale or vector image where connected components shall be identified.

inMask

name: inMask, type: Image, deprecated name: input1

Optional input mask to restrict computations, only used if Use input mask image is TRUE: A mask image that defines which voxels in inImage are processed. Mask value 0 means the corresponding voxels in inImage are ignored. The mask image must have same dimension as the inImage image.

inMarkerList

name: inMarkerList, type: XMarkerList(MLBase)

(Optional) marker list, used for component (de)selection if Output Selection is set to ‘SelectedByCoordinates’. If left open or empty, this is interpreted as an empty marker list, no cluster is selected (unless Invert filtering result is TRUE).

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

Output Fields

outImage

name: outImage, type: Image, deprecated name: output2,outputImage

Output image, result of the connected component analysis result after applying the OUTPUT FILTERING and converting into an ML image according to the OUTPUT VALUES parameters.

outClusters

name: outClusters, type: SelectedClusters(MLBase)

This output allows to perform additional operations on the UNFILTERED connected components structure. It also allows to reproduce additional outputs of the old module. Use FilterConnectedComponents jointly with ConnectedComponentsToImage with suitable parameterizations and maybe a ConnectedComponentsInfo for that.

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

outSelectedClusters

name: outSelectedClusters, type: SelectedClusters(MLBase)

This output allows to perform additional operations on the FILTERED connected components structure. Use ConnectedComponentsToImage with suitable parameterizations or a ConnectedComponentsInfo for that.

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

Parameter Fields

Visible Fields

Update

name: update, type: Trigger

If pressed, the analysis is performed and the output images are updated.

Clear

name: clear, type: Trigger

Clears all output field values to a clean initial state.

On Input Change Behavior

name: onInputChangeBehavior, type: Enum, default: Clear, deprecated name: autoUpdate,shouldAutoUpdate,shouldUpdateAutomatically,updateMode

Defines the behavior if any of the input images or the CLUSTER ANALYSIS settings changes.

Values:

Title Name Deprecated Name Description
Clear Clear AutoClear,FALSE Clears the output automatically
Update Update AutoUpdate,TRUE Updates the output automatically

[]

name: updateDone, type: Trigger, persistent: no

Notifies that an update was performed (Check status interface fields to identify success or failure).

Has Valid Output

name: hasValidOutput, type: Bool, persistent: no

Indicates validity of output field values (success of computation).

Status Code

name: statusCode, type: Enum, persistent: no

Reflects module’s status (successful or failed computations) as one of some predefined enumeration values.

Values:

Title Name
Ok Ok
Invalid input object Invalid input object
Invalid input parameter Invalid input parameter
Internal error Internal error

Status Message

name: statusMessage, type: String, persistent: no

Gives additional, detailed information about status code as human-readable message.

Neighborhood Relation Used

name: inNeighborhoodType, type: Enum, default: NBH_3D_18_XYZ, deprecated name: neighborhoodRelation,neighborhoodType

Defines the connectedness neighborhood relation for the analysis.

Values:

Title Name Deprecated Name
2D-4-Neighborhood (x,y) NBH_2D_4_XY 2D-4-Neighborhood (x,y)
2D-8-Neighborhood (x,y) NBH_2D_8_XY 2D-8-Neighborhood (x,y)
3D-6-Neighborhood (x,y,z) NBH_3D_6_XYZ 3D-6-Neighborhood (x,y,z)
3D-18-Neighborhood (x,y,z) NBH_3D_18_XYZ 3D-18-Neighborhood (x,y,z)
3D-26-Neighborhood (x,y,z) NBH_3D_26_XYZ 3D-26-Neighborhood (x,y,z)

Use background value

name: inUseBackgroundValue, type: Bool, default: TRUE, deprecated name: useBackgroundValue

If checked, the background value is ignored, all voxels are subject to clustering.

In Background Value

name: inBackgroundValue, type: Double, default: 0, deprecated name: backgroundValue,inputIgnoreValue

Sets the voxel value to be ignored. The background value function is not used in vector mode.

Cluster Mode

name: inClusterMode, type: Enum, default: IdenticalIntensities, deprecated name: clusterMode

Defines the cluster rule.

Values:

Title Name Description
Identical Intensities IdenticalIntensities The intensities or vector directions of adjacent voxels need to be identical to form a cluster.
Similar Intensities SimilarIntensities

The intensities of adjacent voxels need to be similar to form a cluster.

Set the similarity tolerance with Similarity Tolerance.
Similar Vector Directions SimilarVectorDirections

The vector directions of adjacent voxels need to be similar to form a cluster.

Set the similarity tolerance with Similarity Dot-Product. This is the threshold for the dot-product of vectors in adjacent voxels.

Similarity Tolerance

name: inSimilarityToleranceIntensities, type: Double, default: 0, deprecated name: similarityToleranceIntensities

Sets the tolerance for the Cluster Mode Similar Intensities.

Similarity Dot-Product

name: inSimilarityToleranceVectors, type: Double, default: 0.98, deprecated name: similarityToleranceVectors

Sets the tolerance for the Cluster Mode Similar Vector Directions.

Hint: Apply it to normalized vectors.

Use input mask image

name: inUseMask, type: Bool, default: FALSE, deprecated name: useMask

Check to make use of the mask image.

Output Selection

name: inSelectionMode, type: Enum, default: Largest, deprecated name: selectionMode

This enum field in new in the macro ConnectedComponentsMacro it replaces the somewhat inconsistent collection of bool flags and choice of outputs in the deprecated ConnectedComponents.

Values:

Title Name Description
All Filtered AllFiltered Outputs all clusters after filtering (via the cluster size range and the Invert filtering result flag).
Selected By Coordinates SelectedByCoordinates Outputs all clusters selected by markers in inMarkerList and remaining after filtering (via the cluster size range and the Invert filtering result flag).
Largest Largest Outputs only the largest cluster (if it survives filtering via the cluster size range and the Invert filtering result flag).
Largest On Slice LargestOnSlice Outputs only the largest cluster on each 2D slice (if it survives filtering via the cluster size range and the Invert filtering result flag). Only works if a 2D neighborhood was selected for Neighborhood Relation Used.

Invert filtering result

name: inShouldInvertSelection, type: Bool, default: FALSE, deprecated name: invertClusterSelection,invertLargestCluster,shouldInvertSelection

Inverts the selection/filtering. Use to e.g. get all but the largest clusters.

[

name: inMinClusterSize, type: Double, default: 0, minimum: 0, deprecated name: minClusterSize

Sets the lower volume or voxel count limit to filter the output clusters by size (see ] for units).

,

name: inMaxClusterSize, type: Double, default: -1, minimum: -1, deprecated name: maxClusterSize

Sets the upper volume or voxel count limit to filter the output clusters by size (see ] for units). A negative value means no upper limit.

]

name: inClusterSizeInterpretation, type: Enum, default: ml, deprecated name: clusterSizeInterpretation

Defines the unit for [ and ,.

Values:

Title Name Description
Voxels Voxels Number of Voxels
ml ml Milliliters

Output Image Values

name: inWriteToImageMode, type: Enum, default: Rank, deprecated name: writeToImageMode

This enum field is new in the macro ConnectedComponentsMacro along with Output Selection if is used to restrict the number of outputs to one in common applications of ConnectedComponents.

Values:

Title Name Description
Cluster Rank Rank The rank of each cluster, i. e. 1 for the largest, N for the Nth largest cluster.
Cluster Voxel Count NumVoxels Each cluster voxel holds the number of voxels in the entire cluster
Cluster Volume [ml] VolumeInMilliliters Each cluster voxel holds the volume in milliliters of the entire cluster
Fixed Values FixedValues The values specified by Foreground (=Cluster) Value and Background Value are used.
User Data UserData  

Foreground (=Cluster) Value

name: inFixedOutputForegroundValue, type: Double, default: 1, deprecated name: clusterValue,objectValue

Sets the value of the selected components if Output Image Values is FixedValues.

Background Value

name: inFixedOutputBackgroundValue, type: Double, default: 0, deprecated name: fillValue,outputBackgroundValue

Sets the value of all voxels not in the selected components.

Crop Output Image to Bounding Box of Selected Clusters

name: inUseBoundingBoxOfSelectedClusters, type: Bool, default: FALSE, deprecated name: inApplyBoundingBox

Automatically shrink output size to the bounding box of the selected clusters

Cluster User Data Default

name: inUserDataDefault, type: Enum, default: ImageValue

This decides how the default user data of a cluster is set. See the documentation of ComputeConnectedComponents for details.

Values:

Title Name Description
Image Value ImageValue Image value of the cluster (only available for Cluster Mode Identical Intensities).
Volume In Ml VolumeInMl Cluster size in milliliters.

<b>Remaining Clusters (after Selection && Filtering):</b>

name: outNumRemainingClusters, type: Integer, persistent: no, deprecated name: numberOfClusters,numSelectedClusters

Shows the number of components AFTER filtering

Total Number of Clusters

name: outNumTotalClusters, type: Integer, persistent: no

Shows the number of components BEFORE filtering

Remaining Clusters Bounding Box

name: outSelectedClustersBoundingBox, type: String, persistent: no

BoundingBox of the union of all selected clusters. Hint: Individual clusters bounding box can be inspected using ConnectedComponentsInfo

Hidden Fields

doNotClearOnFailedUpdate

name: doNotClearOnFailedUpdate, type: Bool, persistent: no

Prevents automated clear after update failed. This does not affect status fields. It enables the developer to analyze module’s state after failure.

logLevel

name: logLevel, type: Enum, default: WARNING, deprecated name: enableLogging

Set console logging level.

Values:

Title Name Deprecated Name
Debug DEBUG  
Info INFO TRUE
Warning WARNING FALSE
Error ERROR  
Critical CRITICAL