visageSDK
Public Member Functions | Public Attributes | List of all members
VisageCSWrapper.VisageFaceRecognition Class Reference

VisageFaceRecognition class 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). More...

Public Member Functions

 VisageFaceRecognition (System::String^dataPath)
 Constructor. More...
 
 ~VisageFaceRecognition ()
 Destructor. More...
 
int GetDescriptorSize ()
 Gets the descriptor's size. More...
 
int ExtractDescriptor (FaceData^facedata, VSImage^image, short[] descriptor)
 Extracts the face descriptor for face recognition from a facial image. More...
 
float DescriptorsSimilarity (short[] first_descriptor, short[] second_descriptor)
 Calculates similarity between two descriptors. More...
 
int AddDescriptor (VSImage^image, FaceData^facedata, System::String^name)
 Extracts a face descriptor from the input RGB image and adds it to the gallery. More...
 
int AddDescriptor (short[] descriptor, System::String^name)
 Adds a face descriptor to the gallery. More...
 
int GetDescriptorCount ()
 Gets number of descriptors in the gallery. More...
 
int GetDescriptorName (char *name, int index)
 Gets the name of a descriptor at the given index in the gallery. More...
 
int ReplaceDescriptorName (const char *name, int index)
 Replaces the name of a descriptor at the given index in the gallery with new name. More...
 
int RemoveDescriptor (int index)
 Removes a descriptor at the given index from the gallery. More...
 
int SaveGallery (System::String^file_name)
 Save gallery as a binary file. More...
 
int LoadGallery (System::String^file_name)
 Load gallery from a binary file. More...
 
void ResetGallery ()
 Clear all face descriptors from the gallery. More...
 
int Recognize (short[] descriptor, int n, ref string[] names, float[] similarities)
 Compare a face to all faces in the current gallery and return n names of the most similar faces. More...
 

Public Attributes

property bool IsInitialized
 If the model used in the VisageFaceRecognition is loaded and initialized successfully value of the is_initialized variable is true, otherwise it is false. More...
 

Detailed Description

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

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. To extract descriptors from facial image, method ExtractDescriptor() is provided. 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) using DescriptorsSimilarity().

For a person to be recognized, its identity has to be stored beforehand. Database of stored face descriptors will be referred to as face recognition gallery. For smaller sets of face descriptors (up to several hundred), higher-level API for recognizing person's identity using face recognition gallery is provided. 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 the following 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 gallery is stored as a simple txt file and as such it is not intended to be used to save large number of face descriptors. The current implementation of gallery is only a demonstration of how Face Recognition API can be used and it is recommended to implement more efficient solution for scenarios which require large face recognition gallery.

An example of face recognition gallery stored to a file is famous_actors.frg, located in Samples/OpenGL/data/ShowcaseDemo.

Definition at line 30 of file VisageFaceRecognition.cs.

Constructor & Destructor Documentation

VisageCSWrapper.VisageFaceRecognition.VisageFaceRecognition ( System::String^  dataPath)

Constructor.

Parameters
dataPathpath to the data file required for face recognition. In the visage|SDK distribution, the file is: Samples/data/vfr/fr.bin.
VisageCSWrapper.VisageFaceRecognition.~VisageFaceRecognition ( )

Destructor.

Member Function Documentation

int VisageCSWrapper.VisageFaceRecognition.AddDescriptor ( VSImage^  image,
FaceData^  facedata,
System::String^  name 
)

Extracts a face descriptor from the input RGB image and adds it to the gallery.

Parameters
imageVsImage pointer that contains the input RGB image. The image should contain only one face and this face will be added to the gallery. In case of multiple faces in the image, it is not defined which face would be used.
facedataFacial data obtained from VisageTracker or VisageFeaturesDetector.
nameName of the face in the image.
Returns
Returns 1 on success, 0 on failure. The function fails if the face is not found in the image or if the image argument is not a valid RGB image pointer.

See also: VSImage

int VisageCSWrapper.VisageFaceRecognition.AddDescriptor ( short[]  descriptor,
System::String^  name 
)

Adds a face descriptor to the gallery.

