DOT Android Face library

v5.4.0

Introduction

DOT Android Face as a part of the DOT Android libraries family provides components for the digital onboarding process using the latest Innovatrics IFace image processing library. It wraps the core functionality of IFace library to a higher-level module which is easy to integrate into an Android application.

Requirements

DOT Android Face has the following requirements:

Minimum Android API level 21
Minimum Kotlin Gradle plugin version 1.6.0 (if used)

Distribution

Modularization

DOT Android Face is divided into core module and optional feature modules. This enables you to reduce the size of the library and include only modules that are actually used in your use case.

DOT Android Face is divided into following modules:

dot-face-core (Required) - provides API for all the features and functionalities.
dot-face-detection-fast (Optional) - enables the fast face detection feature.
dot-face-detection-balanced (Optional) - enables the balanced face detection feature.
dot-face-verification (Optional) - enables template extraction and face and template matching features.
dot-face-eye-gaze-liveness (Optional) - enables the eye gaze liveness feature.
dot-face-passive-liveness (Optional) - enables the passive liveness feature.
dot-face-background-uniformity (Optional) - enables the background uniformity evaluation feature.
dot-face-expression-neutral (Optional) - enables the face expression evaluation feature.

Each feature module can have other modules as their dependency and cannot be used without it, see the table below. Modules dot-face-detection-fast and dot-face-detection-balanced belong to one category, therefore only one of them can be activated.

Table 1. Module dependencies
Module	Dependency
`dot-face-detection-fast`	`dot-face-core`
`dot-face-detection-balanced`	`dot-face-core`
`dot-face-verification`	`dot-face-detection-*`
`dot-face-eye-gaze-liveness`	`dot-face-detection-*`
`dot-face-passive-liveness`	`dot-face-detection-*`
`dot-face-background-uniformity`	`dot-face-detection-*`
`dot-face-expression-neutral`	`dot-face-detection-*`

dot-face-detection-* stands for either dot-face-detection-fast or dot-face-detection-balanced.

For example, if you want to use Eye Gaze Liveness you will have to use these three modules: dot-face-eye-gaze-liveness, dot-face-detection-*(required by dot-face-eye-gaze-liveness) and dot-face-core(always required).

Maven Repository

DOT Android Face is distributed as a set of Android libraries (.aar packages) stored in the Innovatrics maven repository. Each library represents a single module.

In order to integrate DOT Android Face into your project, the first step is to include the Innovatrics maven repository and Google repository to your top level build.gradle file.

build.gradle

allprojects {
    repositories {
        maven {
            url 'https://maven.innovatrics.com/releases'
        }
    }
}

Then, specify the dependencies of DOT Android Face libraries in the app build.gradle file. Dependencies of these libraries will be downloaded alongside them.

build.gradle

dependencies {
    //…
    implementation "com.innovatrics.dot:dot-face-core:$dotVersion"
    implementation "com.innovatrics.dot:dot-face-detection-fast:$dotVersion"
    implementation "com.innovatrics.dot:dot-face-verification:$dotVersion"
    implementation "com.innovatrics.dot:dot-face-eye-gaze-liveness:$dotVersion"
    implementation "com.innovatrics.dot:dot-face-passive-liveness:$dotVersion"
    implementation "com.innovatrics.dot:dot-face-background-uniformity:$dotVersion"
    implementation "com.innovatrics.dot:dot-face-expression-neutral:$dotVersion"
    //…
}

Supported Architectures

DOT Android Face provides binaries for these architectures:

armeabi-v7a
arm64-v8a
x86
x86_64

If your target application format is APK and not Android App Bundle, and the APK splits are not specified, the generated APK file will contain binaries for all available architectures. Therefore we recommend to use APK splits. For example, to generate arm64-v8a APK, add the following section into your module build.gradle:

build.gradle

splits {
    abi {
        enable true
        reset()
        include 'arm64-v8a'
        universalApk false
    }
}

If you do not specify this section, the resulting application can become too large in size.

Licensing

In order to use DOT Android Face in other apps, it must be licensed. The license can be compiled into the application as it is bound to the application ID specified in build.gradle:

build.gradle

defaultConfig {
    applicationId "com.innovatrics.dot.sample"
    //…
}

