# 2.1.22.1.4 ocmath_us_percentile_filter

## Description

Do percentile filter for given matrix. This is an OriginPro only function.

## Syntax

int ocmath_us_percentile_filter( USHORT * pData, int nRows, int nCols, double dPercent, int nWinSizeX, int nWinSizeY, int nSampling = FILTERSHAPE_SQUARE, double dThreshold = 0, int nRowFrom = 0, int nColFrom = 0, int nRowTo = -1, int nColTo = -1 )

## Parameters

pData
[input] pointer to matrix data
nRows
[input] matrix number of rows
nCols
[input] matrix number of columns
dPercent
[input] Percentile
0.0  : same as min filter;
100.0  : same as max filter;
50  : same as median filter;
other values : will sort data in window to get rank
nWinSizeX
[input] window x axle size, must be odd(1, 3, 5,...)
nWinSizeY
[input] window y axle size, must be odd(1, 3, 5,...)
nSampling
[input] can be FILTERSHAPE_SQUARE, FILTERSHAPE_CIRCULAR, FILTERSHAPE_STRAIGHT_CROSS('+'), FILTERSHAPE_DIAGONAL_CROSS('X')
when shape is FILTERSHAPE_CIRCULAR or FILTERSHAPE_DIAGONAL_CROSS nWinSizeX must equal nWinSizeY
dThreshold
[input] Threshold in percent. Use 0 to ignore. Percentage is expressed in terms of matrix min/max values.
When Threshold is different from zero, then it can be both positive and negative and will have different meanings.
When Threshold > 0, then if the calculated value has a smaller deviation from the original value then the threshold, the original value if not changed.
When Threshold < 0, then we will check upper bound instead. The original value is replaced only if the calculated value is deviated no more then the threshold amount.
nRowFrom
[input] the position of the central point of the filer window move range.Only data in this range will be filtered.
nColFrom
[input] the position of the central point of the filer window move range.Only data in this range will be filtered.
nRowTo
[input] the position of the central point of the filer window move range.Only data in this range will be filtered.
nColTo
[input] the position of the central point of the filer window move range.Only data in this range will be filtered.

## Return

return OE_NOERROR for success, otherwise return errors

## Examples

EX1

void ocmath_us_percentile_filter_ex1()
{
matrix<ushort>    matData={{2,3,5,7},{11,13,17,19},{23,29,31,37}};
int nRows = matData.GetNumRows();
int nCols = matData.GetNumCols();
double dPercent = 45.0;
int nWinSizeX = 3;
int nWinSizeY = 3;
int nSampling = FILTERSHAPE_STRAIGHT_CROSS;
double dThreshold = 0;
int nRowFrom = 0;
int nColFrom = 0;
int nRowTo = -1;
int nColTo = -1;
int nRet=ocmath_us_percentile_filter(matData,nRows,nCols,dPercent, nWinSizeX, nWinSizeY, nSampling,dThreshold,nRowFrom,nColFrom,nRowTo , nColTo );
if(nRet!= OE_NOERROR)
printf("Error!");
}

## Remark

Do percentile filter for given matrix. This filter is accomplished by a procedure which first finds the orders of all the pixels within a windowed region around the pixel in question. If the order is 0, the central pixel intensity is set equal to the minimum value; if the order is more than SampleSize, the central pixel intensity is set equal to the maximum value, and otherwise, the central pixel intensity is set equal to *(pData + nOrder).