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. @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.
 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          * @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 face detection feature @b Since: @b 2.1.
 165          * For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/manifest_features.htm">Application Filtering</a>.
 166          * @remarks      Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue() methods.
 167
 168
 169          */
 170         result Construct(void);
 171
 172         /**
 173          * Gets the range and default value of the specified configuration property.
 174          *
 175          * @since         2.0
 176          *
 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.
 186          */
 187         result GetRange(FaceDetectorConfigProperty configProperty, long& min, long& max, long& steppingDelta, long& defaultVal) const;
 188
 189         /**
 190          * Sets the value of the specified property.
 191          *
 192          * @since        2.0
 193          *
 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.
 200          * @see          GetRange()
 201          */
 202         result SetProperty(FaceDetectorConfigProperty configProperty, long value);
 203
 204         /**
 205          * Gets the current setting of the specified configuration property.
 206          *
 207          * @since        2.0
 208          *
 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.
 215          */
 216         long GetProperty(FaceDetectorConfigProperty configProperty) const;
 217
 218         /**
 219          * Gets a list of supported pixel formats.
 220          *
 221          * @since        2.0
 222          *
 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.
 228          */
 229         Tizen::Base::Collection::IListT< Tizen::Graphics::PixelFormat >* GetSupportedFormatListN(void) const;
 230
 231         /**
 232          * Searches for faces from a video.
 233          *
 234          * @since        2.0
 235          *
 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.
 252          */
 253         Tizen::Base::Collection::IList* DetectFacesFromVideoStreamN(const Tizen::Base::ByteBuffer& byteBuffer, const Tizen::Graphics::Dimension& dim, const Tizen::Graphics::PixelFormat format);
 254
 255         /**
 256          * @if OSPDEPREC
 257          * Detects faces from a still image.
 258          *
 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.
 264          * @since        2.0
 265          *
 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.
 276          * @remarks      The specific error code can be accessed using the GetLastResult() method.
 277          * @remarks      BitmapPixelFormat::BITMAP_PIXEL_FORMAT_R8G8B8A8 is not applicable for this method.
 278          * @endif
 279          */
 280         Tizen::Base::Collection::IList* DetectFacesFromStillImageN(const Tizen::Graphics::Bitmap& bitmap);
 281
 282         /**
 283          * Searches for faces from a still image.
 284          *
 285          * @since        2.0
 286          *
 287          * @return       A list of the detected face positions @n
 288          *               Each list's item has a pointer of Tizen::Graphics::Rectangle value. @n
 289          *               An empty list, if there are no detected faces and there is no error @n
 290          *               The faces are not detected when the faces are too small or the image is not clear. @n
 291          *               This is the result of a normal operation, @n
 292          *               else @c null if an exception occurs.
 293          * @param[in]    byteBuffer         The buffer containing the input image data
 294          * @param[in]    dim                The width and height of the input image @n
 295          *                                  Both the width and height must be greater than @c 0.
 296          * @param[in]    format             The color format @n
 297          *                                                      @c BITMAP_PIXEL_FORMAT_R8G8B8A8 is not applicable for this method.
 298          * @exception    E_SUCCESS          The method is successful.
 299          * @exception    E_INVALID_ARG      A specified input parameter is invalid.
 300          * @exception    E_OUT_OF_MEMORY    The memory is insufficient.
 301          * @exception    E_FAILURE          A system error has occurred.
 302          * @remarks      The specific error code can be accessed using the GetLastResult() method.
 303          */
 304         Tizen::Base::Collection::IList* DetectFacesFromStillImageN(const Tizen::Base::ByteBuffer& byteBuffer, const Tizen::Graphics::Dimension& dim, Tizen::Graphics::BitmapPixelFormat format);
 305
 306
 307         /**
 308          * Converts the input data to a proper data format that can be used in the face related methods.
 309          *
 310          * @since        2.0
 311          *
 312          * @return       The preprocessed data, @n
 313          *               else @c null if an exception occurs
 314          * @param[in]    byteBuffer         The buffer containing the input data
 315          * @param[in]    dim                The width and height of the input data @n
 316          *                                  Both the width and height must be greater than @c 0.
 317          * @param[in]    format             The format of the input data @n
 318          *                                  It must be one of the pixel formats extracted from GetSupportedFormatListN().
 319          * @exception    E_SUCCESS          The method is successful.
 320          * @exception    E_INVALID_ARG      A specified input parameter is invalid.
 321          * @exception    E_OUT_OF_MEMORY    The memory is insufficient.
 322          * @exception    E_SYSTEM           A system error has occurred.
 323          * @remarks      The specific error code can be accessed using the GetLastResult() method.
 324          */
 325         FaceBuffer* PreprocessDataN(const Tizen::Base::ByteBuffer& byteBuffer, const Tizen::Graphics::Dimension& dim, Tizen::Graphics::PixelFormat format);
 326
 327         /**
 328          * Searches for faces from the preprocessed data.
 329          *
 330          * @since        2.0
 331          *
 332          * @return       A list of the detected face positions @n
 333          *               Each list's item has a pointer of Tizen::Graphics::Rectangle value. @n
 334          *               An empty list, if there are no detected faces and there is no error. @n
 335          *               The faces are not detected when the faces are too small or the input data is not clear. @n
 336          *               This is the result of a normal operation, @n
 337          *               else @c null if an exception occurs.
 338          * @param[in]    preprocessedFaceBuffer     The preprocessed data @n
 339          *                                          The @c preprocessedFaceBuffer must be obtained from PreprocessDataN().
 340          * @param[in]    option                     The working option of detecting faces
 341          * @exception    E_SUCCESS                  The method is successful.
 342          * @exception    E_UNSUPPORTED_OPERATION    The specified mode is not supported.
 343          * @exception    E_OUT_OF_MEMORY            The memory is insufficient.
 344          * @exception    E_SYSTEM                   A system error has occurred.
 345          * @remarks      The specific error code can be accessed using the GetLastResult() method.
 346          * @see          FaceDetectorConfigProperty
 347          */
 348         Tizen::Base::Collection::IList* DetectFacesN(const FaceBuffer& preprocessedFaceBuffer, FaceDetectionOption option = FACE_DETECTION_OPTION_FAST);
 349
 350         /**
 351          * Extracts the facial components information.
 352          *
 353          * @since        2.0
 354          *
 355          * @return       The facial components information, @n
 356          *               else @c null if an exception occurs
 357          * @param[in]    preprocessedFaceBuffer    The preprocessed data @n
 358          *                                         The @c preprocessedFaceBuffer must be obtained from PreprocessDataN().
 359          * @param[in]    faceRect                  The position of the detected face that is from DetectFacesN() @n
 360          *                                         The value of x and y positions for the @c faceRect parameter must be greater than or equal to @c 0. @n
 361          *                                         The value of width and height for the @c faceRect parameter must be greater than @c 0. @n
 362          *                                         The position of @c faceRect must be within @c preprocessedFaceBuffer.
 363          * @exception    E_SUCCESS                 The method is successful.
 364          * @exception    E_INVALID_ARG             A specified input parameter is invalid.
 365          * @exception    E_SYSTEM                  A system error has occurred.
 366          * @exception    E_OPERATION_FAILED        The method has failed to extract the facial information, but there is no error reported. @n
 367          *                                         This happens when the detected faces are too small or the input data is not clear. This is the result of a normal operation.
 368          * @remarks      The specific error code can be accessed using the GetLastResult() method.
 369          */
 370         FaceComponentsPosition* ExtractFaceComponentsN(const FaceBuffer& preprocessedFaceBuffer, const Tizen::Graphics::Rectangle& faceRect);
 371
 372
 373         /**
 374          * Gets the position difference of the face. @n
 375          * This can be used for tracking the face from a sequential video data.
 376          *
 377          * @since         2.0
 378          *
 379          * @return        An error code
 380          * @param[in]     prevData              The buffer containing the previous video data
 381          * @param[in]     curData               The buffer containing the current video data @n
 382          *                                      The size of @c prevData and @c curData must be the same. @n
 383          *                                      The @c prevData and @c curData must be gotten from PreprocessDataN().
 384          * @param[in]     prevFaceRect          The region of the face inside @c prevData @n
 385          *                                      The value of x and y positions for the @c prevFaceRect parameter must be greater than or equal to @c 0. @n
 386          *                                      The value of width and height for the @c prevFaceRect parameter must be greater than @c 0. @n
 387          *                                      The specified @c prevFaceRect must be within @c prevData.
 388          * @param[out]    xDiff                 The x offset that is moved from the previous to current video data
 389          * @param[out]    yDiff                 The y offset that is moved from the previous to current video data
 390          * @exception     E_SUCCESS             The method is successful.
 391          * @exception     E_INVALID_ARG         A specified input parameter is invalid.
 392          * @exception     E_OPERATION_FAILED    The method has failed to get the position difference of the specified region, but there is no error reported. @n
 393          *                                      In this case, @c xDiff and @c yDiff will be returned with @c 0. @n
 394          *                                      It can happen when the detected faces are too small or two video data are different even if they contain the same face.
 395          *                                      This is the result of a normal operation.
 396          * @remarks       The specific error code can be accessed using the GetLastResult() method.
 397          * @see           DetectFacesN()
 398          */
 399         result GetFaceMovement(const FaceBuffer& prevData, const FaceBuffer& curData, const Tizen::Graphics::Rectangle& prevFaceRect, int& xDiff, int& yDiff);
 400
 401 private:
 402         /**
 403          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 404          */
 405         FaceDetector(const FaceDetector& value);
 406         /**
 407          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 408          */
 409         FaceDetector& operator =(const FaceDetector& value);
 410         friend class _FaceDetectorImpl;
 411
 412 //Member variables
 413 private:
 414         _FaceDetectorImpl* __pFaceDetectorImpl;
 415
 416 }; // FaceDetector
 417
 418 } } } // Tizen::Uix::Vision
 419
 420 #endif // _FUIX_VISION_FACE_DETECTOR_H_