inc/FUixVisionImageRecognizer.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 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     FUixVisionImageRecognizer.h
  21  * @brief    This is the header file for the %ImageRecognizer class.
  22  *
  23  * This header file contains the declarations of the %ImageRecognizer class.
  24  */
  25
  26 #ifndef _FUIX_VISION_IMAGE_RECOGNIZER_H_
  27 #define _FUIX_VISION_IMAGE_RECOGNIZER_H_
  28 #include <FBaseObject.h>
  29 #include <FBase.h>
  30 #include <FUixVisionImageObject.h>
  31
  32 namespace Tizen { namespace Uix { namespace Vision
  33 {
  34 class ImageFeatureManager;
  35 /**
  36  * @class    ImageRecognizer
  37  * @brief    This class provides methods to find same image objects to input image in the feature set that stores features of the reference images.
  38  *
  39  * @since    2.1
  40  *
  41  * The %ImageRecognizer class provides methods to find same image objects to input image in the feature set that stores features of the reference images.
  42  *           This class also provide methods to calculate the 2D position and 3D pose transform matrix of the recognized image objects.
  43  *
  44  * The following example demonstrates how to use the %ImageRecognizer class.
  45  *
  46  * @code
  47  * #include <FBase.h>
  48  * #include <FUix.h>
  49  * #include <FGraphics.h>
  50  * #include <FIo.h>
  51  * #include <FMedia.h>
  52  *
  53  * using namespace Tizen::Base;
  54  * using namespace Tizen::Media;
  55  * using namespace Tizen::Graphics;
  56  * using namespace Tizen::Io;
  57  * using namespace Tizen::Uix::Vision;
  58  * class MyClass
  59  *      : ICameraEventListener
  60  * {
  61  * public:
  62  *      MyClass();
  63  *      ~MyClass();
  64  *      result Initialize(void);
  65  *
  66  *      // Called when camera auto focus occurred
  67  *      void OnCameraAutoFocused(bool completeCondition);
  68  *      // Called when camera preview occurred
  69  *      void OnCameraPreviewed(Tizen::Base::ByteBuffer& previewedData, result r);
  70  *      // Called when camera captured image
  71  *      void OnCameraCaptured(Tizen::Base::ByteBuffer& capturedData, result r);
  72  *      // Called when camera  error occurred
  73  *      void OnCameraErrorOccurred(Tizen::Media::CameraErrorReason r);
  74  *
  75  * private:
  76  *      ImageRecognizer*        __pImageRecognizer;
  77  *      ImageFeatureManager*    __pFeatureManager;
  78  * };
  79  *
  80  * result
  81  * MyClass::Initialize(void)
  82  * {
  83  *      result r;
  84  *
  85  *      // Creates and initializes recognition engine
  86  *      __pImageRecognizer = new Tizen::Uix::Vision::ImageRecognizer();
  87  *      r = __pImageRecognizer->Construct();
  88  *      // Creates an initialized ImageFeatureManager
  89  *      __pFeatureManager  = new Tizen::Uix::Vision::ImageFeatureManager();
  90  *      r = __pFeatureManager->Construct();
  91  *
  92  *      // Loads feature set
  93  *      r = __pFeatureManager->Load("/opt/usr/media/Images/testFeatureSet.xdb");
  94  *
  95  *      // Configures recognition engine
  96  *      r =__pImageRecognizer->SetFeatureManager(*__pFeatureManager);
  97  *
  98  *      //Image size must be same as camera preview size
  99  *      r = __pImageRecognizer->SetImageSize(640, 480);
 100  *
 101  *      __pImageRecognizer->SetMultiTrackingEnabled(false);
 102  *
 103  *      return r;
 104  * }
 105  *
 106  * // We suppose camera to be initialized with Tizen::Graphics::PIXEL_FORMAT_YCbCr420_PLANAR format
 107  * void
 108  * MyClass::OnCameraPreviewed(Tizen::Base::ByteBuffer& previewedData, result r)
 109  * {
 110  *      // Processing of the camera image follows
 111  *      __pImageRecognizer->ProcessImage(previewedData);
 112  *
 113  *      // Loops through all recognized images
 114  *      for (int i = 0; i < __pImageRecognizer->GetRecognizedObjectCount(); i++)
 115  *      {
 116  *              const ImageObject *o = __pImageRecognizer->GetRecognizedObject(i);
 117  *              int featId = o->GetFeatureId();
 118  *      }
 119  * }
 120  *
 121  * @endcode
 122  */
 123
 124 class _OSP_EXPORT_ ImageRecognizer
 125     : public Tizen::Base::Object
 126 {
 127 public:
 128
 129     /**
 130      * This is the default constructor for this class. @n
 131      * The object is not fully constructed after this constructor is called. @n
 132      * For full construction, the Construct() method must be called right after calling this constructor.
 133      *
 134      * @since    2.1
 135      */
 136     ImageRecognizer(void);
 137
 138     /**
 139      * This is the destructor for this class. @n
 140      * The resources are deallocated by this method.
 141      * This destructor overrides Tizen::Base::Object::~Object().
 142      *
 143      * @since    2.1
 144      */
 145     ~ImageRecognizer(void);
 146
 147     /**
 148      * Initializes this instance of %ImageRecognizer. @n
 149      * Every application must call %Construct() before calling any other methods of %ImageRecognizer.
 150      *
 151      * @since        2.1
 152      *
 153      * @feature      %http://tizen.org/feature/vision.image_recognition
 154      *
 155      * @exception    E_SUCCESS          The method is successful.
 156      * @exception    E_UNSUPPORTED_OPERATION   The Emulator or target device does not support the required feature.
 157      * For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 158      * @remarks      Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue() methods.
 159      */
 160     result Construct(void);
 161
 162     /**
 163      * Enables single or multiple tracking mode.
 164      *
 165      * @since        2.1
 166          *
 167      * @param[in]    enable        Enable multiple tracking mode on @c true, default is single tracking mode
 168      *
 169      * @remarks
 170      *                  - In single tracking mode, only one image is recognized in the screen at once.
 171      *                  - In multiple tracking mode, multiple images (maximum 3) can be recognized and tracked simultaneously.
 172      */
 173     void SetMultiTrackingEnabled(bool enable);
 174
 175     /**
 176      * Sets the width and height of an input image.
 177      *
 178      * @since        2.1
 179      *
 180      * @return       An error code
 181      *
 182      * @param[in]    width            The width of the input image
 183      * @param[in]    height           The height of the input image
 184      *
 185      * @exception    E_SUCCESS        The method is successful.
 186      * @exception    E_INVALID_ARG    A specified input parameter is invalid.
 187      */
 188     result SetImageSize(int width, int height);
 189
 190     /**
 191      * Sets the ImageFeatureManager instance for initialization.
 192      *
 193      * @since       2.1
 194      * @pre         ImageFeatureManager should be initialized by loading a feature set file using the ImageFeatureManager::Load() method.
 195      *
 196      * @return      An error code
 197      * @param[in]   imageFeatureManager      The ImageFeatureManager instance managing image feature set to use for recognition
 198      * @exception   E_SUCCESS                The method is successful.
 199      * @exception   E_INVALID_ARG            An input ImageFeatureManager is invalid.
 200      *
 201      * @remarks     ImageFeatureManager should be initialized by loading a feature set file.
 202      */
 203     result SetFeatureManager(ImageFeatureManager& imageFeatureManager);
 204
 205     /**
 206      * Gets a count of the recognized image object.
 207      *
 208      * @since        2.1
 209      *
 210      * @return       A count of the recognized image object
 211      *
 212      * @remarks      The recognized object has index value from @c 0 to (count of the recognized image objects - 1)
 213      * @see          GetRecognizedObject(int)
 214      */
 215     int GetRecognizedObjectCount(void);
 216
 217     /**
 218      * Gets the recognized image object to get information.
 219      *
 220      * @since        2.1
 221      *
 222      * @return       A pointer to ImageObject that includes all information about the recognized image object
 223      * @param[in]    index             The index of the recognized image object @n
 224      *                                 Valid range of this parameter is @c 0 to (count of the recognized image objects - 1).
 225      * @exception    E_SUCCESS         The method is successful.
 226      *
 227      * @see          GetRecognizedObjectCount()
 228      */
 229     const ImageObject* GetRecognizedObject(int index) const;
 230
 231     /**
 232      * Processes an input image for recognition.
 233      *
 234      * @since        2.1
 235      *
 236      * @return       An error code
 237      *
 238      * @param[in]    imageBuffer        The input image buffer @n
 239      *                                  It must be allocated outside and have size of (width*height) set by SetImageSize().
 240      * @exception    E_SUCCESS          The method is successful.
 241      * @exception    E_INVALID_ARG      The specified @c imageBuffer is not allocated or the size of @c imageBuffer is not equal to the input image size set by SetImageSize().
 242      * @exception    E_OUT_OF_MEMORY    The memory is insufficient.
 243      * @see          SetImageSize(int, int)
 244      */
 245     result ProcessImage(const Tizen::Base::ByteBuffer& imageBuffer);
 246
 247 private:
 248     /**
 249      * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 250      */
 251     ImageRecognizer(const ImageRecognizer&);
 252
 253     /**
 254      * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 255      */
 256     ImageRecognizer& operator=(const ImageRecognizer&);
 257
 258 private:
 259     class _ImageRecognizerImpl* __pImageRecognizerImpl; ///< implementation bridge
 260     friend class _ImageRecognizerImpl;
 261 };
 262
 263 } } } //Tizen::Uix::Vision
 264
 265 #endif // _FUIX_VISION_IMAGE_RECOGNIZER_H_