Parameters
descriptorPointer to the face descriptor (an array of DESCRIPTOR_SIZE short values) which will be added to the gallery.
nameName of the face in the image.
Returns
Returns 1 on success, 0 on failure. The function fails if the descriptor is not a valid RGB image pointer.
float VisageCSWrapper.VisageFaceRecognition.DescriptorsSimilarity ( short[]  first_descriptor,
short[]  second_descriptor 
)

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
first_descriptorPointer to the first descriptor, an array of DESCRIPTOR_SIZE short values.
second_descriptorPointer to the second descriptor, an array of DESCRIPTOR_SIZE short values.
Returns
Returns float value between 0 and 1, 1 means full similarity and 0 means full diversity.
int VisageCSWrapper.VisageFaceRecognition.ExtractDescriptor ( FaceData^  facedata,
VSImage^  image,
short[]  descriptor 
)

Extracts the face descriptor for face recognition from a facial image.

Prior to using this function, it is neccessary to process the facial image or video frame using VisageTracker or VisageFeaturesDetector and pass the obtained facial data to this function.

Parameters
facedataFacial data obtained from VisageTracker or VisageFeaturesDetector.
imageVsImage pointer to the input RGB image.
descriptorPointer to a DESCRIPTOR_SIZE-dimensional array of short. The resulting face descriptor is returned in this array.
Returns
Returns 1 on success, 0 on failure.

See also: FaceData, VisageTracker, VisageFeaturesDetector

int VisageCSWrapper.VisageFaceRecognition.GetDescriptorCount ( )

Gets number of descriptors in the gallery.

Returns
Returns number of descriptors in the gallery.
int VisageCSWrapper.VisageFaceRecognition.GetDescriptorName ( char *  name,
int  index 
)

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

Parameters
nameBuffer into which the name of a descriptor is filled.
indexIndex of descriptor in the gallery.
Returns
Returns 1 on success, 0 on failure. The function fails if index is out of range.
int VisageCSWrapper.VisageFaceRecognition.GetDescriptorSize ( )

Gets the descriptor's size.

The function returns size of an array which should be allocated for storing the descriptor.

Returns
descriptor's size.
int VisageCSWrapper.VisageFaceRecognition.LoadGallery ( System::String^  file_name)

Load 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
file_nameName of the file (including path if needed) from which the gallery will be loaded.
Returns
Returns 1 on success, 0 on failure. The function fails if the file can not be opened.
int VisageCSWrapper.VisageFaceRecognition.Recognize ( short[]  descriptor,
int  n,
ref string[]  names,
float[]  similarities 
)

Compare a face to all faces in the current gallery and return n names of the most similar faces.

Parameters
descriptorPointer to the face descriptor of the face to be recognized (compared to the gallery).
nNumber of names and similarities to be returned.
namesPointer to an array of char arrays. In this array the function will return names of n faces from the gallery that are most similar to the input image ascending by similarity.
similaritiesPointer to an array of n floats. The function will return the ascending similarity values for the n most similar faces in this array corresponding to the names array. The values are sorted, with the largest similarity value first.
Returns
Returns number of compared faces.
int VisageCSWrapper.VisageFaceRecognition.RemoveDescriptor ( int  index)

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
indexIndex of descriptor in the gallery.
Returns
Returns 1 on success, 0 on failure. The function fails if index is out of range.
int VisageCSWrapper.VisageFaceRecognition.ReplaceDescriptorName ( const char *  name,
int  index 
)

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

Parameters
nameNew descriptor name.
indexIndex of descriptor in the gallery.
Returns
Returns 1 on success, 0 on failure. The function fails if index is out of range.
void VisageCSWrapper.VisageFaceRecognition.ResetGallery ( )

Clear all face descriptors from the gallery.

int VisageCSWrapper.VisageFaceRecognition.SaveGallery ( System::String^  file_name)

Save gallery as a binary file.

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

Member Data Documentation

property bool VisageCSWrapper.VisageFaceRecognition.IsInitialized

If the model used in the VisageFaceRecognition is loaded and initialized successfully value of the is_initialized variable is true, otherwise it is false.

Make sure the variable is set to true after instantiation and before using other function of VisageFaceRecognition API. An example of use:

VisageFaceRecognition mVFR = new VisageFaceRecognition(@"..\Samples\data\vfr\fr.bin");
if(mVFR.IsInitialized)
{
int descriptor_size = mVFR.GetDescriptorSize();
// use VisageFaceRecognition API functions
}

Read only property.

Returns
Return true if VisageFaceRecognition is successfully initialized otherwise returnes false.

Definition at line 187 of file VisageFaceRecognition.cs.


The documentation for this class was generated from the following file: