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
Settings.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_SETTINGS_H
30 #define _ARGUS_SETTINGS_H
31
32 namespace Argus
33 {
34
35 /**
36 * @class ISourceSettings
37 * - Exposed by the InterfaceProvider returned by IRequest::getSourceSettings().
38 *
39 * An interface to settings that control the sensor module.
40 */
41 DEFINE_UUID(InterfaceID, IID_SOURCE_SETTINGS, eb7ae38c,3c62,4161,a92a,a6,4f,ba,c6,38,83);
42
43 class ISourceSettings : public Interface
44 {
45 public:
46 static const InterfaceID& id() { return IID_SOURCE_SETTINGS; }
47
48 /**
49 * Sets the exposure time range of the source, in nanoseconds.
50 * If the exposure range is outside of the available range, the capture's exposure time
51 * will be as close as possible to the exposure range specified.
52 * @param[in] exposureTimeRange Exposure time range, in nanoseconds.
53 * @see ISensorMode::getExposureTimeRange()
54 * @todo: Have a discussion on quantization.
55 *
56 * @returns success/status of the call.
57 */
58 virtual Status setExposureTimeRange(const Range<uint64_t>& exposureTimeRange) = 0;
59
60 /**
61 * Returns the exposure time range of the source, in nanoseconds.
62 */
63 virtual Range<uint64_t> getExposureTimeRange() const = 0;
64
65 /**
66 * Sets the focus position, in focuser units. If the position
67 * is set outside of the focuser limits, the position will be clamped.
68 * @param[in] position The new focus position, in focuser units.
69 * @see ICameraProperties::getFocusPositionRange()
70 *
71 * @returns success/status of the call.
72 */
73 virtual Status setFocusPosition(int32_t position) = 0;
74
75 /**
76 * Returns the focus position, in focuser units.
77 */
78 virtual int32_t getFocusPosition() const = 0;
79
80 /**
81 * Sets the frame duration range, in nanoseconds.
82 * If frame range is out of bounds of the current sensor mode,
83 * the capture's frame duration will be as close as possible to the range specified.
84 * @param[in] frameDurationRange Frame duration range, in nanoseconds
85 * @see ISensorMode::getFrameDurationRange()
86 *
87 * @returns success/status of the call.
88 */
89 virtual Status setFrameDurationRange(const Range<uint64_t>& frameDurationRange) = 0;
90
91 /**
92 * Returns the frame duration range, in nanoseconds.
93 */
94 virtual Range<uint64_t> getFrameDurationRange() const = 0;
95
96 /**
97 * Sets the gain range for the sensor.
98 * The range has to be within the max and min reported in the CameraProperties
99 * Otherwise the range will be clipped.
100 * @param[in] gainRange scalar gain range
101 * @see ISensorMode::getAnalogGainRange()
102 *
103 * @returns success/status of the call.
104 */
105 virtual Status setGainRange(const Range<float>& gainRange) = 0;
106
107 /**
108 * Returns the gain range.
109 */
110 virtual Range<float> getGainRange() const = 0;
111
112 /**
113 * Sets the sensor mode.
114 * Note that changing sensor mode from one capture to the next may result in
115 * multiple sensor frames being dropped between the two captures.
116 * @param[in] mode Desired sensor mode for the capture.
117 * @see ICameraProperties::getSensorModes()
118 *
119 * @returns success/status of the call.
120 */
121 virtual Status setSensorMode(SensorMode* mode) = 0;
122
123 /**
124 * Returns the sensor mode.
125 */
126 virtual SensorMode* getSensorMode() const = 0;
127
128 protected:
129 ~ISourceSettings() {}
130 };
131
132 /** @class IAutoControlSettings
133 * - Exposed by the InterfaceProvider returned by IRequest::getAutocontrolSettings().
134 *
135 * An interface to settings related to autocontrol.
136 */
137 DEFINE_UUID(InterfaceID, IID_AUTO_CONTROL_SETTINGS, 1f2ad1c6,cb13,440b,bc95,3f,fd,0d,19,91,db);
138
139 class IAutoControlSettings : public Interface
140 {
141 public:
142 static const InterfaceID& id() { return IID_AUTO_CONTROL_SETTINGS; }
143
144 /**
145 * Sets the AE antibanding mode.
146 * @param[in] mode The requested antibanding mode.
147 *
148 * @returns success/status of the call.
149 */
150 virtual Status setAeAntibandingMode(AeAntibandingMode mode) = 0;
151
152 /**
153 * Returns the AE antibanding mode.
154 */
155 virtual AeAntibandingMode getAeAntibandingMode() const = 0;
156
157 /**
158 * Sets the AE lock. When locked, AE will maintain constant exposure.
159 * @param[in] lock If @c true, locks AE at its current exposure.
160 *
161 * @returns success/status of the call.
162 */
163 virtual Status setAeLock(bool lock) = 0;
164
165 /**
166 * Returns the AE lock.
167 */
168 virtual bool getAeLock() const = 0;
169
170 /**
171 * Sets the AE regions of interest.
172 * If no regions are specified, the entire image is the region of interest.
173 * @param[in] regions The AE regions of interest.
174 * The maximum number of regions is returned by @c ICameraProperties::getMaxAeRegions().
175 *
176 * @returns success/status of the call.
177 */
178 virtual Status setAeRegions(const std::vector<AcRegion>& regions) = 0;
179
180 /**
181 * Returns the AE regions of interest.
182 * @param[out] regions, a vector that will be populated with the AE regions of interest.
183 *
184 * @returns success/status of the call.
185 */
186 virtual Status getAeRegions(std::vector<AcRegion>* regions) const = 0;
187
188 /**
189 * Sets the AWB lock.
190 * @param[in] lock If @c true, locks AWB at its current state.
191 *
192 * @returns success/status of the call.
193 */
194 virtual Status setAwbLock(bool lock) = 0;
195
196 /**
197 * Returns the AWB lock.
198 */
199 virtual bool getAwbLock() const = 0;
200
201 /**
202 * Sets the AWB mode.
203 * @param[in] mode The new AWB mode.
204 *
205 * @returns success/status of the call.
206 */
207 virtual Status setAwbMode(const AwbMode& mode) = 0;
208
209 /**
210 * Returns the AWB mode.
211 */
212 virtual AwbMode getAwbMode() const = 0;
213
214 /**
215 * Sets the AWB regions of interest.
216 * If no regions are specified, the entire image is the region of interest.
217 * @param[in] regions The AWB regions of interest.
218 * The maximum number of regions is returned by @c ICameraProperties::getMaxAwbRegions().
219 *
220 * @returns success/status of the call.
221 */
222 virtual Status setAwbRegions(const std::vector<AcRegion>& regions) = 0;
223
224 /**
225 * Returns the AWB regions of interest.
226 * @param[out] regions, a vector that will be populated with the AWB regions of interest.
227 *
228 * @returns success/status of the call.
229 */
230 virtual Status getAwbRegions(std::vector<AcRegion>* regions) const = 0;
231
232 /**
233 * Sets the Manual White Balance gains.
234 * @param[in] gains The Manual White Balance Gains
235 *
236 * @returns success/status of the call.
237 */
238 virtual Status setWbGains(const BayerTuple<float>& gains) = 0;
239
240 /**
241 * Returns the Manual White Balance gains.
242 *
243 * @returns Manual White Balance Gains structure
244 */
245 virtual BayerTuple<float> getWbGains() const = 0;
246
247 /**
248 * Returns the size of the color correction matrix.
249 */
250 virtual Size getColorCorrectionMatrixSize() const = 0;
251
252 /**
253 * Sets the user-specified color correction matrix.
254 * This matrix will be ignored unless <tt>getColorCorrectionMatrixEnable() == true</tt>.
255 * The active color correction matrix used for image processing may be internally modified
256 * to account for the active color saturation value (either user-specified or automatically
257 * generated, after biasing, @see setColorSaturation and @see setColorSaturationBias).
258 * @param[in] matrix A color correction matrix that maps sensor RGB to linear sRGB. This matrix
259 * is given in row-major order and must have the size w*h, where w and h are
260 * the width and height of the Size returned by getColorCorrectionMatrixSize()
261 *
262 * @returns success/status of the call.
263 */
264 virtual Status setColorCorrectionMatrix(const std::vector<float>& matrix) = 0;
265
266 /**
267 * Returns the user-specified color correction matrix.
268 * @param[out] matrix, A matrix that will be populated with the CCM.
269 *
270 * @returns success/status of the call.
271 */
272 virtual Status getColorCorrectionMatrix(std::vector<float>* matrix) const = 0;
273
274 /**
275 * Enables the user-specified color correction matrix.
276 * @param[in] enable If @c true, Argus will use the user-specified matrix.
277 * @see setColorCorrectionMatrix()
278 *
279 * @returns success/status of the call.
280 */
281 virtual Status setColorCorrectionMatrixEnable(bool enable) = 0;
282
283 /**
284 * Returns the enable for the user-specified color correction matrix.
285 */
286 virtual bool getColorCorrectionMatrixEnable() const = 0;
287
288 /**
289 * Sets the user-specified absolute color saturation. This must be enabled via
290 * @see setColorSaturationEnable, otherwise saturation will be determined automatically.
291 * This saturation value may be used to modify the color correction matrix used
292 * for processing (@see setColorCorrectionMatrix), and these changes will be reflected
293 * in the color correction matrix output to the capture metadata.
294 * @param[in] saturation The absolute color saturation. Acceptable values are in
295 * [0.0, 2.0], and the default value is 1.0.
296
297 * @returns success/status of the call.
298 */
299 virtual Status setColorSaturation(float saturation) = 0;
300
301 /**
302 * Returns the user-specified absolute color saturation (@see setColorSaturation).
303 */
304 virtual float getColorSaturation() const = 0;
305
306 /**
307 * Enables the user-specified absolute color saturation.
308 * @param[in] enable If @c true, Argus will use the user-specified color saturation.
309 * @see setColorSaturation()
310 *
311 * @returns success/status of the call.
312 */
313 virtual Status setColorSaturationEnable(bool enable) = 0;
314
315 /**
316 * Returns the enable for the user-specified color saturation.
317 */
318 virtual bool getColorSaturationEnable() const = 0;
319
320 /**
321 * Sets the color saturation bias. This bias is used to multiply the active saturation
322 * value, either the user-specified or the automatically generated value depending on the state
323 * of @see getColorSaturationEnable, and produces the final saturation value to use for
324 * capture processing. This is used primarily to tweak automatically generated saturation
325 * values when the application prefers more or less saturation than what the implementation
326 * or hardware generates by default. The final saturation value (after biasing) may affect the
327 * color correction matrix used for processing (@see setColorCorrectionMatrix).
328 * @param[in] bias The color saturation bias. Acceptable values are in [0.0, 2.0], where
329 * 1.0 does not modify the saturation (default), 0.0 is fully desaturated
330 * (greyscale), and 2.0 is highly saturated.
331 *
332 * @returns success/status of the call.
333 */
334 virtual Status setColorSaturationBias(float bias) = 0;
335
336 /**
337 * Returns the color saturation bias.
338 */
339 virtual float getColorSaturationBias() const = 0;
340
341 /**
342 * Sets the exposure compensation.
343 * Exposure compensation is applied after AE is solved.
344 * @param[in] ev The exposure adjustment step in stops.
345 *
346 * @returns success/status of the call.
347 */
348 virtual Status setExposureCompensation(float ev) = 0;
349
350 /**
351 * Returns the exposure compensation.
352 */
353 virtual float getExposureCompensation() const = 0;
354
355 /**
356 * Returns the number of elements required for the tone map curve.
357 * @param[in] channel The color channel the curve size corresponds to.
358 */
359 virtual uint32_t getToneMapCurveSize(RGBColorChannel channel) const = 0;
360
361 /**
362 * Sets the user-specified tone map curve for a channel on the stream.
363 * The user-specified tone map will be ignored unless <tt>getToneMapCurveEnable() == true</tt>.
364 * @param[in] channel The color the curve corresponds to.
365 * @param[in] curve A float vector that describes the LUT.
366 * The number of elements must match the number of elements
367 * returned from getToneMapCurve() of the same channel.
368 *
369 * @returns success/status of the call.
370 */
371 virtual Status setToneMapCurve(RGBColorChannel channel, const std::vector<float>& curve) = 0;
372
373 /**
374 * Returns the user-specified tone map curve for a channel on the stream.
375 * @param[in] channel The color the curve corresponds to.
376 * @param[out] curve A vector that will be populated by the tone map curve for the specified
377 * color channel.
378 *
379 * @returns success/status of the call.
380 */
381 virtual Status getToneMapCurve(RGBColorChannel channel, std::vector<float>* curve) const = 0;
382
383 /**
384 * Enables the user-specified tone map.
385 * @param[in] enable If @c true, Argus will use the user-specified tone map.
386 *
387 * @returns success/status of the call.
388 */
389 virtual Status setToneMapCurveEnable(bool enable) = 0;
390
391 /**
392 * Returns the enable for the user-specified tone map.
393 */
394 virtual bool getToneMapCurveEnable() const = 0;
395
396 protected:
397 ~IAutoControlSettings() {}
398 };
399
400 /**
401 * @class IStreamSettings
402 * - Exposed by the per-Stream InterfaceProviders returned by IRequest::getStreamSettings().
403 *
404 * An interface to per-stream settings.
405 */
406 DEFINE_UUID(InterfaceID, IID_STREAM_SETTINGS, c477aeaf,9cc8,4467,a834,c7,07,d7,b6,9f,a4);
407
408 class IStreamSettings : public Interface
409 {
410 public:
411 static const InterfaceID& id() { return IID_STREAM_SETTINGS; }
412
413 /**
414 * Sets the clip rectangle for the stream.
415 * A clip rectangle is a normalized rectangle
416 * with valid coordinates contained in the [0.0,1.0] range.
417 * @param[in] clipRect The clip rectangle.
418 *
419 * @returns success/status of the call.
420 */
421 virtual Status setSourceClipRect(const NormalizedRect& clipRect) = 0;
422
423 /**
424 * Returns the clip rectangle for the stream.
425 */
426 virtual NormalizedRect getSourceClipRect() const = 0;
427
428 /**
429 * Sets whether or not post-processing is enabled for this stream.
430 * Post-processing features are controlled on a per-Request basis and all streams share the
431 * same post-processing control values, but this enable allows certain streams to be excluded
432 * from all post-processing. The current controls defined to be a part of "post-processing"
433 * includes:
434 * - Denoise
435 * - Video Stabilization
436 * Default value is true.
437 */
438 virtual void setPostProcessingEnable(bool enable) = 0;
439
440 /**
441 * Returns the post-processing enable for the stream.
442 */
443 virtual bool getPostProcessingEnable() const = 0;
444
445 protected:
446 ~IStreamSettings() {}
447 };
448
449 /**
450 * @class IDenoiseSettings
451 * - Exposed by Request objects.
452 *
453 * An interface to control denoise (noise reduction) algorithms.
454 */
455 DEFINE_UUID(InterfaceID, IID_DENOISE_SETTINGS, 7A461D20,6AE1,11E6,BDF4,08,00,20,0C,9A,66);
456
457 class IDenoiseSettings : public Interface
458 {
459 public:
460 static const InterfaceID& id() { return IID_DENOISE_SETTINGS; }
461
462 /**
463 * Sets the denoise (noise reduction) mode for the request.
464 * @param[in] mode The denoise mode:
465 * OFF: Denoise algorithms are disabled.
466 * FAST: Noise reduction will be enabled, but it will not slow down
467 * the capture rate.
468 * HIGH_QUALITY: Maximum noise reduction will be enabled to achieve
469 * the highest quality, but may slow down the capture rate.
470 * @returns success/status of the call.
471 */
472 virtual Status setDenoiseMode(const DenoiseMode& mode) = 0;
473
474 /**
475 * Returns the denoise mode for the request.
476 */
477 virtual DenoiseMode getDenoiseMode() const = 0;
478
479 /**
480 * Sets the strength for the denoise operation.
481 * @param[in] strength The denoise strength. This must be within the range [0.0, 1.0], where
482 * 0.0 is the least and 1.0 is the most amount of noise reduction that can be
483 * applied. This denoise strength is relative to the current noise reduction mode;
484 * using a FAST denoise mode with a full strength of 1.0 may not perform as well
485 * as using a HIGH_QUALITY mode with a lower relative strength.
486 * @returns success/status of the call.
487 */
488 virtual Status setDenoiseStrength(float strength) = 0;
489
490 /**
491 * Returns the denoise strength.
492 */
493 virtual float getDenoiseStrength() const = 0;
494
495 protected:
496 ~IDenoiseSettings() {}
497 };
498
499 /**
500 * @class IEdgeEnhanceSettings
501 * - Exposed by Request objects.
502 *
503 * An interface to control edge enhancement algorithms.
504 */
505 DEFINE_UUID(InterfaceID, IID_EDGE_ENHANCE_SETTINGS, 7A461D21,6AE1,11E6,BDF4,08,00,20,0C,9A,66);
506
507 class IEdgeEnhanceSettings : public Interface
508 {
509 public:
510 static const InterfaceID& id() { return IID_EDGE_ENHANCE_SETTINGS; }
511
512 /**
513 * Sets the edge enhancement mode for the request.
514 * @param[in] mode The edge enhancement mode:
515 * OFF: Edge enhancement algorithms are disabled.
516 * FAST: Edge enhancement will be enabled, but it will not slow down
517 * the capture rate.
518 * HIGH_QUALITY: Maximum edge enhancement will be enabled to achieve
519 * the highest quality, but may slow down the capture rate.
520 * @returns success/status of the call.
521 */
522 virtual Status setEdgeEnhanceMode(const EdgeEnhanceMode& mode) = 0;
523
524 /**
525 * Returns the edge enhancement mode for the request.
526 */
527 virtual EdgeEnhanceMode getEdgeEnhanceMode() const = 0;
528
529 /**
530 * Sets the strength for the edge enhancement operation.
531 * @param[in] strength The edge enhancement strength. This must be within the range [0.0, 1.0],
532 * where 0.0 is the least and 1.0 is the most amount of edge enhancement that can be
533 * applied. This strength is relative to the current edge enhancement mode; using
534 * a FAST edge enhancement mode with a full strength of 1.0 may not perform as well
535 * as using a HIGH_QUALITY mode with a lower relative strength.
536 * @returns success/status of the call.
537 */
538 virtual Status setEdgeEnhanceStrength(float strength) = 0;
539
540 /**
541 * Returns the edge enhancement strength.
542 */
543 virtual float getEdgeEnhanceStrength() const = 0;
544
545 protected:
546 ~IEdgeEnhanceSettings() {}
547 };
548
549 /**
550 * @class IVideoStabilizationSettings
551 * - Exposed by Request objects.
552 *
553 * An interface to control video stabilization algorithms.
554 */
555 DEFINE_UUID(InterfaceID, IID_VIDEO_STABILIZATION_SETTINGS, 7A461D22,6AE1,11E6,BDF4,08,00,20,0C,9A,66);
556
557 class IVideoStabilizationSettings : public Interface
558 {
559 public:
560 static const InterfaceID& id() { return IID_VIDEO_STABILIZATION_SETTINGS; }
561
562 /**
563 * Sets the video stabilization mode to use for the request.
564 * @param[in] mode The video stabilization mode.
565 *
566 * @returns success/status of the call.
567 */
568 virtual Status setVideoStabilizationMode(const VideoStabilizationMode& mode) = 0;
569
570 /**
571 * Returns the video stabilization mode for the request.
572 */
573 virtual VideoStabilizationMode getVideoStabilizationMode() const = 0;
574
575 protected:
576 ~IVideoStabilizationSettings() {}
577 };
578
579 } // namespace Argus
580
581 #endif // _ARGUS_SETTINGS_H