NormalizeImageByPercentileMapping

MacroModule

author	Grzegorz Chlebus
package	FMEstable/ReleaseMeVis
definition	NormalizeImageByPercentileMapping.def
keywords	image, histogram, rescale

Purpose

Normalize the input image on the range [Lower bound, Upper bound], mapping the intensities between the Lower percentile the Upper percentile percentiles of the image histogram. Optionally, clip the output image values. For the histogram computation, a background value can be specified or a mask can be passed to the module. Normalization can be performed on whole volume or on individual slices in specified dimension. When a mask is used, the intensity bounds are calculated on the entire mask, or on specified mask labels.

Usage

The NormalizeImageByPercentileMapping is designed to normalize an image based on specified percentile range values.

Ensure connecting the input image and optionally a mask to the module, set the parameters based on your problem and press Update to run the normalization.

Details

To use this module, connect the image to be normalized to the first input (inImage). If you want to normalize based on a region of interest (ROI), connect a mask defining the ROI to the second input (inMask). The mask will only be used if In Use Mask is set to True.

Set the lower and upper percentiles (Lower percentile and Upper percentile) and the range they should be mapped to (Lower bound and Upper bound). Note that values of the image outside [Lower percentile, Upper percentile] will be mapped outside the range of [Lower bound, Upper bound]. To restrict the image range to [Lower bound, Upper bound] range, set Clip to True. If you only want to normalize the upper bound of the image, set Use only upper percentile to True.

If a mask is used for normalization, by default all mask values greater than zero define the foreground of the image for computing the percentile values. If different mask values should be considered as foreground for computing the lower and upper bounds, select Use bounds from separate labels and set the corresponding labels in the fields Mask label for lower bound and Mask label for upper bound.

You can choose to normalize per entry in a given dimension, such as normalizing for each slice or time point, by setting Treat each slice along given dimension separately and selecting the dimension of interest (Dimension). It is also possible to compute the values for the given percentiles based only on the first slice in the given dimension (Dimension) by setting Normalize on first slice. Note that only one of Normalize on first slice and Treat each slice along given dimension separately can be set at a time.

When working with parts of the image for normalization, it is possible to have different static min and max values than the actual minimum and maximum values of the image. To ensure they match, set Force min/max update scan to True. The output image type is of type Float by default, however it can be changed if Force min/max update scan is selected and can be set using Output datatype.

Tips

It is also possible to reverse the values of the image, by setting Lower percentile to a larger value than Upper percentile; e.g. 98, 2, while keeping Lower bound and Upper bound in ascending order.

Windows

Default Panel

Input Fields

inImage

name: inImage, type: Image

Input Image

inMask

name: inMask, type: Image

Input Mask [Optional]

Output Fields

outImage

name: outImage, type: Image

Normalized input image

Parameter Fields

Field Index

[]: Trigger	In Use Mask: Bool	outUpperPercentileTo1: Double
Clear: Trigger	Lower bound: Double	Status Code: Enum
Clip: Bool	Lower percentile: Double	Status Message: String
Dimension: Enum	Mask label for lower bound: Integer	Treat each slice along given dimension separately: Bool
doNotClearOnFailedUpdate: Bool	Mask label for upper bound: Integer	Update: Trigger
Force min/max update scan: Bool	Normalize on first slice: Bool	Upper bound: Double
Has Valid Output: Bool	On Input Change Behavior: Enum	Upper percentile: Double
In Background Value: Double	outLowerPercentileTo0: Double	Use bounds from separate labels: Bool
In Use Background Value: Bool	Output datatype: Enum	Use only upper percentile: Bool

Visible Fields

Lower percentile

name: inP1, type: Double, default: 2

Lower percentile to be mapped to Lower bound

Upper percentile

name: inP2, type: Double, default: 98

Upper percentile to be mapped to Upper bound

Lower bound

name: inLowerBound, type: Double, default: 0, minimum: Clipping.imageMin, maximum: Clipping.imageMax, deprecated name: inA

