Argus API
Argus Camera API
 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::getAllSensorModes()
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:
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 
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  */
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  */
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(RGBChannel 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(RGBChannel 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(RGBChannel 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  /**
397  * Sets the user-specified Isp Digital gain range.
398  * @param[in] The user-specified Isp Digital gain
399  *
400  * @returns success/status of the call.
401  */
402  virtual Status setIspDigitalGainRange(const Range<float>& gain) = 0;
403 
404  /**
405  * Returns the user-specified Isp Digital gain range
406  *
407  * @returns Isp Digital gain
408  */
409  virtual Range<float> getIspDigitalGainRange() const = 0;
410 
411 protected:
413 };
414 
415 /**
416  * @class IStreamSettings
417  * - Exposed by the per-Stream InterfaceProviders returned by IRequest::getStreamSettings().
418  *
419  * An interface to per-stream settings.
420  */
421 DEFINE_UUID(InterfaceID, IID_STREAM_SETTINGS, c477aeaf,9cc8,4467,a834,c7,07,d7,b6,9f,a4);
422 
424 {
425 public:
426  static const InterfaceID& id() { return IID_STREAM_SETTINGS; }
427 
428  /**
429  * Sets the clip rectangle for the stream.
430  * A clip rectangle is a normalized rectangle
431  * with valid coordinates contained in the [0.0,1.0] range.
432  * @param[in] clipRect The clip rectangle.
433  *
434  * @returns success/status of the call.
435  */
436  virtual Status setSourceClipRect(const Rectangle<float>& clipRect) = 0;
437 
438  /**
439  * Returns the clip rectangle for the stream.
440  */
441  virtual Rectangle<float> getSourceClipRect() const = 0;
442 
443  /**
444  * Sets whether or not post-processing is enabled for this stream.
445  * Post-processing features are controlled on a per-Request basis and all streams share the
446  * same post-processing control values, but this enable allows certain streams to be excluded
447  * from all post-processing. The current controls defined to be a part of "post-processing"
448  * includes:
449  * - Denoise
450  * - Video Stabilization
451  * Default value is true.
452  */
453  virtual void setPostProcessingEnable(bool enable) = 0;
454 
455  /**
456  * Returns the post-processing enable for the stream.
457  */
458  virtual bool getPostProcessingEnable() const = 0;
459 
460 protected:
462 };
463 
464 /**
465  * @class IDenoiseSettings
466  * - Exposed by Request objects.
467  *
468  * An interface to control denoise (noise reduction) algorithms.
469  */
470 DEFINE_UUID(InterfaceID, IID_DENOISE_SETTINGS, 7A461D20,6AE1,11E6,BDF4,08,00,20,0C,9A,66);
471 
473 {
474 public:
475  static const InterfaceID& id() { return IID_DENOISE_SETTINGS; }
476 
477  /**
478  * Sets the denoise (noise reduction) mode for the request.
479  * @param[in] mode The denoise mode:
480  * OFF: Denoise algorithms are disabled.
481  * FAST: Noise reduction will be enabled, but it will not slow down
482  * the capture rate.
483  * HIGH_QUALITY: Maximum noise reduction will be enabled to achieve
484  * the highest quality, but may slow down the capture rate.
485  * @returns success/status of the call.
486  */
487  virtual Status setDenoiseMode(const DenoiseMode& mode) = 0;
488 
489  /**
490  * Returns the denoise mode for the request.
491  */
492  virtual DenoiseMode getDenoiseMode() const = 0;
493 
494  /**
495  * Sets the strength for the denoise operation.
496  * @param[in] strength The denoise strength. This must be within the range [0.0, 1.0], where
497  * 0.0 is the least and 1.0 is the most amount of noise reduction that can be
498  * applied. This denoise strength is relative to the current noise reduction mode;
499  * using a FAST denoise mode with a full strength of 1.0 may not perform as well
500  * as using a HIGH_QUALITY mode with a lower relative strength.
501  * @returns success/status of the call.
502  */
503  virtual Status setDenoiseStrength(float strength) = 0;
504 
505  /**
506  * Returns the denoise strength.
507  */
508  virtual float getDenoiseStrength() const = 0;
509 
510 protected:
512 };
513 
514 /**
515  * @class IEdgeEnhanceSettings
516  * - Exposed by Request objects.
517  *
518  * An interface to control edge enhancement algorithms.
519  */
520 DEFINE_UUID(InterfaceID, IID_EDGE_ENHANCE_SETTINGS, 7A461D21,6AE1,11E6,BDF4,08,00,20,0C,9A,66);
521 
523 {
524 public:
525  static const InterfaceID& id() { return IID_EDGE_ENHANCE_SETTINGS; }
526 
527  /**
528  * Sets the edge enhancement mode for the request.
529  * @param[in] mode The edge enhancement mode:
530  * OFF: Edge enhancement algorithms are disabled.
531  * FAST: Edge enhancement will be enabled, but it will not slow down
532  * the capture rate.
533  * HIGH_QUALITY: Maximum edge enhancement will be enabled to achieve
534  * the highest quality, but may slow down the capture rate.
535  * @returns success/status of the call.
536  */
537  virtual Status setEdgeEnhanceMode(const EdgeEnhanceMode& mode) = 0;
538 
539  /**
540  * Returns the edge enhancement mode for the request.
541  */
542  virtual EdgeEnhanceMode getEdgeEnhanceMode() const = 0;
543 
544  /**
545  * Sets the strength for the edge enhancement operation.
546  * @param[in] strength The edge enhancement strength. This must be within the range [0.0, 1.0],
547  * where 0.0 is the least and 1.0 is the most amount of edge enhancement that can be
548  * applied. This strength is relative to the current edge enhancement mode; using
549  * a FAST edge enhancement mode with a full strength of 1.0 may not perform as well
550  * as using a HIGH_QUALITY mode with a lower relative strength.
551  * @returns success/status of the call.
552  */
553  virtual Status setEdgeEnhanceStrength(float strength) = 0;
554 
555  /**
556  * Returns the edge enhancement strength.
557  */
558  virtual float getEdgeEnhanceStrength() const = 0;
559 
560 protected:
562 };
563 
564 /**
565  * @class IVideoStabilizationSettings
566  * - Exposed by Request objects.
567  *
568  * An interface to control video stabilization algorithms.
569  */
570 DEFINE_UUID(InterfaceID, IID_VIDEO_STABILIZATION_SETTINGS, 7A461D22,6AE1,11E6,BDF4,08,00,20,0C,9A,66);
571 
573 {
574 public:
575  static const InterfaceID& id() { return IID_VIDEO_STABILIZATION_SETTINGS; }
576 
577  /**
578  * Sets the video stabilization mode to use for the request.
579  * @param[in] mode The video stabilization mode.
580  *
581  * @returns success/status of the call.
582  */
583  virtual Status setVideoStabilizationMode(const VideoStabilizationMode& mode) = 0;
584 
585  /**
586  * Returns the video stabilization mode for the request.
587  */
588  virtual VideoStabilizationMode getVideoStabilizationMode() const = 0;
589 
590 protected:
592 };
593 
594 } // namespace Argus
595 
596 #endif // _ARGUS_SETTINGS_H