Libargus API
Libargus Camera API
 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);
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:
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);
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:
230 };
231 
232 } // namespace Ext
233 
234 } // namespace Argus
235 
236 #endif // _ARGUS_EXT_BAYER_AVERAGE_MAP_H