src/Tizen.Multimedia/MediaVision/FaceRecognitionModel.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.Runtime.InteropServices;
  19 using static Interop.MediaVision;
  20
  21 namespace Tizen.Multimedia
  22 {
  23     /// <summary>
  24     /// This class represents face recognition model interface
  25     /// </summary>
  26     public class FaceRecognitionModel : IDisposable
  27     {
  28         internal IntPtr _recognitionModelHandle = IntPtr.Zero;
  29         private bool _disposed = false;
  30
  31         /// <summary>
  32         /// Construct of FaceRecognitionModel class
  33         /// </summary>
  34         public FaceRecognitionModel()
  35         {
  36             int ret = Interop.MediaVision.FaceRecognitionModel.Create(out _recognitionModelHandle);
  37             MediaVisionErrorFactory.CheckAndThrowException(ret, "Failed to create FaceRecognitionModel.");
  38         }
  39
  40         /// <summary>
  41         /// Construct of FaceRecognitionModel class which creates and loads recognition model from file.
  42         /// </summary>
  43         /// <remarks>
  44         /// FaceRecognitionModel is loaded from the absolute path directory.\n
  45         /// Models has been saved by <see cref="Save()"/> function can be loaded with this function
  46         /// </remarks>
  47         /// <param name="fileName">Name of path/file to load the model</param>
  48         /// <seealso cref="Save()"/>
  49         /// <code>
  50         ///
  51         /// </code>
  52         public FaceRecognitionModel(string fileName)
  53         {
  54             int ret = Interop.MediaVision.FaceRecognitionModel.Load(fileName, out _recognitionModelHandle);
  55             MediaVisionErrorFactory.CheckAndThrowException(ret, "Failed to load FaceRecognitionModel from file.");
  56         }
  57
  58         /// <summary>
  59         /// Destructor of the FaceRecognitionModel class.
  60         /// </summary>
  61         ~FaceRecognitionModel()
  62         {
  63             Dispose(false);
  64         }
  65
  66         /// <summary>
  67         /// Gets labels list
  68         /// </summary>
  69         public int[] FaceLabels
  70         {
  71             get
  72             {
  73                 IntPtr labelsArrayPtr;
  74                 uint numOfLabels = 0;
  75                 int ret = Interop.MediaVision.FaceRecognitionModel.QueryLabels(_recognitionModelHandle, out labelsArrayPtr, out numOfLabels);
  76                 if (ret != 0)
  77                 {
  78                     Tizen.Log.Error(MediaVisionLog.Tag, "Failed to get face labels");
  79                     return null;
  80                 }
  81
  82                 int[] labels = new int[numOfLabels];
  83                 for (int i = 0; i < numOfLabels; i++)
  84                 {
  85                     labels[i] = Marshal.ReadInt32(labelsArrayPtr);
  86                     labelsArrayPtr = IntPtr.Add(labelsArrayPtr, sizeof(int));
  87                 }
  88
  89                 return labels;
  90             }
  91         }
  92
  93         /// <summary>
  94         /// Calls this method to save recognition model to the file.
  95         /// </summary>
  96         /// <remarks>
  97         /// RecognitionModel is saved to the absolute path directory.
  98         /// </remarks>
  99         /// <param name="fileName">Name of the path/file to save the model</param>
 100         /// <code>
 101         ///
 102         /// </code>
 103         public void Save(string fileName)
 104         {
 105             if (string.IsNullOrEmpty(fileName))
 106             {
 107                 throw new ArgumentException("Invalid file name");
 108             }
 109
 110             int ret = Interop.MediaVision.FaceRecognitionModel.Save(fileName, _recognitionModelHandle);
 111             MediaVisionErrorFactory.CheckAndThrowException(ret, "Failed to save recognition model to file");
 112         }
 113
 114         /// <summary>
 115         /// Adds face image example to be used for face recognition model learning with <see cref="Learn()"/>.
 116         /// </summary>
 117         /// <param name="source">Source that contains face image</param>
 118         /// <param name="faceLabel">The label that identifies face for which example is adding. Specify the same labels for the face images of a single person when calling this method. Has to be unique for each face</param>
 119         /// <param name="location">The rectangular location of the face image at the source image.</param>
 120         /// <code>
 121         ///
 122         /// </code>
 123         public void Add(MediaVisionSource source, int faceLabel, Rectangle location = null)
 124         {
 125             if (source == null)
 126             {
 127                 throw new ArgumentException("Invalid source");
 128             }
 129
 130             IntPtr ptr = IntPtr.Zero;
 131             if (location != null)
 132             {
 133                 Interop.MediaVision.Rectangle rectangle = new Interop.MediaVision.Rectangle()
 134                 {
 135                     width = location.Width,
 136                     height = location.Height,
 137                     x = location.Point.X,
 138                     y = location.Point.Y
 139                 };
 140                 ptr = Marshal.AllocHGlobal(Marshal.SizeOf(rectangle));
 141                 Marshal.StructureToPtr(rectangle, ptr, false);
 142             }
 143
 144             int ret = Interop.MediaVision.FaceRecognitionModel.Add(source._sourceHandle, _recognitionModelHandle, ptr, faceLabel);
 145             MediaVisionErrorFactory.CheckAndThrowException(ret, "Failed to add face example image");
 146         }
 147
 148         /// <summary>
 149         /// Removes from RecognitionModel all collected with <see cref="Add()"/> function face examples labeled with faceLabel.
 150         /// </summary>
 151         /// <param name="faceLabel">The label that identifies face for which examples will be removed from the RecognitionModel.</param>
 152         /// <code>
 153         ///
 154         /// </code>
 155         public void Remove(int faceLabel)
 156         {
 157             int ret = Interop.MediaVision.FaceRecognitionModel.Remove(_recognitionModelHandle, ref faceLabel);
 158             MediaVisionErrorFactory.CheckAndThrowException(ret, "Failed to remove image example");
 159         }
 160
 161         /// <summary>
 162         /// Removes all image examples known by RecognitionModel.
 163         /// </summary>
 164         /// <code>
 165         ///
 166         /// </code>
 167         public void Reset()
 168         {
 169             int ret = Interop.MediaVision.FaceRecognitionModel.Reset(_recognitionModelHandle, IntPtr.Zero);
 170             MediaVisionErrorFactory.CheckAndThrowException(ret, "Failed to remove image example");
 171         }
 172
 173         /// <summary>
 174         /// Learns face recognition model.
 175         /// </summary>
 176         /// <remarks>
 177         /// Before you start learning process, face recognition models has to be filled with training data - face image examples.
 178         /// These examples has to be provided by <see cref="Add()"/> function. Usually, recognition accuracy is increased
 179         /// when number of not identical examples is large. But it depends on the used learning algorithm.
 180         /// </remarks>
 181         /// <param name="config">The configuration of engine will be used for learning of the recognition models. If NULL, then default settings will be used</param>
 182         /// <code>
 183         ///
 184         /// </code>
 185         public void Learn(FaceEngineConfiguration config = null)
 186         {
 187             int ret = Interop.MediaVision.FaceRecognitionModel.Learn((config != null) ? config._engineHandle : IntPtr.Zero, _recognitionModelHandle);
 188             MediaVisionErrorFactory.CheckAndThrowException(ret, "Failed to learn");
 189         }
 190
 191         public void Dispose()
 192         {
 193             Dispose(true);
 194             GC.SuppressFinalize(this);
 195         }
 196
 197         protected virtual void Dispose(bool disposing)
 198         {
 199             if (_disposed)
 200             {
 201                 return;
 202             }
 203
 204             if (disposing)
 205             {
 206                 // Free managed objects
 207             }
 208
 209             Interop.MediaVision.FaceRecognitionModel.Destroy(_recognitionModelHandle);
 210             _disposed = true;
 211         }
 212     }
 213 }