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