inc/FUixVisionImageFeatureManager.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     FUixVisionImageFeatureManager.h
  21  * @brief    This is the header file for the %ImageFeatureManager class.
  22  *
  23  * This header file contains the declarations of the %ImageFeatureManager class.
  24  */
  25
  26 #ifndef _FUIX_VISION_IMAGE_FEATURE_MANAGER_H_
  27 #define _FUIX_VISION_IMAGE_FEATURE_MANAGER_H_
  28 #include <FBaseObject.h>
  29 #include <FBase.h>
  30 #include <FGrpBitmap.h>
  31 #include <FUixVisionImageFeatureInfo.h>
  32 #include <FMedia.h>
  33
  34 namespace Tizen { namespace Uix { namespace Vision
  35 {
  36
  37 /**
  38  * @class    ImageFeatureManager
  39  * @brief    This class provides methods to generate individual feature data from an individual image data, and load it into a feature set file.
  40  *
  41  * @since    2.1
  42  *
  43  * The %ImageFeatureManager class provides methods to generate individual feature data from an individual image data.
  44  * This class also provides methods to manage the image feature set which is a collection of individual feature data.
  45  *
  46  * The following example demonstrates how to use the %ImageFeatureManager class.
  47  *
  48  * @code
  49  *
  50  * #include <FBase.h>
  51  * #include <FUix.h>
  52  * #include <FGraphics.h>
  53  * #include <FIo.h>
  54  * #include <FMedia.h>
  55  *
  56  * using namespace Tizen::Base;
  57  * using namespace Tizen::Media;
  58  * using namespace Tizen::Graphics;
  59  * using namespace Tizen::Io;
  60  * using namespace Tizen::Uix::Vision;
  61  *
  62  * class MyClass
  63  * {
  64  *
  65  * public:
  66  *      MyClass();
  67  *      ~MyClass();
  68  *      result GenerateFeatureSet(void);
  69  *      result AddImageFeatureSet(void);
  70  * };
  71  *
  72  * result
  73  * MyClass::GenerateFeatureSet(void)
  74  * {
  75  *     result r;
  76  *     ImageFeatureManager imageFeatureManager;
  77  *     r = imageFeatureManager.Construct();
  78  *
  79  *     //Creates new feature sets
  80  *     imageFeatureManager.AddFeature("/opt/usr/media/Images/image1.jpg");
  81  *     imageFeatureManager.AddFeature("/opt/usr/media/Images/image2.jpg");
  82  *     imageFeatureManager.AddFeature("/opt/usr/media/Images/image3.jpg");
  83  *     r = imageFeatureManager.Flush(new String("/opt/usr/media/Images/testFeatureSet.xdb"));
  84  *
  85  *     return r;
  86  * }
  87  *
  88  * result
  89  * MyClass::AddImageFeatureSet()
  90  * {
  91  *     result r;
  92  *     ImageFeatureManager imageFeatureManager;
  93  *     imageFeatureManager.Construct();
  94  *     imageFeatureManager.Load("/opt/usr/media/Images/testFeatureSet.xdb");
  95  *     imageFeatureManager.AddFeature("/opt/usr/media/Images/image1.jpg");
  96  *     imageFeatureManager.AddFeature("/opt/usr/media/Images/image2.jpg");
  97  *     imageFeatureManager.AddFeature("/opt/usr/media/Images/image3.jpg");
  98  *     r = imageFeatureManager.Flush();
  99  *
 100  *     return r;
 101  * }
 102  * @endcode
 103  */
 104 class _OSP_EXPORT_ ImageFeatureManager
 105     : public Tizen::Base::Object
 106 {
 107 public:
 108
 109     /**
 110      * This is the default constructor for this class. @n
 111      * The object is not fully constructed after this constructor is called. @n
 112      * For full construction, the Construct() method must be called right after calling this constructor.
 113      *
 114      * @since    2.1
 115      */
 116     ImageFeatureManager(void);
 117
 118     /**
 119      * This is the destructor for this class. @n
 120      * The resources are deallocated by this method.
 121      * This destructor overrides Tizen::Base::Object::~Object().
 122      *
 123      * @since    2.1
 124      */
 125     ~ImageFeatureManager(void);
 126
 127     /**
 128      * Initializes this instance of %ImageFeatureManager and creates an image feature set. @n
 129      * Every application must call the %Construct() method before calling any other method of %ImageFeatureManager.
 130      *
 131      * @since       2.1
 132      *
 133      * @feature     %http://tizen.org/feature/vision.image_recognition
 134      *
 135      * @return      An error code
 136      *
 137      * @exception   E_SUCCESS                     The method is successful.
 138      * @exception   E_UNSUPPORTED_OPERATION   The Emulator or target device does not support the required feature.
 139      *                                                                            For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 140      * @remarks     Before calling this method, check whether the feature is supported by Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 141      */
 142     result Construct(void);
 143
 144     /**
 145      * Loads the feature set file.
 146      *
 147      * @since       2.1
 148      *
 149      * @return      An error code
 150      *
 151      * @param[in]   featureSetFilePath       The feature set file path at which to load the file
 152      *
 153      * @exception   E_SUCCESS                The method is successful.
 154      * @exception   E_INVALID_ARG            The specified @c featureSetFilePath is invalid.
 155      * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 156      *
 157      * @remarks
 158      *              - If a feature set file exists, it is updated.
 159      *              - If a feature set file does not exist, it is newly created.
 160      *              - It is not mandatory to call this method to create a new feature set file, but the Flush() method must be called with a valid feature set file path.
 161      */
 162     result Load(const Tizen::Base::String& featureSetFilePath);
 163
 164     /**
 165      * Gets the list of supported image file formats used to add the feature.
 166      *
 167      * @since       2.1
 168          *
 169      * @return      The list of supported image file formats
 170      */
 171     static Tizen::Base::Collection::IListT<Tizen::Media::ImageFormat>* GetSupportedImageFileFormatsListN(void);
 172
 173     /**
 174      * Adds a feature to the feature set.
 175      *
 176      * @since       2.1
 177      *
 178      * @return      The feature index of the newly and successfully created feature, @n
 179          *                              else @c -1 is returned
 180      *
 181      * @param[in]   imagePath            The input image file path
 182      *
 183      * @exception   E_INVALID_ARG        The specified input parameter is invalid.
 184      *
 185      * @remarks
 186      *              - The specific error code can be accessed using the GetLastResult() method.
 187      *              - The input image file must have one of the supported image file formats.
 188      *              - Calling this method actually means 'Mark As Add Feature'
 189          *                                and the marked feature data is added to the feature set file after calling the Flush() method.
 190      * @see         GetSupportedImageFileFormatsListN()
 191      */
 192     int AddFeature(const Tizen::Base::String& imagePath);
 193
 194     /**
 195      * Adds a feature to the feature set.
 196      *
 197      * @since       2.1
 198      *
 199      * @return      The feature index of the newly and successfully created feature, @n
 200          *                              else @c -1 is returned
 201      *
 202      * @param[in]   imageBuffer              The image buffer of the grayscale image data with the specified @c width and @c height
 203      * @param[in]   width                    The width of the input image
 204      * @param[in]   height                   The height of the input image
 205      * @param[in]   description              The description of the feature
 206      *
 207      * @exception   E_INVALID_ARG            A specified input parameter is invalid.
 208      *
 209      * @remarks
 210      *              - The specific error code can be accessed using the GetLastResult() method.
 211      *              - Calling this method actually means 'Mark As Add Feature'.
 212      *                and the marked feature data is added to the feature set file after calling the Flush() method.
 213      * @see         Flush(const Tizen::Base::String*)
 214      */
 215     int AddFeature(const Tizen::Base::ByteBuffer& imageBuffer, int width, int height, const Tizen::Base::String& description);
 216
 217     /**
 218      * Gets the total number of features in the feature set.
 219      *
 220      * @since       2.1
 221      *
 222      * @return      The total number of features in the feature set
 223      */
 224     int GetTotalNumberOfFeatures(void);
 225
 226     /**
 227      * Deletes the feature at the specified index in the feature set.
 228      *
 229      * @since       2.1
 230      *
 231      * @return      An error code
 232      *
 233      * @param[in]   featureIndex             The feature index in the feature set
 234      *
 235      * @exception   E_SUCCESS                The method is successful.
 236      * @exception   E_INVALID_ARG            The specified input parameter is invalid.
 237      * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 238      *
 239      * @remarks     Calling this method actually means 'Mark As Delete Feature'.
 240      *              and the marked feature data is deleted after calling the Flush() method.
 241      * @see    Flush(const Tizen::Base::String*)
 242      */
 243     result DeleteFeature(int featureIndex);
 244
 245     /**
 246      * Deletes all the features in the feature set.
 247      *
 248      * @since       2.1
 249      *
 250      * @return      An error code
 251      *
 252      * @exception   E_SUCCESS          The method is successful.
 253      * @exception   E_OUT_OF_MEMORY    The memory is insufficient.
 254      *
 255      * @remarks     Calling this method actually means 'Mark As Delete All Features'.
 256      *              and all the feature data is deleted after calling the Flush() method.
 257      * @see         Flush(const Tizen::Base::String*)
 258      */
 259     result DeleteAllFeatures(void);
 260
 261     /**
 262      * Flushes features from the feature set file and updates all the changes as marked.
 263      *
 264      *
 265      * @since       2.1
 266      *
 267      * @return      An error code
 268      *
 269      * @param[in]   featureSetFilePath   The feature set file path
 270      * @exception   E_SUCCESS            The method is successful.
 271      * @exception   E_INVALID_ARG        The specified @c featureSetFilePath is invalid.
 272      *
 273      * @remarks
 274      *              - All the changes in the feature set file used by the AddFeature(), DeleteFeature(), or DeleteAllFeatures() method are updated by calling this method.
 275      *              - If the @c featureSetFilePath is not decided or is same as the file path used in the Load() method, the loaded feature set file is updated.
 276      *              - If the @c featureSetFilePath is not same as the file path used by the %Load() method, the loaded feature set file is retained and a new feature set file is created.
 277      *              - If the @c featureSetFilePath is @c null, the feature set file loaded by the %Load() method is overwritten.
 278      *                          - If the @c featureSetFilePath is not decided or is same as the file path used by the %Load() method, and the loaded feature set file is a read-only file, then @c E_INVALID_ARG exception is returned.
 279      *                          - If the %Load() method is not called to create a new feature set file, this method must be called with a valid @c featureSetFilePath.
 280      *
 281      */
 282     result Flush(const Tizen::Base::String* featureSetFilePath = null);
 283
 284     /**
 285      * Gets the information of the specified feature.
 286      *
 287      * @since       2.1
 288      *
 289      * @return      A pointer to the ImageFeatureInfo instance
 290      *
 291      * @param[in]   featureIndex       The feature index in the feature set
 292      */
 293     const Tizen::Uix::Vision::ImageFeatureInfo* GetImageFeatureInfo(int featureIndex) const;
 294
 295
 296 private:
 297     /**
 298      * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 299      */
 300     ImageFeatureManager(const ImageFeatureManager&);
 301
 302     /**
 303      * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 304      */
 305     ImageFeatureManager& operator=(const ImageFeatureManager&);
 306
 307 private:
 308     class _ImageFeatureManagerImpl* __pImageFeatureManagerImpl;
 309     friend class _ImageFeatureManagerImpl;
 310   };
 311
 312 } } } //Tizen::Uix::Vision
 313
 314 #endif // _FUIX_VISION_IMAGE_FEATURE_MANAGER_H_