Threshold

Syntax

Parameters

pSrc	Pointer to the source vector.
pDst	Pointer to the destination vector.
pSrcDst	Pointer to the source and destination vector for the in-place operation.
len	Number of elements in the vector.
level	Value used to limit each element of pSrc or pSrcDst.This parameter must always be real. For complex versions, it must be positive and represent magnitude.
relOp	Values of this argument specify which relational operator to use and whether level is an upper or lower bound for the input. The relOp must have one of the following values:
	ippCmpLess Specifies the “less than” operator and level is a lower bound.
	ippCmpGreater Specifies the “greater than” operator and level is an upper bound.

Description

The function ippsThreshold is declared in the ipps.h file. This function performs the threshold operation on the vector pSrc by limiting each element by the threshold value level. Function operation is similar to that of the functions ippsThreshold_LT, ippsThreshold_GT but its interface contains the relOop parameter that specifies the type of the comparison operation to perform.

The in-place flavors of ippsThreshold perform the threshold operation on the vector pSrcDst by limiting each element by the threshold value level.

The relOp argument specifies which relational operator to use: when its value is ippCmpGreater - “greater than”, when ippCmpLess - “less than,” and determines whether level is an upper or lower bound for the input, respectively.

The formula for ippsThreshold called with the relOp = ippCmpLess is:

The formula for ippsThreshold called with the relOp = ippCmpGreater is:

For complex versions of the function ippsThreshold, the level argument is always real. The formula for complex ippsThreshold called with the relOp = ippCmpLess is:

The formula for complex ippsThreshold called with the relOp = ippCmpGreater is:

Application Notes

For all complex versions, level must be positive and represents a magnitude. The magnitude of the input is limited, but the phase remains unchanged. Zero-valued input is assumed to have zero phase.

A special rule is applied to the integer complex versions of the function ippsThreshold. In general, the resulting point coordinates at the complex plane are not integer. The function rounds them off to integer in such a way that the threshold operation is not performed. Thus, for the “less than” operation (with the ippCmpLess flag) the coordinates are rounded to the infinity (+Inf for positive coordinates, and -Inf for negative), and for the “greater than” operation (with the ippCmpGreater flag) the coordinates are rounded to 0. The code examples below show how to using the “complex” function ippsThreshold_16sc_I the “real” function ippsTreshold_16s_I.

Return Values

ippStsNoErr	Indicates no error.
ippStsNullPtrErr	Indicates an error when the pSrc, pDst, or pSrcDst pointer is NULL.
ippStsSizeErr	Indicates an error when len is less than or equal to 0.
ippStsBadArgErr	Indicates an error when relOp has an invalid value.
ippStsThreshNegLevelErr	Indicates an error when level for the complex version is negative (see appendix A "Handling of Special Cases" for more information).

Using the Complex Version of the ippsThreshold Function

IppStatus cmplx_threshold(void){

     Ipp16sc x[4] = {{2,3},{3,3}, {4,3}, {4,2}};

     /// level is near to the point {2,3} = 3.6

     /// the point {2,3} is to be replaced

     /// the computed coordinates are {2.2188,3.3282}

     /// the point used is {3,4};

     /// notice that it is the point with the phase,

     /// nearest to the source

     IppStatus st = ippsThreshold_16sc_I(x, 4, 4, ippCmpLess);

     printf_16sc("complex threshold result =", x, 4, st);

     return st;

}

Output:

    complex threshold result = {3, 4} {3, 3} {4, 3} {4, 2}

Using the Real Version of the ippsThreshold Function

IppStatus threshold( void) {

     Ipp16s x[4] = { -1, 0, 2, 3 };

     IppStatus st = ippsThreshold_16s_I(x, 4, 2, ippCmpLess );

     printf_16s("threshold result =", x, 4, st );

     return st;

}

Output: 

    threshold result = 2 2 2 3