Mapping target of Lower percentile.

Upper bound

name: inUpperBound, type: Double, default: 1, minimum: Clipping.imageMin, maximum: Clipping.imageMax, deprecated name: inB

Mapping target of Upper percentile.

Clip

name: inClip, type: Bool, default: FALSE

Clip values outside of [Lower bound, Upper bound] range.

Treat each slice along given dimension separately

name: inNormalizeSlicesSeparately, type: Bool, default: FALSE, deprecated name: inNormalizeTimepointsSeparately

If enabled, each slice along given dimension is analyzed and mapped separately.

Normalize on first slice

name: inNormalizeFirstSlice, type: Bool, default: FALSE

If enabled, the input image is normalize along the first slice of given dimension. e.g. in contrast enhanced MR-Images normalize along the first timepoint.

Dimension

name: inDimension, type: Enum, default: T

Select which image dimension slices shall be treated separately, if Treat each slice along given dimension separately or Normalize on first slice are selected.

Values:

Title	Name
X	X
Y	Y
Z	Z
C	C
T	T
U	U

In Use Background Value

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

If checked, each value that equals the background value will be ignored for the histogram computation.

In Background Value

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

Sets the data value to be ignored in the input image (if In Use Background Value is set).

In Use Mask

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

If checked, the optional second input image is used as a mask and only voxels within the mask will be considered during histogram calculation. Otherwise, the histogram is computed for the whole image.

Use bounds from separate labels

name: inUseMaskLabels, type: Bool, default: FALSE

If mask is used, default behaviour means all labels >0 are considered. If lower and upper normalization bounds shall come from different mask labels, check Use bounds from separate labels and define mask labels Mask label for lower bound and Mask label for upper bound.

Mask label for lower bound

name: inMaskLabelForLowerBound, type: Integer, default: 0, deprecated name: inLowerMaskLabel

If Use bounds from separate labels set, defines label of mask to be used to determine lower normalization bound.

Mask label for upper bound

name: inMaskLabelForUpperBound, type: Integer, default: 0, deprecated name: inUpperMaskLabel

If Use bounds from separate labels set, defines label of mask to be used to determine upper normalization bound.

Use only upper percentile

name: inUseOnlyP2, type: Bool, default: FALSE

The normalization function considers only the Upper percentile and Upper bound.

Output datatype

name: inOutputDatatype, type: Enum, default: Proposed Data Type

The output image type is of type Float by default, however it can be changed if Force min/max update scan is selected and can be set in Output datatype.

Values:

Title	Name
Proposed Data Type	Proposed Data Type
UInt8	UInt8
Int8	Int8
UInt16	UInt16
Int16	Int16
UInt32	UInt32
Int32	Int32
Float	Float
Double	Double
Int64	Int64
UInt64	UInt64

Force min/max update scan

name: inForceCalculatedMinMaxUpdate, type: Bool, default: FALSE

When normalizing based on different slices, instead of the whole image, it is possible to have different static minimum and maximum values than the actual minimum and maximum values of the image. To ensure they match, set Force min/max update scan to True, consequently, an extra scan over image is run and the static minimum and maximum values would be updated based on the real values.

Update

name: update, type: Trigger

Initiates update of all output field values.

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: shouldAutoUpdate,shouldUpdateAutomatically

Declares how the module should react if a value of an input field changes.

Values:

Title	Name	Deprecated Name
Update	Update	TRUE
Clear	Clear	FALSE

[]

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.

Hidden Fields

outLowerPercentileTo0

name: outLowerPercentileTo0, type: Double, persistent: no, deprecated name: lowerPercentileTo0

Shows the found quantile for Lower percentile th quantile

outUpperPercentileTo1

name: outUpperPercentileTo1, type: Double, persistent: no, deprecated name: upperPercentileTo1

Shows the found quantile for Upper percentile th quantile

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.