ConnectedComponentsMacro

MacroModule

genre	Region
author	Volker Dicken
package	FMEstable/ReleaseMeVis
definition	ConnectedComponentsMacro.def
see also	ConnectedComponents, ComputeConnectedComponents, FilterConnectedComponents, ConnectedComponentsInfo, ConnectedComponentsToImage, RegionGrowing
keywords	ComputeConnectedComponents, FilterConnectedComponents, ConnectedComponentsInfo, ConnectedComponentsToImage

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

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

Field Index

,: Double	doNotClearOnFailedUpdate: Bool	Remaining Clusters Bounding Box: String
[: Double	Foreground (=Cluster) Value: Double	Similarity Dot-Product: Double
[]: Trigger	Has Valid Output: Bool	Similarity Tolerance: Double
<b>Remaining Clusters (after Selection && Filtering):</b>: Integer	In Background Value: Double	Status Code: Enum
]: Enum	Invert filtering result: Bool	Status Message: String
Background Value: Double	logLevel: Enum	Total Number of Clusters: Integer
Clear: Trigger	Neighborhood Relation Used: Enum	Update: Trigger
Cluster Mode: Enum	On Input Change Behavior: Enum	Use background value: Bool
Cluster User Data Default: Enum	Output Image Values: Enum	Use input mask image: Bool
Crop Output Image to Bounding Box of Selected Clusters: Bool	Output Selection: Enum

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