src/Tizen.Multimedia.Vision/MediaVision/FaceTrackingModel.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 InteropModel = Interop.MediaVision.FaceTrackingModel;
  20
  21 namespace Tizen.Multimedia.Vision
  22 {
  23     /// <summary>
  24     /// Represents the face tracking model.
  25     /// </summary>
  26     /// <feature>http://tizen.org/feature/vision.face_recognition</feature>
  27     /// <since_tizen> 4 </since_tizen>
  28     public class FaceTrackingModel : IDisposable
  29     {
  30         private IntPtr _handle = IntPtr.Zero;
  31         private bool _disposed = false;
  32
  33         /// <summary>
  34         /// Initializes a new instance of the <see cref="FaceTrackingModel"/> class.
  35         /// </summary>
  36         /// <exception cref="NotSupportedException">The feature is not supported.</exception>
  37         /// <since_tizen> 4 </since_tizen>
  38         public FaceTrackingModel()
  39         {
  40             InteropModel.Create(out _handle).Validate("Failed to create FaceTrackingModel.");
  41         }
  42
  43         /// <summary>
  44         /// Initializes a new instance of the <see cref="FaceTrackingModel"/> class with the specified path.
  45         /// </summary>
  46         /// <remarks>
  47         /// Models saved by <see cref="Save(string)"/> can be loaded.
  48         /// </remarks>
  49         /// <param name="modelPath">Path to the model to load.</param>
  50         /// <exception cref="ArgumentNullException"><paramref name="modelPath"/> is null.</exception>
  51         /// <exception cref="FileNotFoundException"><paramref name="modelPath"/> is invalid.</exception>
  52         /// <exception cref="NotSupportedException">
  53         ///     The feature is not supported.<br/>
  54         ///     -or-<br/>
  55         ///     <paramref name="modelPath"/> is not supported format.
  56         /// </exception>
  57         /// <exception cref="UnauthorizedAccessException">No permission to access the specified file.</exception>
  58         /// <seealso cref="Save(string)"/>
  59         /// <since_tizen> 4 </since_tizen>
  60         public FaceTrackingModel(string modelPath)
  61         {
  62             if (modelPath == null)
  63             {
  64                 throw new ArgumentNullException(nameof(modelPath));
  65             }
  66             InteropModel.Load(modelPath, out _handle).Validate("Failed to load FaceTrackingModel from file.");
  67         }
  68
  69         /// <summary>
  70         /// Finalizes an instance of the FaceTrackingModel class.
  71         /// </summary>
  72         ~FaceTrackingModel()
  73         {
  74             Dispose(false);
  75         }
  76
  77         private MediaVisionError InvokePrepare(MediaVisionSource source, Quadrangle region)
  78         {
  79             if (region != null)
  80             {
  81                 var quad = region.ToMarshalable();
  82                 return InteropModel.Prepare(Handle, IntPtr.Zero, source.Handle, ref quad);
  83             }
  84
  85             return InteropModel.Prepare(Handle, IntPtr.Zero, source.Handle, IntPtr.Zero);
  86         }
  87
  88         /// <summary>
  89         /// Initializes the tracking model by the location of the face to be tracked.
  90         ///
  91         /// It is usually called once after the tracking model is created, and each time before tracking
  92         /// is started for the new sequence of sources, which is not the direct continuation of
  93         /// the sequence for which tracking has been performed before. But, it is allowed to call it
  94         /// between tracking sessions to allow Media Vision start to track more accurately.
  95         /// </summary>
  96         /// <remarks>
  97         /// <paramref name="region"/> needs to be the position of the face to be tracked when called first time for the tracking model.
  98         /// <paramref name="region"/> is fitted to the valid region of <paramref name="source"/> if <paramref name="region"/> has invalid points.
  99         /// </remarks>
 100         /// <param name="source">The source where face location is specified.
 101         ///     Usually it is the first frame of the video or the first image in the continuous
 102         ///     image sequence planned to be used for tracking.</param>
 103         /// <param name="region">The region determining position of the face to be tracked on the source.
 104         ///     If null, then tracking model will try to find previously tracked face by itself.</param>
 105         /// <exception cref="ArgumentNullException"><paramref name="source"/> is null.</exception>
 106         /// <exception cref="ObjectDisposedException">
 107         ///     The <see cref="FaceTrackingModel"/> has already been disposed of.<br/>
 108         ///     -or-<br/>
 109         ///     <paramref name="source"/> has already bean disposed of.
 110         /// </exception>
 111         /// <since_tizen> 4 </since_tizen>
 112         public void Prepare(MediaVisionSource source, Quadrangle region)
 113         {
 114             if (source == null)
 115             {
 116                 throw new ArgumentNullException(nameof(source));
 117             }
 118
 119             InvokePrepare(source, region).Validate("Failed to prepare tracking model.");
 120         }
 121
 122         /// <summary>
 123         /// Saves the tracking model to the file.
 124         /// </summary>
 125         /// <param name="path">Path to the file to save the model.</param>
 126         /// <exception cref="ArgumentNullException"><paramref name="path"/> is null.</exception>
 127         /// <exception cref="UnauthorizedAccessException">No permission to write to the specified path.</exception>
 128         /// <exception cref="ObjectDisposedException">The <see cref="FaceTrackingModel"/> has already been disposed of.</exception>
 129         /// <exception cref="DirectoryNotFoundException">The directory for <paramref name="path"/> does not exist.</exception>
 130         /// <since_tizen> 4 </since_tizen>
 131         public void Save(string path)
 132         {
 133             if (path == null)
 134             {
 135                 throw new ArgumentNullException(nameof(path));
 136             }
 137
 138             var ret = InteropModel.Save(path, Handle);
 139
 140             if (ret == MediaVisionError.InvalidPath)
 141             {
 142                 throw new DirectoryNotFoundException($"The directory for the path({path}) does not exist.");
 143             }
 144
 145             ret.Validate("Failed to save tracking model to file");
 146         }
 147
 148         /// <summary>
 149         /// Releases all the resources used by the <see cref="FaceTrackingModel"/> object.
 150         /// </summary>
 151         /// <since_tizen> 4 </since_tizen>
 152         public void Dispose()
 153         {
 154             Dispose(true);
 155             GC.SuppressFinalize(this);
 156         }
 157
 158         /// <summary>
 159         /// Releases the resources used by the <see cref="FaceTrackingModel"/> object.
 160         /// </summary>
 161         /// <param name="disposing">
 162         /// true to release both managed and unmanaged resources; otherwise false to release only unmanaged resources.
 163         /// </param>
 164         /// <since_tizen> 4 </since_tizen>
 165         protected virtual void Dispose(bool disposing)
 166         {
 167             if (_disposed)
 168             {
 169                 return;
 170             }
 171
 172             InteropModel.Destroy(_handle);
 173             _disposed = true;
 174         }
 175
 176         internal IntPtr Handle
 177         {
 178             get
 179             {
 180                 if (_disposed)
 181                 {
 182                     throw new ObjectDisposedException(nameof(FaceTrackingModel));
 183                 }
 184                 return _handle;
 185             }
 186         }
 187     }
 188 }