mlib_ImageExtremaLocations(3mlib)

1mlib_ImageExtremaLocations(m3eMdLiIaBL)ib Library Funmcltiibo_nIsmageExtremaLocations(3MLIB)
2
3
4

NAME

6       mlib_ImageExtremaLocations,   mlib_ImageExtremaLocations_Fp   -   image
7       extrema and their locations
8

SYNOPSIS

10       cc [ flag... ] file... -lmlib [ library... ]
11       #include <mlib.h>
12
13       mlib_status mlib_ImageExtremaLocations( mlib_s32 *min, mlib_s32 *max,
14            const mlib_image *img, mlib_s32 xStart, mlib_s32 yStart,
15            mlib_s32 xPeriod, mlib_s32 yPeriod, mlib_s32 saveLocations,
16            mlib_s32 maxRuns, mlib_s32 *minCounts, mlib_s32 *maxCounts,
17            mlib_s32 **minLocations, mlib_s32 **maxLocations, mlib_s32 len);
18
19
20       mlib_status mlib_ImageExtremaLocations_Fp( mlib_d64 *min, mlib_d64 *max,
21            const mlib_image *img, mlib_s32 xStart, mlib_s32 yStart,
22            mlib_s32 xPeriod, mlib_s32 yPeriod, mlib_s32 saveLocations,
23            mlib_s32 maxRuns, mlib_s32 *minCounts, mlib_s32 *maxCounts,
24            mlib_s32 **minLocations, mlib_s32 **maxLocations, mlib_s32 len);
25
26

DESCRIPTION

28       Each of the functions finds the image-wise minimum  and  maximum  pixel
29       values for each channel, and optionally, their locations.
30
31
32       Each  of  the  functions  scans an image, finds the minimum and maximum
33       pixel values for each channel, and finds the locations of those  pixels
34       with the minimum or maximum values.
35
36
37       The  user provides initial minimum/maximum values through the arguments
38       min and max.  This function will update them based on findings.
39
40
41       The set of pixels scanned may furthermore be reduced by specifying xPe‐
42       riod  and  yPeriod parameters that specify the sampling rate along each
43       axis.
44
45
46       The set of pixels to be scanned may  be  obtained  from  the  following
47       equation:
48
49         x = xStart + p*xPeriod;  0 ≤ p < (w - xStart)/xPeriod
50         y = yStart + q*yPeriod;  0 ≤ q < (h - yStart)/yPeriod
51
52
53
54       The  locations of the minimum/maximum, if asked, are recorded in a for‐
55       mat of run-length coding. Each run-length code, or simply called a run,
56       has a format of (xStart, yStart, length). Here length is defined on the
57       low-resolution image (with downsampling factors of  1/xPeriod,  1/yPer‐
58       iod)  and  does not cross rows. So the run-length code (xStart, yStart,
59       length) means that the pixels at (xStart, yStart), (xStart  +  xPeriod,
60       yStart),  ...,  (xStart + (length - 1)*xPeriod, yStart) of the original
61       image have a value of the minimum/maximum.
62
63
64       The buffers for minLocations and maxLocations are organized in the fol‐
65       lowing format for each channel i:
66
67         minLocations[i][0] = xStart0;  // the 1st run
68         minLocations[i][1] = yStart0;
69         minLocations[i][2] = length0;
70         minLocations[i][3] = xStart1;  // the 2nd run
71         minLocations[i][4] = yStart1;
72         minLocations[i][5] = length1;
73                     ......             // more runs
74         minLocations[i][len-1] = ...;
75
76
77
78       It  is the user's responsibility to allocate enough memory for the buf‐
79       fers for minLocations  and  maxLocations.   This  function  may  return
80       MLIB_OUTOFRANGE, if any of the buffers is not big enough.
81

PARAMETERS

83       The function takes the following arguments:
84
85       min              Pointer to the minimum values.
86
87
88       max              Pointer to the maximum values.
89
90
91       img              Pointer to the input image.
92
93
94       xStart           Initial X sample coordinate.
95
96
97       yStart           Initial Y sample coordinate.
98
99
100       xPeriod          X sampling rate. xPeriod ≥ 1.
101
102
103       yPeriod          Y sampling rate. yPeriod ≥ 1.
104
105
106       saveLocations    If  true  (i.e., saveLocations != 0), find the extrema
107                        locations; otherwise only find the extrema.
108
109
110       maxRuns           Number of runs  of  the  minimum/maximum  the  caller
111                        expects  for  each  channel.  maxRuns  ≥  1.  If it is
112                        MLIB_S32_MAX, all the minimum/maximum locations should
113                        be recorded.
114
115
116       minCounts        Pointer to the numbers of runs of the minimum recorded
117                        in minLocations.
118
119
120       maxCounts        Pointer to the numbers of runs of the maximum recorded
121                        in maxLocations.
122
123
124       minLocations     Pointer  to  the minimum locations in a format of run-
125                        length coding.
126
127
128       maxLocations     Pointer to the maximum locations in a format  of  run-
129                        length coding.
130
131
132       len              Length  of  the  buffers for the minimum/maximum loca‐
133                        tions in each channel.
134
135

RETURN VALUES

137       The function returns MLIB_SUCCESS if successful. Otherwise  it  returns
138       MLIB_FAILURE.
139

ATTRIBUTES

141       See attributes(5) for descriptions of the following attributes:
142
143
144
145
146       ┌─────────────────────────────┬─────────────────────────────┐
147       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
148       ├─────────────────────────────┼─────────────────────────────┤
149       │Interface Stability          │Committed                    │
150       ├─────────────────────────────┼─────────────────────────────┤
151       │MT-Level                     │MT-Safe                      │
152       └─────────────────────────────┴─────────────────────────────┘
153

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUES

ATTRIBUTES

SEE ALSO