The license ID can be retrieved as follows - required only once for license generation:

Log.i(TAG, "LicenseId: " + DotFaceLibrary.getInstance().getLicenseId());

In order to obtain the license, please contact your Innovatrics’ representative specifying the License ID. If the application uses build flavors with different application IDs, each flavor must contain a separate license. Put the license file into the raw resource folder.

Permissions

DOT Android Face declares the following permission in AndroidManifest.xml:

AndroidManifest.xml

<uses-permission android:name="android.permission.CAMERA" />

Basic Setup

Initialization

Before using any of the DOT Android Face components, you need to initialize it with the license and list of feature modules you want to use. Each feature module can be activated by a *Module class. See the table below.

Table 2. DOT Android Face feature modules
Feature module	Class
`dot-face-detection-fast`	`DotFaceDetectionFastModule`
`dot-face-detection-balanced`	`DotFaceDetectionBalancedModule`
`dot-face-verification`	`DotFaceVerificationModule`
`dot-face-eye-gaze-liveness`	`DotFaceEyeGazeLivenessModule`
`dot-face-passive-liveness`	`DotFacePassiveLivenessModule`
`dot-face-background-uniformity`	`DotFaceBackgroundUniformityModule`
`dot-face-expression-neutral`	`DotFaceExpressionNeutralModule`

Following code snippet shows how to initialize DOT Android Face with all feature modules:

private void initialize() {
    List<DotFaceModule> modules = createModules();
    DotFaceLibraryConfiguration configuration = new DotFaceLibraryConfiguration.Builder(context, license, modules).build();
    DotFaceLibrary.getInstance().initializeAsync(configuration, listener);
}

private List<DotFaceModule> createModules() {
    return Arrays.asList(
            DotFaceDetectionFastModule.of(),
            DotFaceVerificationModule.of(),
            DotFaceEyeGazeLivenessModule.of(),
            DotFacePassiveLivenessModule.of(),
            DotFaceBackgroundUniformityModule.of(),
            DotFaceExpressionNeutralModule.of()
    );
}

As a result of the initialization a dot folder under the application files folder is created.

Keep in mind that if you try to use any feature which was not added during initialization, DOT Android Face will throw an exception.

DOT Face Configuration

You can configure DotFaceLibrary using DotFaceLibraryConfiguration DTO and it’s Builder. Here is an example of building such an object:

DotFaceLibraryConfiguration configuration = new DotFaceLibraryConfiguration.Builder(license, modules)
    .faceDetectionConfidenceThreshold(0.06d)
    .build();

Face detection confidence threshold (`faceDetectionConfidenceThreshold`)

The interval of the confidence score is [0.0, 1.0] and the default value of the threshold is 0.06. Faces with a confidence score lower that this value are ignored.

Deinitialization

When a process (e.g. onboarding) using the DOT Android Face has been completed, it is usually a good practice to free the resources used by it.

You can perform this by calling DotFaceLibrary.deinitializeAsync(). If you want to use the DOT Android Face components again after that point, you need to call DotFaceLibrary.initializeAsync() again. This shouldn’t be performed within the lifecycle of individual Android components.

Following code snippet shows how to deinitialize DOT Android Face:

DotFaceLibrary.getInstance().deinitializeAsync(listener);

Logging

By default, logging is disabled. You can enable it by using the following method from the com.innovatrics.dot.core.Logger class.

Logger.setLoggingEnabled(true);

The appropriate place for this call is within the onCreate() method of your subclass of android.app.Application. Each tag of a log message starts with the dot-face: prefix.

This setting enables logging for all DOT Android libraries.

Please note that logging should be used just for debugging purposes as it might produce a lot of log messages.

Components

Overview

DOT Android Face provides both non-UI and UI components. Non-UI components are aimed to be used by developers who want to build their own UI using the DOT Android Face functionality. UI components are build on top of non-UI components. These are available as abstract fragments and can be extended and then embedded into the application’s existing activity providing more control.

List of Non-UI Components

FACE DETECTOR: A component for performing face detection on an image, creating templates and evaluating face attributes.
TEMPLATE MATCHER: A component for performing template matching.
FACE MATCHER: A component for performing face matching.

