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