visageSDK
Functions
VisageRecognitionUnityPlugin

Provides high-level functions for using visage|SDK face recognition capabilities in Unity game engine. More...

Functions

bool _initRecognition (string dataPath)
 Initialises VisageFaceRecognition. More...
 
void _releaseRecognition ()
 Releases memory allocated by the face recogntion in the _initRecognition() function. More...
 
int _getDescriptorSize ()
 Returns the size of descriptor. More...
 
bool _prepareDataForRecog ()
 Extracts the face descriptor for face recognition.
 
int _extractDescriptor (short[] descriptor, int faceIndex)
 Extracts the face descriptor for face recognition. More...
 
float _descriptorsSimilarity (short[] firstDescrtiptor, short[] secondDescriptor)
 Calculates similarity between two descriptors. More...
 
int _addDescriptor (short[] descriptor, string name)
 Adds descriptor to the gallery. More...
 
int _getDescriptorCount ()
 Gets number of descriptors in the gallery. More...
 
string _getDescriptorName (int galleryIndex)
 Gets the name of a descriptor at the given index in the gallery. More...
 
int _replaceDescriptorName (string name, int galleryIndex)
 Replaces the name of a descriptor at the given index in the gallery with new name. More...
 
int _removeDescriptor (int galleryIndex)
 Removes a descriptor at the given index from the gallery. More...
 
int _saveGallery (string fileName)
 Save gallery as a binary file. More...
 
int _loadGallery (string fileName)
 Loads gallery from a binary file. More...
 
void _resetGallery ()
 Clear all face descriptors 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. More...
 

Detailed Description

Provides high-level functions for using visage|SDK face recognition capabilities in Unity game engine.

It implements high-level wrapper functions from visage|SDK that enable usage of visage|SDK face recognition capabilities in Unity C# scripts.

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).

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).

The face descriptor is a condensed representation of a face.It is an array of short values. The dimension of the array is obtained using getDescriptorSize() function, from now on in the text referred to as DESCRIPTOR_SIZE. For any two faces, the distance between descriptors is a measure of their similarity.

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, so that the gallery may contain n descriptors and a corresponding name for each descriptor. 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 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. 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.

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 and the data thus obtained is prepared and forwarded to VisageFaceRecognition.

Before using VisageFaceRecognition, it must be initialized by calling the _initRecognition() function. Afterward, in each frame, the _prepareDataForRecog() function is called first and then all other VisageFaceRecognition's functions can be called otherwise they will return -1 as an indication that the necessary data is missing.

VisageFaceRecognition's functionality can be used in a separate thread.

Function Documentation

◆ _addDescriptor()

int _addDescriptor ( short []  descriptor,
string  name 
)

Adds descriptor to the gallery.

Parameters
descriptorDescriptor to be added to the gallery obtained by calling _extractDescriptor().
nameName of the descriptor.
Returns
1 on success, 0 or -1 on failure.

◆ _descriptorsSimilarity()

float _descriptorsSimilarity ( short []  firstDescrtiptor,
short []  secondDescriptor 
)

Calculates similarity between two descriptors.

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.

Parameters
firstDescrtiptorAn array of DESCRIPTOR_SIZE short values.
secondDescriptorAn array of DESCRIPTOR_SIZE short values.
Returns
Float value between 0 and 1 on success, 1 means full similarity and 0 means full diversity or -1 on failure.

◆ _extractDescriptor()

int _extractDescriptor ( short []  descriptor,
int  faceIndex 
)

Extracts the face descriptor for face recognition.

Prior to using this function, it is necessary to process the video frame using _track() function and prepare obtained data with _prepareDataForRecog() function. In case of multiple trackers running faceIndex specifies tracker ID.

Parameters
descriptorDESCRIPTOR_SIZE-dimensional array that will be filled with the resulting face descriptor.
faceIndexValue between 0 and MAX_FACES-1, used to access the data of a particular tracked face.
Returns
1 on success, 0 or -1 on failure.

See also: FaceData, VisageTracker, VisageFeaturesDetector

◆ _getDescriptorCount()

int _getDescriptorCount ( )

Gets number of descriptors in the gallery.

Returns
Number of descriptors in the gallery.

◆ _getDescriptorName()

string _getDescriptorName ( int  galleryIndex)

Gets the name of a descriptor at the given index in the gallery.

Parameters
galleryIndexIndex of descriptor in the gallery.
Returns
Name on success, empty string on failure.

◆ _getDescriptorSize()

int _getDescriptorSize ( )

Returns the size of descriptor.

Returns
DESCRIPTOR_SIZE.

◆ _initRecognition()

bool _initRecognition ( string  dataPath)

Initialises VisageFaceRecognition.

If the VisageFaceRecognition is initialized successfully function returns true, otherwise it returns false.

Please note that in order for license to be registered, _initializeLicense() method has to be called before.

Parameters
dataPathRelative 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.
Returns
True on success, false otherwise,

◆ _loadGallery()

int _loadGallery ( string  fileName)

Loads gallery from a binary file.

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.

Parameters
fileNameName of the file (including path if needed) from which the gallery will be loaded.
Returns
1 on success, 0 or -1 on failure. The function fails if the file can not be opened.

◆ _recognize()

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.

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:

//maximum number of characters per name
const int SB_CAPACITY = 50;
//prepare stringbuilder
System.Text.StringBuilder[] sbArray = new System.Text.StringBuilder[n];
for (int i = 0; i < n; ++i)
{
sbArray[i] = new System.Text.StringBuilder(SB_CAPACITY);
}
//call of the _recognize function
int ret = _recognize(descriptor, n, sbArray, SB_CAPACITY, similarities);
List<string> names = new List<string>();
//fill list of strings
for (int i = 0; i < n; ++i)
{
names.Add(sbArray[i].ToString());
}

The example can be found in the VisageTrackerNative.Windows.cs (_recognizeWrapper() function) file within the VisageTrackerUnityDemo project.

Parameters
descriptorFace descriptor of the face to be recognized (compared to the gallery).
nNumber of names and similarities to be returned.
namesList type of StringBuilder 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.
capacityNumber representing the desired capacity of a particular name in a string of names.
similaritiesArray 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.
Returns
Number of compared faces.

◆ _releaseRecognition()

void _releaseRecognition ( )

Releases memory allocated by the face recogntion in the _initRecognition() function.

This function is called after the recognition ceases to be used or before the reinitialization of the recognition.

◆ _removeDescriptor()

int _removeDescriptor ( int  galleryIndex)

Removes a descriptor at the given index from the gallery.

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.

Parameters
galleryIndexIndex of descriptor in the gallery.
Returns
1 on success, 0 or -1 on failure. The function may fail if index is out of range.

◆ _replaceDescriptorName()

int _replaceDescriptorName ( string  name,
int  galleryIndex 
)

Replaces the name of a descriptor at the given index in the gallery with new name.

Parameters
nameNew descriptor name.
galleryIndexIndex of descriptor in the gallery.
Returns
1 on success, 0 or -1 on failure. The function may fail if index is out of range.

◆ _saveGallery()

int _saveGallery ( string  fileName)

Save gallery as a binary file.

Parameters
fileNameName of the file (including path if needed) into which the gallery will be saved.
Returns
1 on success, 0 or -1 on failure. The function fails if the file can not be opened.