local_thresholdlocal_thresholdLocalThresholdLocalThresholdlocal_threshold (Operator)


local_thresholdlocal_thresholdLocalThresholdLocalThresholdlocal_threshold — Segment an image using local thresholding.


local_threshold(Image : Region : Method, LightDark, GenParamName, GenParamValue : )

Herror local_threshold(const Hobject Image, Hobject* Region, const char* Method, const char* LightDark, const char* GenParamName, const Hlong GenParamValue)

Herror T_local_threshold(const Hobject Image, Hobject* Region, const Htuple Method, const Htuple LightDark, const Htuple GenParamName, const Htuple GenParamValue)

void LocalThreshold(const HObject& Image, HObject* Region, const HTuple& Method, const HTuple& LightDark, const HTuple& GenParamName, const HTuple& GenParamValue)

HRegion HImage::LocalThreshold(const HString& Method, const HString& LightDark, const HTuple& GenParamName, const HTuple& GenParamValue) const

HRegion HImage::LocalThreshold(const HString& Method, const HString& LightDark, const HString& GenParamName, Hlong GenParamValue) const

HRegion HImage::LocalThreshold(const char* Method, const char* LightDark, const char* GenParamName, Hlong GenParamValue) const

HRegion HImage::LocalThreshold(const wchar_t* Method, const wchar_t* LightDark, const wchar_t* GenParamName, Hlong GenParamValue) const   (Windows only)

static void HOperatorSet.LocalThreshold(HObject image, out HObject region, HTuple method, HTuple lightDark, HTuple genParamName, HTuple genParamValue)

HRegion HImage.LocalThreshold(string method, string lightDark, HTuple genParamName, HTuple genParamValue)

HRegion HImage.LocalThreshold(string method, string lightDark, string genParamName, int genParamValue)

def local_threshold(image: HObject, method: str, light_dark: str, gen_param_name: MaybeSequence[str], gen_param_value: MaybeSequence[Union[int, float]]) -> HObject


local_thresholdlocal_thresholdLocalThresholdLocalThresholdLocalThresholdlocal_threshold segments a single-channel image ImageImageImageImageimageimage using the thresholding method given in MethodMethodMethodMethodmethodmethod and returns the segmented region in RegionRegionRegionRegionregionregion. Currently the operator offers only the Method 'adapted_std_deviation'"adapted_std_deviation""adapted_std_deviation""adapted_std_deviation""adapted_std_deviation""adapted_std_deviation". This algorithm is a text binarization technique and provides good results for document images.

Adaptive Thresholding

By selecting MethodMethodMethodMethodmethodmethod = 'adapted_std_deviation'"adapted_std_deviation""adapted_std_deviation""adapted_std_deviation""adapted_std_deviation""adapted_std_deviation", a locally adaptive thresholding based on local mean and standard deviation according to Sauvola (see the paper in References) is invoked. The algorithm is able to segment document images even if they are degraded, e.g., due to inhomogeneous illumination or noise. It enables text binarization on an inhomogeneous background by taking into account the local contrast.

For a segmentation of the dark foreground (see parameter LightDarkLightDarkLightDarkLightDarklightDarklight_dark), for a pixel at position (r,c), a local threshold T(r,c) is calculated within a window of size 'mask_size'"mask_size""mask_size""mask_size""mask_size""mask_size" x 'mask_size'"mask_size""mask_size""mask_size""mask_size""mask_size" (see the generic parameter 'mask_size'"mask_size""mask_size""mask_size""mask_size""mask_size") as follows: where is the local mean value within the window and denotes the corresponding standard deviation. The parameter R (see 'range'"range""range""range""range""range") is the assumed maximum value of the standard deviation (R = 128 for byte images) and k (see 'scale'"scale""scale""scale""scale""scale") a parameter that controls how much the threshold value T(r,c) differs from the mean value . If there is high contrast in the neighborhood of a point (r,c) the standard deviation has a value close to R which yields a threshold value T(r,c) close to the local mean . If the contrast is low, the local threshold is below the local mean value. For dark text on light background containing also darker regions, this lower threshold enables the segmentation of the text even in darker areas.