List of UI Components

FACE AUTO CAPTURE: A visual component for capturing good quality face images and creating templates suitable for matching.
FACE SIMPLE CAPTURE: A visual component for capturing face images and creating templates suitable for matching without considering image quality requirements.
EYE GAZE LIVENESS: A visual component which performs the liveness check based on object tracking. An object is shown on the screen and the user is instructed to follow the movement of this object by her/his eyes.
SMILE LIVENESS: A visual component which performs the liveness check based on the changes in the face expression.
MAGNIFEYE LIVENESS: A visual component for capturing images suitable for MagnifEye liveness evaluation.

Non-UI Components

Face Detector

The FaceDetector interface provides the face detection functionality. Face detection stops when maximumFaces is reached. This component requires dot-face-detection-* module.

Create a FaceDetector:

FaceDetector faceDetector = FaceDetectorFactory.create();

To perform detection, call the following method on the background thread:

List<DetectedFace> detectedFaces = faceDetector.detect(faceImage, maximumFaces);

Template Matcher

In order to match face templates (1:1), use the TemplateMatcher interface. The recommended approach is to create face templates using FaceDetector or Face Auto Capture component and use only templates for matching. This component requires dot-face-verification module.

Create a TemplateMatcher:

TemplateMatcher templateMatcher = TemplateMatcherFactory.create();

To perform matching, call the following method on the background thread:

TemplateMatcher.Result result = templateMatcher.match(referenceTemplate, probeTemplate);

Face Matcher

In order to match face images (1:1), use the FaceMatcher interface. It is also possible to match a face image against a template (This is a recommended approach if you already have an available reference template). This component requires dot-face-verification module.

Create a FaceMatcher:

FaceMatcher faceMatcher = FaceMatcherFactory.create();

To perform matching, call one of the following methods on the background thread:

FaceMatcher.Result result = faceMatcher.match(referenceFaceImage, probeFaceImage);
FaceMatcher.Result result = faceMatcher.match(referenceTemplate, probeFaceImage);
FaceMatcher.Result result = faceMatcher.match(referenceTemplate, probeTemplate);

UI Components

Fragment Configuration

Components containing UI are embedded into the application as fragments from Android Support Library. All fragments are abstract. They must be subclassed and override their abstract methods.

Fragments requiring runtime interaction provide public methods, for example start().

public class DemoFaceAutoCaptureFragment extends FaceAutoCaptureFragment {

    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        start();
    }

    …
}

For configuration not intended to be changed in runtime, fragment arguments are available.

FaceAutoCaptureConfiguration faceAutoCaptureConfiguration = new FaceAutoCaptureConfiguration.Builder().build();

Bundle arguments = new Bundle();
arguments.putSerializable(FaceAutoCaptureFragment.CONFIGURATION, faceAutoCaptureConfiguration);

Fragment fragment = new DemoFaceAutoCaptureFragment();
fragment.setArguments(arguments);

getSupportFragmentManager()
        .beginTransaction()
        .replace(android.R.id.content, fragment)
        .commit();

Configuration parameters are wrapped by the *Configuration data class and you must put them as a Serializable under the CONFIGURATION key to the fragment.

Builder.build() method throws IllegalArgumentException if any of the arguments is not valid. Keep in mind to handle the exception.

Face size ratio range

The face size ratio range is defined by minFaceSizeRatio and maxFaceSizeRatio arguments. If a face present in an image has the face size out of the minimum or maximum face size range, it won’t be detected. Please note that a wider minimum or maximum face size range results in a lower performance (detection FPS).

Camera permission

A fragment (UI component) will check the camera permission (Manifest.permission.CAMERA) right before the camera is started. If the camera permission is granted the fragment will start the camera. If the camera permission is not granted the fragment will use Android API - ActivityResultContracts.RequestPermission to request the camera permission. Android OS will present the system dialog to the user of the app. If the user explicitly denies the permission at this point, onNoCameraPermission() callback is called. Implement this callback in order to navigate the user further in your app workflow.

Orientation Change

In order to handle the orientation change in multi-window mode correctly, configure the activity in your AndroidManifest.xml file as follows:

