Class: VisageFaceRecognition

VisageFaceRecognition

new VisageFaceRecognition()

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

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 point values. The size of the array (size_descriptor in the documentation) can be obtained by calling function getDescriptorSize(). 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.

Note: After the end of use VisageFaceRecognition object needs to be deleted to release the allocated memory. Example:

<script>
m_Recognition = new VisageModule.VisageFaceRecognition();
...
m_Recognition.delete();
</script>


Dependencies

VisageFaceRecognition class requires, by default, data files bundled in visageRecognitionData.data file and a loader script visageRecognitionData.js located in www/lib folder. Files for visageFaceRecognition are bundled and loaded separately from files bundled for VisageTracker class.

For every application using VisageFaceRecognition API, visageRecognitionData.data file and visageRecognitionData.js loading script must be copied to the same folder where the application's main html file is located (e.g. Samples/ShowcaseDemo folder).
Additionally, visageFaceRecognition.js script must be loaded after the main visageSDK.js script has been loaded and after VisageModule object has been created.

For example - loading visageFaceRecognition.data file:


<script src="../../lib/visageSDK.js"></script>

<script>
var VisageModule = VisageModule({onRuntimeInitialized: onModuleInitialized});
</script>

<script src="visageRecognitionData.js"></script>


If webassembly format is used, then the visageSDK.wasm file is also expected to be located in the same folder as the application's main html file.

Changing the location of the .data file
Location of the .data and .wasm files can be changed by overriding the locateFile attribute of the VisageModule object to return the URL where the data file is currently stored. Note that all visage|SDK data files (visageSDK.data, visageRecognitionData.data and visageAnalysisData.data) and .wasm file must be loacated in the same folder (i.e same URL) (see www/Samples/FaceTracer/sampleTracker.html). This additional code needs to be added to the application's main html file and the VisageModule' attribute must be specified in a script element before the one that loads the data file (in this case visageSDK.js and visageAnalysisData.js).

Sample usage - changing .data and .wasm files location:


<script>
var locateFile = function(dataFileName) {var relativePath = "../../lib/" + dataFileName; return relativePath}
</script>

<script src="../../lib/visageSDK.js"></script>

<script>
VisageModule = VisageModule({onRuntimeInitialized: onModuleInitialized, locateFile: locateFile});
</script>




VisageFaceRecognition class implementation in Web Worker
VisageFaceRecognition class can be implemented in a separate thread in relation to the VisageTracker class resulting in better performance. To send FaceData object from VisageTracker to Recognition Worker, convert FaceData object to JSON-formatted string using FaceData.toJson() function. In recognition Web Worker, FaceData is converted back from string to object using FaceData.parseJson() function.
Note: The worker thread as well as the main thread has to load the visageSDK.js script and additionally visageRecognitionData.js (see link).

Methods

extractDescriptor(faceData, frameWidth, frameHeight, p_imageData, descriptor) → {number}

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.


Sample usage:


// ... initialize visageFaceRecognition object ...
// ... create a face data object ...
// ... initialize and call VisageTracker/VisageFeaturesDetector on the image ...
//
// construct a VectorShort object to pass to the extractDescriptor method
var descriptor = new Module.VectorShort();
//
// call extractDescriptor and pass the faceData input parameter, image data and information and a short vector to be populated
var success = visageFaceRecognition.extractDescriptor(faceData, mWidth, mHeight, ppixels, descriptor);
if (success)
{
  // ... descriptor is populated and ready to be used ...
  // read the first element
  var first = descriptor.get(0);
}
// when done using descriptor clear memory
descriptor.delete();


Parameters:
Name Type Description
faceData FaceData FaceData instance. Facial data obtained from VisageTracker or VisageFeaturesDetector.
frameWidth number Width of the frame
frameHeight number Height of the frame
p_imageData number Pointer to image pixel data, size of the array must correspond to frameWidth and frameHeight
descriptor VectorShort size_descriptor-dimensional array of short. The resulting face descriptor is returned in this array.
See:
Returns:
status - 1 on success, 0 on failure.

Type
number

descriptorsSimilarity(first_descriptor, second_descriptor) → {number}

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:
Name Type Description
first_descriptor VectorShort VectorShort object, size of size_descriptor, obtained from extractDescriptor function which contains the first face descriptor information.
second_descriptor VectorShort VectorShort object, size of size_descriptor, obtained from extractDescriptor function which contains the second face descriptor information
See:
Returns:
similarity - Value between 0 and 1, 1 means full similarity and 0 means full diversity.

