mlib_ImageHistogram2(3MLIB)				    mediaLib Library Functions				       mlib_ImageHistogram2(3MLIB)

NAME

       mlib_ImageHistogram2 - histogram

SYNOPSIS

       cc [ flag... ] file... -lmlib [ library... ]
       #include <mlib.h>

       mlib_status mlib_ImageHistogram2(mlib_s32 **histo, const mlib_image *img, const mlib_s32 *numBins, const mlib_s32 *lowValue, const mlib_s32
       *highValue, mlib_s32 xStart, mlib_s32 yStart, mlib_s32 xPeriod, mlib_s32 yPeriod);

DESCRIPTION

       The mlib_ImageHistogram2() function creates a histogram by scanning an image, counting the number of pixels within a given range  for  each
       channel of the image, and then generating a histogram.

       The  image can have 1, 2, 3 or 4 channels. The data type of the image can be MLIB_BYTE, MLIB_SHORT, MLIB_USHORT, or MLIB_INT. The histogram
       must have the same number of channels as the image has.

       One entry of the histogram, or a bin, is used to accumulate the number of pixels within a certain sub-range. The legal pixel range and  the
       number of bins may be controlled separately.

       If binWidth is defined as (highValue - lowValue )/numBins then bin i counts pixel values in the following range:

       lowValue + i*binWidth <= x < lowValue + (i + 1)*binWidth

       The set of pixels scanned may furthermore be reduced by specifying xPeriod and yPeriod parameters that specify the sampling rate along each
       axis.

       The set of pixels to be accumulated may be obtained from the following equation:

       x = xStart + p*xPeriod;	0 <= p < (w - xStart)/xPeriod
       y = yStart + q*yPeriod;	0 <= q < (h - yStart)/yPeriod

       It is the user's responsibility to clear the histogram table before this function is called and to ensure that the histogram table supplied
       is suitable for the source image and the parameters. Otherwise, the result of this function is undefined.

       The range from lowValue[k] to (highValue[k] - 1) must be a valid subrange of the image type range.

PARAMETERS

       The function takes the following arguments:

       histo	       Pointer	to  histogram.	The format of the histogram is histo[channel][index].  The index values for channel i can be 0, 1,
		       ..., numBins[i]-1.

       img	       Pointer to source image.

       numBins	       The number of bins for each channel of the image.

       lowValue        The lowest pixel value checked for each channel.

       highValue       The highest pixel value checked for each channel.  When counting the pixel values, highValue is not included.

       xStart	       The initial X sample coordinate.

       yStart	       The initial Y sample coordinate.

       xPeriod	       The X sampling rate.  xPeriod >= 1.

       yPeriod	       The Y sampling rate.  yPeriod >= 1.

RETURN VALUES

       The function returns MLIB_SUCCESS if successful. Otherwise it returns MLIB_FAILURE.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       mlib_ImageHistogram(3MLIB), attributes(5)

SunOS 5.10							    10 Nov 2004 				       mlib_ImageHistogram2(3MLIB)