Libargus API
Libargus Camera API
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
FaceDetect.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016-2017, 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 Extension: Face Detect API</b>
32  *
33  * @b Description: This file defines the FaceDetect extension.
34  */
35 
36 #ifndef _ARGUS_FACE_DETECT_H
37 #define _ARGUS_FACE_DETECT_H
38 
39 namespace Argus
40 {
41 
42 /**
43  * Adds internal face-detection algorithms. It introduces four new interfaces:
44  * - IFaceDetectCaps; exposes the face detection capabilities of a CaptureSession.
45  * - IFaceDetectSettings; used to enable face detection for a Request.
46  * - IFaceDetectMetadata; returns a list of FaceDetectResult objects from a
47  * completed capture's CaptureMetadata.
48  * - IFaceDetectResult; exposes the image rect and confidence level of a result object
49  * returned by getFaceDetectResults.
50  *
51  * @defgroup ArgusExtFaceDetect Ext::FaceDetect
52  * @ingroup ArgusExtensions
53  */
54 DEFINE_UUID(ExtensionName, EXT_FACE_DETECT, 40412bb0,ba24,11e5,a837,08,00,20,0c,9a,66);
55 
56 namespace Ext
57 {
58 
59 /**
60  * @class IFaceDetectCaps
61  *
62  * Interface to expose the face detection capabilities of a CaptureSession.
63  *
64  * @ingroup ArgusCaptureSession ArgusExtFaceDetect
65  */
66 DEFINE_UUID(InterfaceID, IID_FACE_DETECT_CAPS, 40412bb0,ba24,11e5,a837,08,00,20,0c,9a,66);
67 class IFaceDetectCaps : public Interface
68 {
69 public:
70  static const InterfaceID& id() { return IID_FACE_DETECT_CAPS; }
71 
72  /**
73  * Returns the maximum number of faces that can be detected by the face detection
74  * algorithm per request. Returned value must be >= 1.
75  */
76  virtual uint32_t getMaxFaceDetectResults() const = 0;
77 
78 protected:
80 };
81 
82 /**
83  * @class IFaceDetectSettings
84  *
85  * Interface to face detection settings.
86  *
87  * @ingroup ArgusRequest ArgusExtFaceDetect
88  */
89 DEFINE_UUID(InterfaceID, IID_FACE_DETECT_SETTINGS, 40412bb1,ba24,11e5,a837,08,00,20,0c,9a,66);
91 {
92 public:
93  static const InterfaceID& id() { return IID_FACE_DETECT_SETTINGS; }
94 
95  /**
96  * Enables or disables face detection. When face detection is enabled the CaptureMetadata
97  * returned by completed captures will expose the IFaceDetectMetadata interface and the
98  * FaceDetectResults returned by this interface will expose the IFaceDetectResults interface.
99  * @param[in] enable whether or not face detection is enabled.
100  */
101  virtual void setFaceDetectEnable(bool enable) = 0;
102 
103  /**
104  * @returns whether or not face detection is enabled.
105  */
106  virtual bool getFaceDetectEnable() const = 0;
107 
108 protected:
110 };
111 
112 /**
113  * @class IFaceDetectMetadata
114  *
115  * Interface to overall face detection results metadata.
116  *
117  * @ingroup ArgusCaptureMetadata ArgusExtFaceDetect
118  *
119  * @defgroup ArgusFaceDetectResult FaceDetectResult
120  * Metadata for a single face detection result, returned by
121  * Ext::IFaceDetectMetadata::getFaceDetectResults
122  * @ingroup ArgusCaptureMetadata
123  */
124 DEFINE_UUID(InterfaceID, IID_FACE_DETECT_METADATA, 40412bb2,ba24,11e5,a837,08,00,20,0c,9a,66);
126 {
127 public:
128  static const InterfaceID& id() { return IID_FACE_DETECT_METADATA; }
129 
130  /**
131  * @returns the face detection results.
132  * @param[out] results A vector that will be populated with the face detect results.
133  *
134  * @returns success/status of the call.
135  */
136  virtual Status getFaceDetectResults(std::vector<InterfaceProvider*>* results) const = 0;
137 
138 protected:
140 };
141 
142 /**
143  * @class IFaceDetectResult
144  *
145  * Interface to the properties of a single face detection result.
146  *
147  * @ingroup ArgusFaceDetectResult ArgusExtFaceDetect
148  */
149 DEFINE_UUID(InterfaceID, IID_FACE_DETECT_RESULT, 40412bb3,ba24,11e5,a837,08,00,20,0c,9a,66);
151 {
152 public:
153  static const InterfaceID& id() { return IID_FACE_DETECT_RESULT; }
154 
155  /**
156  * @returns the normlized coordinates of the region containing the face, relative
157  * to the uncropped image sensor mode size.
158  */
159  virtual Rectangle<float> getRect() const = 0;
160 
161  /**
162  * @returns the confidence level of the result. This confidence is in the range
163  * [0, 1], where 1 is the highest confidence. For a typical application that
164  * highlights faces in a scene, filtering results to ignore those with a
165  * confidence less than 0.5 is suggested.
166  */
167  virtual float getConfidence() const = 0;
168 
169 protected:
171 };
172 
173 } // namespace Ext
174 
175 } // namespace Argus
176 
177 #endif // _ARGUS_FACE_DETECT_H