2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
20 * @file FUixVisionFaceDetector.h
21 * @brief This is the header file for the %FaceDetector class.
23 * This header file contains the declarations of the %FaceDetector class.
26 #ifndef _FUIX_VISION_FACE_DETECTOR_H_
27 #define _FUIX_VISION_FACE_DETECTOR_H_
29 #include <FBaseDataType.h>
30 #include <FBaseObject.h>
31 #include <FGrpBitmapCommon.h>
32 #include <FGrpPixelFormat.h>
33 #include <FUixVisionFaceTypes.h>
34 #include <FUixVisionFaceBuffer.h>
35 #include <FUixVisionFaceComponentsPosition.h>
37 namespace Tizen { namespace Base
42 namespace Tizen { namespace Base { namespace Collection
45 template< class Type > class IListT;
48 namespace Tizen { namespace Graphics
55 namespace Tizen { namespace Uix { namespace Vision
57 class _FaceDetectorImpl;
61 * @brief This class is used to trace faces in an image or a video.
65 * @remarks @b Header @b %file: @b \#include @b <FUix.h> @n
66 * @b Library : @b osp-face
68 * The %FaceDetector class provides the ability to automatically detect and trace faces in a still image or a video stream.
70 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/uix/face_detector_recognizer.htm">Face Detector and Recognizer</a>.
72 * The following example demonstrates how to use the %FaceDetector class.
77 * #include <FGraphics.h>
81 * using namespace Tizen::Base;
82 * using namespace Tizen::Media;
83 * using namespace Tizen::Graphics;
84 * using namespace Tizen::Io;
85 * using namespace Tizen::Uix::Vision;
88 * MyClass::TestFaceDetect(void)
90 * ByteBuffer* pByteBuffer = null;
91 * int width = 0, height = 0;
92 * result r = E_SUCCESS;
94 * Image* pImage = new Image();
95 * r = pImage->Construct();
97 * String path(L"test.bmp");
99 * pByteBuffer = pImage->DecodeToBufferN(path, BITMAP_PIXEL_FORMAT_RGB565,width,height );
101 * //Deletes the image object
107 * FaceDetector faceDetect;
108 * r = faceDetect.Construct();
109 * const Tizen::Base::Collection::IList* pFaceDetectList = faceDetect.DetectFacesFromStillImageN(*pByteBuffer, Dimension(width,height), BITMAP_PIXEL_FORMAT_RGB565);
111 * if(pFaceDetectList == null)
113 * delete pByteBuffer;
114 * return GetLastResult();
117 * for(int i=0; i < pFaceDetectList->GetCount(); i++)
119 * Tizen::Graphics::Rectangle* pRect = (Tizen::Graphics::Rectangle*)pFaceDetectList->GetAt(i);
122 * delete pFaceDetectList;
129 class _OSP_EXPORT_ FaceDetector
130 : public Tizen::Base::Object
136 * This is the default constructor for this class. @n
137 * The object is not fully constructed after this constructor is called.
138 * For full construction, the Construct() method must be called right after calling this constructor.
145 * This is the destructor for this class. @n
146 * The resources are deallocated by this method.
147 * This destructor overrides Tizen::Base::Object::~Object().
151 virtual ~FaceDetector(void);
157 * Initializes this instance of %FaceDetector.
161 * @feature %http://tizen.org/feature/vision.face_recognition
162 * @return An error code
163 * @exception E_SUCCESS The method is successful.
164 * @exception E_UNSUPPORTED_OPERATION The target device does not support the face detection feature. @b Since: @b 2.1
165 * For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
166 * @remarks Before calling this method, check whether the feature is supported by the %Tizen::System::SystemInfo::GetValue() methods.
170 result Construct(void);
173 * Gets the range and default value of the specified configuration property.
177 * @return An error code
178 * @param[in] configProperty The property to query
179 * @param[out] min The minimum value of the property
180 * @param[out] max The maximum value of the property
181 * @param[out] steppingDelta The step size for the property @n
182 * The step size is the smallest increment by which the property can be changed.
183 * @param[out] defaultVal The default value of the property
184 * @exception E_SUCCESS The method is successful.
185 * @exception E_UNSUPPORTED_OPERATION The device does not support this property.
187 result GetRange(FaceDetectorConfigProperty configProperty, long& min, long& max, long& steppingDelta, long& defaultVal) const;
190 * Sets the value of the specified property.
194 * @return An error code
195 * @param[in] configProperty The property to query
196 * @param[in] value The new value of the property
197 * @exception E_SUCCESS The method is successful.
198 * @exception E_UNSUPPORTED_OPERATION The device does not support this property.
199 * @exception E_OUT_OF_RANGE The specified @c value is out of range.
202 result SetProperty(FaceDetectorConfigProperty configProperty, long value);
205 * Gets the current setting of the specified configuration property.
209 * @return The value of the property, @n
210 * else @c -1 if an exception occurs
211 * @param[in] configProperty The property to query
212 * @exception E_SUCCESS The method is successful.
213 * @exception E_UNSUPPORTED_OPERATION The device does not support this property.
214 * @remarks The specific error code can be accessed using the GetLastResult() method.
216 long GetProperty(FaceDetectorConfigProperty configProperty) const;
219 * Gets a list of supported pixel formats.
223 * @return A list of the supported pixel formats that are used in the DetectFacesFromVideoStreamN() method @n
224 * The format is in the form of a string.
225 * @exception E_SUCCESS The method is successful.
226 * @exception E_OUT_OF_MEMORY The memory is insufficient.
227 * @remarks The specific error code can be accessed using the GetLastResult() method.
229 Tizen::Base::Collection::IListT< Tizen::Graphics::PixelFormat >* GetSupportedFormatListN(void) const;
232 * Searches for faces from a video.
236 * @return A list of the detected face positions @n
237 * Each list's item has a pointer of Tizen::Graphics::Rectangle value. @n
238 * An empty list, if there are no detected faces and there is no error. @n
239 * The faces are not detected when the faces are too small or the video data is not clear. @n
240 * This is the result of a normal operation, @n
241 * else @c null if an exception occurs.
242 * @param[in] byteBuffer The buffer containing the video data
243 * @param[in] dim The width and height of the video data @n
244 * Both the width and height must be greater than @c 0.
245 * @param[in] format The format of video data @n
246 * It must be one of the pixel formats extracted from GetSupportedFormatListN().
247 * @exception E_SUCCESS The method is successful.
248 * @exception E_INVALID_ARG A specified input parameter is invalid.
249 * @exception E_OUT_OF_MEMORY The memory is insufficient.
250 * @exception E_FAILURE A system error has occurred.
251 * @remarks The specific error code can be accessed using the GetLastResult() method.
253 Tizen::Base::Collection::IList* DetectFacesFromVideoStreamN(const Tizen::Base::ByteBuffer& byteBuffer, const Tizen::Graphics::Dimension& dim, const Tizen::Graphics::PixelFormat format);
257 * Detects faces from a still image.
259 * @brief <i> [Deprecated] </i>
260 * @deprecated This method is deprecated as it may return an improper result.
261 * Instead of using this method, use DetectFacesFromStillImageN(Tizen::Base::ByteBuffer &, Tizen::Graphics::Dimension &, Tizen::Graphics::BitmapPixelFormat).
262 * To optimize the memory usage and processing time, the bitmap scales down an image by decreasing its resolution in some models,
263 * that in turn decreases the accuracy of the face library. Therefore, the usage of this method using Tizen::Base::ByteBuffer is encouraged.
266 * @return A list of the detected face positions @n
267 * Each list's item has a pointer of Tizen::Graphics::Rectangle value. @n
268 * An empty list, if there are no detected faces and there is no error @n
269 * The faces are not detected when the faces are too small or the image is not clear. @n
270 * This is the result of a normal operation, @n
271 * else @c null if an exception occurs.
272 * @param[in] bitmap The bitmap file containing the input image data
273 * @exception E_SUCCESS The method is successful.
274 * @exception E_OUT_OF_MEMORY The memory is insufficient.
275 * @exception E_FAILURE A system error has occurred.
277 * - The specific error code can be accessed using the GetLastResult() method.
278 * - BitmapPixelFormat::BITMAP_PIXEL_FORMAT_R8G8B8A8 is not applicable for this method.
281 Tizen::Base::Collection::IList* DetectFacesFromStillImageN(const Tizen::Graphics::Bitmap& bitmap);
284 * Searches for faces from a still image.
288 * @return A list of the detected face positions @n
289 * Each list's item has a pointer of Tizen::Graphics::Rectangle value. @n
290 * An empty list, if there are no detected faces and there is no error @n
291 * The faces are not detected when the faces are too small or the image is not clear. @n
292 * This is the result of a normal operation, @n
293 * else @c null if an exception occurs.
294 * @param[in] byteBuffer The buffer containing the input image data
295 * @param[in] dim The width and height of the input image @n
296 * Both the width and height must be greater than @c 0.
297 * @param[in] format The color format @n
298 * @c BITMAP_PIXEL_FORMAT_R8G8B8A8 is not applicable for this method.
299 * @exception E_SUCCESS The method is successful.
300 * @exception E_INVALID_ARG A specified input parameter is invalid.
301 * @exception E_OUT_OF_MEMORY The memory is insufficient.
302 * @exception E_FAILURE A system error has occurred.
303 * @remarks The specific error code can be accessed using the GetLastResult() method.
305 Tizen::Base::Collection::IList* DetectFacesFromStillImageN(const Tizen::Base::ByteBuffer& byteBuffer, const Tizen::Graphics::Dimension& dim, Tizen::Graphics::BitmapPixelFormat format);
309 * Converts the input data to a proper data format that can be used in the face related methods.
313 * @return The preprocessed data, @n
314 * else @c null if an exception occurs
315 * @param[in] byteBuffer The buffer containing the input data
316 * @param[in] dim The width and height of the input data @n
317 * Both the width and height must be greater than @c 0.
318 * @param[in] format The format of the input data @n
319 * It must be one of the pixel formats extracted from GetSupportedFormatListN().
320 * @exception E_SUCCESS The method is successful.
321 * @exception E_INVALID_ARG A specified input parameter is invalid.
322 * @exception E_OUT_OF_MEMORY The memory is insufficient.
323 * @exception E_SYSTEM A system error has occurred.
324 * @remarks The specific error code can be accessed using the GetLastResult() method.
326 FaceBuffer* PreprocessDataN(const Tizen::Base::ByteBuffer& byteBuffer, const Tizen::Graphics::Dimension& dim, Tizen::Graphics::PixelFormat format);
329 * Searches for faces from the preprocessed data.
333 * @return A list of the detected face positions @n
334 * Each list's item has a pointer of Tizen::Graphics::Rectangle value. @n
335 * An empty list, if there are no detected faces and there is no error. @n
336 * The faces are not detected when the faces are too small or the input data is not clear. @n
337 * This is the result of a normal operation, @n
338 * else @c null if an exception occurs.
339 * @param[in] preprocessedFaceBuffer The preprocessed data @n
340 * The @c preprocessedFaceBuffer must be obtained from PreprocessDataN().
341 * @param[in] option The working option of detecting faces
342 * @exception E_SUCCESS The method is successful.
343 * @exception E_UNSUPPORTED_OPERATION The specified mode is not supported.
344 * @exception E_OUT_OF_MEMORY The memory is insufficient.
345 * @exception E_SYSTEM A system error has occurred.
346 * @remarks The specific error code can be accessed using the GetLastResult() method.
347 * @see FaceDetectorConfigProperty
349 Tizen::Base::Collection::IList* DetectFacesN(const FaceBuffer& preprocessedFaceBuffer, FaceDetectionOption option = FACE_DETECTION_OPTION_FAST);
352 * Extracts the facial components information.
356 * @return The facial components information, @n
357 * else @c null if an exception occurs
358 * @param[in] preprocessedFaceBuffer The preprocessed data @n
359 * The @c preprocessedFaceBuffer must be obtained from PreprocessDataN().
360 * @param[in] faceRect The position of the detected face that is from DetectFacesN() @n
361 * The value of x and y positions for the @c faceRect parameter must be greater than or equal to @c 0. @n
362 * The value of width and height for the @c faceRect parameter must be greater than @c 0. @n
363 * The position of @c faceRect must be within @c preprocessedFaceBuffer.
364 * @exception E_SUCCESS The method is successful.
365 * @exception E_INVALID_ARG A specified input parameter is invalid.
366 * @exception E_SYSTEM A system error has occurred.
367 * @exception E_OPERATION_FAILED The method has failed to extract the facial information, but there is no error reported. @n
368 * This happens when the detected faces are too small or the input data is not clear. This is the result of a normal operation.
369 * @remarks The specific error code can be accessed using the GetLastResult() method.
371 FaceComponentsPosition* ExtractFaceComponentsN(const FaceBuffer& preprocessedFaceBuffer, const Tizen::Graphics::Rectangle& faceRect);
375 * Gets the position difference of the face. @n
376 * The %GetFaceMovement() method can be used for tracking the face from a sequential video data.
380 * @return An error code
381 * @param[in] prevData The buffer containing the previous video data
382 * @param[in] curData The buffer containing the current video data @n
383 * The size of @c prevData and @c curData must be the same. @n
384 * The @c prevData and @c curData must be gotten from PreprocessDataN().
385 * @param[in] prevFaceRect The region of the face inside @c prevData @n
386 * The value of x and y positions for the @c prevFaceRect parameter must be greater than or equal to @c 0. @n
387 * The value of width and height for the @c prevFaceRect parameter must be greater than @c 0. @n
388 * The specified @c prevFaceRect must be within @c prevData.
389 * @param[out] xDiff The x offset that is moved from the previous to current video data
390 * @param[out] yDiff The y offset that is moved from the previous to current video data
391 * @exception E_SUCCESS The method is successful.
392 * @exception E_INVALID_ARG A specified input parameter is invalid.
393 * @exception E_OPERATION_FAILED The method has failed to get the position difference of the specified region, but there is no error reported. @n
394 * In this case, @c xDiff and @c yDiff are returned with @c 0. @n
395 * It can happen when the detected faces are too small or two video data are different even if they contain the same face.
396 * This is the result of a normal operation.
397 * @remarks The specific error code can be accessed using the GetLastResult() method.
398 * @see DetectFacesN()
400 result GetFaceMovement(const FaceBuffer& prevData, const FaceBuffer& curData, const Tizen::Graphics::Rectangle& prevFaceRect, int& xDiff, int& yDiff);
404 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
406 FaceDetector(const FaceDetector& value);
408 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
410 FaceDetector& operator =(const FaceDetector& value);
411 friend class _FaceDetectorImpl;
415 _FaceDetectorImpl* __pFaceDetectorImpl;
419 } } } // Tizen::Uix::Vision
421 #endif // _FUIX_VISION_FACE_DETECTOR_H_