Knomi S Face API¶

Methods¶

Constructor¶

Description

Create a FaceLiveness object.

Prototypes

FaceLiveness()
FaceLiveness( Context context )

Input Parameters

context - Android application context.

Return Value

A FaceLiveness Object.

Throws

This function does not throw any exceptions.

Get Version¶

Description

Get the version string for the version of Knomi S Face SDK being used.

Prototypes

static String getVersion()

Input Parameters

This function does not take any input parameters.

Return Value

A string detailing the Knomi S Face SDK version being used.

Throws

This function does not throw any exceptions.

Allocate Face Liveness View¶

Description

Save the context being sent in and allocated necessary data.

Prototypes

void AllocateFaceLivenessView(Context c)

Input Parameters

context to be used.

Return Value

No return value.

Throws

This function does not throw any exceptions.

Bind Face Liveness Api¶

Description

Bind the library to using the provided FrameLayout for the necessary display.

Prototypes

void bindFaceLivenessApi(FrameLayout livenessComponentView, final Activity activity) throws FaceLivenessException

Input Parameters

FrameLayout - display
Activity - the activity in which the library is running.

Return Value

No return value.

Throws

FaceLivenessException.ErrorCode.InsufficientCameraPermission
FaceLivenessException.ErrorCode.InsufficientWriteSettingsPermission
FaceLivenessException.ErrorCode.FeedbackCallbackNotSet
FaceLivenessException.ErrorCode.WorkflowStateCallbackNotSet
FaceLivenessException.ErrorCode.WorkflowInvalid

Initialize Face Liveness Library¶

Description

Set the LivenessActivityPresenter to be used by the library.

Prototypes

void initializeFaceLivenessLibrary(LivenessActivityPresenter presenter) throws FaceLivenessException

Input Parameters

LivenessActivityPresenter

Return Value

No return value.

Throws

FaceLivenessException.ErrorCode.WorkflowInProgress
FaceLivenessException.ErrorCode.InvalidApi
FaceLivenessException.ErrorCode.InvalidProperty

On Create View¶

Description

Create the view for camera presentation.

Prototypes

void onCreateView(Activity activity, FrameLayout parent)

Input Parameters

Activity - activity in which the library is running
FrameLayout - the frame for the camera display

Return Value

No return value.

Throws

This function does not throw any exceptions.

Set Static Property¶

Description

Set the value for a static property to affect all FaceLiveness objects.

Prototypes

static void setStaticProperty( StaticPropertyTag property, String value ) throws FaceLivenessException

Input Parameters

property - The property to set.
value - The value to assign to the specified property.

Return Value

No return value.

Throws

FaceLivenessException.ErrorCode.InvalidApi
FaceLivenessException.ErrorCode.InvalidProperty

Set Property¶

Description

Set the value for the specified property.

Prototypes

void setProperty( PropertyTag property, String value ) throws FaceLivenessException
void setProperty( PropertyTag property, boolean value ) throws FaceLivenessException
void setProperty( PropertyTag property, double value ) throws FaceLivenessException

Input Parameters

property - The property to set. See the PropertyTag enumeration explanation for additional details.
value - The value to assign to the specified property.

Return Value

No return value.

Throws

FaceLivenessException.ErrorCode.InvalidApi
FaceLivenessException.ErrorCode.InvalidProperty

Select Workflow¶

Description

Specify which Workflow to use starting with the next facial data collection.

Prototypes

void selectWorkflow( Context context, String workflow ) throws FaceLivenessException
void selectWorkflow( Context context, String workflow, String overrideJson ) throws FaceLivenessException

Input Parameters

context - Android context.
workflow - String representation of the Workflow name to use in all subsequent facial data collection sessions.
overrideJson - An optional JSON string parameter to override specified properties of the Workflow selected.

Return Value

No return value.

Throws

FaceLivenessException.ErrorCode.WorkflowInvalid

Start Liveness¶

Description

Start the next workflow when there are multiple specified. The facial data collection is started.

Prototypes

void startLiveness( ) throws FaceLivenessException

Input Parameters

