Argus API
Argus Camera API
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
CaptureMetadata.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_CAPTURE_METADATA_H
30 #define _ARGUS_CAPTURE_METADATA_H
31 
32 
33 namespace Argus
34 {
35 
36 /**
37  * A container for metadata from a single capture.
38  */
40 {
41 protected:
43 };
44 
45 /**
46  * An object that holds a CaptureMetadata instance
47  * and is used to read the capture metadata from a consumer thread directly from
48  * the embedded EGLStream metadata. It exposes the same interfaces as
49  * CaptureMetadata, but is owned by the consumer.
50  */
52 {
53 protected:
55 };
56 
57 
58 /**
59  * @class IBayerHistogram
60  *
61  * An interface to a histogram created from Bayer pixel data.
62  * Bins are evenly distributed across the possible range of values, each containing
63  * the number of pixels whose value fell within the range for that bin.
64  */
65 DEFINE_UUID(InterfaceID, IID_BAYER_HISTOGRAM, 50bc4f1c,6424,beb7,baae,b0,90,c9,c3,25,9e);
66 
67 class IBayerHistogram : public Interface
68 {
69 public:
70 
71  static const InterfaceID& id() { return IID_BAYER_HISTOGRAM; }
72 
73  /**
74  * Returns the number of bins in the histogram.
75  */
76  virtual uint32_t getBinCount() const = 0;
77 
78  /**
79  * Returns the histogram data.
80  *
81  * @param[out] histogram The output vector to store the histogram data. Upon successful
82  * return, this vector will be replaced with getBinCount() bin values,
83  * each containing per-channel pixel counts within a BayerTuple container.
84  */
85  virtual Status getHistogram(std::vector< BayerTuple<uint32_t> >* histogram) const = 0;
86 
87 protected:
88 
90 };
91 
92 
93 /**
94  * @class IRGBHistogram
95  *
96  * An interface to a histogram created from Bayer pixel data.
97  * Bins are evenly distributed across the possible range of values, each containing
98  * the number of pixels whose value fell within the range for that bin.
99  */
100  DEFINE_UUID(InterfaceID, IID_RGB_HISTOGRAM, 50bc4f1d,6424,beb7,baae,b0,90,c9,c3,25,9e);
101 
102 class IRGBHistogram : public Interface
103 {
104 public:
105 
106  static const InterfaceID& id() { return IID_RGB_HISTOGRAM; }
107 
108  /**
109  * Returns the number of bins in the histogram.
110  */
111  virtual uint32_t getBinCount() const = 0;
112 
113  /**
114  * Returns the histogram data.
115  *
116  * @param[out] histogram The output vector to store the histogram data. Upon successful
117  * return, this vector will be replaced with getBinCount() bin values,
118  * each containing per-channel pixel counts within an RGBTuple container.
119  */
120  virtual Status getHistogram(std::vector< RGBTuple<uint32_t> >* histogram) const = 0;
121 
122 protected:
123 
125 };
126 
127 
128 /**
129  * @class IStreamCaptureMetadata
130  *
131  * An interface that reports metadata for a single stream in a single capture.
132  */
133 DEFINE_UUID(InterfaceID, IID_STREAM_CAPTURE_METADATA, 61cbe0a8,0ee1,4c67,baae,02,02,1a,b8,d9,47);
134 
136 {
137 public:
138 
139  static const InterfaceID& id() { return IID_STREAM_CAPTURE_METADATA; }
140 
141  /**
142  * Returns the clip rectangle used for this stream.
143  */
144  virtual Rectangle<float> getSourceClipRect() const = 0;
145 
146 protected:
147 
149 };
150 
151 
152 /**
153  * @class ICaptureMetadata
154  *
155  * An interface that reports metadata for a single capture.
156  */
157 DEFINE_UUID(InterfaceID, IID_CAPTURE_METADATA, 5f6ac5d4,59e8,45d0,8bac,38,09,1f,f8,74,a9);
158 
160 {
161 public:
162 
163  static const InterfaceID& id() { return IID_CAPTURE_METADATA; }
164 
165  static const uint32_t NUM_COLOR_CORRECTION_ELEMENTS = 9;
166  static const uint32_t NUM_AWB_WB_ESTIMATE_ELEMENTS = 4;
167 
168  /**
169  * Returns the capture id (the value returned from ICaptureSession::capture())
170  * of the capture that generated this metadata.
171  */
172  virtual uint32_t getCaptureId() const = 0;
173 
174  /**
175  * Returns the @c clientData value for the Request used in the capture
176  * that generated this metadata.
177  *
178  * @see ICaptureSession::createRequest()
179  */
180  virtual uint32_t getClientData() const = 0;
181 
182  /**
183  * Returns the per-stream metadata provider for @c stream.
184  * This object will provide the IStreamCaptureMetadata interface.
185  */
186  virtual InterfaceProvider* getStreamMetadata(const OutputStream* stream) const = 0;
187 
188  /**
189  * Returns the Bayer histogram for this capture.
190  * This object will provide the IBayerHistogram interface.
191  */
192  virtual const InterfaceProvider* getBayerHistogram() const = 0;
193 
194  /**
195  * Returns the RGB histogram for this capture.
196  * This object will provide the IRGBHistogram interface.
197  */
198  virtual const InterfaceProvider* getRGBHistogram() const = 0;
199 
200  /**
201  * Returns true if and only if AE was locked for this capture.
202  */
203  virtual bool getAeLocked() const = 0;
204 
205  /**
206  * Gets the AE regions of interest used for this capture.
207  *
208  * @param[in] regions A vector that will be populated with the AE regions used in capture.
209  *
210  * @returns success/status of the call.
211  */
212  virtual Status getAeRegions(std::vector<AcRegion>* regions) const = 0;
213 
214  /**
215  * Returns the state of AE when it ran for this capture.
216  */
217  virtual AeState getAeState() const = 0;
218 
219  /**
220  * Returns the focuser position used for this capture (in focuser steps).
221  */
222  virtual int32_t getFocuserPosition() const = 0;
223 
224  /**
225  * Returns the CCT calculated by AWB for this capture.
226  */
227  virtual uint32_t getAwbCct() const = 0;
228 
229  /**
230  * Returns the AWB gains used for this capture.
231  */
232  virtual BayerTuple<float> getAwbGains() const = 0;
233 
234  /**
235  * Returns the AWB mode used for this capture.
236  */
237  virtual AwbMode getAwbMode() const = 0;
238 
239  /**
240  * Gets the AWB regions of interest used for this capture.
241  *
242  * @param[in] regions A vector that will be populated with the AWB regions used in capture.
243  *
244  * @returns success/status of the call.
245  */
246  virtual Status getAwbRegions(std::vector<AcRegion>* regions) const = 0;
247 
248  /**
249  * @returns the state of AWB when it ran for this capture.
250  */
251  virtual AwbState getAwbState() const = 0;
252 
253  /**
254  * Gets the current AWB WB estimate as a vector of NUM_AWB_WB_ESTIMATE_ELEMENTS values.
255  * @todo DOC describe getAwbWbEstimate() really.
256  *
257  * @param[in] estimate A vector that will be populated with the AWB WB estimates.
258  *
259  * @returns success/status of the call.
260  */
261  virtual Status getAwbWbEstimate(std::vector<float>* estimate) const = 0;
262 
263  /**
264  * Returns the enable state for the client-supplied Color Correction Matrix.
265  */
266  virtual bool getColorCorrectionMatrixEnable() const = 0;
267 
268  /**
269  * Gets the 3x3 client-supplied Color Correction Matrix as a flattened
270  * (row-major) vector of 9 values. This matrix is irrelevant if
271  * <tt>getColorCorrectionMatrixEnable() == false</tt>.
272  *
273  * @param[in] ccMatrix A vector that will be populated with the color correction matrix.
274  *
275  * @returns success/status of the call.
276  */
277  virtual Status getColorCorrectionMatrix(std::vector<float>* ccMatrix) const = 0;
278 
279  /**
280  * Returns the color saturation value used for this capture (including biasing).
281  */
282  virtual float getColorSaturation() const = 0;
283 
284  /**
285  * Returns the time it took to integrate this capture (in nanoseconds).
286  * @todo DOC a more precise description
287  */
288  virtual uint64_t getFrameDuration() const = 0;
289 
290  /**
291  * Returns the digital gain used for this capture.
292  */
293  virtual float getIspDigitalGain() const = 0;
294 
295  /**
296  * Returns the frame readout time for this capture (in nanoseconds) from
297  * the beginning of the first line to the beginning of the last line.
298  */
299  virtual uint64_t getFrameReadoutTime() const = 0;
300 
301  /**
302  * Returns the estimated scene brightness for this capture (in lux).
303  */
304  virtual float getSceneLux() const = 0;
305 
306  /**
307  * Returns the sensor analog gain used for this capture.
308  */
309  virtual float getSensorAnalogGain() const = 0;
310 
311  /**
312  * Returns the sensor exposure time for this capture (in nanoseconds).
313  */
314  virtual uint64_t getSensorExposureTime() const = 0;
315 
316  /**
317  * Returns the ISO value used for this capture.
318  */
319  virtual uint32_t getSensorSensitivity() const = 0;
320 
321  /**
322  * Returns the start timestamp for the sensor (in nanoseconds).
323  * This is the time that the first data from this capture arrives from the sensor.
324  */
325  virtual uint64_t getSensorTimestamp() const = 0;
326 
327  /**
328  * Returns true if and only if a user-specified tone map curve was used for this capture.
329  */
330  virtual bool getToneMapCurveEnabled() const = 0;
331 
332  /**
333  * Returns the specified color channel for the tone mapping table
334  * (as a vector of NUM_TONE_MAP_ELEMENTS values). These values are irrelevant if
335  * <tt>getToneMapCurveEnabled() == false</tt>.
336  *
337  * @param[in] channel Specified the color channel for which the curve will be returned.
338  * @param[in] curve A vector that will be populated with the color curve used in capture.
339  *
340  * @returns success/status of the call.
341  */
342  virtual Status getToneMapCurve(RGBChannel channel, std::vector<float>* curve) const = 0;
343 
344 protected:
346 };
347 
348 /**
349  * @class IDenoiseMetadata
350  * - Exposed by CaptureMetadata objects.
351  */
352 DEFINE_UUID(InterfaceID, IID_DENOISE_METADATA, 7A461D23,6AE1,11E6,BDF4,08,00,20,0C,9A,66);
353 
355 {
356 public:
357  static const InterfaceID& id() { return IID_DENOISE_METADATA; }
358 
359  /**
360  * Returns the denoise mode used for the capture.
361  */
362  virtual DenoiseMode getDenoiseMode() const = 0;
363 
364  /**
365  * Returns the denoise strength used for the capture.
366  */
367  virtual float getDenoiseStrength() const = 0;
368 
369 protected:
371 };
372 
373 /**
374  * @class IEdgeEnhanceMetadata
375  * - Exposed by CaptureMetadata objects.
376  */
377 DEFINE_UUID(InterfaceID, IID_EDGE_ENHANCE_METADATA, 7A461D24,6AE1,11E6,BDF4,08,00,20,0C,9A,66);
378 
380 {
381 public:
382  static const InterfaceID& id() { return IID_EDGE_ENHANCE_METADATA; }
383 
384  /**
385  * Returns the edge enhancement mode used for the capture.
386  */
387  virtual EdgeEnhanceMode getEdgeEnhanceMode() const = 0;
388 
389  /**
390  * Returns the edge enhancement strength used for the capture.
391  */
392  virtual float getEdgeEnhanceStrength() const = 0;
393 
394 protected:
396 };
397 
398 /**
399  * @class IVideoStabilizationMetadata
400  * - Exposed by CaptureMetadata objects.
401  */
402 DEFINE_UUID(InterfaceID, IID_VIDEO_STABILIZATION_METADATA, 7A461D25,6AE1,11E6,BDF4,08,00,20,0C,9A,66);
403 
405 {
406 public:
407  static const InterfaceID& id() { return IID_VIDEO_STABILIZATION_METADATA; }
408 
409  /**
410  * Returns the video stabilization mode used for the capture.
411  */
412  virtual VideoStabilizationMode getVideoStabilizationMode() const = 0;
413 
414 protected:
416 };
417 
418 } // namespace Argus
419 
420 #endif // _ARGUS_CAPTURE_METADATA_H