You are here: Start » Function Reference » All Functions » Conditional Processing » ClassifyByRange

ClassifyByRange

This is Filter Equivalent. This function may be present in generated code, but should not be used in hand-written code.

Header:	STD.h
Namespace:	fil
Module:	FoundationLite

Separates the elements of the input array into three output arrays, depending on whether the related values fall below, into or above the specified range.

Applications: E.g. selection of the objects (e.g. blobs) whose associated values (e.g. area) meet the specified minimum and maximum requirements.

Syntax

void fil::ClassifyByRange
(
	const ftl::Array<Type>& inArray,
	const ftl::Array<float>& inValues,
	ftl::Optional<float> inMinimum,
	ftl::Optional<float> inMaximum,
	ftl::Optional<ftl::Array<Type>&> outAccepted = ftl::NIL,
	ftl::Optional<ftl::Array<Type>&> outRejected = ftl::NIL,
	ftl::Optional<ftl::Array<Type>&> outLower = ftl::NIL,
	ftl::Optional<ftl::Array<Type>&> outHigher = ftl::NIL,
	ftl::Optional<ftl::Array<bool>&> outIsAccepted = ftl::NIL,
	ftl::Optional<ftl::Array<bool>&> outIsRejected = ftl::NIL
)

Parameters

Name	Type	Default	Description
inArray	const Array<Type>&		Elements to be classified
inValues	const Array<float>&		Corresponding values to be compared against the range
inMinimum	Optional<float>	NIL	Lowest value of the range
inMaximum	Optional<float>	NIL	Highest value of the range
outAccepted	Optional<Array<Type>&>	NIL	Array of elements corresponding to values matching the range
outRejected	Optional<Array<Type>&>	NIL	Array of elements corresponding to values outside the range
outLower	Optional<Array<Type>&>	NIL	Array of elements corresponding to values lower than inMinimum
outHigher	Optional<Array<Type>&>	NIL	Array of elements corresponding to values higher than inMaximum
outIsAccepted	Optional<Array<bool>&>	NIL	Represents whether corresponding values are in the range
outIsRejected	Optional<Array<bool>&>	NIL	Represents whether corresponding values are outside the range

Optional Outputs

The computation of following outputs can be switched off by passing value ftl::NIL to these parameters: outAccepted, outRejected, outLower, outHigher, outIsAccepted, outIsRejected.

Description

The filter accepts an array of objects of type T (decided on filter creation) along with corresponding array of float values and splits the array of objects into three output arrays, depending on how each of the values fits the (inMinimum, inMaximum) range.

Objects corresponding to values lower than inMinimum are passed onto outLower and outRejected.
Objects corresponding to values that fit closed range (inMinimum, inMaximum) are passed onto outAccepted.
Objects corresponding to values higher than inMaximum are passed onto outHigher and outRejected.

In the special case of inMinimum being greater than inMaximum, first matching condition is applied, which means that objects corresponding to values higher than inMaximum and lower than inMinimum are passed onto outLower.

Hints

Also consider using the "select" function in formulas.
Before using this filter you need to have an array of objects (to be classified) and an array of feature values that describe the objects.
Connect the array of objects to the inArray input and connect the array of feature values to the inValues input.
Set the range of inMinimum and inMaximum to define the accepted objects.
Consider showing additional outputs: outLower, outHigher, outIsAccepted, outIsRejected.
If you need the highest possible speed, also consider using a more simple filter SelectByRange.

Examples


inArray = {"Alice", "Bill", "Frank", "Patricia", "Thomas"} inValues = {5.0, 4.0, 5.0, 8.0, 6.0} inMinimum = 5.0 inMaximum = 6.0	outLower = {"Bill"} outAccepted = {"Alice", "Frank", "Thomas"} outHigher = {"Patricia"}

Errors

List of possible exceptions:

Error type	Description
DomainError	Inconsistent array lengths on input in ClassifyByRange.
DomainError	Incorrect (NaN) float value on inValues input in ClassifyByRange.