'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved 
.TH mlib_ImageExtremaLocations 3MLIB "2 Mar 2007" "SunOS 5.11" "mediaLib Library Functions"
.SH NAME
mlib_ImageExtremaLocations, mlib_ImageExtremaLocations_Fp \- image extrema and their locations
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR... ] \fIfile\fR... \fB-lmlib\fR [ \fIlibrary\fR... ]
#include <mlib.h>

\fBmlib_status\fR \fBmlib_ImageExtremaLocations\fR(\fB mlib_s32 *\fR\fImin\fR, \fBmlib_s32 *\fR\fImax\fR,
     \fBconst mlib_image *\fR\fIimg\fR, \fBmlib_s32\fR \fIxStart\fR, \fBmlib_s32\fR \fIyStart\fR,
     \fBmlib_s32\fR \fIxPeriod\fR, \fBmlib_s32\fR \fIyPeriod\fR, \fBmlib_s32\fR \fIsaveLocations\fR,
     \fBmlib_s32\fR \fImaxRuns\fR, \fBmlib_s32 *\fR\fIminCounts\fR, \fBmlib_s32 *\fR\fImaxCounts\fR,
     \fBmlib_s32 **\fR\fIminLocations\fR, \fBmlib_s32 **\fR\fImaxLocations\fR, \fBmlib_s32\fR \fIlen\fR);
.fi

.LP
.nf
\fBmlib_status\fR \fBmlib_ImageExtremaLocations_Fp\fR(\fB mlib_d64 *\fR\fImin\fR, \fBmlib_d64 *\fR\fImax\fR,
     \fBconst mlib_image *\fR\fIimg\fR, \fBmlib_s32\fR \fIxStart\fR, \fBmlib_s32\fR \fIyStart\fR,
     \fBmlib_s32\fR \fIxPeriod\fR, \fBmlib_s32\fR \fIyPeriod\fR, \fBmlib_s32\fR \fIsaveLocations\fR,
     \fBmlib_s32\fR \fImaxRuns\fR, \fBmlib_s32 *\fR\fIminCounts\fR, \fBmlib_s32 *\fR\fImaxCounts\fR,
     \fBmlib_s32 **\fR\fIminLocations\fR, \fBmlib_s32 **\fR\fImaxLocations\fR, \fBmlib_s32\fR \fIlen\fR);
.fi

.SH DESCRIPTION
.sp
.LP
Each of the functions finds the image-wise minimum and maximum pixel values for each channel, and optionally, their locations.
.sp
.LP
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.
.sp
.LP
The user provides initial minimum/maximum values through the arguments \fBmin\fR and \fBmax\fR.  This function will update them based on findings.
.sp
.LP
The set of pixels scanned may furthermore be reduced by specifying \fBxPeriod\fR and \fByPeriod\fR parameters that specify the sampling rate along each axis.
.sp
.LP
The set of pixels to be scanned may be obtained from the following equation: 
.sp
.in +2
.nf
x = xStart + p*xPeriod;  0 \(<= p < (w - xStart)/xPeriod
y = yStart + q*yPeriod;  0 \(<= q < (h - yStart)/yPeriod
.fi
.in -2

.sp
.LP
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 \fB(xStart, yStart, length)\fR. Here \fBlength\fR is defined on the low-resolution image (with downsampling factors of \fB1/xPeriod\fR, \fB1/yPeriod\fR) and does not cross rows. So the run-length code \fB(xStart, yStart, length)\fR means that the pixels at \fB(xStart, yStart), (xStart + xPeriod, yStart), ..., (xStart + (length - 1)*xPeriod, yStart)\fR of the original image have a value of the minimum/maximum.
.sp
.LP
The buffers for \fBminLocations\fR and \fBmaxLocations\fR are organized in the following format for each channel \fBi\fR:
.sp
.in +2
.nf
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] = ...;
.fi
.in -2

.sp
.LP
It is the user's responsibility to allocate enough memory for the buffers for \fBminLocations\fR and \fBmaxLocations\fR.  This function may return \fBMLIB_OUTOFRANGE\fR, if any of the buffers is not big enough.
.SH PARAMETERS
.sp
.LP
The function takes the following arguments:
.sp
.ne 2
.mk
.na
\fB\fImin\fR\fR
.ad
.RS 17n
.rt  
Pointer to the minimum values.
.RE

.sp
.ne 2
.mk
.na
\fB\fImax\fR\fR
.ad
.RS 17n
.rt  
Pointer to the maximum values.
.RE

.sp
.ne 2
.mk
.na
\fB\fIimg\fR\fR
.ad
.RS 17n
.rt  
Pointer to the input image.
.RE

.sp
.ne 2
.mk
.na
\fB\fIxStart\fR\fR
.ad
.RS 17n
.rt  
Initial X sample coordinate.
.RE

.sp
.ne 2
.mk
.na
\fB\fIyStart\fR\fR
.ad
.RS 17n
.rt  
Initial Y sample coordinate.
.RE

.sp
.ne 2
.mk
.na
\fB\fIxPeriod\fR\fR
.ad
.RS 17n
.rt  
X sampling rate. \fBxPeriod \(>= 1\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIyPeriod\fR\fR
.ad
.RS 17n
.rt  
Y sampling rate. \fByPeriod \(>= 1\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIsaveLocations\fR\fR
.ad
.RS 17n
.rt  
If true (i.e., \fBsaveLocations != 0\fR), find the extrema locations; otherwise only find the extrema.
.RE

.sp
.ne 2
.mk
.na
\fB\fImaxRuns\fR\fR
.ad
.RS 17n
.rt  
 Number of runs of the minimum/maximum the caller expects for each channel. \fBmaxRuns \(>= 1\fR. If it is \fBMLIB_S32_MAX\fR, all the minimum/maximum locations should be recorded.
.RE

.sp
.ne 2
.mk
.na
\fB\fIminCounts\fR\fR
.ad
.RS 17n
.rt  
Pointer to the numbers of runs of the minimum recorded in \fBminLocations\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fImaxCounts\fR\fR
.ad
.RS 17n
.rt  
Pointer to the numbers of runs of the maximum recorded in \fBmaxLocations\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIminLocations\fR\fR
.ad
.RS 17n
.rt  
Pointer to the minimum locations in a format of run-length coding.
.RE

.sp
.ne 2
.mk
.na
\fB\fImaxLocations\fR\fR
.ad
.RS 17n
.rt  
Pointer to the maximum locations in a format of run-length coding.
.RE

.sp
.ne 2
.mk
.na
\fB\fIlen\fR\fR
.ad
.RS 17n
.rt  
Length of the buffers for the minimum/maximum locations in each channel.
.RE

.SH RETURN VALUES
.sp
.LP
The function returns \fBMLIB_SUCCESS\fR if successful. Otherwise it returns \fBMLIB_FAILURE\fR.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBmlib_ImageExtrema2\fR(3MLIB), \fBmlib_ImageMaximum\fR(3MLIB), \fBmlib_ImageMaximum_Fp\fR(3MLIB), \fBmlib_ImageMinimum\fR(3MLIB), \fBmlib_ImageMinimum_Fp\fR(3MLIB), \fBattributes\fR(5)