HistogramEven

Computes the intensity histogram of an image using equal bins.

Syntax

Case 1: Operation on one-channel integer data

IppStatus ippiHistogramEven_<mod>(const Ipp<datatype>* pSrc, int srcStep, IppiSize roiSize, Ipp32s* pHist, Ipp32s* pLevels, int nLevels, Ipp32s lowerLevel, Ipp32s upperLevel);

Supported values for mod:

8u_C1R

16u_C1R

16s_C1R

Case 2: Operation on multi-channel integer data

IppStatus ippiHistogramEven_<mod>(const Ipp<datatype>* pSrc, int srcStep, IppiSize roiSize, Ipp32s* pHist[3], Ipp32s* pLevels[3], int nLevels[3], Ipp32s lowerLevel[3], Ipp32s upperLevel[3]);

Supported values for mod:

8u_C3R	16u_C3R	16s_C3R
8u_AC4R	16u_AC4R	16s_AC4R

IppStatus ippiHistogramEven_<mod>(const Ipp<datatype>* pSrc, int srcStep, IppiSize roiSize, Ipp32s* pHist[4], Ipp32s* pLevels[4], int nLevels[4], Ipp32s lowerLevel[4], Ipp32s upperLevel[4]);

Supported values for mod:

8u_C4R

16u_C4R

16s_C4R

Parameters

pSrc	Pointer to the source image ROI.
srcStep	Distance in bytes between starts of consecutive lines in the source image.
roiSize	Size of the source ROI in pixels
pHist	Pointer to the computed histogram. In case of multi-channel data, pHist is an array of pointers to the histogram for each channel.
pLevels	Pointer to the array of level values. In case of multi-channel data, pLevels is an array of pointers to the level values array for each channel.
nLevels	Number of levels, separate for each channel.
lowerLevel	Lower level boundary, separate for each channel.
upperLevel	Upper level boundary, separate for each channel.

Description

The function ippiHistogramEven is declared in the ippi.h file. It operates with ROI (see Regions of Interest in Intel IPP). This function computes the intensity histogram of an image in the ranges specified by the values lowerLevel (inclusive), upperLevel (exclusive), and nLevels. The function operates on the assumption that all histogram bins have the same width and equal boundary values of the bins (levels). The function stores computed histograms in the array pHist separately for each channel. The calculated levels are stored in the array pLevels.

Length of the arrays pLevels and pHist is defined by the nLevels parameter. Since nLevels is the number of levels, the number of histogram bins is nLevels - 1. Similarly, the number of values in the array pHist is also nLevels - 1. The meaning of pHist and pLevels values can be illustrated by the following example: pHist [k] is a number of source image pixels pSrc(x,y) that satisfy the condition

pLevels[k] ≤ pSrc(x,y) < pLevels[k+1].

Example "Computing the Even Histogram of an Image” shows how to use the ippiHistogramEven function.

Computing the Even Histogram of an Image

// Compute histogram of an image for 4 bins in the range [28, 127];

// compute level values for the bins.

Ipp8u img[WIDTH*HEIGHT];

IppiSize imgSize = {WIDTH, HEIGHT};

Ipp32s levels[5], histo[5];

ippiHistogramEven_8u_C1R(img, WIDTH, imgSize, levels,                      
                         histo, 5, 28, 128);

// When the function completes operation the array histo will      
// contain a histogram in specified range, and the array

// levels will contain the level values {28, 53, 78, 103, 128}

Return Values

ippStsNoErr	Indicates no error. Any other value indicates an error or a warning.
ippStsNullPtrErr	Indicates an error if one of the specified pointers is `NULL`.
ippStsSizeErr	Indicates an error condition if roiSize has a field with a zero or negative value.
ippStsMemAllocErr	Indicates an error if there is not enough memory for the inner histogram.
ippStsHistoNofLevelsErr	Indicates an error if nLevels is less than 2.