var_thresholdvar_thresholdVarThresholdVarThreshold (Operator)

Name

var_thresholdvar_thresholdVarThresholdVarThreshold — Threshold an image by local mean and standard deviation analysis.

Signature

var_threshold(Image : Region : MaskWidth, MaskHeight, StdDevScale, AbsThreshold, LightDark : )

Herror var_threshold(const Hobject Image, Hobject* Region, const Hlong MaskWidth, const Hlong MaskHeight, double StdDevScale, double AbsThreshold, const char* LightDark)

Herror T_var_threshold(const Hobject Image, Hobject* Region, const Htuple MaskWidth, const Htuple MaskHeight, const Htuple StdDevScale, const Htuple AbsThreshold, const Htuple LightDark)

void VarThreshold(const HObject& Image, HObject* Region, const HTuple& MaskWidth, const HTuple& MaskHeight, const HTuple& StdDevScale, const HTuple& AbsThreshold, const HTuple& LightDark)

HRegion HImage::VarThreshold(Hlong MaskWidth, Hlong MaskHeight, const HTuple& StdDevScale, const HTuple& AbsThreshold, const HString& LightDark) const

HRegion HImage::VarThreshold(Hlong MaskWidth, Hlong MaskHeight, double StdDevScale, double AbsThreshold, const HString& LightDark) const

HRegion HImage::VarThreshold(Hlong MaskWidth, Hlong MaskHeight, double StdDevScale, double AbsThreshold, const char* LightDark) const

HRegion HImage::VarThreshold(Hlong MaskWidth, Hlong MaskHeight, double StdDevScale, double AbsThreshold, const wchar_t* LightDark) const   (Windows only)

static void HOperatorSet.VarThreshold(HObject image, out HObject region, HTuple maskWidth, HTuple maskHeight, HTuple stdDevScale, HTuple absThreshold, HTuple lightDark)

HRegion HImage.VarThreshold(int maskWidth, int maskHeight, HTuple stdDevScale, HTuple absThreshold, string lightDark)

HRegion HImage.VarThreshold(int maskWidth, int maskHeight, double stdDevScale, double absThreshold, string lightDark)

Description

With var_thresholdvar_thresholdVarThresholdVarThresholdVarThreshold, it's possible to select the pixels of the input ImageImageImageImageimage which

and

Thus, it is possible to segment regions on inhomogeneous, noisy, or unevenly illuminated backgrounds.

Hints for the input parameters

MaskWidth, MaskHeight

The size of the filter mask defined by MaskWidthMaskWidthMaskWidthMaskWidthmaskWidth and MaskHeightMaskHeightMaskHeightMaskHeightmaskHeight determines the maximum size of the objects to be segmented. However, if the mask is chosen too large, objects that are very close might be merged.

(1) (2)
(3) (4)
(1) Original image; the goal is to count the vertical lines. (2) MaskWidthMaskWidthMaskWidthMaskWidthmaskWidth := 12, MaskHeightMaskHeightMaskHeightMaskHeightmaskHeight := 12, StdDevScaleStdDevScaleStdDevScaleStdDevScalestdDevScale := 0.1, all vertical lines are segmented correctly. (3) If the mask size is chosen too low (3), the desired regions are not selected properly. (4) If the mask size is too high (40), objects that are very close might be merged.

If MaskWidthMaskWidthMaskWidthMaskWidthmaskWidth or MaskHeightMaskHeightMaskHeightMaskHeightmaskHeight is even, the next larger odd value is used. Altogether, a value of 3 can be considered the minimum sensible value.

StdDevScale

The local standard deviation is used as a measure of noise in the image. It can be scaled by StdDevScaleStdDevScaleStdDevScaleStdDevScalestdDevScale to reflect the desired sensitivity. A higher value means that only pixels that are very different from their surrounding are selected.

For the parameter StdDevScaleStdDevScaleStdDevScaleStdDevScalestdDevScale values between -1.0 and 1.0 are sensible choices, with 0.2 as a suggested value. If the parameter is too high or too low, an empty or full region may be returned.

(1) (2)
(1) If StdDevScaleStdDevScaleStdDevScaleStdDevScalestdDevScale is too high (1.3), the operator is 'picky'; only pixels that are very similar to their surrounding are selected. (2) If StdDevScaleStdDevScaleStdDevScaleStdDevScalestdDevScale is too low (-0.3), too many pixels that are somewhat similar to their surrounding are incorrectly selected.
AbsThreshold

In homogeneous areas of an image, the standard deviation is low; thus, the influence of single gray values is high. To reduce the sensitivity of the operator in homogeneous areas, it's possible to adjust AbsThresholdAbsThresholdAbsThresholdAbsThresholdabsThreshold. Thus, small gray value changes in homogeneous surroundings can be ignored. Note that for negative values of StdDevScaleStdDevScaleStdDevScaleStdDevScalestdDevScale, AbsThresholdAbsThresholdAbsThresholdAbsThresholdabsThreshold should also be chosen negative.

LightDark

'light'"light""light""light""light" or 'dark'"dark""dark""dark""dark" returns all pixels that are lighter or darker than their surrounding, respectively. 'equal'"equal""equal""equal""equal" returns all pixels that are not selected by either option, i.e. the pixels that are relatively equal to their surrounding. 'not_equal'"not_equal""not_equal""not_equal""not_equal" returns the combined results of 'light'"light""light""light""light" and 'dark'"dark""dark""dark""dark", i.e., all pixels that differ from their surrounding.

The calculation

