VisageTrackerUnityPlugin
docs_VisageRecognitionUnityPlugin.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 recognition capabilities in Unity game engine.
9 /// It implements high-level wrapper functions from visage|SDK that enable usage of visage|SDK face recognition capabilities in Unity C# scripts.
10 ///
11 /// VisageFaceRecognition contains a face recognition algorithm capable of measuring similarity between human faces and recognizing a person's identity from frontal facial images (yaw angle approximately from -20 to 20 degrees).
12 ///
13 /// Similarity between two faces is calculated as difference between their face descriptors and returned as a value between 0 (no similarity) and 1 (maximum similarity).
14 ///
15 /// The face descriptor is a condensed representation of a face.It is an array of short values.
16 /// The dimension of the array is obtained using getDescriptorSize() function, from now on in the text referred to as DESCRIPTOR_SIZE.
17 /// For any two faces, the distance between descriptors is a measure of their similarity.
18 ///
19 /// For the purpose of face recognition, faces are stored in a gallery.The gallery is an array of face descriptors, with a corresponding array of names,
20 /// so that the gallery may contain n descriptors and a corresponding name for each descriptor.
21 /// To perform recognition, the face descriptor extracted from the input image is then compared with face descriptors from the gallery and the similarity between the input face descriptor
22 /// and all face descriptors from the gallery is calculated in order to find the face(s) from the gallery that are most similar to the input face.
23 /// The VisageFaceRecognition class includes a full set of functions for manipulating the gallery, including adding, removing, naming descriptors in the gallery as well as loading and saving the gallery to file.
24 ///
25 /// The functionality of VisageFaceRecognition is dependent on the VisageTracker and it is expected that prior to the call of VisageFaceRecognition's functions frame is processed with _track() function
26 /// and the data thus obtained is prepared and forwarded to VisageFaceRecognition.
27 ///
28 /// Before using VisageFaceRecognition, it must be initialized by calling the _initRecognition() function.
29 /// Afterward, in each frame, the _prepareDataForRecog() function is called first and then all other VisageFaceRecognition's functions can be called
30 /// otherwise they will return -1 as an indication that the necessary data is missing.
31 ///
32 /// VisageFaceRecognition's functionality can be used in a separate thread.
33 /// </summary>
34 ///
35 
36 /**
37  * \defgroup VisageRecognitionUnityPlugin VisageRecognitionUnityPlugin
38  * @{
39  */
40 
41 /** Initialises VisageFaceRecognition.
42 *
43 * If the VisageFaceRecognition is initialized successfully function returns true, otherwise it returns false.
44 *
45 * Please note that in order for license to be registered, _initializeLicense() method has to be called before.
46 *
47 * @param dataPath Relative path to the data file required for face recognition, including data file name. In the visage|SDK distribution, the file is: Samples/data/vfr/fr.bin.
48 * @return True on success, false otherwise,
49 */
50 bool _initRecognition(string dataPath);
51 
52 /** Releases memory allocated by the face recogntion in the _initRecognition() function.
53  *
54  * This function is called after the recognition ceases to be used or before the reinitialization of the recognition.
55 */
56 void _releaseRecognition();
57 
58 /** Returns the size of descriptor.
59 *
60 * @return DESCRIPTOR_SIZE.
61 */
62  int _getDescriptorSize();
63 
64 /** Extracts the face descriptor for face recognition.
65 *
66 */
67  bool _prepareDataForRecog();
68 
69 /** Extracts the face descriptor for face recognition. Prior to using this function, it is necessary to process the video frame
70 * using _track() function and prepare obtained data with _prepareDataForRecog() function.
71 * In case of multiple trackers running faceIndex specifies tracker ID.
72 *
73 * @param descriptor DESCRIPTOR_SIZE-dimensional array that will be filled with the resulting face descriptor.
74 * @param faceIndex Value between 0 and MAX_FACES-1, used to access the data of a particular tracked face.
75 * @return 1 on success, 0 or -1 on failure.
76 *
77 * See also: FaceData, VisageTracker, VisageFeaturesDetector
78 */
79 int _extractDescriptor(short[] descriptor, int faceIndex);
80 
81 /** Calculates similarity between two descriptors.
82 *
83 * The function returns a float value between 0 and 1. Two descriptors are equal if the similarity is 1. Two descriptors are completely different if the similarity is 0.
84 *
85 * @param firstDescrtiptor An array of DESCRIPTOR_SIZE short values.
86 * @param secondDescriptor An array of DESCRIPTOR_SIZE short values.
87 * @return Float value between 0 and 1 on success, 1 means full similarity and 0 means full diversity or -1 on failure.
88 */
89 float _descriptorsSimilarity(short[] firstDescrtiptor, short[] secondDescriptor);
90 
91 /** Adds descriptor to the gallery.
92 *
93 * @param descriptor Descriptor to be added to the gallery obtained by calling _extractDescriptor().
94 * @param name Name of the descriptor.
95 * @return 1 on success, 0 or -1 on failure.
96 */
97 int _addDescriptor(short[] descriptor, string name);
98 
99 /** Gets number of descriptors in the gallery.
100 *
101 * @return Number of descriptors in the gallery.
102 */
103 int _getDescriptorCount();
104 
105 /** Gets the name of a descriptor at the given index in the gallery.
106 *
107 * @param galleryIndex Index of descriptor in the gallery.
108 * @return Name on success, empty string on failure.
109 */
110 string _getDescriptorName(int galleryIndex);
111 
112 /** Replaces the name of a descriptor at the given index in the gallery with new name.
113 *
114 * @param name New descriptor name.
115 * @param galleryIndex Index of descriptor in the gallery.
116 * @return 1 on success, 0 or -1 on failure. The function may fail if index is out of range.
117 */
118 int _replaceDescriptorName(string name, int galleryIndex);
119 
120 /** Removes a descriptor at the given index from the gallery.
121 * The remaining descriptors in the gallery above the given index (if any) are shifted down in the gallery array by one place, filling the gap created by removing the descriptor.
122 *
123 * @param galleryIndex Index of descriptor in the gallery.
124 * @return 1 on success, 0 or -1 on failure. The function may fail if index is out of range.
125 */
126 int _removeDescriptor(int galleryIndex);
127 
128 /** Save gallery as a binary file.
129 *
130 * @param fileName Name of the file (including path if needed) into which the gallery will be saved.
131 * @return 1 on success, 0 or -1 on failure. The function fails if the file can not be opened.
132 */
133 int _saveGallery(string fileName);
134 
135 /** Loads gallery from a binary file.
136 * The entries from the loaded gallery are appended to the current gallery. If it is required to replace existing gallery with the loaded one, call _resetGallery() first.
137 *
138 * @param fileName Name of the file (including path if needed) from which the gallery will be loaded.
139 * @return 1 on success, 0 or -1 on failure. The function fails if the file can not be opened.
140 */
141 int _loadGallery(string fileName);
142 
143 /** Clear all face descriptors from the gallery.
144 */
145  void _resetGallery();
146 
147 /** Compare a face to all faces in the current gallery and return n names of the most similar faces.
148 *
149 * Names array is passed as StringBuilder array to the function. The following code is an example of how the StringBuilder array is created, passed to the function and used after it is filled with strings:
150 * \code
151 *
152 * //maximum number of characters per name
153 * const int SB_CAPACITY = 50;
154 *
155 * //prepare stringbuilder
156 * System.Text.StringBuilder[] sbArray = new System.Text.StringBuilder[n];
157 * for (int i = 0; i < n; ++i)
158 * {
159 * sbArray[i] = new System.Text.StringBuilder(SB_CAPACITY);
160 * }
161 * //call of the _recognize function
162 * int ret = _recognize(descriptor, n, sbArray, SB_CAPACITY, similarities);
163 *
164 * List<string> names = new List<string>();
165 *
166 * //fill list of strings
167 * for (int i = 0; i < n; ++i)
168 * {
169 * names.Add(sbArray[i].ToString());
170 * }
171 *
172 * \endcode
173 *
174 * The example can be found in the VisageTrackerNative.Windows.cs (_recognizeWrapper() function) file within the VisageTrackerUnityDemo project.
175 *
176 * @param descriptor Face descriptor of the face to be recognized (compared to the gallery).
177 * @param n Number of names and similarities to be returned.
178 * @param names List type of <a href="https://msdn.microsoft.com/en-us/library/system.text.stringbuilder(v=vs.110).aspx">StringBuilder</a> that will be filled with the names of n faces from the gallery that are most similar to the input image ascending by similarity. Maximum number of characters per name is set to 256, for larger name only first 256 characters will be returned.
179 * @param capacity Number representing the desired capacity of a particular name in a string of names.
180 * @param similarities Array that will be filled with the similarity values for the n most similar faces, corresponding to the names array. The values are sorted, with the largest similarity value first.
181 * @return Number of compared faces.
182 */
183 int _recognize(short[] descriptor, int n, System.Text.StringBuilder[] names, int capacity, float[] similarities);
184 
185 /** @} */
186 
bool _prepareDataForRecog()
Extracts the face descriptor for face recognition.
void _resetGallery()
Clear all face descriptors from the gallery.
string _getDescriptorName(int galleryIndex)
Gets the name of a descriptor at the given index in the gallery.
int _getDescriptorSize()
Returns the size of descriptor.
int _getDescriptorCount()
Gets number of descriptors in the gallery.
void _releaseRecognition()
Releases memory allocated by the face recogntion in the _initRecognition() function.
int _replaceDescriptorName(string name, int galleryIndex)
Replaces the name of a descriptor at the given index in the gallery with new name.
bool _initRecognition(string dataPath)
Initialises VisageFaceRecognition.
int _loadGallery(string fileName)
Loads gallery from a binary file.
int _extractDescriptor(short[] descriptor, int faceIndex)
Extracts the face descriptor for face recognition.
int _removeDescriptor(int galleryIndex)
Removes a descriptor at the given index from the gallery.
int _recognize(short[] descriptor, int n, System.Text.StringBuilder[] names, int capacity, float[] similarities)
Compare a face to all faces in the current gallery and return n names of the most similar faces...
float _descriptorsSimilarity(short[] firstDescrtiptor, short[] secondDescriptor)
Calculates similarity between two descriptors.
int _addDescriptor(short[] descriptor, string name)
Adds descriptor to the gallery.
int _saveGallery(string fileName)
Save gallery as a binary file.