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