inc/FUixVisionFaceDetector.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  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.
  16 //
  17
  18
  19 /**
  20  * @file     FUixVisionFaceDetector.h
  21  * @brief    This is the header file for the %FaceDetector class.
  22  *
  23  * This header file contains the declarations of the %FaceDetector class.
  24  */
  25
  26 #ifndef _FUIX_VISION_FACE_DETECTOR_H_
  27 #define _FUIX_VISION_FACE_DETECTOR_H_
  28
  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>
  36
  37 namespace Tizen { namespace Base
  38 {
  39 class ByteBuffer;
  40 } }
  41
  42 namespace Tizen { namespace Base { namespace Collection
  43 {
  44 class IList;
  45 template<class Type> class IListT;
  46 } } }
  47
  48 namespace Tizen { namespace Graphics
  49 {
  50 class Bitmap;
  51 class Dimension;
  52 class Rectangle;
  53 } }
  54
  55 namespace Tizen { namespace Uix { namespace Vision
  56 {
  57 class _FaceDetectorImpl;
  58
  59 /**
  60  * @class    FaceDetector
  61  * @brief    This class is used to trace faces in an image or a video.
  62  *
  63  * @since    2.0
  64  *
  65  * @remarks  @b Header @b %file: @b \#include @b <FUix.h> @n
  66  *           @b Library : @b osp-face
  67  *
  68  * The %FaceDetector class provides the ability to automatically detect and trace faces in a still image or a video stream.
  69  * @n
  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>.
  71  *
  72  * The following example demonstrates how to use the %FaceDetector class.
  73  *
  74  * @code
  75  * #include <FBase.h>
  76  * #include <FUix.h>
  77  * #include <FGraphics.h>
  78  * #include <FIo.h>
  79  * #include <FMedia.h>
  80  *
  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;
  86  *
  87  * result
  88  * MyClass::TestFaceDetect(void)
  89  * {
  90  *         ByteBuffer* pByteBuffer = null;
  91  *         int width = 0, height = 0;
  92  *         result r = E_SUCCESS;
  93  *
  94  *         Image* pImage = new Image();
  95  *         r = pImage->Construct();
  96  *
  97  *         String path(L"test.bmp");
  98  *
  99  *         pByteBuffer = pImage->DecodeToBufferN(path, BITMAP_PIXEL_FORMAT_RGB565,width,height );
 100  *
 101  *         //Deletes the image object
 102  *         delete pImage;
 103  *
 104  *         if (pByteBuffer)
 105  *         {
 106  *             //Detects faces
 107  *             FaceDetector faceDetect;
 108  *             r = faceDetect.Construct();
 109  *             const Tizen::Base::Collection::IList* pFaceDetectList = faceDetect.DetectFacesFromStillImageN(*pByteBuffer, Dimension(width,height), BITMAP_PIXEL_FORMAT_RGB565);
 110  *
 111  *             if(pFaceDetectList == null)
 112  *             {
 113  *                 delete pByteBuffer;
 114  *                 return GetLastResult();
 115  *             }
 116  *
 117  *             for(int i=0; i < pFaceDetectList->GetCount(); i++)
 118  *             {
 119  *                 Tizen::Graphics::Rectangle* pRect = (Tizen::Graphics::Rectangle*)pFaceDetectList->GetAt(i);
 120  *             }
 121  *
 122  *             delete pFaceDetectList;
 123  *         }
 124  *
 125  *         return r;
 126  * }
 127  * @endcode
 128  */
 129 class _OSP_EXPORT_ FaceDetector
 130         : public Tizen::Base::Object
 131 {
 132
 133 // Lifecycle
 134 public:
 135         /**
 136          * This is the default constructor for this class.
 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.
 139          *
 140          * @since    2.0
 141          */
 142         FaceDetector(void);
 143
 144         /**
 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().
 148          *
 149          * @since    2.0
 150          */
 151         virtual ~FaceDetector(void);
 152
 153
 154 // Operation
 155
 156         /**
 157          * Initializes this instance of %FaceDetector.
 158          *
 159          * @since        2.0
 160          *
 161          * @return       An error code
 162          * @exception    E_SUCCESS          The method is successful.
 163          * @exception    E_OUT_OF_MEMORY    The memory is insufficient.
 164          */
 165         result Construct(void);
 166
 167         /**
 168          * Gets the range and default value of the specified configuration property.
 169          *
 170          * @since         2.0
 171          *
 172          * @return        An error code
 173          * @param[in]     configProperty             The property to query
 174          * @param[out]    min                        The minimum value of the property
 175          * @param[out]    max                        The maximum value of the property
 176          * @param[out]    steppingDelta              The step size for the property @n
 177          *                                           The step size is the smallest increment by which the property can be changed.
 178          * @param[out]    defaultVal                 The default value of the property
 179          * @exception     E_SUCCESS                  The method is successful.
 180          * @exception     E_UNSUPPORTED_OPERATION    The device does not support this property.
 181          */
 182         result GetRange(FaceDetectorConfigProperty configProperty, long& min, long& max, long& steppingDelta, long& defaultVal) const;
 183
 184         /**
 185          * Sets the value of the specified property.
 186          *
 187          * @since        2.0
 188          *
 189          * @return       An error code
 190          * @param[in]    configProperty             The property to query
 191          * @param[in]    value                      The new value of the property
 192          * @exception    E_SUCCESS                  The method is successful.
 193          * @exception    E_UNSUPPORTED_OPERATION    The device does not support this property.
 194          * @exception    E_OUT_OF_RANGE             The specified @c value is out of range.
 195          * @see          GetRange()
 196          */
 197         result SetProperty(FaceDetectorConfigProperty configProperty, long value);
 198
 199         /**
 200          * Gets the current setting of the specified configuration property.
 201          *
 202          * @since        2.0
 203          *
 204          * @return       The value of the property, @n
 205          *               else @c -1 if an exception occurs
 206          * @param[in]    configProperty             The property to query
 207          * @exception    E_SUCCESS                  The method is successful.
 208          * @exception    E_UNSUPPORTED_OPERATION    The device does not support this property.
 209          * @remarks      The specific error code can be accessed using the GetLastResult() method.
 210          */
 211         long GetProperty(FaceDetectorConfigProperty configProperty) const;
 212
 213         /**
 214          * Gets a list of supported pixel formats.
 215          *
 216          * @since        2.0
 217          *
 218          * @return       A list of the supported pixel formats that are used in the DetectFacesFromVideoStreamN() method @n
 219          *               The format is in the form of a string.
 220          * @exception    E_SUCCESS          The method is successful.
 221          * @exception    E_OUT_OF_MEMORY    The memory is insufficient.
 222          * @remarks      The specific error code can be accessed using the GetLastResult() method.
 223          */
 224         Tizen::Base::Collection::IListT <Tizen::Graphics::PixelFormat>* GetSupportedFormatListN(void) const;
 225
 226         /**
 227          * Searches for faces from a video.
 228          *
 229          * @since        2.0
 230          *
 231          * @return       A list of the detected face positions @n
 232          *               Each list's item has a pointer of Tizen::Graphics::Rectangle value. @n
 233          *               An empty list, if there are no detected faces and there is no error. @n
 234          *               The faces are not detected when the faces are too small or the video data is not clear. @n
 235          *               This is the result of a normal operation, @n
 236          *               else @c null if an exception occurs.
 237          * @param[in]    byteBuffer         The buffer containing the video data
 238          * @param[in]    dim                The width and height of the video data @n
 239          *                                  Both the width and height must be greater than @c 0.
 240          * @param[in]    format             The format of video data @n
 241          *                                  It must be one of the pixel formats extracted from GetSupportedFormatListN().
 242          * @exception    E_SUCCESS          The method is successful.
 243          * @exception    E_INVALID_ARG      A specified input parameter is invalid.
 244          * @exception    E_OUT_OF_MEMORY    The memory is insufficient.
 245          * @exception    E_FAILURE          A system error has occurred.
 246          * @remarks      The specific error code can be accessed using the GetLastResult() method.
 247          */
 248         Tizen::Base::Collection::IList* DetectFacesFromVideoStreamN(const Tizen::Base::ByteBuffer& byteBuffer, const Tizen::Graphics::Dimension& dim, const Tizen::Graphics::PixelFormat format);
 249
 250         /**
 251          * @if OSPDEPREC
 252          * Detects faces from a still image.
 253          *
 254          * @brief <i> [Deprecated]  </i>
 255          * @deprecated This method is deprecated as it may return an improper result.
 256          * Instead of using this method, use DetectFacesFromStillImageN(Tizen::Base::ByteBuffer &, Tizen::Graphics::Dimension &, Tizen::Graphics::BitmapPixelFormat).
 257          * To optimize the memory usage and processing time, the bitmap scales down an image by decreasing its resolution in some models,
 258          * that in turn decreases the accuracy of the face library. Therefore, the usage of this method using Tizen::Base::ByteBuffer is encouraged.
 259          * @since        2.0
 260          *
 261          * @return       A list of the detected face positions @n
 262          *               Each list's item has a pointer of Tizen::Graphics::Rectangle value. @n
 263          *               An empty list, if there are no detected faces and there is no error @n
 264          *               The faces are not detected when the faces are too small or the image is not clear. @n
 265          *               This is the result of a normal operation, @n
 266          *               else @c null if an exception occurs.
 267          * @param[in]    bitmap             The bitmap file containing the input image data
 268          * @exception    E_SUCCESS          The method is successful.
 269          * @exception    E_OUT_OF_MEMORY    The memory is insufficient.
 270          * @exception    E_FAILURE          A system error has occurred.
 271          * @remarks      The specific error code can be accessed using the GetLastResult() method.
 272          * @remarks      BitmapPixelFormat::BITMAP_PIXEL_FORMAT_R8G8B8A8 is not applicable for this method.
 273          * @endif
 274          */
 275         Tizen::Base::Collection::IList* DetectFacesFromStillImageN(const Tizen::Graphics::Bitmap& bitmap);
 276
 277         /**
 278          * Searches for faces from a still image.
 279          *
 280          * @since        2.0
 281          *
 282          * @return       A list of the detected face positions @n
 283          *               Each list's item has a pointer of Tizen::Graphics::Rectangle value. @n
 284          *               An empty list, if there are no detected faces and there is no error @n
 285          *               The faces are not detected when the faces are too small or the image is not clear. @n
 286          *               This is the result of a normal operation, @n
 287          *               else @c null if an exception occurs.
 288          * @param[in]    byteBuffer         The buffer containing the input image data
 289          * @param[in]    dim                The width and height of the input image @n
 290          *                                  Both the width and height must be greater than @c 0.
 291          * @param[in]    format             The color format defined by Tizen::Graphics::BitmapPixelFormat
 292          * @exception    E_SUCCESS          The method is successful.
 293          * @exception    E_INVALID_ARG      A specified input parameter is invalid.
 294          * @exception    E_OUT_OF_MEMORY    The memory is insufficient.
 295          * @exception    E_FAILURE          A system error has occurred.
 296          * @remarks      The specific error code can be accessed using the GetLastResult() method.
 297          * @remarks      BitmapPixelFormat::BITMAP_PIXEL_FORMAT_R8G8B8A8 is not applicable for this method.
 298          */
 299         Tizen::Base::Collection::IList* DetectFacesFromStillImageN(const Tizen::Base::ByteBuffer& byteBuffer, const Tizen::Graphics::Dimension& dim, Tizen::Graphics::BitmapPixelFormat format);
 300
 301
 302         /**
 303          * Converts the input data to a proper data format that can be used in the face related methods.
 304          *
 305          * @since        2.0
 306          *
 307          * @return       The preprocessed data, @n
 308          *               else @c null if an exception occurs
 309          * @param[in]    byteBuffer         The buffer containing the input data
 310          * @param[in]    dim                The width and height of the input data @n
 311          *                                  Both the width and height must be greater than @c 0.
 312          * @param[in]    format             The format of the input data @n
 313          *                                  It must be one of the pixel formats extracted from GetSupportedFormatListN().
 314          * @exception    E_SUCCESS          The method is successful.
 315          * @exception    E_INVALID_ARG      A specified input parameter is invalid.
 316          * @exception    E_OUT_OF_MEMORY    The memory is insufficient.
 317          * @exception    E_SYSTEM           A system error has occurred.
 318          * @remarks      The specific error code can be accessed using the GetLastResult() method.
 319      * @see              FaceBuffer
 320          */
 321         FaceBuffer* PreprocessDataN(const Tizen::Base::ByteBuffer& byteBuffer, const Tizen::Graphics::Dimension& dim, Tizen::Graphics::PixelFormat format);
 322
 323         /**
 324          * Searches for faces from the preprocessed data.
 325          *
 326          * @since        2.0
 327          *
 328          * @return       A list of the detected face positions @n
 329          *               Each list's item has a pointer of Tizen::Graphics::Rectangle value. @n
 330          *               An empty list, if there are no detected faces and there is no error. @n
 331          *               The faces are not detected when the faces are too small or the input data is not clear. @n
 332          *               This is the result of a normal operation, @n
 333          *               else @c null if an exception occurs.
 334          * @param[in]    preprocessedFaceBuffer     The preprocessed data @n
 335          *                                          The @c preprocessedFaceBuffer must be obtained from PreprocessDataN().
 336          * @param[in]    option                     The working option of detecting faces
 337          * @exception    E_SUCCESS                  The method is successful.
 338          * @exception    E_UNSUPPORTED_OPERATION    The specified mode is not supported.
 339          * @exception    E_OUT_OF_MEMORY            The memory is insufficient.
 340          * @exception    E_SYSTEM                   A system error has occurred.
 341          * @remarks      The specific error code can be accessed using the GetLastResult() method.
 342      * @see              FaceDetectorConfigProperty
 343          */
 344         Tizen::Base::Collection::IList* DetectFacesN(const FaceBuffer& preprocessedFaceBuffer, FaceDetectionOption option = FACE_DETECTION_OPTION_FAST);
 345
 346         /**
 347          * Extracts the facial components information.
 348          *
 349          * @since        2.0
 350          *
 351          * @return       The facial components information, @n
 352          *               else @c null if an exception occurs
 353          * @param[in]    preprocessedFaceBuffer    The preprocessed data @n
 354          *                                         The @c preprocessedFaceBuffer must be obtained from PreprocessDataN().
 355          * @param[in]    faceRect                  The position of the detected face that is from DetectFacesN() @n
 356          *                                         The value of x and y positions for the @c faceRect parameter must be greater than or equal to @c 0. @n
 357          *                                         The value of width and height for the @c faceRect parameter must be greater than @c 0. @n
 358          *                                         The position of @c faceRect must be within @c preprocessedFaceBuffer.
 359          * @exception    E_SUCCESS                 The method is successful.
 360          * @exception    E_INVALID_ARG             A specified input parameter is invalid.
 361          * @exception    E_SYSTEM                  A system error has occurred.
 362          * @exception    E_OPERATION_FAILED        The method has failed to extract the facial information, but there is no error reported. @n
 363          *                                         This happens when the detected faces are too small or the input data is not clear. This is the result of a normal operation.
 364          * @remarks      The specific error code can be accessed using the GetLastResult() method.
 365      * @see              FaceComponentsPosition
 366          */
 367         FaceComponentsPosition* ExtractFaceComponentsN(const FaceBuffer& preprocessedFaceBuffer, const Tizen::Graphics::Rectangle& faceRect);
 368
 369
 370         /**
 371          * Gets the position difference of the face.
 372          *
 373          * @since         2.0
 374          *
 375          * @return        An error code
 376          * @param[in]     prevData              The buffer containing the previous video data
 377          * @param[in]     curData               The buffer containing the current video data @n
 378          *                                      The size of @c prevData and @c curData must be the same. @n
 379          *                                      The @c prevData and @c curData must be gotten from PreprocessDataN().
 380          * @param[in]     prevFaceRect          The region of the face inside @c prevData @n
 381          *                                      The value of x and y positions for the @c prevFaceRect parameter must be greater than or equal to @c 0. @n
 382          *                                      The value of width and height for the @c prevFaceRect parameter must be greater than @c 0. @n
 383          *                                      The specified @c prevFaceRect must be within @c prevData.
 384          * @param[out]    xDiff                 The x offset that is moved from the previous to current video data
 385          * @param[out]    yDiff                 The y offset that is moved from the previous to current video data
 386          * @exception     E_SUCCESS             The method is successful.
 387          * @exception     E_INVALID_ARG         A specified input parameter is invalid.
 388          * @exception     E_OPERATION_FAILED    The method has failed to get the position difference of the specified region, but there is no error reported. @n
 389          *                                      In this case, @c xDiff and @c yDiff will be returned with @c 0. @n
 390          *                                      It can happen when the detected faces are too small or two video data are different even if they contain the same face.
 391          *                                      This is the result of a normal operation.
 392          * @remarks       The specific error code can be accessed using the GetLastResult() method.
 393          * @remarks       This can be used for tracking the face from a sequential video data.
 394      * @see               DetectFacesN()
 395          */
 396         result GetFaceMovement(const FaceBuffer& prevData, const FaceBuffer& curData, const Tizen::Graphics::Rectangle& prevFaceRect, int& xDiff, int& yDiff);
 397
 398 private:
 399         /**
 400          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 401          */
 402         FaceDetector(const FaceDetector& value);
 403         /**
 404          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 405          */
 406         FaceDetector& operator =(const FaceDetector& value);
 407         friend class _FaceDetectorImpl;
 408
 409 //Member variables
 410 private:
 411         _FaceDetectorImpl* __pFaceDetectorImpl;
 412
 413 }; // FaceDetector
 414
 415 } } } // Tizen::Uix::Vision
 416
 417 #endif // _FUIX_VISION_FACE_DETECTOR_H_