This function does not take any input parameters..

Return Value

No return value.

Throws

FaceLivenessException.ErrorCode.WorkflowInvalid
FaceLivenessException.ErrorCode.ApiNotBound

Stop Liveness¶

Description

Stop the the current workflow of facial data.

Prototypes

void stopLiveness( ) throws FaceLivenessException

Input Parameters

This function does not take any input parameters..

Return Value

No return value.

Throws

FaceLivenessException.ErrorCode.WorkflowInvalid
FaceLivenessException.ErrorCode.ApiNotBound

Set Feedback Callback¶

Description

Specify the function to be used as a callback whenever the FaceLiveness needs to communicate AutoFeedback codes to the application.

Prototypes

void setFeedbackCallback( FeedbackCallback callback )

Input Parameters

callback - A function matching the FeedbackCallback interface to be called whenever the FaceLiveness has new or updated AutoFeedback codes for the application to process.

Return Value

No return value.

Throws

This function does not throw any exceptions.

Set Workflow State Callback¶

Description

Specify the function to be used as a callback whenever the FaceLiveness needs to communicate a WorkflowState change to the application.

Prototypes

void setWorkflowStateCallback( WorkflowStateCallback callback )

Input Parameters

callback - A function matching the WorkflowStateCallback interface to be called whenever the FaceLiveness needs to alert the application to a new WorkflowState.

Return Value

No return value.

Throws

This function does not throw any exceptions.

Set Device Position Callback¶

Description

Specify the function to be used as a callback whenever the FaceLiveness needs to communicate an update to the device’s position based on accelerometer data.

Prototypes

void setDevicePositionCallback( DevicePositionCallback callback )

Input Parameters

callback - A function matching the DevicePositionCallback interface to be called whenever the FaceLiveness updates information regarding the device’s vertical positioning.

Return Value

No return value.

Throws

This function does not throw any exceptions.

Set Canvas Update Callback¶

Description

Specify the function to be used as a callback whenever the FaceLiveness needs to communicate a change to the canvas.

Prototypes

void setCanvasUpdateCallback( CanvasUpdateCallback callback )

Input Parameters

callback - A function matching the CanvasUpdateCallback interface to be called whenever the FaceLiveness updates the canvas.

Return Value

No return value.

Throws

This function does not throw any exceptions.

Set Error Reporter Callback¶

Description

Specify the function to be used as a callback whenever FaceLiveness library encounters a critical issue and needs to terminate.

Prototypes

void setErrorReporter( ErrorReporterCallback callback )

Input Parameters

callback - A function matching the ErrorReporterCallback interface to be called whenever the FaceLiveness FaceLiveness library encounters a critical issue and needs to terminate.

Return Value

No return value.

Throws

This function does not throw any exceptions.

Get Region of Interest¶

Description

Get the area where the face is expected to be located. This is based on the currently selected Workflow and should be called after selecting the Workflow for the next facial data collection. This function is to assist in the creation of UI elements that are based on the ideal face location.

Prototypes

final RectF getRegionOfInterest()

Input Parameters

This function does not take any parameters.

Return Value

Returns a Rectangle in terms of the current canvas specifying the pixel coordinates for where the face should be located.

Throws

This function does not throw any exceptions.

Get Server Package¶

Description

Get the JSON string to be sent to the Face Liveness Server back-end. This function can be called after a Workflow has run to a successful completion or a timeout has occurred. When a timeout has occurred the JSON package will be marked with a timeout flag set to true. This function is only available in Knomi S Face SDK.

Prototypes

String getServerPackage() throws FaceLivenessException

Input Parameters

This function does not take any parameters.

Return Value

Returns a JSON string to be used by the Knomi S Services endpoints.

Throws

FaceLivenessException.ErrorCode.InvalidApi
FaceLivenessException.ErrorCode.WorkflowInProgress

Get Encrypted Server Package¶

Description

Get the encrypted JSON string to be sent to the Face Liveness Server back-end. This function can be called after a Workflow has run to a successful completion or a timeout has occurred. When a timeout has occurred the JSON package will be marked with a timeout flag set to true. This function is only available in Knomi S Face SDK.

Prototypes

String getEncryptedServerPackage(FaceLiveness.EncryptionType method, String key) throws FaceLivenessException

Input Parameters

method - The encryption type to use in creating the encrypted JSON string. See the FaceLiveness.EncryptionType enumeration.
key - The encryption key to use (RSA public Key).

Return Value

Returns a JSON string to be used by the Knomi S Services endpoints.

Throws

FaceLivenessException.ErrorCode.InvalidApi
FaceLivenessException.ErrorCode.WorkflowInProgress

Get Liveness Decision¶

Description

Get the Liveness Decision made by the Knomi D Face SDK. This function can only be called after a Workflow has run to a successful completion. This function is only available in the Knomi D Face SDK.

Prototypes

LivenessDecision getLivenessDecision() throws FaceLivenessException

Input Parameters

This function does not take any parameters.

Return Value

Returns a decision on liveness indicating that the subject was considered a spoof attack or live. In rare cases, the data collected is not capable of determining liveness which can lead to an ERROR value being returned. This is generally only the case when a face has moved out of range of detection or the phone was moved significantly leading to very poor image quality.

Throws

FaceLivenessException.ErrorCode.InvalidApi

Get Captured Image¶

Description

Get an image captured on device during the Workflow data collection. This function will only return an image if the CAPTURE_ON_DEVICE property has been enabled.

Prototypes

byte[] getCapturedImage()

Input Parameters

This function does not take any parameters.

Return Value

An RGB 480x640 image as a byte array. The byte array will be of size 0 if the CAPTURE_ON_DEVICE property was set to false before the Workflow was run.

Throws

This function does not throw any exceptions.

Android Lifecycle Methods¶

The FaceLiveness object provides methods to be called by the Fragment managing it when the Fragment lifecycle state changes. After each capture attempt (capture, timeout, or abort) the fragment being used must be removed from the stack. This will initiate calling of the lifecycle procedures.

onDestroy()

onDetatch()

onPause()

onResume()

onStart()

Enumerations¶

Property Tag¶

The PropertyTag is used in the setProperty method to indicate which property should be set to what value.

Listing 2 Property Tag Enumeration¶

 public enum PropertyTag {
   USERNAME, CONSTRUCT_IMAGE, TIMEOUT, CAPTURE_ON_DEVICE, CHECK_PHONE_POSITION, EYE_SEPARATION, IMAGE_PREVIEW_ZOOM
 }

Table 4 Property Tags:¶
Value	Type	Description
Username	String	Used to set the Username/ID field when communicating with the Face Liveness Server. Default is a blank string.
Construct Image	Boolean	When possible, return a cropped and rotated image from the Face Liveness Server. See the Face Liveness Server manual for JSON response details. Default is False.
Timeout	Double	Duration (in seconds) of attempting facial capture before aborting the Workflow. Set to 0 for no timeout. Default is no timeout.
Capture On Device	Boolean	Make a 480x640 capture image available via the getCapturedImage method. Default False.
Check Phone Position	Boolean	When enabled, the phone must be held vertically as part of the capture process. When disabled, the phone may be held at any angle during capture. This is enabled by default.
Eye Separation	Double	Adjusts the minimum eye separation (in pixels) required for on device captures.
Image Preview Zoom	Double	Set the image display zoom factor. The default value is 1.4

Static Property Tag¶

The StaticPropertyTag is used in the static version of the setProperty method to indicate which property should be set to what value.

Listing 3 Static Property Tag Enumeration¶

 public enum StaticPropertyTag {
   FACE_MODEL
 }

Table 5 Static Property Tags:¶
Value	Type	Description
Face Model	String	Determines if the application is using the Light Weight Face Model or the High Accuracy Face Model. Valid values are ‘Mobile’ for the Light Weight Face Model and the path to the ‘FaceModelStandardv2.dat’ for the High Accuracy Model.

Encryption Type¶

The EncryptionType is used to select the encryption type.

