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