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