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