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
CaptureMetadata.h
Go to the documentation of this file.
1 /*
2 * Copyright (c) 2016-2018, 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 */
48 class CaptureMetadata : public InterfaceProvider
49 {
50 protected:
51 ~CaptureMetadata() {}
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 */
60 class CaptureMetadataContainer : public InterfaceProvider, public Destructable
61 {
62 protected:
63 ~CaptureMetadataContainer() {}
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
99 ~IBayerHistogram() {}
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
135 ~IRGBHistogram() {}
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);
146 class IStreamCaptureMetadata : public Interface
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
159 ~IStreamCaptureMetadata() {}
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);
182 class ICaptureMetadata : public Interface
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 @c clientData value for the Request used in the capture
199 * that generated this metadata.
200 *
201 * @see ICaptureSession::createRequest()
202 */
203 virtual uint32_t getClientData() const = 0;
204
205 /**
206 * Returns the per-stream metadata provider for @c stream.
207 * This object will provide the IStreamCaptureMetadata interface.
208 */
209 virtual InterfaceProvider* getStreamMetadata(const OutputStream* stream) const = 0;
210
211 /**
212 * Returns the Bayer histogram for this capture.
213 * This object will provide the IBayerHistogram interface.
214 */
215 virtual const InterfaceProvider* getBayerHistogram() const = 0;
216
217 /**
218 * Returns the RGB histogram for this capture.
219 * This object will provide the IRGBHistogram interface.
220 */
221 virtual const InterfaceProvider* getRGBHistogram() const = 0;
222
223 /**
224 * Returns true if and only if AE was locked for this capture.
225 */
226 virtual bool getAeLocked() const = 0;
227
228 /**
229 * Gets the AE regions of interest used for this capture.
230 *
231 * @param[in] regions A vector that will be populated with the AE regions used in capture.
232 *
233 * @returns success/status of the call.
234 */
235 virtual Status getAeRegions(std::vector<AcRegion>* regions) const = 0;
236
237 /**
238 * Returns the state of AE when it ran for this capture.
239 */
240 virtual AeState getAeState() const = 0;
241
242 /**
243 * Returns the focuser position used for this capture (in focuser steps).
244 */
245 virtual int32_t getFocuserPosition() const = 0;
246
247 /**
248 * Returns the CCT calculated by AWB for this capture.
249 */
250 virtual uint32_t getAwbCct() const = 0;
251
252 /**
253 * Returns the AWB gains used for this capture.
254 */
255 virtual BayerTuple<float> getAwbGains() const = 0;
256
257 /**
258 * Returns the AWB mode used for this capture.
259 */
260 virtual AwbMode getAwbMode() const = 0;
261
262 /**
263 * Gets the AWB regions of interest used for this capture.
264 *
265 * @param[in] regions A vector that will be populated with the AWB regions used in capture.
266 *
267 * @returns success/status of the call.
268 */
269 virtual Status getAwbRegions(std::vector<AcRegion>* regions) const = 0;
270
271 /**
272 * @returns the state of AWB when it ran for this capture.
273 */
274 virtual AwbState getAwbState() const = 0;
275
276 /**
277 * Gets the current AWB WB estimate as a vector of NUM_AWB_WB_ESTIMATE_ELEMENTS values.
278 * @todo Document the meaning of an AWB WB estimate.
279 *
280 * @param[in] estimate A vector that will be populated with the AWB WB estimates.
281 *
282 * @returns success/status of the call.
283 */
284 virtual Status getAwbWbEstimate(std::vector<float>* estimate) const = 0;
285
286 /**
287 * Returns the enable state for the client-supplied Color Correction Matrix.
288 */
289 virtual bool getColorCorrectionMatrixEnable() const = 0;
290
291 /**
292 * Gets the 3x3 client-supplied Color Correction Matrix as a flattened
293 * (row-major) vector of 9 values. This matrix is irrelevant if
294 * <tt>getColorCorrectionMatrixEnable() == false</tt>.
295 *
296 * @param[in] ccMatrix A vector that will be populated with the color correction matrix.
297 *
298 * @returns success/status of the call.
299 */
300 virtual Status getColorCorrectionMatrix(std::vector<float>* ccMatrix) const = 0;
301
302 /**
303 * Returns the color saturation value used for this capture (including biasing).
304 */
305 virtual float getColorSaturation() const = 0;
306
307 /**
308 * Returns the time it took to integrate this capture (in nanoseconds).
309 * @todo Provide a more precise description of frame duration.
310 */
311 virtual uint64_t getFrameDuration() const = 0;
312
313 /**
314 * Returns the digital gain used for this capture.
315 */
316 virtual float getIspDigitalGain() const = 0;
317
318 /**
319 * Returns the frame readout time for this capture (in nanoseconds) from
320 * the beginning of the first line to the beginning of the last line.
321 */
322 virtual uint64_t getFrameReadoutTime() const = 0;
323
324 /**
325 * Returns the estimated scene brightness for this capture (in lux).
326 */
327 virtual float getSceneLux() const = 0;
328
329 /**
330 * Returns the sensor analog gain used for this capture.
331 */
332 virtual float getSensorAnalogGain() const = 0;
333
334 /**
335 * Returns the sensor exposure time for this capture (in nanoseconds).
336 */
337 virtual uint64_t getSensorExposureTime() const = 0;
338
339 /**
340 * Returns the ISO value used for this capture.
341 */
342 virtual uint32_t getSensorSensitivity() const = 0;
343
344 /**
345 * Returns the start timestamp for the sensor (in nanoseconds).
346 * This is the time that the first data from this capture arrives from the sensor.
347 */
348 virtual uint64_t getSensorTimestamp() const = 0;
349
350 /**
351 * Returns true if and only if a user-specified tone map curve was used for this capture.
352 */
353 virtual bool getToneMapCurveEnabled() const = 0;
354
355 /**
356 * Returns the specified color channel for the tone mapping table
357 * (as a vector of NUM_TONE_MAP_ELEMENTS values). These values are irrelevant if
358 * <tt>getToneMapCurveEnabled() == false</tt>.
359 *
360 * @param[in] channel Specified the color channel for which the curve will be returned.
361 * @param[in] curve A vector that will be populated with the color curve used in capture.
362 *
363 * @returns success/status of the call.
364 */
365 virtual Status getToneMapCurve(RGBChannel channel, std::vector<float>* curve) const = 0;
366
367 protected:
368 ~ICaptureMetadata() {}
369 };
370
371 /**
372 * @class IDenoiseMetadata
373 *
374 * Interface to denoise metadata.
375 *
376 * @ingroup ArgusCaptureMetadata
377 */
378 DEFINE_UUID(InterfaceID, IID_DENOISE_METADATA, 7A461D23,6AE1,11E6,BDF4,08,00,20,0C,9A,66);
379 class IDenoiseMetadata : public Interface
380 {
381 public:
382 static const InterfaceID& id() { return IID_DENOISE_METADATA; }
383
384 /**
385 * Returns the denoise mode used for the capture.
386 */
387 virtual DenoiseMode getDenoiseMode() const = 0;
388
389 /**
390 * Returns the denoise strength used for the capture.
391 */
392 virtual float getDenoiseStrength() const = 0;
393
394 protected:
395 ~IDenoiseMetadata() {}
396 };
397
398 /**
399 * @class IEdgeEnhanceMetadata
400 *
401 * Interface to edge enhancement metadata.
402 *
403 * @ingroup ArgusCaptureMetadata
404 */
405 DEFINE_UUID(InterfaceID, IID_EDGE_ENHANCE_METADATA, 7A461D24,6AE1,11E6,BDF4,08,00,20,0C,9A,66);
406 class IEdgeEnhanceMetadata : public Interface
407 {
408 public:
409 static const InterfaceID& id() { return IID_EDGE_ENHANCE_METADATA; }
410
411 /**
412 * Returns the edge enhancement mode used for the capture.
413 */
414 virtual EdgeEnhanceMode getEdgeEnhanceMode() const = 0;
415
416 /**
417 * Returns the edge enhancement strength used for the capture.
418 */
419 virtual float getEdgeEnhanceStrength() const = 0;
420
421 protected:
422 ~IEdgeEnhanceMetadata() {}
423 };
424
425 } // namespace Argus
426
427 #endif // _ARGUS_CAPTURE_METADATA_H