Ava

Superclass:
NSObject
Declared In:

Introduction

The main class to access face verification, spoof detection and enrollment.



Methods

-detectLargestFaceAndLandmarks:

Detects the largest face from the front camera using the CMSampleBufferRef that comes from the iPhone camera

-downloadBiomatrics:apiKey:minConfidence:

Downloads the biometric information from frAPI using an image and enroll this person on the phone.

-enrollThisPerson:apiUrl:apiKey:

Enrolls the person from the last liveness detection on the device and upload the biometrics to the cloud (frAPI). It calls enrollThisPersonOnDevice() and uploadBiometricsToCloud sequentially.

-enrollThisPersonOnDevice:

Enrolls the person from the last liveness detection only on the device.

-getBiometricsFromDevice

Get the biometrics (image) of the person currently enrolled on the phone.

-getUserLabelFromDevice

Get the user label enrolled on frAPI.

-mirrorXAxis:

This function set if the image coming from the camera need to be flipped horizontally. It's useful to address the different cameras in the iPhone. Set to true if using front camera.

-setInvalidFaceTimeout:

This function set the timeout for the spoof detector to consider a invalid face. It assumes that the frame rate of the camera is around 25fps to compute the number of frames.

-setShakeThreshold:

This function set the threshold for detecting shake movement of the camera. The default value is 8. Increasing this value will lead to a *less* sensible shake detector.

-spoofDetection:

Detects if there is a real person on the camera by checking their eyes movement. Must be called with succeeding frames (i.e. a video stream).

-verifyThisPerson

Verify if the person from the last liveness detection is indeed the one enrolled.


detectLargestFaceAndLandmarks:


Detects the largest face from the front camera using the CMSampleBufferRef that comes from the iPhone camera

- (FaceAndLandmarks*) detectLargestFaceAndLandmarks:(CMSampleBufferRef) sampleBuffer; 
Parameters
sampleBuffer

The image coming from the camera, only the luminance will be used.

Return Value

The face rectangle and individual landmarks positions. If there is no face on the image, it returns nil


downloadBiomatrics:apiKey:minConfidence:


Downloads the biometric information from frAPI using an image and enroll this person on the phone.

- (bool) downloadBiomatrics: (NSString*) apiUrl : (NSString*) 
        apiKey : (float) minConfidence; 
Parameters
apiUrl

URL to the frAPI server

apiKey

The api key to access frAPI

minConfidence

Minimum acceptable recognition confidence to enroll this person. Range from 0-100.

Return Value

A boolean indicating if the download and enrollment was successful.


enrollThisPerson:apiUrl:apiKey:


Enrolls the person from the last liveness detection on the device and upload the biometrics to the cloud (frAPI). It calls enrollThisPersonOnDevice() and uploadBiometricsToCloud sequentially.

- (bool) enrollThisPerson:(NSString*) userName :(NSString*) 
        apiUrl : (NSString*) apiKey; 
Parameters
userName

The label that will be used to enroll this person on frAPI. It must be unique on frAPI, otherwise two different people will be treated as the same

apiUrl

URL to the frAPI server

apiKey

The api key to access frAPI

Return Value

A boolean indicating if this person was correctly enrolled. Notice that if the server is down or an invalid APIkey was used it will return false.

Discussion

This function must be called after the liveness/spoofing detection is over and a real person was indeed found. It will use those same frames to extract and save the biometrics information.


enrollThisPersonOnDevice:


Enrolls the person from the last liveness detection only on the device.

- (bool) enrollThisPersonOnDevice:(NSString*) userName; 
Parameters
userName

The label that will be used to enroll this person on frAPI afterwards. It must be unique on frAPI, otherwise two different people will be treated as the same

Return Value

A boolean indicating if this person was correctly enrolled.

Discussion

This function must be called after the liveness/spoofing detection is over and a real person was indeed found. It will use those same frames to extract and save the biometrics information.


getBiometricsFromDevice


Get the biometrics (image) of the person currently enrolled on the phone.

- (UIImage*) getBiometricsFromDevice; 
Return Value

An image (type UIImage) of the persons biometrics. It will return nil in case of internal errors or when no biometric was enrolled.


getUserLabelFromDevice


Get the user label enrolled on frAPI.

- (NSString*) getUserLabelFromDevice; 
Return Value

String containing the user label.


mirrorXAxis:


This function set if the image coming from the camera need to be flipped horizontally. It's useful to address the different cameras in the iPhone. Set to true if using front camera.

- (void) mirrorXAxis: (bool) mirror; 
Parameters
mirror

A boolean to determine if flip image


setInvalidFaceTimeout:


This function set the timeout for the spoof detector to consider a invalid face. It assumes that the frame rate of the camera is around 25fps to compute the number of frames.

- (void) setInvalidFaceTimeout: (int) seconds; 
Parameters
seconds

Number of seconds (approximately) before given invalid face


setShakeThreshold:


This function set the threshold for detecting shake movement of the camera. The default value is 8. Increasing this value will lead to a *less* sensible shake detector.

- (void) setShakeThreshold: (float) threshold; 
Parameters
threshold

Threshold value. A reasonable value range from 5 to 20.


spoofDetection:


Detects if there is a real person on the camera by checking their eyes movement. Must be called with succeeding frames (i.e. a video stream).

- (SpoofResult*) spoofDetection:(CMSampleBufferRef) sampleBuffer; 
Parameters
sampleBuffer

The image coming from the camera, only the luminance will be used.

Return Value

Face, landmarks and spoofing status.

Discussion

This function should be called for every frame of the camera. The spoofing process will end with either detecting a spoof attempt or a real person. Once it has ended, the next call of this function will start a new spoofing detection procedure.


verifyThisPerson


Verify if the person from the last liveness detection is indeed the one enrolled.

- (VerifyResult*) verifyThisPerson; 
Return Value

A boolean indicating if this person is the same as the one enrolled with a confidence value. (See VerifyResult).

Discussion

This function must be called after the liveness/spoofing detection is over and a real person was indeed found. It will use those same frames to extract the biometrics information.