src/Tizen.Multimedia.Vision/MediaVision/ImageObject.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 using System.IO;
  19 using InteropImage = Interop.MediaVision.Image;
  20
  21 namespace Tizen.Multimedia.Vision
  22 {
  23     /// <summary>
  24     /// Represents an image object.
  25     /// </summary>
  26     /// <since_tizen> 3 </since_tizen>
  27     public class ImageObject : IDisposable
  28     {
  29         private IntPtr _handle = IntPtr.Zero;
  30         private bool _disposed = false;
  31
  32         /// <summary>
  33         /// Initializes a new instance of the <see cref="ImageObject"/> class.
  34         /// </summary>
  35         /// <exception cref="NotSupportedException">The feature is not supported.</exception>
  36         /// <since_tizen> 3 </since_tizen>
  37         public ImageObject()
  38         {
  39             InteropImage.Create(out _handle).Validate("Failed to create image object");
  40         }
  41
  42         /// <summary>
  43         /// Initializes a new instance of the <see cref="ImageObject"/> class from the specified file.
  44         /// </summary>
  45         /// <remarks>
  46         /// ImageObject has been saved by <see cref="Save(string)"/> can be loaded.
  47         /// </remarks>
  48         /// <param name="path">Path to the image object to load.</param>
  49         /// <exception cref="ArgumentNullException"><paramref name="path"/> is null.</exception>
  50         /// <exception cref="FileNotFoundException"><paramref name="path"/> is invalid.</exception>
  51         /// <exception cref="NotSupportedException">
  52         ///     The feature is not supported.\n
  53         ///     -or-\n
  54         ///     <paramref name="path"/> is not supported file.
  55         /// </exception>
  56         /// <exception cref="UnauthorizedAccessException">No permission to access the specified file.</exception>
  57         /// <seealso cref="Save(string)"/>
  58         /// <since_tizen> 3 </since_tizen>
  59         public ImageObject(string path)
  60         {
  61             if (path == null)
  62             {
  63                 throw new ArgumentNullException(nameof(path));
  64             }
  65             InteropImage.Load(path, out _handle).Validate("Failed to load image object from file");
  66         }
  67
  68         /// <summary>
  69         /// Finalizes an instance of the ImageObject class.
  70         /// </summary>
  71         ~ImageObject()
  72         {
  73             Dispose(false);
  74         }
  75
  76         /// <summary>
  77         /// Gets a value that determines how well an image object can be recognized.
  78         /// </summary>
  79         /// <remarks>
  80         /// If recognition rate is too low, try to use another image or change some configuration parameters
  81         /// and fill the image object again.
  82         /// </remarks>
  83         /// <value>
  84         /// Recognition rate determines how well an image object can be recognized. This value can be from 0 to 1.
  85         /// If the recognition rate is 0 object can not be recognized and the bigger it is the more likely to recognize the object.
  86         /// </value>
  87         /// <exception cref="ObjectDisposedException">The <see cref="ImageObject"/> has already been disposed of.</exception>
  88         /// <seealso cref="ImageFillConfiguration"/>
  89         /// <seealso cref="Fill(MediaVisionSource)"/>
  90         /// <seealso cref="Fill(MediaVisionSource, ImageFillConfiguration)"/>
  91         /// <seealso cref="Fill(MediaVisionSource, Rectangle)"/>
  92         /// <seealso cref="Fill(MediaVisionSource, ImageFillConfiguration, Rectangle)"/>
  93         /// <since_tizen> 3 </since_tizen>
  94         public double RecognitionRate
  95         {
  96             get
  97             {
  98                 InteropImage.GetRecognitionRate(Handle, out var rate).Validate("Failed to get recognition rate");
  99                 return rate;
 100             }
 101         }
 102
 103         #region Methods
 104         /// <summary>
 105         /// Gets the label for the image object.
 106         /// </summary>
 107         /// <returns>
 108         /// The label value if the <see cref="ImageObject"/> has label, otherwise null.
 109         /// </returns>
 110         /// <exception cref="ObjectDisposedException">The <see cref="ImageObject"/> has already been disposed of.</exception>
 111         /// <seealso cref="SetLabel(int)"/>
 112         /// <since_tizen> 3 </since_tizen>
 113         public int? GetLabel()
 114         {
 115             var ret = InteropImage.GetLabel(Handle, out var label);
 116
 117             if (ret == MediaVisionError.NoData)
 118             {
 119                 return null;
 120             }
 121
 122             ret.Validate("Failed to get label");
 123             return label;
 124         }
 125
 126         /// <summary>
 127         /// Sets the label for the <see cref="ImageObject"/>.
 128         /// </summary>
 129         /// <seealso cref="GetLabel"/>
 130         /// <since_tizen> 3 </since_tizen>
 131         public void SetLabel(int label)
 132         {
 133             InteropImage.SetLabel(Handle, label).Validate("Failed to set label");
 134         }
 135
 136         /// <summary>
 137         /// Fills the image object.\n
 138         /// Extracts data from @a source image which will be needed for recognition of depicted object in @a location.
 139         /// </summary>
 140         /// <param name="source">The source image where image object is depicted.</param>
 141         /// <exception cref="ArgumentNullException"><paramref name="source"/> is null.</exception>
 142         /// <exception cref="ObjectDisposedException">
 143         ///     The <see cref="ImageObject"/> has already been disposed of.\n
 144         ///     -or-\n
 145         ///     <paramref name="source"/> has already been disposed of.
 146         /// </exception>
 147         /// <since_tizen> 3 </since_tizen>
 148         public void Fill(MediaVisionSource source)
 149         {
 150             InvokeFill(source, null, null);
 151         }
 152
 153         /// <summary>
 154         /// Fills the image object.\n
 155         /// Extracts data from @a source image which will be needed for recognition of depicted object in @a location.
 156         /// </summary>
 157         /// <param name="source">The source image where image object is depicted.</param>
 158         /// <param name="config">The configuration used for extract recognition data from source. This value can be null.</param>
 159         /// <exception cref="ArgumentNullException"><paramref name="source"/> is null.</exception>
 160         /// <exception cref="ObjectDisposedException">
 161         ///     The <see cref="ImageObject"/> has already been disposed of.\n
 162         ///     -or-\n
 163         ///     <paramref name="source"/> has already been disposed of.\n
 164         ///     -or-\n
 165         ///     <paramref name="config"/> has already been disposed of.
 166         /// </exception>
 167         /// <since_tizen> 3 </since_tizen>
 168         public void Fill(MediaVisionSource source, ImageFillConfiguration config)
 169         {
 170             InvokeFill(source, config, null);
 171         }
 172
 173         /// <summary>
 174         /// Fills the image object.\n
 175         /// Extracts data from @a source image which will be needed for recognition of depicted object in @a location.
 176         /// </summary>
 177         /// <param name="source">The source image where image object is depicted.</param>
 178         /// <param name="rect">Rectangular bound of the image object on the source image.</param>
 179         /// <exception cref="ArgumentNullException"><paramref name="source"/> is null.</exception>
 180         /// <exception cref="ObjectDisposedException">
 181         ///     The <see cref="ImageObject"/> has already been disposed of.\n
 182         ///     -or-\n
 183         ///     <paramref name="source"/> has already been disposed of.\n
 184         /// </exception>
 185         /// <since_tizen> 3 </since_tizen>
 186         public void Fill(MediaVisionSource source, Rectangle rect)
 187         {
 188             InvokeFill(source, null, rect);
 189         }
 190
 191         /// <summary>
 192         /// Fills the image object.\n
 193         /// Extracts data from @a source image which will be needed for recognition of depicted object in @a location.
 194         /// </summary>
 195         /// <param name="source">The source image where image object is depicted.</param>
 196         /// <param name="config">The configuration used for extract recognition data from source. This value can be null.</param>
 197         /// <param name="rect">Rectangular bound of the image object on the source image.</param>
 198         /// <exception cref="ArgumentNullException"><paramref name="source"/> is null.</exception>
 199         /// <exception cref="ObjectDisposedException">
 200         ///     The <see cref="ImageObject"/> has already been disposed of.\n
 201         ///     -or-\n
 202         ///     <paramref name="source"/> has already been disposed of.\n
 203         ///     -or-\n
 204         ///     <paramref name="config"/> has already been disposed of.
 205         /// </exception>
 206         /// <since_tizen> 3 </since_tizen>
 207         public void Fill(MediaVisionSource source, ImageFillConfiguration config, Rectangle rect)
 208         {
 209             InvokeFill(source, config, rect);
 210         }
 211
 212         private MediaVisionError InvokeFill(IntPtr source, IntPtr config, Rectangle? area)
 213         {
 214             if (area == null)
 215             {
 216                 return InteropImage.Fill(Handle, config, source, IntPtr.Zero);
 217             }
 218
 219             var rect = area.Value.ToMarshalable();
 220
 221             return InteropImage.Fill(Handle, config, source, ref rect);
 222         }
 223
 224         private void InvokeFill(MediaVisionSource source, ImageFillConfiguration config, Rectangle? area)
 225         {
 226             if (source == null)
 227             {
 228                 throw new ArgumentNullException(nameof(source));
 229             }
 230
 231             InvokeFill(source.Handle, EngineConfiguration.GetHandle(config), area).
 232                 Validate("Failed to fill the image object");
 233         }
 234
 235         /// <summary>
 236         /// Saves the image object.
 237         /// </summary>
 238         /// <param name="path">Path to the file to save the model.</param>
 239         /// <exception cref="ArgumentNullException"><paramref name="path"/> is null.</exception>
 240         /// <exception cref="UnauthorizedAccessException">No permission to write to the specified path.</exception>
 241         /// <exception cref="ObjectDisposedException">The <see cref="FaceRecognitionModel"/> has already been disposed of.</exception>
 242         /// <exception cref="DirectoryNotFoundException">The directory for <paramref name="path"/> does not exist.</exception>
 243         /// <since_tizen> 3 </since_tizen>
 244         public void Save(string path)
 245         {
 246             if (path == null)
 247             {
 248                 throw new ArgumentNullException(nameof(path));
 249             }
 250
 251             var ret = InteropImage.Save(path, Handle);
 252
 253             if (ret == MediaVisionError.InvalidPath)
 254             {
 255                 throw new DirectoryNotFoundException($"The directory for the path({path}) does not exist.");
 256             }
 257
 258             ret.Validate("Failed to save the image object");
 259         }
 260         #endregion
 261
 262         #region IDisposable-support
 263
 264         /// <summary>
 265         /// Releases all the resources used by the <see cref="ImageObject"/> object.
 266         /// </summary>
 267         public void Dispose()
 268         {
 269             Dispose(true);
 270             GC.SuppressFinalize(this);
 271         }
 272
 273         /// <summary>
 274         /// Releases the resources used by the <see cref="ImageObject"/> object.
 275         /// </summary>
 276         /// <param name="disposing">
 277         /// true to release both managed and unmanaged resources; otherwise false to release only unmanaged resources.
 278         /// </param>
 279         protected virtual void Dispose(bool disposing)
 280         {
 281             if (_disposed)
 282             {
 283                 return;
 284             }
 285
 286             InteropImage.Destroy(_handle);
 287             _disposed = true;
 288         }
 289
 290         internal IntPtr Handle
 291         {
 292             get
 293             {
 294                 if (_disposed)
 295                 {
 296                     throw new ObjectDisposedException(nameof(ImageObject));
 297                 }
 298                 return _handle;
 299             }
 300         }
 301         #endregion
 302     }
 303 }