Back to FabImage Library website

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


Header: FIL.h
Namespace: fil
Module: FoundationLite

Transforms each pixel value to minimum or maximum depending on whether it belongs to specified region in the HSV, HSL or HSI color space.

Applications: Color analysis.


void fil::ThresholdImage_HSx
	const fil::Image& inRgbImage,
	ftl::Optional<const fil::Region&> inRoi,
	fil::HSxColorModel::Type inColorModel,
	int inBeginHue,
	int inEndHue,
	ftl::Optional<int> inMinSaturation,
	ftl::Optional<int> inMaxSaturation,
	ftl::Optional<int> inMinBrightness,
	ftl::Optional<int> inMaxBrightness,
	float inFuzziness,
	fil::Image& outMonoImage,
	fil::Image& diagHSxImage


Name Type Range Default Description
Input value inRgbImage const Image& Input image in the RGB color space
Input value inRoi Optional<const Region&> NIL Region of interest
Input value inColorModel HSxColorModel::Type Selected color model
Input value inBeginHue int 0 - 255 0 Lowest acceptable Hue; if higher than inEndHue, then range wrapping is used
Input value inEndHue int 0 - 255 255 Highest acceptable Hue, if lower than inBeginHue, then range wrapping is used
Input value inMinSaturation Optional<int> 0 - 255 128
Input value inMaxSaturation Optional<int> 0 - 255 NIL
Input value inMinBrightness Optional<int> 0 - 255 128 Minimum brightness; denotes V, L or I, depending on inColorModel
Input value inMaxBrightness Optional<int> 0 - 255 NIL Maximum brightness; denotes V, L or I, depending on inColorModel
Input value inFuzziness float 0.0 - Tolerance for value ranges that results in intermediate output values
Output value outMonoImage Image&
Diagnostic input diagHSxImage Image& Image in HSx color space


For input inRgbImage only pixel formats are supported: 3⨯uint8.

Read more about pixel formats in Image documentation.


The operation transforms each pixel of three-channel inRgbImage to the maximum or minimum level thus creating binary image. The input image is considered to be encoded using RGB color representation. Each of the image pixel is internally converted to HSx (HSV, HSL or HSI) color representation and then examined.

  • Pixels meeting all of the following conditions are transformed to the maximum level:
    • Value of the Hue parameter is in cyclic range (inBeginHue, inEndHue).
    • Value of the Saturation parameter is in range (inMinSaturation, inMaxSaturation).
    • Value of the Brightness parameter is in range (inMinBrightness, inMaxBrightness).
  • Other pixels are transformed to the minimum level.

If any of the parameters inMinSaturation, inMinBrightness is not set, it is assumed to be -infinity.

If any of the parameters inMaxSaturation, inMaxBrightness is not set, it is assumed to be infinity.

Parameter inFuzziness (set to 0 by default) allows to perform fuzzy thresholding which linearly interpolates those pixel values that differ by at most inFuzziness from the border parameter values; thus creating smooth transition between minimum and maximum values in the resulting image.


  • Choose inColorModel taking into account accuracy and execution speed (HSV is the fastest, HSI is usually the most accurate).
  • Define the range of HSV/HSL/HSI values that best separates the foreground and background pixels. Analyze the results on the outMonoImage output.
  • Use inFuzziness to add some smooth transitions between black and white pixels in the result.


ThresholdImage_HSx performed on the sample image with inColorModel = HSV, inBeginHue = 0.0, inEndHue = 10.0, inMinSaturation = 120.0, inMinBrightness = 70.0.

Hardware Acceleration

This operation supports automatic parallelization for multicore and multiprocessor systems.


List of possible exceptions:

Error type Description
DomainError Not a 3-channel and 8-bit image in ThresholdImage_HSx.
DomainError Region exceeds an input image in ThresholdImage_HSx.
DomainError Not supported inRgbImage pixel format in ThresholdImage_HSx. Supported formats: 3xUInt8.

See Also

  • ThresholdToRegion_HSx – Creates a region containing image pixels which belongs to specified region in HSV, HSL or HSI space.