Operator Reference

HALCON Operator Reference / Segmentation / Threshold
ClassesClasses | | Operators

var_thresholdvar_thresholdVarThresholdVarThresholdvar_threshold (Operator)

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

Signature

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)

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

Description

With var_thresholdvar_thresholdVarThresholdVarThresholdvar_threshold, 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

MaskWidthMaskWidthMaskWidthmaskWidthmask_width, MaskHeightMaskHeightMaskHeightmaskHeightmask_height

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

StdDevScaleStdDevScaleStdDevScalestdDevScalestd_dev_scale

The local standard deviation is used as a measure of noise in the image. It can be scaled by StdDevScaleStdDevScaleStdDevScalestdDevScalestd_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 StdDevScaleStdDevScaleStdDevScalestdDevScalestd_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 StdDevScaleStdDevScaleStdDevScalestdDevScalestd_dev_scale is too high (1.3), the operator is 'picky'; only pixels that are very similar to their surrounding are selected. (2) If StdDevScaleStdDevScaleStdDevScalestdDevScalestd_dev_scale is too low (-0.3), too many pixels that are somewhat similar to their surrounding are incorrectly selected.
AbsThresholdAbsThresholdAbsThresholdabsThresholdabs_threshold

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

LightDarkLightDarkLightDarklightDarklight_dark

'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 (StdDevScaleStdDevScaleStdDevScalestdDevScalestd_dev_scale := 0.6, MaskWidthMaskWidthMaskWidthmaskWidthmask_width := 15, MaskHeightMaskHeightMaskHeightmaskHeightmask_height := 15, AbsThresholdAbsThresholdAbsThresholdabsThresholdabs_threshold := 10). The following images visualize exemplary how the result along the blue arrow came to be.

var_thresholdvar_thresholdVarThresholdVarThresholdvar_threshold 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 MaskWidthMaskWidthMaskWidthmaskWidthmask_width x MaskHeightMaskHeightMaskHeightmaskHeightmask_height around each pixel (x,y).

Let

  • g(x,y) be the gray value at position (x,y) in the input ImageImageImageimageimage,

  • m(x,y) the corresponding mean gray value, and

  • d(x,y) the corresponding standard deviation in the mask around that pixel.

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 StdDevScaleStdDevScaleStdDevScalestdDevScalestd_dev_scale, each pixel is analyzed. It is determined whether the user-defined AbsThresholdAbsThresholdAbsThresholdabsThresholdabs_threshold or the scaled standard deviation is greater. The bigger value is chosen as variable threshold v(x,y). For a negative StdDevScaleStdDevScaleStdDevScalestdDevScalestd_dev_scale, the corresponding smaller value is chosen.

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

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

  • 'light'"light""light""light""light":

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

  • 'dark'"dark""dark""dark""dark":

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

    LightDarkLightDarkLightDarklightDarklight_dark = '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.

  • '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

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

  • Multithreading type: reentrant (runs in parallel with non-exclusive operators).
  • Multithreading scope: global (may be called from any thread).
  • Automatically parallelized on tuple level.
  • Automatically parallelized on domain level.

Parameters

ImageImageImageimageimage (input_object)  singlechannelimage(-array) → objectHImageHObjectHObjectHobject (byte / int2 / int4 / uint2 / real)

Input image.

RegionRegionRegionregionregion (output_object)  region(-array) → objectHRegionHObjectHObjectHobject *

Segmented regions.

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

Mask width for mean and deviation calculation.

Default: 15

Suggested values: 9, 11, 13, 15

Restriction: MaskWidth >= 1

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

Mask height for mean and deviation calculation.

Default: 15

Suggested values: 9, 11, 13, 15

Restriction: MaskHeight >= 1

StdDevScaleStdDevScaleStdDevScalestdDevScalestd_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: 0.2

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

AbsThresholdAbsThresholdAbsThresholdabsThresholdabs_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: 2

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

LightDarkLightDarkLightDarklightDarklight_dark (input_control)  string → HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Threshold type.

Default: '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_thresholdVarThresholdVarThresholdvar_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", '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" with set_systemset_systemSetSystemSetSystemset_system. If necessary, an exception is raised.

Alternatives

dyn_thresholddyn_thresholdDynThresholdDynThresholddyn_threshold, thresholdthresholdThresholdThresholdthreshold

References

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

Module

Foundation

ClassesClasses | | Operators