The parameter LightDarkLightDarkLightDarkLightDarklightDarklight_dark controls, whether light or dark structures are segmented.

By setting GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name to one of the following values, additional parameters specific for the 'adapted_std_deviation'"adapted_std_deviation""adapted_std_deviation""adapted_std_deviation""adapted_std_deviation""adapted_std_deviation" method can be set with GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value:


specifies the mask size, i.e., the size of the neighborhood in which the local threshold is calculated. The smaller the window size the thinner the segmented strokes. 'mask_size'"mask_size""mask_size""mask_size""mask_size""mask_size" must be set to a value that is larger than the stroke width of the characters or structures to be segmented. If 'mask_size'"mask_size""mask_size""mask_size""mask_size""mask_size" is even, the next larger odd value is used.

Suggested values: 15, 21, 31.

Default: 15.


sets the parameter k ( ), that controls how much the threshold value differs from the local mean value. Use smaller values for 'scale'"scale""scale""scale""scale""scale" to also segment structures with a lower contrast to their background. Use larger values to suppress clutter.

Suggested values: 0.2, 0.3, 0.5.

Default: 0.2.


sets the maximum assumed value of standard deviation R . This parameter should be adapted based on the expected gray value range. As a rule of thumb, the value for 'range'"range""range""range""range""range" can be set to , where MinGray and MaxGray are the minimum and maximum gray values in the image, which can be determined with min_max_graymin_max_grayMinMaxGrayMinMaxGrayMinMaxGraymin_max_gray.

Suggested values: 128, 32767.5.

Default: 128 (for byte images), 32767.5 (for uint2 images).


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 / uint2)

Input Image.

RegionRegionRegionRegionregionregion (output_object)  region(-array) objectHRegionHObjectHRegionHobject *

Segmented output region.

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

Segmentation method.

Default value: 'adapted_std_deviation' "adapted_std_deviation" "adapted_std_deviation" "adapted_std_deviation" "adapted_std_deviation" "adapted_std_deviation"

List of values: 'adapted_std_deviation'"adapted_std_deviation""adapted_std_deviation""adapted_std_deviation""adapted_std_deviation""adapted_std_deviation"

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

Extract foreground or background?

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

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

GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name (input_control)  attribute.name(-array) HTupleMaybeSequence[str]HTupleHtuple (string) (string) (HString) (char*)

List of generic parameter names.

Default value: []

List of values: 'mask_size'"mask_size""mask_size""mask_size""mask_size""mask_size", 'range'"range""range""range""range""range", 'scale'"scale""scale""scale""scale""scale"

GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value (input_control)  attribute.value(-array) HTupleMaybeSequence[Union[int, float]]HTupleHtuple (integer / real) (int / long / double) (Hlong / double) (Hlong / double)

List of generic parameter values.

Default value: []

Suggested values: 0.2, 15, 30, 128.0

Possible Successors

connectionconnectionConnectionConnectionConnectionconnection, select_shapeselect_shapeSelectShapeSelectShapeSelectShapeselect_shape, select_grayselect_graySelectGraySelectGraySelectGrayselect_gray


auto_thresholdauto_thresholdAutoThresholdAutoThresholdAutoThresholdauto_threshold, binary_thresholdbinary_thresholdBinaryThresholdBinaryThresholdBinaryThresholdbinary_threshold, char_thresholdchar_thresholdCharThresholdCharThresholdCharThresholdchar_threshold

See also

gray_histogray_histoGrayHistoGrayHistoGrayHistogray_histo, thresholdthresholdThresholdThresholdThresholdthreshold


J. Sauvola, M. Pietikäinen, “Adaptive document image binarization", Pattern Recognition, 33, 225-236 (2000)