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 a recognition engine
  86  *      __pImageRecognizer = new Tizen::Uix::Vision::ImageRecognizer();
  87  *      r = __pImageRecognizer->Construct();
  88  *
  89  *      // Creates an initialized ImageFeatureManager
  90  *      __pFeatureManager  = new Tizen::Uix::Vision::ImageFeatureManager();
  91  *      r = __pFeatureManager->Construct();
  92  *
  93  *      // Loads a feature set
  94  *      r = __pFeatureManager->Load("/opt/usr/media/Images/testFeatureSet.xdb");
  95  *
  96  *      // Configures the recognition engine
  97  *      r =__pImageRecognizer->SetFeatureManager(*__pFeatureManager);
  98  *
  99  *   // Sets the image size to be same as the camera preview size
 100  *      r = __pImageRecognizer->SetImageSize(640, 480);
 101  *
 102  *      __pImageRecognizer->SetMultiTrackingEnabled(false);
 103  *
 104  *      return r;
 105  * }
 106  *
 107  * // We suppose camera to be initialized with Tizen::Graphics::PIXEL_FORMAT_YCbCr420_PLANAR format
 108  * void
 109  * MyClass::OnCameraPreviewed(Tizen::Base::ByteBuffer& previewedData, result r)
 110  * {
 111  *      // Processes the camera image
 112  *      __pImageRecognizer->ProcessImage(previewedData);
 113  *
 114  *      // Loops through all recognized images
 115  *      for (int i = 0; i < __pImageRecognizer->GetRecognizedObjectCount(); i++)
 116  *      {
 117  *              const ImageObject *o = __pImageRecognizer->GetRecognizedObject(i);
 118  *              int featId = o->GetFeatureId();
 119  *      }
 120  * }
 121  *
 122  * @endcode
 123  */
 124
 125 class _OSP_EXPORT_ ImageRecognizer
 126     : public Tizen::Base::Object
 127 {
 128 public:
 129
 130     /**
 131      * This is the default constructor for this class. @n
 132      * The object is not fully constructed after this constructor is called. @n
 133      * For full construction, the Construct() method must be called right after calling this constructor.
 134      *
 135      * @since    2.1
 136      */
 137     ImageRecognizer(void);
 138
 139     /**
 140      * This is the destructor for this class. @n
 141      * The resources are deallocated by this method.
 142      * This destructor overrides Tizen::Base::Object::~Object().
 143      *
 144      * @since    2.1
 145      */
 146     ~ImageRecognizer(void);
 147
 148     /**
 149      * Initializes this instance of %ImageRecognizer. @n
 150      * Every application must call %Construct() before calling any other methods of %ImageRecognizer.
 151      *
 152      * @since        2.1
 153      *
 154      * @feature      %http://tizen.org/feature/vision.image_recognition
 155      *
 156      * @exception    E_SUCCESS          The method is successful.
 157      * @exception    E_UNSUPPORTED_OPERATION   The Emulator or target device does not support the required feature.
 158      * For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 159      * @remarks      Before calling this method, check whether the feature is supported by
 160          *                      Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 161      */
 162     result Construct(void);
 163
 164     /**
 165      * Enables single or multiple tracking mode.
 166      *
 167      * @since        2.1
 168          *
 169      * @param[in]    enable        Enable multiple tracking mode on @c true, default is single tracking mode
 170      *
 171      * @remarks
 172      *                  - In single tracking mode, only one image is recognized in the screen at once.
 173      *                  - In multiple tracking mode, multiple images (maximum 3) can be recognized and tracked simultaneously.
 174      */
 175     void SetMultiTrackingEnabled(bool enable);
 176
 177     /**
 178      * Sets the width and height of an input image.
 179      *
 180      * @since        2.1
 181      *
 182      * @return       An error code
 183      *
 184      * @param[in]    width            The width of the input image
 185      * @param[in]    height           The height of the input image
 186      *
 187      * @exception    E_SUCCESS        The method is successful.
 188      * @exception    E_INVALID_ARG    A specified input parameter is invalid.
 189      */
 190     result SetImageSize(int width, int height);
 191
 192     /**
 193      * Sets the ImageFeatureManager instance for initialization.
 194      *
 195      * @since       2.1
 196      * @pre         ImageFeatureManager should be initialized by loading a feature set file using the ImageFeatureManager::Load() method.
 197      *
 198      * @return      An error code
 199      * @param[in]   imageFeatureManager      The ImageFeatureManager instance managing image feature set to use for recognition
 200      * @exception   E_SUCCESS                The method is successful.
 201      * @exception   E_INVALID_ARG            An input ImageFeatureManager is invalid.
 202      *
 203      * @remarks     ImageFeatureManager should be initialized by loading a feature set file.
 204      */
 205     result SetFeatureManager(ImageFeatureManager& imageFeatureManager);
 206
 207     /**
 208      * Gets a count of the recognized image object.
 209      *
 210      * @since        2.1
 211      *
 212      * @return       A count of the recognized image object
 213      *
 214      * @remarks      The recognized object has index value from @c 0 to (count of the recognized image objects - 1)
 215      * @see          GetRecognizedObject(int)
 216      */
 217     int GetRecognizedObjectCount(void);
 218
 219     /**
 220      * Gets the recognized image object to get information.
 221      *
 222      * @since        2.1
 223      *
 224      * @return       A pointer to ImageObject that includes all information about the recognized image object
 225      * @param[in]    index             The index of the recognized image object @n
 226      *                                 Valid range of this parameter is @c 0 to (count of the recognized image objects - 1).
 227      * @exception    E_SUCCESS         The method is successful.
 228      *
 229      * @see          GetRecognizedObjectCount()
 230      */
 231     const ImageObject* GetRecognizedObject(int index) const;
 232
 233     /**
 234      * Processes an input image for recognition.
 235      *
 236      * @since        2.1
 237      *
 238      * @return       An error code
 239      *
 240      * @param[in]    imageBuffer        The input image buffer @n
 241      *                                  It must be allocated outside and have size of (width*height) set by SetImageSize().
 242      * @exception    E_SUCCESS          The method is successful.
 243      * @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().
 244      * @exception    E_OUT_OF_MEMORY    The memory is insufficient.
 245      * @see          SetImageSize(int, int)
 246      */
 247     result ProcessImage(const Tizen::Base::ByteBuffer& imageBuffer);
 248
 249 private:
 250     /**
 251      * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 252      */
 253     ImageRecognizer(const ImageRecognizer&);
 254
 255     /**
 256      * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 257      */
 258     ImageRecognizer& operator=(const ImageRecognizer&);
 259
 260 private:
 261     class _ImageRecognizerImpl* __pImageRecognizerImpl; ///< implementation bridge
 262     friend class _ImageRecognizerImpl;
 263 };
 264
 265 } } } //Tizen::Uix::Vision
 266
 267 #endif // _FUIX_VISION_IMAGE_RECOGNIZER_H_