<activity
    android:name=".MyActivity"
    android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation" />

Face Auto Capture

The fragment with instructions for obtaining quality face images suitable for matching. This component requires dot-face-detection-* module. If you want to evaluate background uniformity during the face auto capture process, you will also need dot-face-background-uniformity module. If you want to evaluate face mask during the face auto capture process, you will need dot-face-detection-balanced module.

In order to configure the behaviour of FaceAutoCaptureFragment, use FaceAutoCaptureConfiguration (see Fragment Configuration). The following arguments are wrapped in FaceAutoCaptureConfiguration:

(Optional) [CameraFacing.FRONT] CameraFacing cameraFacing - Camera facing.
- CameraFacing.FRONT
- CameraFacing.BACK
(Optional) [CameraPreviewScaleType.FIT] CameraPreviewScaleType cameraPreviewScaleType - The camera preview scale type.
- CameraPreviewScaleType.FIT
- CameraPreviewScaleType.FILL
(Optional) [0.10] double minFaceSizeRatio - The minimum ratio of the face size to the shorter side of the image. This value must be equal or greater than minimum valid face size ratio.
(Optional) [0.30] double maxFaceSizeRatio - The maximum ratio of the face size to the shorter side of the image.
(Optional) [false] boolean checkAnimationEnabled - Shows a checkmark animation after enrollment (or a static icon on devices which don’t support animation).
(Optional) Set<QualityAttribute> qualityAttributes - Sets the required quality attributes, which the output image must meet.

To use the fragment, create a subclass of FaceAutoCaptureFragment and override appropriate callbacks:

public class DemoFaceAutoCaptureFragment extends FaceAutoCaptureFragment {

    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        start();
    }

    @Override
    protected void onNoCameraPermission() {
        // Callback implementation
    }

    @Override
    protected void onStepChanged(@NonNull CaptureStepId captureStepId, @Nullable DetectedFace detectedFace) {
        // Callback implementation
    }

    @Override
    protected void onCaptured(@NonNull DetectedFace detectedFace) {
        // Callback implementation
    }

    @Override
    protected void onStopped() {
        // Callback implementation
    }
}

Start the face auto capture process:

Check whether DOT Android Face is initialized. This step is important, because Android OS can terminate an application running in background in order to free resources and then it creates an instance of the top activity in the activity stack. At this point the DOT Android Face is no longer initialized and the face auto capture process must not be started.
If DOT Android Face is initialized, you can call the start() method immediately. If not, you need to initialize DOT Android Face and call start() in the DotFaceLibrary.InitializationListener callback.

When the face auto capture process finishes successfully, the result will be returned via the onCaptured() callback.

Call restart() method in order to start over the face auto capture process. You can also call restart() method to stop and start over ongoing process.

In case you want to stop the face auto capture process prematurely, call the stopAsync() method. The onStopped() callback indicates that the processing is over.

Once the face auto capture process has started, it is not safe to deinitialize the DOT Android Face until one of these callbacks is called:

onCaptured()
onStopped()

CaptureStepId events are emitted when the user enters each step.

PRESENCE
PROXIMITY
POSITION
BACKGROUND_UNIFORMITY
PITCH_ANGLE
YAW_ANGLE
EYE_STATUS
GLASS_STATUS
MOUTH_STATUS
MASK
LIGHT

Quality Attributes of the Output Image

You may adjust quality requirements for the output image. To perform this, you can use various QualityProvider implementations with recommended values and pass this configuration via FaceAutoCaptureConfiguration by setting the qualityAttributes. You can also extend the default implementations according to your needs.

For example, if you wish to capture an image suitable for matching but you also want to make sure a user doesn’t wear glasses, you can use the following implementation:

public class MatchingWithGlassesStatusQualityProvider extends MatchingQualityProvider {

    public MatchingWithGlassesStatusQualityProvider() {
        qualityAttributes.add(DefaultQualityAttributeRegistry.findById(QualityAttributeId.GLASS_STATUS));
    }
}

See DefaultQualityAttributeRegistry for default values and all available quality attributes.

Available quality providers:

MatchingQualityProvider - The resulting image suitable for matching.
PassiveLivenessQualityProvider - The resulting image suitable for evaluation of the passive liveness.
IcaoQualityProvider - The resulting image passing ICAO checks.

