Developer Reference

  • 2020
  • 07/15/2020
  • Public Content
Contents

Histogram

Computes the intensity histogram of an image.

Syntax

Case 1: One-channel data
IppStatus ippiHistogram_<mod>(const Ipp<dataType>*
pSrc
, int
srcStep
, IppiSize
roiSize
, Ipp32u*
pHist
, const IppiHistogramSpec*
pSpec
, Ipp8u*
pBuffer
);
Supported values for
mod
:
8u_C1R
16u_C1R
16s_C1R
32f_C1R
Case 2: Three-channel data
IppStatus ippiHistogram_<mod>(const Ipp<dataType>*
pSrc
, int
srcStep
, IppiSize
roiSize
, Ipp32u*
pHist[3]
, const IppiHistogramSpec*
pSpec
, Ipp8u*
pBuffer
);
Supported values for
mod
:
8u_C3R
16u_C3R
16s_C3R
32f_C3R
Case 3: Four-channel data
IppStatus ippiHistogram_<mod>(const Ipp<dataType>*
pSrc
, int
srcStep
, IppiSize
roiSize
, Ipp32u*
pHist[4]
, const IppiHistogramSpec*
pSpec
, Ipp8u*
pBuffer
);
Supported values for
mod
:
8u_C4R
16u_C4R
16s_C4R
32f_C4R
Include Files
ippi.h
Domain Dependencies
Headers:
ippcore.h
,
ippvm.h
,
ipps.h
Libraries:
ippcore.lib
,
ippvm.lib
,
ipps.lib
Parameters
pSrc
Pointer to the source image ROI.
srcStep
Distance, in bytes, between the starting points of consecutive lines in the source image.
roiSize
Size of the source image 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.
pSpec
Pointer to the specification structure.
pBuffer
Pointer to the work buffer.
Description
The
ippiHistogram
function operates with ROI (see Regions of Interest in Intel IPP ).
This function computes the intensity histogram for each channel of the source image and stores the result in the
pHist
array.
Before calling this function, initialize the specification structure using the
HistogramInit
or
HistogramUniformInit
functions. The specification structure defines the following parameters for histogram calculation:
  • Histogram type: with uniform or random levels step
  • Number of levels
  • Level values
Length of the
pHist
array is defined by the
nLevels
parameter passed to the
HistogramInit
or
HistogramUniformInit
function.
As
nLevels
is the number of levels, the number of values in the
pHist
array, which is the number of histogram bins, is
nLevels
- 1. The meaning of the
pHist
and
pLevels
values can be illustrated by the following example:
pHist[k]
is the number of the source image pixels
pSrc(x, y)
that satisfy the condition
pLevels[k]
<=
pSrc(x, y)
<
pLevels(k+1)
.
Return Values
ippStsNoErr
Indicates no error. Any other value indicates an error or a warning.
ippStsNullPtrErr
Indicates an error when one of the specified pointers is
NULL
.
ippStsSizeErr
Indicates an error when
roiSize
has a zero or negative value.
ippStsStepErr
Indicates an error when
srcStep
is less than
roiSize.width
*
sizeOf(*pSrc)
*
nChannels
.
ippStsBadArgErr
Indicates an error when the
pSpec
object is not initialized.

Example

The code example below demonstrates how to use the
HistogramGetBufferSize
,
HistogramUniformInit
,
HistogramGetLevels
, and
Histogram
functions.
void HistogramExample() { const int HEIGHT = 8; const int WIDTH = 8; Ipp8u pImg[WIDTH*HEIGHT]; IppiSize roi = {WIDTH, HEIGHT}; int i; IppStatus sts; { // fill image with random values in [0..255] range with uniform distribution. IppsRandUniState_8u* pRndObj; int sizeRndObj; // get spec size ippsRandUniformGetSize_8u( &sizeRndObj ); pRndObj = (IppsRandUniState_8u*)ippsMalloc_8u( sizeRndObj ); // initialize rnd spec ippsRandUniformInit_8u(pRndObj, 0/*low*/, 255/*high*/, 0/*seed*/ ); // fill image for ( i=0; i<HEIGHT; i++ ) { sts = ippsRandUniform_8u(pImg + i*WIDTH, WIDTH, pRndObj); } ippsFree( pRndObj ); } printf_8u_2D("pImg:", pImg, roi, WIDTH, sts); { const int nBins = 5; int nLevels[] = { nBins+1 }; Ipp32f lowerLevel[] = {0}; Ipp32f upperLevel[] = {256}; Ipp32f pLevels[nBins+1], *ppLevels[1]; int sizeHistObj, sizeBuffer; IppiHistogramSpec* pHistObj; Ipp8u* pBuffer; Ipp32u pHistVec[nBins]; // get sizes for spec and buffer ippiHistogramGetBufferSize(ipp8u, roi, nLevels, 1/*nChan*/, 1/*uniform*/, &sizeHistObj, &sizeBuffer); pHistObj = (IppiHistogramSpec*)ippsMalloc_8u( sizeHistObj ); pBuffer = (Ipp8u*)ippsMalloc_8u( sizeBuffer ); // initialize spec ippiHistogramUniformInit( ipp8u, lowerLevel, upperLevel, nLevels, 1, pHistObj ); // check levels of bins ppLevels[0] = pLevels; sts = ippiHistogramGetLevels( pHistObj, ppLevels ); printf_32f( "pLevels:", pLevels, nBins+1, sts ); // calculate histogram sts = ippiHistogram_8u_C1R( pImg, WIDTH, roi, pHistVec, pHistObj, pBuffer ); ippsFree( pHistObj ); ippsFree( pBuffer ); printf_32u( "Histogram:", pHistVec, nBins, sts ); } }
Output:
pImg: 0 33 53 102 90 188 210 60 195 137 247 137 7 15 65 244 149 44 210 20 170 140 183 144 133 61 191 32 212 108 178 89 86 30 54 93 168 93 2 114 30 145 216 42 86 113 148 205 148 181 217 99 219 31 156 156 237 36 74 80 208 121 118 106 pLevels: 0.0 51.0 102.0 153.0 204.0 255.0 Histogram: 13 14 16 10 11

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804