Type
number

recognize(descriptor, n, names, similarities) → {number}

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

Parameters:
Name Type Description
descriptor VectorShort VectorShort object, size of size_descriptor, obtained from extractDescriptor function which contains the first face descriptor information.
n number Number of names and similarities to be returned.
names VectorString VectorString object containing names of n faces from the gallery that are most similar to the input image, ascending by similarity.
similarities VectorFloat VectorFloat object. The function will return the 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.
See:
Returns:
compared_faces - number of compared faces.

Type
number

addDescriptor(faceData, frameWidth, frameHeight, p_imageData, name) → {number}

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

Parameters:
Name Type Description
faceData FaceData FaceData instance. Input parameter.
frameWidth number Width of the frame
frameHeight number Height of the frame
p_imageData number Pointer to image pixel data, size of the array must correspond to frameWidth and frameHeight
name string Descriptor name to be added to the gallery.
Returns:
success - 1 on success, 0 on failure. The function may fail if the face is not found in the image.

Type
number

addDescriptor(descriptor, name) → {number}

Adds face descriptor to the gallery.

Parameters:
Name Type Description
descriptor VectorShort VectorShort object, size of size_descriptor, obtained from extractDescriptor function which contains the first face descriptor information.
name string Descriptor name to be added to the gallery.
Returns:
success - 1 on success, 0 on failure.

Type
number

getDescriptorCount() → {number}

Returns number of descriptors in the gallery.

Returns:
num_descriptors - Number of descriptors in the gallery

Type
number

getDescriptorName(index) → {string}

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

Parameters:
Name Type Description
index number Gallery index
Returns:
name - Name of the descriptor at the given index in the gallery.

Type
string

getDescriptorSize() → {number}

Returns size of an array which should be allocated for storing the descriptor.

Returns:
size_descriptor - Size of descriptor

Type
number

replaceDescriptorName(name, index) → {number}

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

Parameters:
Name Type Description
name string New descriptor name
index number Index of descriptor in the gallery
Returns:
success - 1 on success, 0 on failure. The function may fail if index is out of range.

Type
number

removeDescriptor(index) → {number}

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:
Name Type Description
index number Index of descriptor in the gallery
Returns:
success - 1 on success, 0 on failure. The function may fail if index is out of range.

Type
number

saveGallery(file_name, callback)

Save gallery to the file.

The file format:
<name_of_the_face_in_the_image_1>;<elements_of_the_getDescriptorSize()_dimensional_face_descriptor_separated_by_a_space>
<name_of_the_face_in_the_image_2>;<elements_of_the_getDescriptorSize()_dimensional_face_descriptor_separated_by_a_space>
(...)
<name_of_the_face_in_the_image_n>;<elements_of_the_getDescriptorSize()_dimensional_face_descriptor_separated_by_a_space>


This function is asynchronous and uses Emscripten IDBFS file system API. IDBFS uses browsers' IndexedDB in order to persist data.

Since saveGallery is asynchronous a callback function needs to be provided to notify the user when the function is complete. The callback function is expected to have two parameters - name and status. Parameter name returns name of txt file in which gallery is saved while parameter status returns 1 on success and 0 on function failure.
Sample usage:

visageFaceRecognition.saveGallery("test_recognition.txt", 
function(name, status)
{   
   // ... do something based on status ...
}
);


Parameters:
Name Type Description
file_name string Name of the file (including path if needed) from which the gallery will be loaded.
callback function Callback function which will be called when saving is complete

loadGallery(file_name, callback)

Load gallery from 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.

This function is asynchronous and uses Emscripten IDBFS file system API. IDBFS uses browsers' IndexedDB in order to persist data.

Since loadGallery is asynchronous a callback function needs to be provided to notify the user when the function is complete. The callback function is expected to have two parameters - name and status. Parameter name returns name of txt file in which gallery is saved while parameter status returns 1 on success and 0 on function failure.

Sample usage:

visageFaceRecognition.loadGallery("test_recognition.txt", 
function(name, status)
{   
   // ... do something based on status ...
}
);


Parameters:
Name Type Description
file_name string Name of the file (including path if needed) from which the gallery will be loaded.
callback function Callback function which will be called when loading is complete

resetGallery()

Clear all face descriptors from the gallery.