var_thresholdvar_thresholdVarThresholdVarThresholdvar_threshold (Operator)


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


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)

def var_threshold(image: HObject, mask_width: int, mask_height: int, std_dev_scale: Union[int, float], abs_threshold: Union[int, float], light_dark: str) -> HObject


With var_thresholdvar_thresholdVarThresholdVarThresholdVarThresholdvar_threshold, it's possible to select the pixels of the input ImageImageImageImageimageimage which


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

Hints for the input parameters

MaskWidthMaskWidthMaskWidthMaskWidthmaskWidthmask_width, MaskHeightMaskHeightMaskHeightMaskHeightmaskHeightmask_height

The size of the filter mask defined by MaskWidthMaskWidthMaskWidthMaskWidthmaskWidthmask_width and MaskHeightMaskHeightMaskHeightMaskHeightmaskHeightmask_height 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) MaskWidthMaskWidthMaskWidthMaskWidthmaskWidthmask_width := 12, MaskHeightMaskHeightMaskHeightMaskHeightmaskHeightmask_height := 12, StdDevScaleStdDevScaleStdDevScaleStdDevScalestdDevScalestd_dev_scale := 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 MaskWidthMaskWidthMaskWidthMaskWidthmaskWidthmask_width or MaskHeightMaskHeightMaskHeightMaskHeightmaskHeightmask_height is even, the next larger odd value is used. Altogether, a value of 3 can be considered the minimum sensible value.


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

For the parameter StdDevScaleStdDevScaleStdDevScaleStdDevScalestdDevScalestd_dev_scale 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 StdDevScaleStdDevScaleStdDevScaleStdDevScalestdDevScalestd_dev_scale is too high (1.3), the operator is 'picky'; only pixels that are very similar to their surrounding are selected. (2) If StdDevScaleStdDevScaleStdDevScaleStdDevScalestdDevScalestd_dev_scale is too low (-0.3), too many pixels that are somewhat similar to their surrounding are incorrectly selected.

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 AbsThresholdAbsThresholdAbsThresholdAbsThresholdabsThresholdabs_threshold. Thus, small gray value changes in homogeneous surroundings can be ignored. Note that for negative values of StdDevScaleStdDevScaleStdDevScaleStdDevScalestdDevScalestd_dev_scale, AbsThresholdAbsThresholdAbsThresholdAbsThresholdabsThresholdabs_threshold should also be chosen negative.


'light'"light""light""light""light""light" or 'dark'"dark""dark""dark""dark""dark" returns all pixels that are lighter or darker than their surrounding, respectively. 'equal'"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""not_equal" returns the combined results of 'light'"light""light""light""light""light" and 'dark'"dark""dark""dark""dark""dark", i.e., all pixels that differ from their surrounding.

The calculation

(1) (2)
(1) Initial image. (2) Thresholded image (StdDevScaleStdDevScaleStdDevScaleStdDevScalestdDevScalestd_dev_scale := 0.6, MaskWidthMaskWidthMaskWidthMaskWidthmaskWidthmask_width := 15, MaskHeightMaskHeightMaskHeightMaskHeightmaskHeightmask_height := 15, AbsThresholdAbsThresholdAbsThresholdAbsThresholdabsThresholdabs_threshold := 10). The following images visualize exemplary how the result along the blue arrow came to be.

var_thresholdvar_thresholdVarThresholdVarThresholdVarThresholdvar_threshold selects from the input image ImageImageImageImageimageimage those regions RegionRegionRegionRegionregionregion 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 MaskWidthMaskWidthMaskWidthMaskWidthmaskWidthmask_width x MaskHeightMaskHeightMaskHeightMaskHeightmaskHeightmask_height around each pixel (x,y).


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


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

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

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

'light'"light""light""light""light""light" and 'dark'"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""dark" is selected, all pixels where the 'Dark' curve is above the 'GrayValues' curve would be selected.


Note that filter operators may return unexpected results if an image with a reduced domain is used as input. Please refer to the chapter Filters.

Execution Information


ImageImageImageImageimageimage (input_object)  singlechannelimage(-array) objectHImageHObjectHImageHobject (byte / int2 / int4 / uint2 / real)

Input image.

RegionRegionRegionRegionregionregion (output_object)  region(-array) objectHRegionHObjectHRegionHobject *

Segmented regions.

MaskWidthMaskWidthMaskWidthMaskWidthmaskWidthmask_width (input_control)  extent.x HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Mask width for mean and deviation calculation.

Default value: 15

Suggested values: 9, 11, 13, 15

Restriction: MaskWidth >= 1

MaskHeightMaskHeightMaskHeightMaskHeightmaskHeightmask_height (input_control)  extent.y HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Mask height for mean and deviation calculation.

Default value: 15

Suggested values: 9, 11, 13, 15

Restriction: MaskHeight >= 1

StdDevScaleStdDevScaleStdDevScaleStdDevScalestdDevScalestd_dev_scale (input_control)  number HTupleUnion[int, float]HTupleHtuple (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

AbsThresholdAbsThresholdAbsThresholdAbsThresholdabsThresholdabs_threshold (input_control)  number HTupleUnion[int, float]HTupleHtuple (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

LightDarkLightDarkLightDarkLightDarklightDarklight_dark (input_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Threshold type.

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

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


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


var_thresholdvar_thresholdVarThresholdVarThresholdVarThresholdvar_threshold 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'"no_object_result""no_object_result""no_object_result""no_object_result""no_object_result", 'empty_region_result'"empty_region_result""empty_region_result""empty_region_result""empty_region_result""empty_region_result", and 'store_empty_region'"store_empty_region""store_empty_region""store_empty_region""store_empty_region""store_empty_region" with set_systemset_systemSetSystemSetSystemSetSystemset_system. If necessary, an exception is raised.


dyn_thresholddyn_thresholdDynThresholdDynThresholdDynThresholddyn_threshold, thresholdthresholdThresholdThresholdThresholdthreshold


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