visageSDK
Instance Methods | List of all members
VisageFaceRecognition Class Reference

Objective-C wrapper of the VisageSDK::VisageFaceRecognition class. More...

#import <objc_VisageFaceRecognition.h>

Inherits NSObject.

Instance Methods

(VisageFaceRecognition *) - init:
 Constructor. More...
 
(int) - getDescriptorSize
 Gets the descriptor's size. More...
 
(int) - extractDescriptor:withImage:withDescriptor:
 Extracts the face descriptor for face recognition from a facial image. More...
 
(float) - descriptorsSimilarity:withSecondDescriptor:
 Calculates similarity between two descriptors. More...
 
(int) - addDescriptor:withFaceData:withName:
 Extracts a face descriptor from the input RGB, RGBA or grayscale image and adds it to the gallery. More...
 
(int) - addDescriptor:withName:
 Adds face descriptor to the gallery. More...
 
(int) - getDescriptorCount
 Gets number of descriptors in the gallery. More...
 
(int) - getDescriptorName:withIndex:
 Gets the name of a descriptor at the given index in the gallery. More...
 
(int) - replaceDescriptorName:withIndex:
 Replaces the name of a descriptor at the given index in the gallery with new name. More...
 
(int) - removeDescriptor:
 Removes a descriptor at the given index from the gallery. More...
 
(int) - saveGallery:
 Save gallery as a binary file. More...
 
(int) - loadGallery:
 Load gallery from a binary file. More...
 
(void) - resetGallery
 Clear all face descriptors from the gallery.
 
(int) - recognize:withNameCount:withNames:withSimilarities:
 Compare a face to all faces in the current gallery and return n names of the most similar faces. More...
 

Detailed Description

Objective-C wrapper of the VisageSDK::VisageFaceRecognition class.

Definition at line 22 of file objc_VisageFaceRecognition.h.

Method Documentation

◆ addDescriptor:withFaceData:withName:()

- (int) addDescriptor: (VisageImage *)  image
withFaceData: (FaceData *)  faceData
withName: (NSString *)  name 

Extracts a face descriptor from the input RGB, RGBA or grayscale image and adds it to the gallery.

Parameters
imageVisageImage pointer that contains the input RGB, RGBA or grayscale 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
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 image pointer.

◆ addDescriptor:withName:()

- (int) addDescriptor: (short *)  descriptor
withName: (NSString *)  name 

Adds face 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 on failure. The function fails if the descriptor is not a valid pointer.

◆ descriptorsSimilarity:withSecondDescriptor:()

- (float) descriptorsSimilarity: (short *)  firstDescriptor
withSecondDescriptor: (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
first_descriptorpointer to the first descriptor, an array of DESCRIPTOR_SIZE Int16 values.
second_descriptorpointer to the second descriptor, an array of DESCRIPTOR_SIZE Int16 values.
Returns
float value between 0 and 1, 1 means full similarity and 0 means full diversity.

◆ extractDescriptor:withImage:withDescriptor:()

- (int) extractDescriptor: (FaceData *)  faceData
withImage: (VisageImage *)  image
withDescriptor: (short *)  descriptor 

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

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

Example:

let recognition = VisageFaceRecognition("vfr/fr.tflite")
let descriptorSize = recognition?.getDescriptorSize()
var descriptor = [Int16].init(repeating: 0, count: NSNumber.init(value: descriptorSize!).intValue)
recognition?.extractDescriptor(faceData![0], with: image, withDescriptor: &descriptor)
Parameters
facedatafacial data obtained from VisageTracker or VisageFeaturesDetector.
imageVisageImage pointer to the input RGB, RGBA or grayscale image.
descriptorpointer to a DESCRIPTOR_SIZE-dimensional array of Int16. The resulting face descriptor is returned in this array.
Returns
1 on success, 0 on failure.

See also: FaceData, VisageTracker, VisageFeaturesDetector

◆ getDescriptorCount()

- (int) getDescriptorCount

Gets number of descriptors in the gallery.

Returns
returns number of descriptors in the gallery.

◆ getDescriptorName:withIndex:()

- (int) getDescriptorName: (NSMutableString *)  name
withIndex: (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
1 on success, 0 on failure. The function fails if index is out of range.

◆ getDescriptorSize()

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

◆ init:()

- (VisageFaceRecognition *) init: (NSString *)  dataPath

Constructor.

Parameters
dataPathpath to the data file required for face recognition - fr.tflite provided in Samples/data/vfr.

◆ loadGallery:()

- (int) loadGallery: (NSString *)  fileName

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
1 on success, 0 on failure. The function fails if the file can not be opened.

◆ recognize:withNameCount:withNames:withSimilarities:()

- (int) recognize: (short *)  descriptor
withNameCount: (int)  n
withNames: (NSMutableArray *)  names
withSimilarities: (NSMutableArray *)  similarities 

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

Example:

let image = UIImage(contentsOfFile: testImagePath)
let recognition = VisageFaceRecognition("vfr/fr.tflite")
let detector = VisageFeaturesDetector("Face Detector.cfg")
let faceData = FaceDataCollection(maxFaces: maxFaces)
let minFaceScale = Float(0.05)
let maxFaceScale = Float(0.95)
detector!.detectFacialFeatures(image, withFaceData: faceData, withMaxFaces: maxFaces, withMinFaceScale: minFaceScale, withMaxFaceScale: maxFaceScale, withOutputOnly2DFeatures: false)
let descriptorSize = Int(recognition.getDescriptorSize())
let names = NSMutableArray(capacity: 5)
let similarities = NSMutableArray(capacity: 5)
var descriptor = [Int16].init(repeating: 0, count: descriptorSize)
descriptor.withUnsafeMutableBufferPointer { ptr in
recognition!.extractDescriptor(faceData![0], with: image, withDescriptor: ptr.baseAddress)
recognition!.recognize(ptr.baseAddress, withNameCount: 5, withNames: names, withSimilarities: similarities)
}
Parameters
descriptorpointer to the face descriptor of the face to be recognized (compared to the gallery).
nnumber of names and similarities to be returned.
namesNSMutableArray. 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.
similaritiesNSMutableArray. 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.
Returns
number of compared faces.

◆ removeDescriptor:()

- (int) 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
1 on success, 0 on failure. The function fails if index is out of range.

◆ replaceDescriptorName:withIndex:()

- (int) replaceDescriptorName: (NSString *)  name
withIndex: (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
1 on success, 0 on failure. The function fails if index is out of range.

◆ saveGallery:()

- (int) saveGallery: (NSString *)  fileName

Save gallery as a binary file.

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

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