src/Tizen.Multimedia.Vision/MediaVision/ImageRecognitionConfiguration.cs

   1 /*
   2  * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 using System;
  18
  19 namespace Tizen.Multimedia
  20 {
  21     /// <summary>
  22     /// Represents a configuration of <see cref="ImageRecognizer"/>.
  23     /// </summary>
  24     /// <since_tizen> 3</since_tizen>
  25     public class ImageRecognitionConfiguration : EngineConfiguration
  26     {
  27         private const string KeySceneScaleFactor = "MV_IMAGE_RECOGNITION_SCENE_SCALE_FACTOR";
  28         private const string KeySceneMaxKeypoints = "MV_IMAGE_RECOGNITION_SCENE_MAX_KEYPOINTS_NUM";
  29
  30         private const string KeyMinKeypointsMatch = "MV_IMAGE_RECOGNITION_MIN_MATCH_NUM";
  31         private const string KeyReqMatchPartKey = "MV_IMAGE_RECOGNITION_REQ_MATCH_PART";
  32         private const string KeyTolerantPartMatchingError = "MV_IMAGE_RECOGNITION_TOLERANT_MATCH_PART_ERR";
  33
  34         /// <summary>
  35         /// A read-only field that represents the default value of <see cref="KeySceneScaleFactor"/>.
  36         /// </summary>
  37         /// <since_tizen> 3</since_tizen>
  38         public static readonly double DefaultSceneScaleFactor = 1.2;
  39
  40         /// <summary>
  41         /// A read-only field that represents the default value of <see cref="SceneMaxKeyPoints"/>.
  42         /// </summary>
  43         /// <since_tizen> 3</since_tizen>
  44         public static readonly int DefaultSceneMaxKeypoints = 5000;
  45
  46         /// <summary>
  47         /// A read-only field that represents the default value of <see cref="MinKeyPointMatches"/>.
  48         /// </summary>
  49         /// <since_tizen> 3</since_tizen>
  50         public static readonly int DefaultMinKeyPointMatches = 30;
  51
  52         /// <summary>
  53         /// A read-only field that represents the default value of <see cref="RequiredMatchingPart"/>.
  54         /// </summary>
  55         /// <since_tizen> 3</since_tizen>
  56         public static readonly double DefaultRequiredMatchPart = 0.05;
  57
  58         /// <summary>
  59         /// A read-only field that represents the default value of <see cref="TolerantPartMatchError"/>.
  60         /// </summary>
  61         /// <since_tizen> 3</since_tizen>
  62         public static readonly double DefaultTolerantPartMatchError = 0.1;
  63
  64         /// <summary>
  65         /// Initializes a new instance of the <see cref="ImageRecognitionConfiguration"/> class.
  66         /// </summary>
  67         /// <exception cref="NotSupportedException">The feature is not supported.</exception>
  68         /// <since_tizen> 3</since_tizen>
  69         public ImageRecognitionConfiguration() : base("image_recognition")
  70         {
  71         }
  72
  73         /// <summary>
  74         /// Gets or sets the scene scale factor.
  75         /// </summary>
  76         /// <value>
  77         /// The value indicating the factor will be used for resizing of the scene including the images (objects) for recognition.
  78         /// The default is 1.2.
  79         /// </value>
  80         /// <exception cref="ObjectDisposedException">The <see cref="ImageRecognitionConfiguration"/> already has been disposed of.</exception>
  81         /// <since_tizen> 3</since_tizen>
  82         public double SceneScaleFactor
  83         {
  84             get
  85             {
  86                 return GetDouble(KeySceneScaleFactor);
  87             }
  88             set
  89             {
  90                 Set(KeySceneScaleFactor, value);
  91             }
  92         }
  93
  94         /// <summary>
  95         /// Gets or sets the maximum key points that should be detected on the scene.
  96         /// The maximal number of key points can be selected on the scene including the images (objects) to calculate descriptors.
  97         /// </summary>
  98         /// <value>
  99         /// The maximal key points for image recognition.
 100         /// The default is 5000.
 101         /// </value>
 102         /// <exception cref="ObjectDisposedException">The <see cref="ImageRecognitionConfiguration"/> already has been disposed of.</exception>
 103         /// <exception cref="ArgumentOutOfRangeException"><paramref name="value"/> is less than zero.</exception>
 104         /// <since_tizen> 3</since_tizen>
 105         public int SceneMaxKeyPoints
 106         {
 107             get
 108             {
 109                 return GetInt(KeySceneMaxKeypoints);
 110             }
 111             set
 112             {
 113                 if (value < 0)
 114                 {
 115                     throw new ArgumentOutOfRangeException(nameof(SceneMaxKeyPoints), value,
 116                         $"{nameof(SceneMaxKeyPoints)} can't be less than zero.");
 117                 }
 118                 Set(KeySceneMaxKeypoints, value);
 119             }
 120         }
 121
 122         /// <summary>
 123         /// Gets or sets the minimum number of key points matches required for recognition.
 124         /// </summary>
 125         /// <value>
 126         /// The minimal number of key points should be matched between an image and a scene for image objects recognition.
 127         /// The default is 30.
 128         /// </value>
 129         /// <exception cref="ObjectDisposedException">The <see cref="ImageRecognitionConfiguration"/> already has been disposed of.</exception>
 130         /// <exception cref="ArgumentOutOfRangeException"><paramref name="value"/> is less than zero.</exception>
 131         /// <since_tizen> 3</since_tizen>
 132         public int MinKeyPointMatches
 133         {
 134             get
 135             {
 136                 return GetInt(KeyMinKeypointsMatch);
 137             }
 138             set
 139             {
 140                 if (value < 0)
 141                 {
 142                     throw new ArgumentOutOfRangeException(nameof(MinKeyPointMatches), value,
 143                         $"{nameof(MinKeyPointMatches)} can't be less than zero.");
 144                 }
 145                 Set(KeyMinKeypointsMatch, value);
 146             }
 147         }
 148
 149         /// <summary>
 150         /// Gets or sets the required matching part for the image recognition.
 151         /// To recognize occluded or hidden an image by other images, required relative part of the matches in respect to the total
 152         /// amount of matching keypoints required for image recognition. Too low value will result in unsustainable behavior,
 153         /// but effect of object overlapping will be reduced.
 154         /// </summary>
 155         /// <value>
 156         /// The value indicating required relative part of the matches; can be from 0 to 1, inclusive.
 157         /// The default is 0.05.
 158         /// </value>
 159         /// <exception cref="ObjectDisposedException">The <see cref="ImageRecognitionConfiguration"/> already has been disposed of.</exception>
 160         /// <exception cref="ArgumentOutOfRangeException">
 161         ///     <paramref name="value"/> is less than zero.\n
 162         ///     -or-\n
 163         ///     <paramref name="value"/> is greater than one.
 164         /// </exception>
 165         /// <since_tizen> 3</since_tizen>
 166         public double RequiredMatchingPart
 167         {
 168             get
 169             {
 170                 return GetDouble(KeyReqMatchPartKey);
 171             }
 172             set
 173             {
 174                 if (value < 0 || value > 1)
 175                 {
 176                     throw new ArgumentOutOfRangeException(nameof(value), value, "Valid range is 0 to 1 inclusive,");
 177                 }
 178                 Set(KeyReqMatchPartKey, value);
 179             }
 180         }
 181
 182         /// <summary>
 183         /// Gets or sets the part matching error for the image recognition.\n
 184         /// Allowable error of matches number.
 185         /// </summary>
 186         /// <value>
 187         /// The value indicating allowable error of matches; can be from 0 to 1, inclusive.
 188         /// The default is 0.1.
 189         /// </value>
 190         /// <exception cref="ObjectDisposedException">The <see cref="ImageRecognitionConfiguration"/> already has been disposed of.</exception>
 191         /// <exception cref="ArgumentOutOfRangeException">
 192         ///     <paramref name="value"/> is less than zero.\n
 193         ///     -or-\n
 194         ///     <paramref name="value"/> is greater than one.
 195         /// </exception>
 196         /// <since_tizen> 3</since_tizen>
 197         public double TolerantPartMatchError
 198         {
 199             get
 200             {
 201                 return GetDouble(KeyTolerantPartMatchingError);
 202             }
 203             set
 204             {
 205                 if (value < 0 || value > 1)
 206                 {
 207                     throw new ArgumentOutOfRangeException(nameof(value), value, "Valid range is 0 to 1 inclusive.");
 208                 }
 209
 210                 Set(KeyTolerantPartMatchingError, value);
 211             }
 212         }
 213     }
 214 }