VisageTrackerUnityPlugin
docs_VisageAnalyserUnityPlugin.cs
1 using System;
2 using System.Collections.Generic;
3 using System.Linq;
4 using System.Text;
5 
6 
7 /// <summary>
8 /// Provides high-level functions for using visage|SDK face analysis capabilities in Unity game engine.
9 /// It implements high-level wrapper functions from visage|SDK that enable usage of visage|SDK face analysis capabilities in Unity C# scripts.
10 ///
11 /// VisageFaceAnalyser contains face analysis algorithms for estimating age, gender and emotion from facial images/frames.
12 ///
13 /// The functionality of VisageFaceAnalyser is dependent on the VisageTracker and it is expected that prior to the call of VisageFaceAnalyser's functions frame is processed with _track() function
14 /// and the data thus obtained is prepared and forwarded to VisageFaceAnalyser.
15 ///
16 /// Before using VisageFaceAnalyser, it must be initialized by calling the _initAnalyser() function.
17 /// Afterward, in each frame, the _prepareDataForAnalysis() function is called first, followed by calling _analyseStream() function,
18 /// otherwise analysis will fail which will be indicated by function's return code.
19 ///
20 /// VisageFaceAnalyser's functionality can be used in a separate thread.
21 ///
22 /// </summary>
23 ///
24 
25 /**
26 * \defgroup VisageAnalyserUnityPlugin VisageAnalyserUnityPlugin
27 * @{
28 */
29 
30 /** Managed equivalent of the native <a href="../../../../../../doc/OpenGL/sdk-html/structVisageSDK_1_1AnalysisData.html">AnalysisData</a> structure, used as a container for all face analysis results.
31 * This structure is passed as a parameter to the _analyseImage() or _analyseStream() method. Both methods store analysis results into the structure.
32 *
33 * Members ageValid, genderValid and emotionsValid may be used to verify that analysis for those features was performed successfully, before checking the results.
34 * If an operation was not performed (turned off via options) or failed, the respective validity boolean will return false and estimations will contain the default value.
35 *
36 * Member emotionProbabilities is a 7-element float array. If emotion estimation was performed successfully, the array will be filled with estimated probabilities for emotions in the following order: anger, disgust, fear, happiness, sadness, surprise, neutral.
37 */
39 {
40  float age; ///< result of age estimation
41  bool ageValid; ///< boolean flag returning whether age estimation has been successful or not
42  int gender; ///< result of gender estimation
43  bool genderValid; ///< boolean flag returning whether gender estimation has been successful or not
44  float emotionProbabilities[7]; ///< result of emotion estimation, array indices correspond with the native <a href="../../../../../../doc/OpenGL/sdk-html/namespaceVisageSDK.html#aeb7ccb178e0a6bdc4fa452360b65e5ce"> VFAEmotionIndices</a> enumeration.
45  bool emotionsValid; ///< boolean flag returning whether emotion estimation has been successful or not
46 };
47 
48 /** Initialises VisageFaceAnalyser.
49 *This function must be called before using VisageFaceAnalyser by passing it a path to the folder containing the VisageFaceAnalyser data files. Within the Visage|SDK package, this folder is Samples/data/vfa. The VisageFaceAnalyser data folder contains the following subfolders corresponding to the various types of analysis that can be performed:
50 *
51 <ul>
52 <li>ad: age estimation</li>
53 <li>gd: gender estimation</li>
54 <li>ed: emotion estimation</li>
55 </ul>
56 *
57 * An example of use:
58 * \code
59 *
60 * private ManagedAnalysisData[] analysisData = new ManagedAnalysisData[Tracker.MAX_FACES];
61 * int analyserInited = VisageTrackerNative._initAnalyser(dataPath);
62 *
63 * for (int faceIndex = 0; faceIndex < MAX_FACES; faceIndex++)
64 * {
65 * if ((analyserInited & (int)VFAFlags.VFA_AGE) == (int)VFAFlags.VFA_AGE)
66 * {
67 * VFAReturnCode status = VisageTrackerNative._analyseStream(faceIndex, (int)VFAFlags.VFA_AGE, ref analysisData[faceIndex]);
68 * if ((status == NoError) && analysisData[faceIndex].ageValid)
69 * age[faceIndex] = analysisData[faceIndex].age;
70 * }
71 * }
72 * \endcode
73 *
74 *Note that it is not necessary for all subfolders to be present, only the ones needed by the types of analysis that will be performed. For example, if only age estimation will be performed, then only the ad folder is required.
75 *The return value of the function indicates which types of analysis have been successfully initialised. Subsequent attempt to use a type of analysis that was not initialized shall fail; for example, if only ad folder was present at initialization, calling either of the analyse functions with VFAFlags.VFA_EMOTION option will result in non valid emotion estimation.
76 *The return value is a bitwise combination of flags indicating which types of analysis are successfully initialized.
77 *
78 *Please note that in order for license to be registered, _initializeLicense() method has to be called before.
79 *
80 * @param dataPath Relative path from the working directory to the directory that contains VisageFaceAnalyser data files (e.g. Application.streamingAssetsPath + /Visage Tracker/vfa").
81 * @return The return value of 0 indicates that no data files are found and no analysis will be possible. In such case, the placement of data files should be verified. A non-zero value indicates that one or more types of analysis are successfully initialized. The specific types of analysis that have been initialized are indicated by a bitwise combination of the following flags: VFA_AGE, VFA_GENDER, VFA_EMOTION.
82 */
83 int _initAnalyser(string dataPath);
84 
85 /** Releases memory allocated by the face analyser in the _initAnalyser() function.
86 *
87 * This function is called after the analyser ceases to be used or before the reinitialization of the analyser.
88 */
89 void _releaseAnalyser();
90 
91 /** Performs the specified face analysis tasks on a given image and outputs results to ManagedAnalysisData object instance.
92 *
93 * This function is primarily intended for performing face analysis on a single image, or consecutive unrelated images.
94 * As such, it outputs raw, unfiltered estimation data without smoothing or averaging.
95 *
96 * \note Prior to using this function it is necessary to process the facial image using VisageTracker or VisageFeaturesDetector and pass the frame and obtained data to this function.
97 *
98 * @param faceIndex Value between 0 and MAX_FACES-1, used to access the data of a particular tracked face.
99 * @param options Bitwise combination of the native <a href="../../../../../../doc/OpenGL/sdk-html/namespaceVisageSDK.html#ae9488b04d41d214ff1962a7a17a14374">VFAFlags</a> enumeration which determines the analysis operations to be performed.
100 * @param results Managed equivalent of the native AnalysisData structure, used as a container for all face analysis results.
101 * @return <a href="../../../../../../doc/OpenGL/sdk-html/namespaceVisageSDK.html#a71d4437838eb33f68ddce77257c783e0"> VFAReturnCode</a> Return code indicating status of performed face analysis.
102 */
103 VFAReturnCode _analyseImage(int faceIndex, int options, ManagedAnalysisData& results);
104 
105 /** Performs the specified face analysis tasks on a given frame and outputs results to ManagedAnalysisData object instance.
106 *
107 * This function is primarily intended for performing face analysis on a continuous stream of related frames, such as a video or camera feed.
108 * Sampling face analysis data from multiple frames can increase estimation accuracy by averaging the result over multiple frames.
109 * Internally, the suitability of frames chosen for analysis is continually evaluted based on head pose and overall tracking quality.
110 * This guarantees that the analysis buffer is always working with the best available frames, ensuring highest possible estimation accuracy.
111 *
112 * \note Prior to using this function it is necessary to process the facial image using VisageTracker and pass the frame and obtained data to this function.
113 * The bitwise set of analysis operations determined by the 'options' parameter is expected to be constant between subsequent calls to analyseStream(). If the next iteration of
114 * analyseStream() is called with a different set of bitwise flags than the previous, the internal buffers will be reset and previously collected analysis data will be lost.
115 *
116 * An example of use:
117 * \code
118 *
119 * public float[] Age = new float[MAX_FACES];
120 * public int[] Gender = new int[MAX_FACES];
121 * public float[,] Emotions = new float[MAX_FACES, NUM_EMOTIONS];
122 * private ManagedAnalysisData[] analysisData = new ManagedAnalysisData[Tracker.MAX_FACES];
123 *
124 * for(int i = 0; i < MAX_FACES; ++i)
125 * {
126 * int status = VisageTrackerNative._analyseStream(faceIndex, analyserOptions, ref analysisData[faceIndex]);
127 *
128 * if(status == VFAReturnCode.NoError)
129 * {
130 * if (analysisData[faceIndex].ageValid)
131 * Age[faceIndex] = analysisData[faceIndex].age;
132 * if (analysisData[faceIndex].genderValid)
133 * Gender[faceIndex] = analysisData[faceIndex].gender;
134 * if (analysisData[faceIndex].emotionsValid)
135 * {
136 * for (int j = 0; j < NUM_EMOTIONS; j++)
137 * Emotions[i, j] = analysisData[faceIndex].emotionProbabilities[j];
138 * }
139 * }
140 * }
141 * \endcode
142 *
143 * @param faceIndex Value between 0 and MAX_FACES-1, used to access the data of a particular tracked face.
144 * @param options Bitwise combination of the native <a href="../../../../../../doc/OpenGL/sdk-html/namespaceVisageSDK.html#ae9488b04d41d214ff1962a7a17a14374">VFAFlags</a> enumeration which determines the analysis operations to be performed.
145 * @param results Managed equivalent of the native AnalysisData structure, used as a container for all face analysis results.
146 * @return <a href="../../../../../../doc/OpenGL/sdk-html/namespaceVisageSDK.html#a71d4437838eb33f68ddce77257c783e0"> VFAReturnCode</a> Return code indicating status of performed face analysis.
147 */
148 VFAReturnCode _analyseStream(int faceIndex, int options, ManagedAnalysisData& results);
149 
150 /** Prepares data obtained by the track function.
151 */
153 
154 /** @} */
155 
int _initAnalyser(string dataPath)
Initialises VisageFaceAnalyser.
float emotionProbabilities[7]
result of emotion estimation, array indices correspond with the native VFAEmotionIndices enumeration...
VFAReturnCode _analyseStream(int faceIndex, int options, ManagedAnalysisData &results)
Performs the specified face analysis tasks on a given frame and outputs results to ManagedAnalysisDat...
bool emotionsValid
boolean flag returning whether emotion estimation has been successful or not
bool _prepareDataForAnalysis()
Prepares data obtained by the track function.
Managed equivalent of the native AnalysisData structure, used as a container for all face analysis re...
VFAReturnCode _analyseImage(int faceIndex, int options, ManagedAnalysisData &results)
Performs the specified face analysis tasks on a given image and outputs results to ManagedAnalysisDat...
bool ageValid
boolean flag returning whether age estimation has been successful or not
float age
result of age estimation
void _releaseAnalyser()
Releases memory allocated by the face analyser in the _initAnalyser() function.
int gender
result of gender estimation
bool genderValid
boolean flag returning whether gender estimation has been successful or not