Libargus API Libargus Camera API

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

- File List
- File Members

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
BayerAverageMap.h
Go to the documentation of this file.
1 /*
2 * Copyright (c) 2016-2017, 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 /**
30 * @file
31 * <b>Libargus Extension: Bayer Average Map API</b>
32 *
33 * @b Description: This file defines the BayerAverageMap extension.
34 */
35
36 #ifndef _ARGUS_EXT_BAYER_AVERAGE_MAP_H
37 #define _ARGUS_EXT_BAYER_AVERAGE_MAP_H
38
39 namespace Argus
40 {
41
42 /**
43 * Generates local averages of a capture's raw Bayer data. These averages are generated for
44 * a number of small rectangles, called bins, that are evenly distributed across the image.
45 * These averages may be calculated before optical clipping to the output bit depth occurs, thus
46 * the working range of this averaging may extend beyond the optical range of the output pixels;
47 * this allows the averages to remain steady while the sensor freely modifies its optical range.
48 *
49 * Any pixel values outside of the working range are clipped with respect to this averaging.
50 * Specifically, the API excludes them from the average calculation and increments
51 * the clipped pixel counter for the containing region.
52 * @see Ext::IBayerAverageMap::getClipCounts()
53 *
54 * This extension introduces two new interfaces:
55 * - Ext::IBayerAverageMapSettings enables average map generation in a capture Request.
56 * - Ext::IBayerAverageMap exposes the average map values from the CaptureMetadata.
57 *
58 * @defgroup ArgusExtBayerAverageMap Ext::BayerAverageMap
59 * @ingroup ArgusExtensions
60 */
61 DEFINE_UUID(ExtensionName, EXT_BAYER_AVERAGE_MAP, 12c3de20,64c5,11e6,bdf4,08,00,20,0c,9a,66);
62
63 namespace Ext
64 {
65
66 /**
67 * @class IBayerAverageMapSettings
68 *
69 * Interface to Bayer average map settings.
70 *
71 * @ingroup ArgusRequest ArgusExtBayerAverageMap
72 */
73 DEFINE_UUID(InterfaceID, IID_BAYER_AVERAGE_MAP_SETTINGS, 12c3de21,64c5,11e6,bdf4,08,00,20,0c,9a,66);
74 class IBayerAverageMapSettings : public Interface
75 {
76 public:
77 static const InterfaceID& id() { return IID_BAYER_AVERAGE_MAP_SETTINGS; }
78
79 /**
80 * Enables or disables Bayer average map generation. When enabled, CaptureMetadata
81 * returned by completed captures will expose the IBayerAverageMap interface.
82 *
83 * @param[in] enable whether or not Bayer average map generation is enabled.
84 */
85 virtual void setBayerAverageMapEnable(bool enable) = 0;
86
87 /**
88 * @returns whether or not Bayer average map generation is enabled.
89 */
90 virtual bool getBayerAverageMapEnable() const = 0;
91
92 protected:
93 ~IBayerAverageMapSettings() {}
94 };
95
96 /**
97 * @class IBayerAverageMap
98 *
99 * Interface to Bayer average map metadata.
100 *
101 * The Bayer average map provides local averages of the capture's raw pixels for a number
102 * of small rectangular regions, called bins, that are evenly distributed across the image.
103 * Each average is a floating-point value that is nomalized such that [0.0, 1.0] maps to the
104 * full optical range of the output pixels, but values outside this range may be included in
105 * the averages so long as they are within the working range of the average calculation.
106 * For pixels that have values outside the working range, the API excludes such pixels from the
107 * average calculation and increments the clipped pixel counter for the containing region.
108 * @see IBayerAverageMap::getWorkingRange()
109 * @see IBayerAverageMap::getClipCounts()
110 *
111 * The size and layout of the bins used to calculate the averages are determined by the Argus
112 * implementation and are illustrated in the following diagram. The bin size and interval are
113 * constant across the image, and are positioned such that the generated averages cover the
114 * majority of the full image. All dimensions are given in pixels.
115 *
116 * @code
117 * start.x interval.width
118 * _______ _________________
119 * | | | |
120 * _ ________________________________________________________
121 * | | |
122 * start.y | | |
123 * |_ | _____ _____ _____ | _
124 * | | | | | | | | |
125 * | | 0,0 | | 1,0 | | 2,0 | | |
126 * | |_____| |_____| |_____| | |
127 * | | | interval.height
128 * | | |
129 * | | |
130 * | _____ _____ _____ | _|
131 * | | | | | | | |
132 * | | 0,1 | | 1,1 | | 2,1 | |
133 * | |_____| |_____| |_____| |
134 * | |
135 * | |
136 * | |
137 * | _____ _____ _____ | _
138 * | | | | | | | | |
139 * | | 0,2 | | 1,2 | | 2,2 | | | size.height
140 * | |_____| |_____| |_____| | _|
141 * | |
142 * | |
143 * |________________________________________________________|
144 *
145 * |_____|
146 *
147 * size.width
148 * @endcode
149 *
150 * @ingroup ArgusCaptureMetadata ArgusExtBayerAverageMap
151 */
152 DEFINE_UUID(InterfaceID, IID_BAYER_AVERAGE_MAP, 12c3de22,64c5,11e6,bdf4,08,00,20,0c,9a,66);
153 class IBayerAverageMap : public Interface
154 {
155 public:
156 static const InterfaceID& id() { return IID_BAYER_AVERAGE_MAP; }
157
158 /**
159 * Returns the starting location of the first bin, in pixels, where the
160 * location is relative to the top-left corner of the image.
161 */
162 virtual Point2D<uint32_t> getBinStart() const = 0;
163
164 /**
165 * Returns the size of each bin, in pixels.
166 */
167 virtual Size2D<uint32_t> getBinSize() const = 0;
168
169 /**
170 * Returns the number of bins in both the horizontal (width) and vertical (height) directions.
171 * This size is equivalent to the array dimensions for the output from
172 * IBayerAverageMap::getAverages() or IBayerAverageMap::getClipCounts().
173 */
174 virtual Size2D<uint32_t> getBinCount() const = 0;
175
176 /**
177 * Returns the bin intervals for both the x and y axis. These intervals are defined as the
178 * number of pixels between the first pixel of a bin and that of the immediate next bin.
179 */
180 virtual Size2D<uint32_t> getBinInterval() const = 0;
181
182 /**
183 * Returns the working range of the averaging calculation. The working range is defined as
184 * the range of values that are included in the average calculation (e.g. not clipped),
185 * and may extend beyond the normalized [0.0, 1.0] range of the optical output. For example,
186 * if the working range is [-0.5, 1.5], this means that values in [-0.5, 0) and (1, 1.5] will
187 * still be included in the average calculation despite being clipped to [0.0, 1.0] in the
188 * output pixels. Any pixels outside this working range are excluded from average calculation
189 * and will increment the clip count.
190 * @see IBayerAverageMap::getClipCounts()
191 *
192 * @note When the bit depth available for averaging is equal to the optical bit depth of
193 * the output, the working range will be less than the full [0.0, 1.0] optical range. For
194 * example, when 10 bits of data are available, the raw output pixels in [0u, 1023u] will
195 * map to [0.0, 1.0]; however, the values of 0 and 1023 will be considered clipped for the
196 * sake of average calculation, and so the working range would be [1/1023.0, 1022/1023.0].
197 */
198 virtual Range<float> getWorkingRange() const = 0;
199
200 /**
201 * Returns the average values for all bins. These values are normalized such that
202 * [0.0, 1.0] maps to the optical range of the output, but the range of possible values
203 * is determined by the working range. For input pixels that have values outside the
204 * working range, the API excludes such pixels from the average calculation and
205 * increments the clipped pixel counter for the containing region.
206 * @see IBayerAverageMap::getWorkingRange()
207 * @see IBayerAverageMap::getClipCounts()
208 *
209 * @param[out] averages The output array to store the averages for all bins. This
210 * 2-dimensional array is sized as returned by IBayerAverageMap::getBinCount(),
211 * where each array element is a floating point BayerTuple containing the R,
212 * G_EVEN, G_ODD, and B averages for that bin.
213 */
214 virtual Status getAverages(Array2D< BayerTuple<float> >* averages) const = 0;
215
216 /**
217 * Returns the clipped pixel counts for all bins. This is the number of pixels in the bin
218 * whose value exceeds the working range and have been excluded from average calculation.
219 * @see IBayerAverageMap::getWorkingRange()
220 *
221 * @param[out] clipCounts The output array to store the clip counts for all bins. This
222 * 2-dimensional array is sized as returned by
223 * Ext::IBayerAverageMap::getBinCount(), where each array element is an uint32_t
224 * BayerTuple containing the R, G_EVEN, G_ODD, and B clip counts for that bin.
225 */
226 virtual Status getClipCounts(Array2D< BayerTuple<uint32_t> >* clipCounts) const = 0;
227
228 protected:
229 ~IBayerAverageMap() {}
230 };
231
232 } // namespace Ext
233
234 } // namespace Argus
235
236 #endif // _ARGUS_EXT_BAYER_AVERAGE_MAP_H