Purpose

The module Histogram computes the histogram of image values found in the input image.

A second image can optionally be used as a mask image.

Usage

The histogram of a input image is generated which can be displayed by the SoDiagram2D module.

Details

If the mask image is used, each input image value is weighted with the corresponding mask image value, after transforming mask image values such that the mask image’s data range is mapped to the interval [0, 1].

Consequently, voxels where the mask image value equals the mask image’s minimum data value are ignored.

Special floating point values (NaN or infinite values) in floating point images will be ignored, too.

Windows

Default Panel

../../../Modules/ML/MLVolumetry/mhelp/Images/Screenshots/Histogram._default.png

Input Fields

input0

name: input0, type: Image

Input Image

input1

name: input1, type: Image

Mask Image

Output Fields

outputHistogram

name: outputHistogram, type: HistogramObject/HistogramObjectList(MLBase)

A Histogram object, used in HistogramVolumetrySimple.

outputHistogramCurve

name: outputHistogramCurve, type: CurveData/CurveDataBaseList(MLBase)

CurveData object, used in SoDiagram2D.

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

Parameter Fields

Field Index

Background Value: Double Status: String Use Zero As Bin Center: Bool
Bin Size: Double Style: Integer X-Range: Enum
Clear: Trigger Type: Enum  
containing: Enum Update: Trigger  
Curve Title: String Update Mode: Enum  
maxBinCount: Integer Use Background Value: Bool  
progress: Double Use mask: Bool  
Results Valid: Bool Use Step Function: Bool  

Visible Fields

Use mask

name: useMask, type: Bool, default: TRUE

If checked, the optional second input image is used as a mask.

Otherwise, or if the second input image is unconnected, the histogram is computed for the whole image.

X-Range

name: xRange, type: Enum, default: Image Min/Max

Defines the X-range or image value range of the histogram.

Values:

Title Name Deprecated Name Description
Image Min/Max Image Min/Max Static Min/Max The static min/max values stored in the image are used.
Dynamic Min/Max Dynamic Min/Max   The histogram is dynamically resized to fit all actual values found in the input image. Caution: With excessively large floating point values, this approach leads to problems (slowness, even crashes) due to too large memory allocations.

containing

name: maskMode, type: Enum, default: Weights

Defines the mode for the used mask values.

Values:

Title Name Description
Weights Weights The mask is interpreted as described in the Details section.
Labels Labels

The mask image contains several distinct integer values (“labels”), each one identifying an object for which a separate histogram is computed.

Each non-empty histogram is appended to a Histogram List which is put out at output0. The id of the new list item will be set to the corresponding label in the mask. To retrieve a specific histogram from the list, the module DecomposeBaseList can be used. The same goes for the Curve List.

Another alternative for extracting an object from the list is the module ExtractObjectFromList. For its usage it is suggested that you connect its Index field from the DecomposeBaseList - Global List Index field if you want to access the curve with a specific ID (i.e. label in mask image).

Type

name: curveType, type: Enum, default: Line

Defines the type of the output curve.

Values:

Title Name
Line Line
Area Area

Style

name: curveStyle, type: Integer, default: 0

Sets the style of the output curve. 0 is a special value and assigns the curve ids as style id if multiple curves are created (if there is a mask image as input and containing is set to “Labels”).

Curve Title

name: curveTitle, type: String

Sets a title string for the output curve.

Update Mode

name: updateMode, type: Enum, default: Off, deprecated name: autoApply

Defines the update mode of this module.

Values:

Title Name Deprecated Name Description
Off Off FALSE Nothing happens on any field or input change.
Auto-Clear AutoClear   The output curve and histogram are cleared on any field or input change.
Auto-Update AutoUpdate TRUE The output curve and histogram is updated on any field or input change.

Update

name: update, type: Trigger, deprecated name: getHistogram

If pressed, the module computes anew.

Clear

name: clear, type: Trigger, deprecated name: clearAll

If pressed, the output curve and histogram are cleared.

Results Valid

name: upToDate, type: Bool, persistent: no

Status

name: status, type: String, persistent: no

Shows status information about the module.

Use Step Function

name: useStepFunction, type: Bool, default: FALSE

If checked, a curve of rectangular columns is created instead of piecewise linearly connections between histogram values.

The histogram columns may be a more truthful representation of the histogram, while the piecewise linear polygon may look better.

Use Zero As Bin Center

name: useZeroAsBinCenter, type: Bool, default: TRUE, deprecated name: useBinSizeOneRepresentation

If checked, the bins of the histogram will be arranged in such a way that zero is the center of a bin; otherwise zero will be at the edge of a bin.

For example, if Bin Size is 1 and Use Zero As Bin Center is true, bin edges will be […, -0.5, 0.5, 1.5, …] and bin centers will be […, -1, 0, 1, …]. If Use Zero As Bin Center is false, bin edges will be […, -1, 0, 1, …] and bin centers will be […, -0.5, 0.5, 1.5, …]. However, both options work for arbitrary Bin Size.

Use Background Value

name: useBackgroundValue, type: Bool, default: FALSE

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

Background Value

name: backgroundValue, type: Double, default: 0

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

Bin Size

name: binSize, type: Double, default: 1

Sets the size of histogram bins.

Hidden Fields

maxBinCount

name: maxBinCount, type: Integer, default: 25000000

progress

name: progress, type: Double, persistent: no