Face Simple Capture

The fragment for obtaining images for matching without considering any image quality requirements. This component requires dot-face-detection-* module.

In order to configure the behaviour of FaceSimpleCaptureFragment, use FaceSimpleCaptureConfiguration (see Fragment Configuration). The following arguments are wrapped in FaceSimpleCaptureConfiguration:

(Optional) [CameraFacing.FRONT] CameraFacing cameraFacing - Camera facing.
- CameraFacing.FRONT
- CameraFacing.BACK
(Optional) [CameraPreviewScaleType.FIT] CameraPreviewScaleType cameraPreviewScaleType - The camera preview scale type.
- CameraPreviewScaleType.FIT
- CameraPreviewScaleType.FILL
(Optional) [0.10] double minFaceSizeRatio - The minimum ratio of the face size to the shorter side of the image. This value must be equal or greater than minimum valid face size ratio.
(Optional) [0.30] double maxFaceSizeRatio - The maximum ratio of the face size to the shorter side of the image.

To use the fragment, create a subclass of FaceSimpleCaptureFragment and override appropriate callbacks:

public class DemoFaceSimpleCaptureFragment extends FaceSimpleCaptureFragment {

    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        start();
        requestCapture();
    }

    @Override
    protected void onNoCameraPermission() {
        // Callback implementation
    }

    @Override
    protected void onCaptured(@NonNull DetectedFace detectedFace) {
        // Callback implementation
    }

    @Override
    protected void onStopped() {
        // Callback implementation
    }
}

Start the face simple capture process:

Check whether DOT Android Face is initialized. This step is important, because Android OS can terminate an application running in background in order to free resources and then it creates an instance of the top activity in the activity stack. At this point the DOT Android Face is no longer initialized and the face simple capture process must not be started.
If DOT Android Face is initialized, you can call the start() method immediately. If not, you need to initialize DOT Android Face and call start() in the DotFaceLibrary.InitializationListener callback.

You need to call requestCapture() method in order to request a capture. In the example above, the component will capture a face as soon as possible. The result will be returned via the onCaptured() callback asynchronously.

In case you want to stop the face simple capture process prematurely, call the stopAsync() method. The onStopped() callback indicates that the processing is over.

Once the face simple capture process has started, it is not safe to deinitialize the DOT Android Face until one of these callbacks is called:

onStopped()

Eye Gaze Liveness

The fragment with a moving or a fading object on the screen. This component requires dot-face-eye-gaze-liveness module.

In order to configure the behaviour of EyeGazeLivenessFragment, use EyeGazeLivenessConfiguration (see Fragment Configuration). The following arguments are wrapped in EyeGazeLivenessConfiguration:

(Required) [-] List<Segment> segments - List of segments for the object animation.
(Optional) [0.10] double minFaceSizeRatio - The minimum ratio of the face size to the shorter side of the image. This value must be equal or greater than minimum valid face size ratio.
(Optional) [0.30] double maxFaceSizeRatio - The maximum ratio of the face size to the shorter side of the image.
(Optional) [0.5] double proximityTolerance - The tolerance of the face size ratio (The tolerance of the distance between the face and the camera). A value greater than 1.0 disables the proximity check.
(Optional) [4] int minValidSegmentCount - The minimum number of valid captured segments. The value can be within the interval [4, 7].
(Optional) [MOVE] EyeGazeLivenessConfiguration.TransitionType transitionType - The transition type used for the liveness check object animation.
- MOVE
- FADE

To use the fragment, create a subclass of EyeGazeLivenessFragment and override appropriate callbacks:

public class DemoEyeGazeLivenessFragment extends EyeGazeLivenessFragment {

    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        start();
    }

    @Override
    protected void onStateChanged(@NonNull EyeGazeLivenessState state) {
        // Callback implementation
    }

    @Override
    protected void onFinished(float score, @NonNull List<SegmentImage> segmentImages) {
        // Callback implementation
    }

    @Override
    protected void onNoMoreSegments() {
        // Callback implementation
    }

    @Override
    protected void onEyesNotDetected() {
        // Callback implementation
    }

    @Override
    protected void onFaceTrackingFailed() {
        // Callback implementation
    }

    @Override
    protected void onNoCameraPermission() {
        // Callback implementation
    }

    @Override
    protected void onStopped() {
        // Callback implementation
    }
}

