Back to Adaptive Vision Library website

You are here: Start » Function Reference » Image » Image Thresholding » SelectThresholdValue

SelectThresholdValue


Header: AVL.h
Namespace: avl
Module: FoundationBasic

Selects best threshold value using the image histogram.

Applications: Usually used before a thresholding filter when the image brightness is variable. Use with care.

Syntax

C++
C#
 
void avl::SelectThresholdValue
(
	const avl::Image& inImage,
	atl::Optional<const avl::Region&> inRoi,
	avl::ThresholdSelectionMethod::Type inMethod,
	float& outThresholdValue,
	atl::Array<float>& diagThresholdRatings,
	atl::Array<float>& diagBackgroundPixelsFraction,
	atl::Array<float>& diagForegroundPixelsFraction
)

Parameters

Name Type Default Description
inImage const Image& Input image
inRoi Optional<const Region&> NIL Range of pixels to be processed
inMethod ThresholdSelectionMethod::Type Method used to select the best threshold
outThresholdValue float& Best threshold separating background pixels from foreground pixels
diagThresholdRatings Array<float>& Contains ratings gained if that threshold would be chosen
diagBackgroundPixelsFraction Array<float>& Fraction of pixels that are darker than the index value
diagForegroundPixelsFraction Array<float>& Fraction of pixels that are brighter than the index value

Requirements

For input inImage only pixel formats are supported: uint8.

Read more about pixel formats in Image documentation.

Description

The operation estimates an intensity threshold value that discriminates foreground pixels from background pixels in inImage.

Note that to provide meaningful results it is required that the image in fact consists of foreground and background components that strongly differ in brightness.

Hints

  • Choose inMethod that works best in your application. None of the methods is perfect, but ClusteringOtsu is the most universal one.

Examples

SelectThresholdValue performed on the sample image (on the left) with inMethod = ClusteringKittler yields outThresholdValue = 189.5. Pixels of the input image brighter than 189.5 are presented on the right.

Errors

List of possible exceptions:

Error type Description
DomainError Region exceeds an input image in SelectThresholdValue.
DomainError Not supported inImage pixel format in SelectThresholdValue.

See Also

  • ThresholdImage – Transforms each pixel value to maximum or minimum depending on whether they belong to the specified range.