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
 159          *                      Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 160      */
 161     result Construct(void);
 162
 163     /**
 164      * Enables single or multiple tracking mode.
 165      *
 166      * @since        2.1
 167          *
 168      * @param[in]    enable        Enable multiple tracking mode on @c true, default is single tracking mode
 169      *
 170      * @remarks
 171      *                  - In single tracking mode, only one image is recognized in the screen at once.
 172      *                  - In multiple tracking mode, multiple images (maximum 3) can be recognized and tracked simultaneously.
 173      */
 174     void SetMultiTrackingEnabled(bool enable);
 175
 176     /**
 177      * Sets the width and height of an input image.
 178      *
 179      * @since        2.1
 180      *
 181      * @return       An error code
 182      *
 183      * @param[in]    width            The width of the input image
 184      * @param[in]    height           The height of the input image
 185      *
 186      * @exception    E_SUCCESS        The method is successful.
 187      * @exception    E_INVALID_ARG    A specified input parameter is invalid.
 188      */
 189     result SetImageSize(int width, int height);
 190
 191     /**
 192      * Sets the ImageFeatureManager instance for initialization.
 193      *
 194      * @since       2.1
 195      * @pre         ImageFeatureManager should be initialized by loading a feature set file using the ImageFeatureManager::Load() method.
 196      *
 197      * @return      An error code
 198      * @param[in]   imageFeatureManager      The ImageFeatureManager instance managing image feature set to use for recognition
 199      * @exception   E_SUCCESS                The method is successful.
 200      * @exception   E_INVALID_ARG            An input ImageFeatureManager is invalid.
 201      *
 202      * @remarks     ImageFeatureManager should be initialized by loading a feature set file.
 203      */
 204     result SetFeatureManager(ImageFeatureManager& imageFeatureManager);
 205
 206     /**
 207      * Gets a count of the recognized image object.
 208      *
 209      * @since        2.1
 210      *
 211      * @return       A count of the recognized image object
 212      *
 213      * @remarks      The recognized object has index value from @c 0 to (count of the recognized image objects - 1)
 214      * @see          GetRecognizedObject(int)
 215      */
 216     int GetRecognizedObjectCount(void);
 217
 218     /**
 219      * Gets the recognized image object to get information.
 220      *
 221      * @since        2.1
 222      *
 223      * @return       A pointer to ImageObject that includes all information about the recognized image object
 224      * @param[in]    index             The index of the recognized image object @n
 225      *                                 Valid range of this parameter is @c 0 to (count of the recognized image objects - 1).
 226      * @exception    E_SUCCESS         The method is successful.
 227      *
 228      * @see          GetRecognizedObjectCount()
 229      */
 230     const ImageObject* GetRecognizedObject(int index) const;
 231
 232     /**
 233      * Processes an input image for recognition.
 234      *
 235      * @since        2.1
 236      *
 237      * @return       An error code
 238      *
 239      * @param[in]    imageBuffer        The input image buffer @n
 240      *                                  It must be allocated outside and have size of (width*height) set by SetImageSize().
 241      * @exception    E_SUCCESS          The method is successful.
 242      * @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().
 243      * @exception    E_OUT_OF_MEMORY    The memory is insufficient.
 244      * @see          SetImageSize(int, int)
 245      */
 246     result ProcessImage(const Tizen::Base::ByteBuffer& imageBuffer);
 247
 248 private:
 249     /**
 250      * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 251      */
 252     ImageRecognizer(const ImageRecognizer&);
 253
 254     /**
 255      * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 256      */
 257     ImageRecognizer& operator=(const ImageRecognizer&);
 258
 259 private:
 260     class _ImageRecognizerImpl* __pImageRecognizerImpl; ///< implementation bridge
 261     friend class _ImageRecognizerImpl;
 262 };
 263
 264 } } } //Tizen::Uix::Vision
 265
 266 #endif // _FUIX_VISION_IMAGE_RECOGNIZER_H_