Listing 4 Encryption Enumeration¶

 public enum EncryptionType {
   RSA_AES_256_CBC
 }

Table 6 Encryption Type:¶
Value	Type	Description
RSA_AES_256_CBC	RSA/AES hybrid	A hybrid of RSA and AES encryption.

Workflow State¶

The WorkflowState informs the application of the current state of the Workflow being performed. The application is alerted to transitions between Workflow states via the workflowStateCallback.

Listing 5 Workflow States¶

 public enum WorkflowState {
   PREPARING,
   DEVICE_IN_POSITION,
   HOLD_STEADY,
   CAPTURING,
   EVENT,
   SHOW_UI,
   HIDE_UI,
   POST_PROCESSING,
   COMPLETE,
   TIMEDOUT,
   ABORT,
   SENSOR_ERROR
 }

Table 7 Workflow States:¶
Value	Description
Preparing	The Workflow is preparing for facial image analysis. Device is not in the correct position.
Device in Position	The Workflow has detected the device is being held in the correct position.
Hold Steady	The Workflow has detected the device and subject are both in the correct position. This is received along with the COMPLIANT AutoFeedback code.
Capturing	The Workflow is collecting final data. Continue to hold device steady with subject in the same position.
Complete	The Workflow is done. The server package is available via getServerPackage (Knomi S Face SDK) or the liveness decision can be retrieved via getLivenessDecision (Knomi D Face SDK).
Timedout	The Workflow has timed out. The server package is available via getServerPackage (Knomi S Face SDK).
Abort	The Workflow has been aborted. Handle the Workflow exiting.
Event	Currently unused.
Show UI	Currently unused.
Hide UI	Currently unused.
Post Processing	Currently unused.
Sensor Error	The Workflow has stopped due to invalid sensor readings being detected. Check that the device is functioning normally.

Subject Feedback¶

The AutoFeedback returned via the onFeedbackResultCallback callback function. The feedback codes indicate issues with the subject’s positioning or Workflow checks. See the Workflows chapter for a review of which Workflows are capable of returning which AutoFeedback codes.

Listing 6 AutoFeedback¶

 public enum AutoFeedback {
   OFF,
   COMPLIANT_IMAGE,
   NO_FACE_DETECTED,
   FACE_TOO_FAR,
   FACE_TOO_CLOSE,
   FACE_ON_LEFT,
   FACE_ON_RIGHT,
   FACE_TOO_HIGH,
   FACE_TOO_LOW,
   INSUFFICIENT_LIGHTING,
   LIGHT_TOO_BRIGHT,
   SMILE_PRESENT,
   FOREHEAD_COVERING,
   LEFT_EYE_CLOSED,
   RIGHT_EYE_CLOSED,
   LEFT_EYE_OBSTRUCTED,
   RIGHT_EYE_OBSTRUCTED,
   HEAVY_FRAMES,
   DARK_GLASSES,
   UNNATURAL_LIGHTING_COLOR
   MOUTH_OBSCURED
}

Table 8 Subject Feedback:¶
Value	Description
Off	The Workflow was still preparing to perform facial analysis. Wait for next set of feedback.
Compliant Image	The subject was compliant with all checks. The subject and device should maintain current position to finish data collection.
No Face Detected	No face was detected in the current image.
Face Too Far	The subject’s face is too far from the camera. The subject must move closer or move the device closer.
Face Too Close	The subject’s face is too close to the camera. The subject must back up or move the device slightly away.
Face On Left	The subject’s face is too far to the left. The subject must shift right closer towards the center.
Face On Right	The subject’s face is too far to the right. The subject must shift left closer towards the center.
Face Too High	The subject’s face is too high. The subject must shift downwards towards the center.
Face Too Low	The subject’s face is too high. The subject must shift upwards towards the center.
Insufficient Lighting	There is insufficient lighting in the current environment to gather data. The subject needs to relocate to better lighting conditions.
Light Too Bright	There is too much lighting in the current environment to gather data. The subject needs to relocate to better lighting conditions.
Smile Present	The subject was detected smiling or with an open mouth. The subject needs to close their mouth and have a neutral expression on their face.
Forehead Covering	The subject was detected as having an obstruction on their forehead. The subject needs to remove the obstruction from their head.
Left Eye Closed	The subject was detected as having their left eye closed. The subject needs to open their eye.
Right Eye Closed	The subject was detected as having their right eye closed. The subject needs to open their eye.
Left Eye Obstructed	The subject’s left eye was detected as being obstructed. The subject needs to ensure a clear view of their eye.
Right Eye Obstructed	The subject’s right eye was detected as being obstructed. The subject needs to ensure a clear view of their right eye.
Heavy Frames	The subject was detected as wearing heavy or thick glasses frames. The subject needs to remove their glasses for capture.
Dark Glasses	The subject was detected as wearing tinted or dark glasses. The subject needs to remove their glasses for capture.
Unnatural Lighting Color	The subject was detected being in unnatural lighting conditions. The subject needs to relocate to better lighting conditions.
Mouth Obscured	The subject was detected as having their mouth obscured. The subject needs to ensure a clear view of their mouth.

