DOT Android Face Lite library

v5.2.0

Introduction

DOT Android Face Lite provides components for face capture and related functionalities which are easy to integrate into an Android application.

Requirements

DOT Android Face Lite has the following requirements:

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

Distribution

Maven Repository

DOT Android Face Lite is distributed as an Android library (.aar package) stored in the Innovatrics maven repository.

In order to integrate DOT Android Face Lite 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 {
        google()
        maven {
            url 'https://maven.innovatrics.com/releases'
        }
    }
}

Then, specify the dependency on DOT Android Face Lite library in the module’s build.gradle file. Dependencies of this library will be downloaded alongside the library.

build.gradle

dependencies {
    //…
    implementation "com.innovatrics.dot:dot-face-lite:$dotVersion"
    //…
}

Supported Architectures

DOT Android Face Lite 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.

Permissions

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

AndroidManifest.xml

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

Basic Setup

Logging

Although logging is disabled by default, it can be enabled explicitly 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 prefix dot-face-lite:.

This setting enables logging for all DOT Android libraries.

Keep in mind that logging should be used just for debug purposes as it might produce a lot of log messages.

Components

Overview

DOT Android Face Lite 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 Lite 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.
FACE AUTO CAPTURE CONTROLLER: A component for capturing good quality image of human face.

List of UI Components

FACE AUTO CAPTURE: A visual component for capturing good quality image of human face.

Non-UI Components

Face Detector

The FaceDetector interface provides a face detection functionality.

Create a FaceDetector:

FaceDetector faceDetector = FaceDetectorFactory.create();

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

FaceDetector.Result result = faceDetector.detect(bgraRawImage);

Face Auto Capture Controller

The FaceAutoCaptureController interface provides a stateful face auto capture functionality.

Create FaceAutoCaptureController:

FaceAutoCaptureControllerConfiguration configuration = new FaceAutoCaptureControllerConfiguration.Builder(validators)
    .minValidFramesInRowToStartCandidateSelection(minValidFramesInRowToStartCandidateSelection)
    .candidateSelectionDurationMillis(candidateSelectionDurationMillis)
    .detectionNormalizedRectangle(detectionNormalizedRectangle)
    .build();
FaceAutoCaptureController faceAutoCaptureController = FaceAutoCaptureControllerFactory.create(configuration);

To capture a good quality face image, repeatedly call the process() method using the camera frames:

FaceAutoCaptureController.ProcessingResult processingResult = faceAutoCaptureController.process(bgraRawImage, timestampMillis);

The controller evaluates the image requirements for each frame. Once there are minValidFramesInRowToStartCandidateSelection valid frames in a row, candidate selection is started with duration of candidateSelectionDurationMillis milliseconds. After the candidate selection is finished, the best face image candidate is returned and the face auto capture process is over.

In case you want to restart the face auto capture process, call the restart() method.

faceAutoCaptureController.restart();

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.

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.

In order to configure the behaviour of FaceAutoCaptureFragment, use FaceAutoCaptureConfiguration (see Fragment Configuration).

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
    public void onCandidateSelectionStarted() {
        // Callback implementation
    }

    @Override
    public void onCaptured(@NonNull FaceAutoCaptureResult result) {
        // Callback implementation
    }

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

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

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

To start the face auto capture 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. The callback onCandidateSelectionStarted() is called only once for the whole process, when candidate selection is started. When the face auto capture process finishes successfully, the result will be returned via the onCaptured() callback.

In case you want to force the capture event, call the requestCapture() method. The most recent image will be returned via the onCaptured() callback asynchronously.

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.

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_face_auto_capture_instruction_face_not_present">Position your face into the circle</string>
<string name="dot_face_auto_capture_instruction_candidate_selection">Stay still&#8230;</string>
<string name="dot_face_auto_capture_instruction_face_centering">Center your face</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_lighting">Turn towards light</string>

Colors

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

<color name="dot_detection_layer">#ffffffff</color>
<color name="dot_instruction_background">#fff8fbfb</color>
<color name="dot_instruction_candidate_selection_background">#ff00bfb2</color>
<color name="dot_instruction_text">#ff131313</color>
<color name="dot_placeholder">#ffffffff</color>
<color name="dot_placeholder_candidate_selection">#ff00bfb2</color>
<color name="dot_placeholder_overlay">#80131313</color>

Styles

Text views and buttons can be styled by overriding the parent style in the application.

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

Technical release. No changes.

5.1.0 - 2023-02-06

Changed

Minimum Kotlin Gradle plugin version to 1.6.0.

5.0.0 - 2023-01-30

Changed

New SDK versioning: All libraries (DOT Document, DOT Face, DOT Face Lite and DOT NFC) are released simultaneously with a single version name. Libraries with the same version name work correctly at build time and at run time.
String resource dot_face_auto_capture_instruction_face_not_present.
Minimum Kotlin Gradle plugin version to 1.7.0.

1.1.6 - 2022-12-16

Fixed

Stability issue in image conversion.

1.1.5 - 2022-12-15

Fixed

Proguard rules.

1.1.4 - 2022-11-02

Fixed

SizeTooSmallValidator and SizeTooLargeValidator threshold valid interval is [0.0, inf].
QualityAttributeThresholds.sizeInterval valid values are in interval [0.0, inf].