Start the eye gaze liveness process:

Check whether DOT Android Face is initialized. This step is important, because Android OS can terminate an application running in background in order to free resources and then it creates an instance of the top activity in the activity stack. At this point the DOT Android Face is no longer initialized and the eye gaze liveness process must not be started.
If DOT Android Face is initialized, you can call the start() method immediately. If not, you need to initialize DOT Android Face and call start() in the DotFaceLibrary.InitializationListener callback.

The eye gaze liveness follows List<Segment> segments and renders an object in the specified corners of the screen. For the best accuracy it is recommended to display the object in at least three different corners.

If the user’s eyes can’t be detected in the first segment, the process will be terminated with the onEyesNotDetected() callback.

The process is automatically finished when the number of valid items in segmentImages reaches minValidSegmentCount. After that, onFinished() callback is called and the score can be evaluated.

The process fails with the onNoMoreSegments() callback when all the segments in List<Segment> segments were displayed but it wasn’t possible to collect a number of valid images specified in minValidSegmentCount. You can use SegmentImage items for matching purposes, even when the eyes weren’t detected in a segment.

For a better user experience, it is recommended to provide the user more attempts, so the size of List<Segment> segments should be greater than minValidSegmentCount. However, this should be limited, as it is better to terminate the process if the user is failing in many segments. The recommended way of segment generation is to use a RandomSegmentsGenerator:

SegmentsGenerator segmentsGenerator = new RandomSegmentsGenerator();
int segmentCount = 8;
int segmentDurationMillis = 800;
List<Segment> segments = segmentsGenerator.generate(segmentCount, segmentDurationMillis);

If you want to perform a server side validation of the liveness check, please follow this recommended approach:

The object movement is generated on your server and then rendered on the device using List<Segment> segments. When the process is finished successfully, the List<SegmentImage> segmentImages is transferred to the server to evaluate the liveness check. Please note that segments is no longer transferred and you should store it in the session of the server. You can evaluate the liveness check by combining the corresponding segmentImages with segments and sending the request to DOT Core Server. If the user could finish the process without using all segments, the remaining items of segments should be dropped to match the number of items in segmentImages.

In case you want to stop the eye gaze liveness process prematurely, call the stopAsync() method. The onStopped() callback indicates that the processing is over.

Once the eye gaze liveness process has started, it is not safe to deinitialize the DOT Android Face until one of these callbacks is called:

onFinished()
onNoMoreSegments()
onEyesNotDetected()
onFaceTrackingFailed()
onStopped()

Custom object on the screen

The moving or fading object on the screen is a drawable resource res/drawable/eye_gaze_liveness_object.xml. It is a circle filled by ?attr/colorAccent color. If you want to use a custom object, override this resource.

Smile Liveness

The fragment which performs the liveness check based on the changes in the face expression. This component requires dot-face-expression-neutral module.

In order to configure the behaviour of SmileLivenessFragment, use SmileLivenessConfiguration (see Fragment Configuration). The following arguments are wrapped in SmileLivenessConfiguration:

(Optional) [CameraFacing.FRONT] CameraFacing cameraFacing - Camera facing.
- CameraFacing.FRONT
- CameraFacing.BACK
(Optional) [CameraPreviewScaleType.FIT] CameraPreviewScaleType cameraPreviewScaleType - The camera preview scale type.
- CameraPreviewScaleType.FIT
- CameraPreviewScaleType.FILL
(Optional) [0.10] double minFaceSizeRatio - The minimum ratio of the face size to the shorter side of the image. This value must be equal or greater than minimum valid face size ratio.
(Optional) [0.30] double maxFaceSizeRatio - The maximum ratio of the face size to the shorter side of the image.
(Optional) [false] boolean detectionLayerVisible - If detection UI layer (tracking rectangle) is visible.

To use the fragment, create a subclass of SmileLivenessFragment and override appropriate callbacks:

public class DemoSmileLivenessFragment extends SmileLivenessFragment {

    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        start();
    }

    @Override
    protected void onNoCameraPermission() {
        // Callback implementation
    }

    @Override
    protected void onCriticalFacePresenceLost() {
        // Callback implementation
    }

    @Override
    protected void onProcessed(@NonNull FaceAutoCaptureDetection detection) {
        // Callback implementation
    }

    @Override
    protected void onFinished(@NonNull SmileLivenessResult result) {
        // Callback implementation
    }

    @Override
    protected void onStopped() {
        // Callback implementation
    }
}

Start the smile liveness process:

Check whether DOT Android Face is initialized. This step is important, because Android OS can terminate an application running in background in order to free resources and then it creates an instance of the top activity in the activity stack. At this point the DOT Android Face is no longer initialized and the smile liveness process must not be started.
If DOT Android Face is initialized, you can call the start() method immediately. If not, you need to initialize DOT Android Face and call start() in the DotFaceLibrary.InitializationListener callback.

The process is automatically finished when both the neutral and the smile face expression images are captured. After that, onFinished() callback is called and the passive liveness and face matching can be evaluated.

If the face presence is lost after the neutral face expression image is captured, onCriticalFacePresenceLost() callback is called. If the face presence between the neutral and the smile face expression images is required, call restart() method. Otherwise the callback can be ignored.

In case you want to stop the smile liveness process prematurely, call the stopAsync() method. The onStopped() callback indicates that the processing is over.

Once the smile liveness process has started, it is not safe to deinitialize the DOT Android Face until one of these callbacks is called:

onFinished()
onStopped()

MagnifEye Liveness

The fragment with instructions for obtaining face data suitable for MagnifEye liveness evaluation.

In order to configure the behaviour of MagnifEyeLivenessFragment, use MagnifEyeLivenessConfiguration (see Fragment Configuration).

To use the fragment, create a subclass of MagnifEyeLivenessFragment and override appropriate callbacks.

To start the MagnifEye liveness process call the start() method. You can start the process any time.

In case you want to handle detection data, implement onProcessed() callback. This callback is called with each processed camera frame. When the MagnifEye liveness process finishes successfully, the result will be returned via the onFinished() callback.

In case you want to stop the MagnifEye liveness process prematurely, call the stopAsync() method. The onStopped() callback indicates that the processing is over.

Once the MagnifEye liveness process has started, it is not safe to deinitialize the DOT Android Face until one of these callbacks is called:

onFinished()
onStopped()

Customization of UI components

Strings

You can override the string resources in your application and provide alternative strings for supported languages using the standard Android localization mechanism.

<string name="dot_eye_gaze_liveness_instruction_face_not_present">Look straight</string>
<string name="dot_eye_gaze_liveness_instruction_face_too_close">Move back</string>
<string name="dot_eye_gaze_liveness_instruction_face_too_far">Move closer</string>
<string name="dot_eye_gaze_liveness_instruction_lighting">Turn towards light</string>
<string name="dot_eye_gaze_liveness_instruction_watch_object">Watch the object</string>
<string name="dot_face_auto_capture_instruction_background_nonuniform">Plain background required</string>
<string name="dot_face_auto_capture_instruction_candidate_selection">Stay still&#8230;</string>
<string name="dot_face_auto_capture_instruction_eye_status_low">Open your eyes</string>
<string name="dot_face_auto_capture_instruction_face_centering">Center your face</string>
<string name="dot_face_auto_capture_instruction_face_not_present">Position your face into the circle</string>
<string name="dot_face_auto_capture_instruction_face_too_close">Move back</string>
<string name="dot_face_auto_capture_instruction_face_too_far">Move closer</string>
<string name="dot_face_auto_capture_instruction_expression_neutral_too_high">Smile :)</string>
<string name="dot_face_auto_capture_instruction_expression_neutral_too_low">Keep neutral expression</string>
<string name="dot_face_auto_capture_instruction_glasses_present">Remove glasses</string>
<string name="dot_face_auto_capture_instruction_lighting">Turn towards light</string>
<string name="dot_face_auto_capture_instruction_mask_present">Remove mask</string>
<string name="dot_face_auto_capture_instruction_mouth_status_low">Close your mouth</string>
<string name="dot_face_auto_capture_instruction_pitch_too_high">Lower your chin</string>
<string name="dot_face_auto_capture_instruction_pitch_too_low">Lift your chin</string>
<string name="dot_face_auto_capture_instruction_yaw_too_left">Look right</string>
<string name="dot_face_auto_capture_instruction_yaw_too_right">Look left</string>
<string name="dot_face_magnifeye_liveness_instruction_eye_centering">Fit your eye into square</string>

