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