Argus API Argus Camera API

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- File List
- File Members

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
BayerAverageMap.h
Go to the documentation of this file.
1 /*
2 * Copyright (c) 2016, NVIDIA CORPORATION. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 * * Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * * Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
12 * * Neither the name of NVIDIA CORPORATION nor the names of its
13 * contributors may be used to endorse or promote products derived
14 * from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY
17 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
19 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
20 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
21 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
22 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
23 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
24 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
26 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28
29 #ifndef _ARGUS_EXT_BAYER_AVERAGE_MAP_H
30 #define _ARGUS_EXT_BAYER_AVERAGE_MAP_H
31
32 namespace Argus
33 {
34
35 /**
36 * The Ext::BayerAverageMap extension generates local averages of a capture's raw Bayer data for
37 * a number of small rectangles, called bins, that are evenly distributed across the image.
38 * These averages may be calculated before optical clipping to the output bit depth occurs, thus
39 * the working range of this averaging may extend beyond the optical range of the output pixels;
40 * this allows the averages to remain steady while the sensor freely modifies its optical range.
41 *
42 * Any pixel values outside of the working range are clipped with respect to this averaging: they
43 * are excluded from the average calculation and will increment the clipped pixel counter for the
44 * containing region (@see IBayerAverageMapMetadata::getClipCounts()).
45 *
46 * This extension introduces two new interfaces:
47 * - IBayerAverageMapSettings; used to enable average map generation in a capture Request.
48 * - IBayerAverageMapMetadata; exposes the average map values from the CaptureMetadata.
49 */
50 DEFINE_UUID(ExtensionName, EXT_BAYER_AVERAGE_MAP, 12c3de20,64c5,11e6,bdf4,08,00,20,0c,9a,66);
51
52 namespace Ext
53 {
54
55 /**
56 * @class IBayerAverageMapSettings
57 *
58 * Request settings used to configure Bayer average map generation.
59 */
60 DEFINE_UUID(InterfaceID, IID_BAYER_AVERAGE_MAP_SETTINGS, 12c3de21,64c5,11e6,bdf4,08,00,20,0c,9a,66);
61 class IBayerAverageMapSettings : public Interface
62 {
63 public:
64 static const InterfaceID& id() { return IID_BAYER_AVERAGE_MAP_SETTINGS; }
65
66 /**
67 * Enables or disables Bayer average map generation. When enabled, CaptureMetadata
68 * returned by completed captures will expose the IBayerAverageMap interface.
69 *
70 * @param[in] enable whether or not Bayer average map generation is enabled.
71 */
72 virtual void setBayerAverageMapEnable(bool enable) = 0;
73
74 /**
75 * @returns whether or not Bayer average map generation is enabled.
76 */
77 virtual bool getBayerAverageMapEnable() const = 0;
78
79 protected:
80 ~IBayerAverageMapSettings() {}
81 };
82
83 /**
84 * @class IBayerAverageMap
85 *
86 * The Bayer average map provides local averages of the capture's raw pixels for a number
87 * of small rectangular regions, called bins, that are evenly distributed across the image.
88 * Each average is a floating-point value that is nomalized such that [0.0, 1.0] maps to the
89 * full optical range of the output pixels, but values outside this range may be included in
90 * the averages so long as they are within the working range of the average calculation
91 * (@see IBayerAverageMap::getWorkingRange()). Pixels outside of the working range will be
92 * excluded from average calculation and added to the clipped count for the region
93 * (@see IBayerAverageMap::getClipCounts()).
94 *
95 * The size and layout of the bins used to calculate the averages are determined by the Argus
96 * implementation and are illustrated in the following diagram. The bin size and interval are
97 * constant across the image, and are positioned such that the generated averages cover the
98 * majority of the full image. All dimensions are given in pixels.
99 *
100 * start.x interval.width
101 * _______ _________________
102 * | | | |
103 * _ ________________________________________________________
104 * | | |
105 * start.y | | |
106 * |_ | _____ _____ _____ | _
107 * | | | | | | | | |
108 * | | 0,0 | | 1,0 | | 2,0 | | |
109 * | |_____| |_____| |_____| | |
110 * | | | interval.height
111 * | | |
112 * | | |
113 * | _____ _____ _____ | _|
114 * | | | | | | | |
115 * | | 0,1 | | 1,1 | | 2,1 | |
116 * | |_____| |_____| |_____| |
117 * | |
118 * | |
119 * | |
120 * | _____ _____ _____ | _
121 * | | | | | | | | |
122 * | | 0,2 | | 1,2 | | 2,2 | | | size.height
123 * | |_____| |_____| |_____| | _|
124 * | |
125 * | |
126 * |________________________________________________________|
127 *
128 * |_____|
129 *
130 * size.width
131 *
132 */
133 DEFINE_UUID(InterfaceID, IID_BAYER_AVERAGE_MAP, 12c3de22,64c5,11e6,bdf4,08,00,20,0c,9a,66);
134 class IBayerAverageMap : public Interface
135 {
136 public:
137 static const InterfaceID& id() { return IID_BAYER_AVERAGE_MAP; }
138
139 /**
140 * Returns the starting location of the first bin, in pixels.
141 * Relative to the top-left corner of the image.
142 */
143 virtual Location getBinStart() const = 0;
144
145 /**
146 * Returns the size of each bin, in pixels.
147 */
148 virtual Size getBinSize() const = 0;
149
150 /**
151 * Returns the number of bins in both the horizontal (width) and vertical (height) directions.
152 * This size will be equivalent to the array dimensions for the output from
153 * @see IBayerAverageMap::getAverages() or @see IBayerAverageMap::getClipCounts().
154 */
155 virtual Size getBinCount() const = 0;
156
157 /**
158 * Returns the bin intervals for both the x and y axis. These intervals are defined as the
159 * number of pixels between the first pixel of a bin and that of the immediate next bin.
160 */
161 virtual Size getBinInterval() const = 0;
162
163 /**
164 * Returns the working range of the averaging calculation. The working range is defined as
165 * the range of values that will be included in the average calculation (eg. not clipped),
166 * and may extend beyond the normalized [0.0, 1.0] range of the optical output. For example,
167 * if the working range is [-0.5, 1.5], this means that values in [-0.5, 0) and (1, 1.5] will
168 * still be included in the average calculation despite being clipped to [0.0, 1.0] in the
169 * output pixels. Any pixels outside this working range are excluded from average calculation
170 * and will increment the clip count (@see IBayerAverageMap::getClipCount()).
171 *
172 * Note that when the bit depth available for averaging is equal to the optical bit depth of
173 * the output, the working range will be less than the full [0.0, 1.0] optical range. For
174 * example, when 10 bits of data are available, the raw output pixels in [0u, 1023u] will
175 * map to [0.0, 1.0]; however, the values of 0 and 1023 will be considered clipped for the
176 * sake of average calculation, and so the working range would be [1/1023.0, 1022/1023.0].
177 */
178 virtual Range<float> getWorkingRange() const = 0;
179
180 /**
181 * Returns the average values for all bins. These values are normalized such that
182 * [0.0, 1.0] maps to the optical range of the output, but the range of possible values
183 * is determined by the working range (@see IBayerAverageMap::getWorkingRange()).
184 * Any input pixels having values outside the working range will be excluded from average
185 * calculation and will increment the clip count (@see IBayerAverageMap::getClipCounts()).
186 *
187 * @param[out] averages The output array to store the averages for all bins. This
188 * 2-dimensional array will be sized as returned by @see getBinCount(), where
189 * each array element is a floating point BayerTuple containing the R, G_EVEN,
190 * G_ODD, and B averages for that bin.
191 */
192 virtual Status getAverages(Array2D< BayerTuple<float> >* averages) const = 0;
193
194 /**
195 * Returns the clipped pixel counts for all bins. This is the number of pixels in the bin
196 * whose value exceeds the working range and have been excluded from average calculation
197 * (@see IBayerAverageMap::getWorkingRange()).
198 *
199 * @param[out] clipCounts The output array to store the clip counts for all bins. This
200 * 2-dimensional array will be sized as returned by @see getBinCount(), where
201 * each array element is a uint32_t BayerTuple containing the R, G_EVEN, G_ODD,
202 * and B clip counts for that bin.
203 */
204 virtual Status getClipCounts(Array2D< BayerTuple<uint32_t> >* clipCounts) const = 0;
205
206 protected:
207 ~IBayerAverageMap() {}
208 };
209
210 } // namespace Ext
211
212 } // namespace Argus
213
214 #endif // _ARGUS_EXT_BAYER_AVERAGE_MAP_H