Colors

You may customize the colors used by DOT Android Face in your application. To use custom colors, override the specific color.

<color name="dot_detection_layer">#ffffffff</color>
<color name="dot_eye_gaze_liveness_background">#ffffffff</color>
<color name="dot_eye_gaze_liveness_instruction_text">#ff000000</color>
<color name="dot_eye_gaze_liveness_instruction_text_background">#ffffffff</color>
<color name="dot_face_auto_capture_background_overlay">#80131313</color>
<color name="dot_face_auto_capture_circle_outline">#ffffff</color>
<color name="dot_face_auto_capture_circle_outline_stay_still">#ff00bfb2</color>
<color name="dot_face_auto_capture_tracking_circle_outline">#ffffffff</color>
<color name="dot_face_auto_capture_instruction_text">#ff131313</color>
<color name="dot_face_auto_capture_instruction_text_background">#fff8fbfb</color>
<color name="dot_face_auto_capture_instruction_text_stay_still">#ff131313</color>
<color name="dot_face_auto_capture_instruction_text_background_stay_still">#ff00bfb2</color>
<color name="dot_instruction_background">#fff8fbfb</color>
<color name="dot_instruction_text">#ff131313</color>
<color name="dot_placeholder">#ffffffff</color>
<color name="dot_placeholder_overlay">#80131313</color>

Styles

You can style the text views and buttons by overriding the parent style in the application. The default style is AppCompat.

<style name="TextAppearance.Dot.Medium" />
<style name="TextAppearance.Dot.Medium.Instruction" />

Common Classes

`ImageSize`

DTO which represents a size of an image. To create an instance:

ImageSize imageSize = ImageSize.of(width, height);

`BgrRawImage`

DTO which represents and an image. To create an instance:

BgrRawImage bgrRawImage = BgrRawImage.of(size, bytes);

To create an instance from Bitmap:

BgrRawImage bgrRawImage = BgrRawImageFactory.create(bitmap);

`FaceImage`

Data class which contains the face image and desired face size ratio range. It can be used for face detection and matching. To create an instance:

FaceImage faceImage = FaceImageFactory.create(bgrRawImage, minFaceSizeRatio, maxFaceSizeRatio);

minFaceSizeRatio and maxFaceSizeRatio, or commonly face size ratio, must be equal or greater than minimum valid face size ratio.

`DetectedFace`

This interface represents the face detection result. The following methods are available:

@NonNull BgrRawImage getImage(); - Get a full (original) image of the face.
float getConfidence(); - The confidence score of the face detection. It also represents the quality of the detected face.
@NonNull BgrRawImage createFullFrontalImage(); - Creates a ICAO full frontal image of a face. If boundaries of the normalized image leak outside of the original image, a white background is applied.
@NonNull Template createTemplate(); - The face template which can be used for matching. This method requires dot-face-verification module.
@NonNull FaceAspects evaluateFaceAspects(); - Evaluates face aspects.
@NonNull FaceQuality evaluateFaceQuality(); - Evaluates face attributes that can be used for a detailed face quality assessment.
@NonNull FaceQuality evaluateFaceQuality(@NonNull FaceQualityQuery faceQualityQuery); - Evaluates only specific face attributes that can be used for a detailed face quality assessment. This is the recommended way for face quality evaluation due to performance reasons.
@NonNull FaceAttribute evaluatePassiveLiveness(); - Evaluates passive liveness. This component requires dot-face-passive-liveness module.

MagnifEye Liveness UI component (MagnifEyeLivenessFragment, MagnifEyeLivenessConfiguration and MagnifEyeLivenessResult).
String resource dot_face_magnifeye_liveness_instruction_eye_centering.

DOT Android Face library

v5.4.0#

v5.4.0