mlib_ImageExtremaLocations(3MLIB)			    mediaLib Library Functions				 mlib_ImageExtremaLocations(3MLIB)

NAME

       mlib_ImageExtremaLocations, mlib_ImageExtremaLocations_Fp - image extrema and their locations

SYNOPSIS

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

       mlib_status  mlib_ImageExtremaLocations(  mlib_s32  *min,  mlib_s32 *max, const mlib_image *img, mlib_s32 xStart, mlib_s32 yStart, mlib_s32
       xPeriod, mlib_s32 yPeriod, mlib_s32 saveLocations, mlib_s32 maxRuns, mlib_s32 *minCounts,  mlib_s32  *maxCounts,  mlib_s32  **minLocations,
       mlib_s32 **maxLocations, mlib_s32 len);

       mlib_status  mlib_ImageExtremaLocations_Fp( mlib_d64 *min, mlib_d64 *max, const mlib_image *img, mlib_s32 xStart, mlib_s32 yStart, mlib_s32
       xPeriod, mlib_s32 yPeriod, mlib_s32 saveLocations, mlib_s32 maxRuns, mlib_s32 *minCounts,  mlib_s32  *maxCounts,  mlib_s32  **minLocations,
       mlib_s32 **maxLocations, mlib_s32 len);

DESCRIPTION

       Each of the functions finds the image-wise minimum and maximum pixel values for each channel, and optionally, their locations.

       Each  of the functions scans an image, finds the minimum and maximum pixel values for each channel, and finds the locations of those pixels
       with the minimum or maximum values.

       The user provides initial minimum/maximum values through the arguments min and max.  This function will update them based on findings.

       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 scanned 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

       The  locations  of  the minimum/maximum, if asked, are recorded in a format of run-length coding.  Each run-length code, or simply called a
       run, has a format of (xStart, yStart, length).  Here length is defined on the low-resolution image (with downsampling factors of 1/xPeriod,
       1/yPeriod)  and	does not cross rows.  So the run-length code (xStart, yStart, length) means that the pixels at (xStart, yStart), (xStart +
       xPeriod, yStart), ..., (xStart + (length - 1)*xPeriod, yStart) of the original image have a value of the minimum/maximum.

       The buffers for minLocations and maxLocations are organized in the following format for each channel i:

       minLocations[i][0] = xStart0;  // the 1st run
       minLocations[i][1] = yStart0;
       minLocations[i][2] = length0;
       minLocations[i][3] = xStart1;  // the 2nd run
       minLocations[i][4] = yStart1;
       minLocations[i][5] = length1;
		   ......	      // more runs
       minLocations[i][len-1] = ...;

       It is the user's responsibility to allocate enough memory for the buffers for minLocations and  maxLocations.   This  function  may  return
       MLIB_OUTOFRANGE, if any of the buffers is not big enough.

PARAMETERS

       The function takes the following arguments:

       min	       Pointer to the minimum values.

       max	       Pointer to the maximum values.

       img	       Pointer to the input image.

       xStart	       Initial X sample coordinate.

       yStart	       Initial Y sample coordinate.

       xPeriod	       X sampling rate.  xPeriod >= 1.

       yPeriod	       Y sampling rate.  yPeriod >= 1.

       saveLocations   If true (i.e., saveLocations != 0), find the extrema locations; otherwise only find the extrema.

       maxRuns		Number	of  runs of the minimum/maximum the caller expects for each channel.  maxRuns >= 1. If it is MLIB_S32_MAX, all the
		       minimum/maximum locations should be recorded.

       minCounts       Pointer to the numbers of runs of the minimum recorded in minLocations.

       maxCounts       Pointer to the numbers of runs of the maximum recorded in maxLocations.

       minLocations    Pointer to the minimum locations in a format of run-length coding.

       maxLocations    Pointer to the maximum locations in a format of run-length coding.

       len	       Length of the buffers for the minimum/maximum locations in each channel.

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_ImageExtrema2(3MLIB), mlib_ImageMaximum(3MLIB),  mlib_ImageMaximum_Fp(3MLIB),  mlib_ImageMinimum(3MLIB),  mlib_ImageMinimum_Fp(3MLIB),
       attributes(5)

SunOS 5.10							    10 Nov 2004 				 mlib_ImageExtremaLocations(3MLIB)