Initialization Errors¶

The InitializationError informs the application of the current state of the Liveness Initialization. The application is alerted to any error in the SDK initialization.

Listing 7 Initialization Errors¶

 public enum InitializationError {
     NO_ERROR,
     ASSET_LOAD_ERROR,
     LICENSE_EXPIRATION_ERROR,
     COULD_NOT_LOAD_PROFILE,
     INTERNAL_INIT_ERROR;
 }

Table 9 Initialization Errors:¶
Value	Description
No Error	No Error.
Asset Load Error	Could not load file from assets directory (example ert file).
License expiration error	Possible SDK license expiration.
Could Not Load Profile	SDK proflle could not be loaded.
Internal Init Error	Other initialization error.

Callback Interfaces¶

Description¶

The Knomi S Face SDK requires the application provide four callbacks in order to share feedback and statuses needed by the application. The application is responsible for taking the data returned and performing any actions based on what is returned (i.e. displaying a message to the subject based on AutoFeedback received). The callback functions are each defined in a separate interface file.

Workflow State Callback¶

Description

Used to communicate Workflow status related information to the application. This callback is sent to the application whenever a change in the WorkflowState occurs. See the Workflow State enumeration for a list of status and their meanings.

Prototype

void workflowStateCallback( WorkflowState state, String event );

Callback Parameters

state - The WorkflowState that was entered triggering the callback.
event - Currently unused. Deprecated.

Feedback Callback¶

Description

Used to communicate subjected related statuses to the application. Most feedback codes indicate a problem with the subject based on the checks performed by the Workflow. This callback is called each time a frame has finished processing. The same AutoFeedback codes can be returned multiple times in a row. See the Subject Feedback (AutoFeedback) enumeration for the full list of codes and their meanings. See the Workflows chapter for the list of which checks are performed for which Workflows.

Prototype

void onFeedbackResultCallback( FeedbackResult result )

Callback Parameters

result - A FeedbackResult object which contains the AutoFeedback code describing the subject’s current status.

Device Position Callback¶

Description

Used to communicate the device’s vertical position.

Prototype

void onDevicePositionCallback( float position )

Callback Parameters

position - A float value between -1.0 and 1.0 indicating the current vertical tilt of the device. Values closer to 0.0 indicate the device is more vertical. Values closer to -1.0 or 1.0 indicate the device is more horizontal.

Canvas Update Callback¶

Description

Used to communicate the interface initialization or when the size of the interface is updated. Provides an updated region of interest for the area where the subject’s face is expected to be located to be Compliant.

Prototype

void onCanvasUpdateCallback( Canvas canvas, RectF roi, float displayWidthScale )

Callback Parameters

canvas - The canvas used as a coordinate plane for the region of interest returned.
roi - The Region of Interest that was updated. See the Get Region of Interest return value description for additional details.
displayWidthScale - Scale applied to the canvas’s display width.

Error Reporter Callback¶

Description

