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