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

ThresholdToRegion_HSx

Header:	AVL.h
Namespace:	avl
Module:	FoundationBasic

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

Applications: Extraction of a region characterized with a specific color.

Syntax

void avl::ThresholdToRegion_HSx
(
	const avl::Image& inRgbImage,
	atl::Optional<const avl::Region&> inRoi,
	const avl::HSxColorModel::Type inColorModel,
	int inBeginHue,
	int inEndHue,
	atl::Optional<int> inMinSaturation,
	atl::Optional<int> inMaxSaturation,
	atl::Optional<int> inMinBrightness,
	atl::Optional<int> inMaxBrightness,
	avl::Region& outRegion,
	avl::Image& diagHSxImage
)

Parameters

Name	Type	Range	Default	Description
inRgbImage	const Image&
inRoi	Optional<const Region&>		NIL	Range of pixels to be processed
inColorModel	const HSxColorModel::Type			Selected color model
inBeginHue	int	0 - 255	0	Lowest acceptable Hue; if higher than inEndHue, then range wrapping is used
inEndHue	int	0 - 255	255	Highest acceptable Hue, if lower than inBeginHue, then range wrapping is used
inMinSaturation	Optional<int>	0 - 255	128
inMaxSaturation	Optional<int>	0 - 255	NIL
inMinBrightness	Optional<int>	0 - 255	128	Minimum brightness; denotes V, L or I, depending on inColorModel
inMaxBrightness	Optional<int>	0 - 255	NIL	Maximum brightness; denotes V, L or I, depending on inColorModel
outRegion	Region&			Output region
diagHSxImage	Image&			Diagnostic image in HSx color space

Requirements

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

Read more about pixel formats in Image documentation.

Description

The operation is a cousin of ThresholdImage_HSx yet it computes a region instead of an image. The three-channel inRgbImage 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. The resulting region contains only those pixels of the input image, which meets all of the following conditions:

Value of the Hue parameter is in cyclic range (inBeginHue, inEndHue).
Value of the Saturation parameter is in range (inMinSaturation, inMaxSaturation).
Value of the Value parameter is in range (inMinBrightness, inMaxBrightness).

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.

Hints

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 outRegion output.

Examples

ThresholdToRegion_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.

Errors

List of possible exceptions:

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