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