(1) (2)
(1) Initial image. (2) Thresholded image (StdDevScaleStdDevScaleStdDevScaleStdDevScalestdDevScale := 0.6, MaskWidthMaskWidthMaskWidthMaskWidthmaskWidth := 15, MaskHeightMaskHeightMaskHeightMaskHeightmaskHeight := 15, AbsThresholdAbsThresholdAbsThresholdAbsThresholdabsThreshold := 10). The following images visualize exemplary how the result along the blue arrow came to be.

var_thresholdvar_thresholdVarThresholdVarThresholdVarThreshold selects from the input image ImageImageImageImageimage those regions RegionRegionRegionRegionregion in which the pixels fulfill a threshold condition. The threshold is calculated from the mean gray value and the standard deviation in a local mask of size MaskWidthMaskWidthMaskWidthMaskWidthmaskWidth x MaskHeightMaskHeightMaskHeightMaskHeightmaskHeight around each pixel (x,y).

Let

The original gray values, the corresponding mean gray values, and the corresponding standard deviation in the mask around these pixels.

Then, the variable threshold v(x,y) is defined as

or

Interpretation: For a positive StdDevScaleStdDevScaleStdDevScaleStdDevScalestdDevScale, each pixel is analyzed. It is determined whether the user-defined AbsThresholdAbsThresholdAbsThresholdAbsThresholdabsThreshold or the scaled standard deviation is greater. The bigger value is chosen as variable threshold v(x,y). For a negative StdDevScaleStdDevScaleStdDevScaleStdDevScalestdDevScale, the corresponding smaller value is chosen.

The standard deviation can be scaled with StdDevScaleStdDevScaleStdDevScaleStdDevScalestdDevScale.
The variable threshold is chosen based on the scaled standard deviation and AbsThresholdAbsThresholdAbsThresholdAbsThresholdabsThreshold.

Which pixels are chosen based on the variable threshold is defined by the parameter LightDarkLightDarkLightDarkLightDarklightDark:

LightDarkLightDarkLightDarkLightDarklightDark = 'light'"light""light""light""light":

Interpretation: If the pixel is brighter by v(x,y) than its surrounding, it is selected.

LightDarkLightDarkLightDarkLightDarklightDark = 'dark'"dark""dark""dark""dark":

Interpretation: If the pixel is darker by v(x,y) than its surrounding, it is selected.

LightDarkLightDarkLightDarkLightDarklightDark = 'equal'"equal""equal""equal""equal":

Interpretation: Select exactly those pixels that are not selected by 'light'"light""light""light""light" and 'dark'"dark""dark""dark""dark", i.e., the pixels that are relatively equal to their surrounding.

LightDarkLightDarkLightDarkLightDarklightDark = 'not_equal'"not_equal""not_equal""not_equal""not_equal":

Interpretation: Select all pixels of 'light'"light""light""light""light" and 'dark'"dark""dark""dark""dark", i.e., all pixels that differ by v(x,y) from their surrounding.

'light'"light""light""light""light" and 'dark'"dark""dark""dark""dark" are calculated based on the corresponding mean gray value and the variable threshold.
For example, if 'dark'"dark""dark""dark""dark" is selected, all pixels where the 'Dark' curve is above the 'GrayValues' curve would be selected.

Attention

This operator may return unexpected results if an image with a reduced domain is used as input. Please refer to the chapter Filters.

Execution Information

Parameters

ImageImageImageImageimage (input_object)  singlechannelimage(-array) objectHImageHImageHobject (byte / int2 / int4 / uint2 / real)

Input image.

RegionRegionRegionRegionregion (output_object)  region(-array) objectHRegionHRegionHobject *

Segmented regions.

MaskWidthMaskWidthMaskWidthMaskWidthmaskWidth (input_control)  extent.x HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Mask width for mean and deviation calculation.

Default value: 15

Suggested values: 9, 11, 13, 15

Restriction: MaskWidth >= 1

MaskHeightMaskHeightMaskHeightMaskHeightmaskHeight (input_control)  extent.y HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Mask height for mean and deviation calculation.

Default value: 15

Suggested values: 9, 11, 13, 15

Restriction: MaskHeight >= 1

StdDevScaleStdDevScaleStdDevScaleStdDevScalestdDevScale (input_control)  number HTupleHTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)

Factor for the standard deviation of the gray values.

Default value: 0.2

Suggested values: -0.2, -0.1, 0.1, 0.2

AbsThresholdAbsThresholdAbsThresholdAbsThresholdabsThreshold (input_control)  number HTupleHTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)

Minimum gray value difference from the mean.

Default value: 2

Suggested values: -2, -1, 0, 1, 2

LightDarkLightDarkLightDarkLightDarklightDark (input_control)  string HTupleHTupleHtuple (string) (string) (HString) (char*)

Threshold type.

Default value: 'dark' "dark" "dark" "dark" "dark"

List of values: 'dark'"dark""dark""dark""dark", 'equal'"equal""equal""equal""equal", 'light'"light""light""light""light", 'not_equal'"not_equal""not_equal""not_equal""not_equal"

Complexity

Let A be the area of the input region, then the runtime is O(A).

Result

var_thresholdvar_thresholdVarThresholdVarThresholdVarThreshold returns 2 (H_MSG_TRUE) if all parameters are correct. The behavior with respect to the input images and output regions can be determined by setting the values of the flags 'no_object_result', 'empty_region_result', and 'store_empty_region' with set_systemset_systemSetSystemSetSystemSetSystem. If necessary, an exception is raised.

Alternatives

dyn_thresholddyn_thresholdDynThresholdDynThresholdDynThreshold, thresholdthresholdThresholdThresholdThreshold

References

W.Niblack, ”An Introduction to Digital Image Processing”, Page 115-116, Englewood Cliffs, N.J., Prentice Hall, 1986

Module

Foundation