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