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