Specify the function to be used as a callback whenever FaceLiveness library encounters a critical issue and needs to terminate. The callback enables the application to implement a graceful termination.m When this procedure is complete the application must terminate. The errorCode and info parameters sent to the callback are informational only and cannot be acted upon. Their purpose is logging/reporting.

Prototype

void onErrorReporter( int errorCode, final String info, final Context context )

Callback Parameters

errorCode - a code for the error that can be used for logging.
info - a string describing the error that can be used for logging.
conttext - the Android context that can be used to present a dialog to the user.

Example Callback Registration¶

From the demo application, some of the callbacks are registered in the LivenessFragment as part of the onCreateView procedure. See the code snippet (Listing 15)

Listing 8 onCreateView¶

 public View onCreateView(LayoutInflater inflater,
                               @Nullable ViewGroup container, @Nullable Bundle savedInstanceState) {
       mLivenessApi =
       mWorkflowActiveListener.getFaceLiveness().get();
         View view = inflater.inflate(R.layout.fragment_liveness_view, container, false);
         LivenessFeedbackView feedbackView = new

         LivenessFeedbackView(getActivity(), this);
       mFrameLayout = (FrameLayout)
         view.findViewById(R.id.liveness_component_imp);
         mLivenessApi.AllocateFaceLivenessView(getContext());
         mLivenessApi.setWorkflowStateCallback(this);
         mLivenessApi.setFeedbackCallback(feedbackView);
         mLivenessApi.setDevicePositionCallback(feedbackView);
         mLivenessApi.setErrorReporter(mUI);
                  //…

Example Callback Implementation¶

See code snippets (Listing 9) and (Listing 10)

Listing 9 Samples1¶

 @Override
 public void onCanvasUpdateCallback(Canvas canvas, RectF areaOfInterest, float displayWidthScale) {
    mCanvas = canvas;
    mAreadOfInterest = areaOfInterest;
    mDisplayWidthScale = displayWidthScale;
 }

 //In the preceding example the values are set to member variables that
 //can then be used when updating the user interface (ie the “race track”).

 @Override
 public void onDevicePositionCallback(float positionState) {
   //!! TODO: fill in device indicator
   Log.v(CUSTOM_VIEW_TAG, "onDevicePositionCallback positionState: " + positionState);
   mLastPositionState** = positionState;
   reportValues(mLastPositionState);
 }

 //In the preceding example the position state of the device is recorded and then used for display.

Listing 10 Samples2¶

 @Override
 public void onFeedbackResultCallback(FeedbackResult
 feedbackResult) {
   //!! TODO: update the canvas
   Log.v (CUSTOM_VIEW_TAG, "onFeedbackResultCallback feedbackResult: " + feedbackResult.getFeedback());
   updateFeedback(feedbackResult);
 }

 //In the preceding example the feedback regarding the image capture is used for display.

Exceptions¶

The Knomi Face SDK has its own set of error codes thrown with the LivenessException class.

Table 10 Error Codes:¶
Code	Description
WorkflowInProgress	The function call cannot be completed. A Workflow capture session is currently in progress.
WorkflowInvalid	The specified Workflow name is invalid. Please see the Workflows Chapter for valid Workflow names or contact Aware.
ClassifierDataFileNotFound	The High Accuracy model file specified was not found.
FeedbackCallbackNotSet	The function call cannot be completed. The Feedback Callback must be set first.
WorkflowStateCallbackNotSet	The function call cannot be completed. The Workflow State Callback must be set first.
InvalidProperty	The Property specified was invalid or the value specified was not the correct type.
InvalidApi	The function being called is not available in this version of the API.
NoDeviceLivenessDecisionAvailable	No liveness decision is available. Capture session timed out.
ApiNotBound

Deprecated Methods¶

Is Workflow In Progress¶

Description

Determine if a Workflow is running or not.

Prototypes

boolean isWorkflowInProgress()

Input Parameters

This function does not take any input parameters.

Return Value

A boolean that is true if a Workflow is currently running a data collection session and false otherwise.

Throws

This function does not throw any exceptions.

How to Replace

Utilize the WorkflowStateCallback to know what state the current Workflow is in.