Purpose

The module CombineLabels is designed to simplify label image handling by allowing to add objects to an existing label image or combine them to create a new one.

Each object is typically represented by non-zero values in a mask image. This module allows to encode multiple mask images into certain bits within a new or given label image. In contrast to a mere OR operation with a bitmask, it supports the invertible encoding of all 2^n objects that can be represented by an n-bit label image, allowing their separate extraction, e.g. using the ExtractLabels module.

In addition, the full MergeRegions region modification functionality is available, so that the input image voxel boxes do not need to be identical.

Usage

Connect the label image (e.g. generated using the CombineLabels module) to inLabelImage and specify the object label bits to search for. In addition, you must define the bits of interest, i.e., those bits for which the object label must be equal to a label image voxel.

Consistently with the MergeRegions requirements, the input image voxel boxes are allowed to differ, but make sure that orientation, voxel size, and subvoxel translation are identical. The typical case of application is merging several segmentation masks extracted from the same original image given in their minimum bounding box.

Details

The formula applied to input voxels i0, i1, i2, i3 to compute an output label voxel v is:

v := OR(i0 ?AND(i0, NEG(bitsOfInterest)) : 0, AND(bisOfInterest, OR(ik ? (useWriteLabelk ? writeLabelk : ik) : 0)))

Algorithmically speaking:

  1. For each input mask for which useWriteLabel is TRUE, replace all non-zero values by the corresponding writeLabel.
  2. Compute a bitwise OR of all additional input images (inMask1, inMask2, …). Undefined regions are filled with 0.
  3. Erase all bits except for those set in Bits Of Interest.
  4. If a valid image is connected to inLabelImage, erase Bits Of Interest in inLabelImage before OR-ing the result to the result of step 3.

Windows

Default Panel

../../../Modules/Macros/Arithmetic/mhelp/Images/Screenshots/CombineLabels._default.png

Input Fields

inLabelImage

name: inLabelImage, type: Image

Input label image

inMask1

name: inMask1, type: Image

Mask/Label image to add #1

inMask2

name: inMask2, type: Image

Mask/Label image to add #2

inMask3

name: inMask3, type: Image

Mask/Label image to add #3

Output Fields

outLabelImage

name: outLabelImage, type: Image

Combined label image

Parameter Fields

Field Index

#: Integer Writelabel 2: Double
-> Outbox (in WC): String Writelabel 3: Double
Bits Of Interest: Double  
Merge Regions Mode: Enum  
Use (useWriteLabel1): Bool  
Use (useWriteLabel2): Bool  
Use (useWriteLabel3): Bool  
Writelabel 1: Double  

Visible Fields

Merge Regions Mode

name: mergeRegionsMode, type: Enum, default: UseUnion

Defines the mode in which the internal MergeRegions operates.

Values:

Title Name Deprecated Name
Region from input0 (deprecated, use UseInputRegion instead) UseRegion0_deprecated Use region from input0,UseRegion0
Region from input1 (deprecated, use UseInputRegion instead) UseRegion1_deprecated Use region from input1,UseRegion1
Region from input2 (deprecated, use UseInputRegion instead) UseRegion2_deprecated Use region from input2,UseRegion2
Region from input3 (deprecated, use UseInputRegion instead) UseRegion3_deprecated Use region from input3,UseRegion3
Input Region UseInputRegion  
Union of all regions UseUnion Use union of all regions
Intersection of all regions UseSection Use section of all regions
Custom region UseCustomRegion Use custom region

#

name: roiSourceIndex, type: Integer, default: 1, minimum: 0, maximum: 3

Sets the index for the ROI input.

-> Outbox (in WC)

name: outWorldBox, type: String, default: 0 0 0 0 0 0 -1 -1 -1 -1 -1 -1

Sets, the output Box (in world coordinates of voxel centers).

Bits Of Interest

name: bitsOfInterest, type: Double, default: 128

Sets the input label image that will only be modified at positions set in this bitmask.

Writelabel 1

name: writeLabel1, type: Double, default: 15

Sets a label to write for inMask1 hits.

Writelabel 2

name: writeLabel2, type: Double, default: 0

Sets a label to write for inMask2 hits.

Writelabel 3

name: writeLabel3, type: Double, default: 0

Sets a label to write for inMask3 hits.

Use (useWriteLabel1)

name: useWriteLabel1, type: Bool, default: FALSE

If disabled, AND(inMask1, bitsOfInterest) is directly used for output image computation.

Use (useWriteLabel2)

name: useWriteLabel2, type: Bool, default: FALSE

If disabled, AND(inMask2, bitsOfInterest) is directly used for output image computation.

Use (useWriteLabel3)

name: useWriteLabel3, type: Bool, default: FALSE

If disabled, AND(inMask3, bitsOfInterest) is directly used for output image computation.