Argus API Argus Camera API

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

- File List
- File Members

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 */
39 class CaptureMetadata : public InterfaceProvider
40 {
41 protected:
42 ~CaptureMetadata() {}
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 */
51 class CaptureMetadataContainer : public InterfaceProvider, public Destructable
52 {
53 protected:
54 ~CaptureMetadataContainer() {}
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
89 ~IBayerHistogram() {}
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
124 ~IRGBHistogram() {}
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
135 class IStreamCaptureMetadata : public Interface
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
148 ~IStreamCaptureMetadata() {}
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
159 class ICaptureMetadata : public Interface
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:
345 ~ICaptureMetadata() {}
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
354 class IDenoiseMetadata : public Interface
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:
370 ~IDenoiseMetadata() {}
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
379 class IEdgeEnhanceMetadata : public Interface
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:
395 ~IEdgeEnhanceMetadata() {}
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
404 class IVideoStabilizationMetadata : public Interface
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:
415 ~IVideoStabilizationMetadata() {}
416 };
417
418 } // namespace Argus
419
420 #endif // _ARGUS_CAPTURE_METADATA_H