logo logo

DOT Android Face Lite library

v1.1.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 {
        jcenter()
        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:$dotFaceLiteVersion"
    //…
}

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.android.commons.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.process(bgraRawImage);

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

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 a circle placeholder for a face on the screen. The component is embedded into the application as a fragment from the Android Support Library. The fragment is abstract, so it must be subclassed.

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

In order to configure the behavior of FaceAutoCaptureFragment, use FaceAutoCaptureConfiguration:

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();

As soon as the fragment is created, the camera preview starts. To start the 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. The process is automatically finished when candidate selection ends. After that, onCaptured() callback is called.

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.

In case you want to restart the face auto capture process, call the restart() method. The whole process will start from the beginning.

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">Center your face</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" />

Appendix

Changelog

1.1.0 - 2022-07-06

Added

  • Method DotFaceLiteLibrary.getVersionName().

Changed

  • Update CameraX to 1.1.0.

  • Minimum Kotlin Gradle plugin version to 1.6.0.

1.0.2 - 2022-05-31

Fixed

  • Stability issue in BgraRawImageFactory.

1.0.1 - 2022-05-19

Fixed

  • API visibility issue.

1.0.0 - 2022-05-18

Added

  • First release.

← DOT Android Face Lite library
DOT Android Face Lite library →