DOT Android Face Lite library
v5.3.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.
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.
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
:
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
:
<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.
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 start()
method again in case you need to start over the face auto capture process. You can also call start()
method to stop and start over ongoing process as well.
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…</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
5.3.0 - 2023-03-20
Added
Property
FaceAutoCaptureController.ProcessingResult.phase
.Enum
Phase
.
Changed
Method
FaceAutoCaptureFragment.start()
(re)starts the process any time during the lifecycle of the component.
Removed
Property
FaceAutoCaptureController.ProcessingResult.events
. Use propertyFaceAutoCaptureController.ProcessingResult.phase
instead.Enum
FaceAutoCaptureController.ProcessingResult.Event
.Method
FaceAutoCaptureController.restart()
. Create new instance ofFaceAutoCaptureController
instead.Method
FaceAutoCaptureFragment.restart()
. UseFaceAutoCaptureFragment.start()
instead.
5.2.0 - 2023-03-07
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
andSizeTooLargeValidator
threshold valid interval is[0.0, inf]
.QualityAttributeThresholds.sizeInterval
valid values are in interval[0.0, inf]
.
1.1.3 - 2022-10-21
Added
Property
FaceAutoCaptureDetectionValidator.dependencyIdentifiers
.
Changed
FaceAutoCaptureControllerConfiguration.Builder()
throws anIllegalArgumentException
.
1.1.2 - 2022-10-11
Changed
Target Android API level to 33.
Fixed
Issues if the consumer application is obfuscated (consumer proguard rules).
1.1.1 - 2022-08-18
Fixed
Minor UI issues in Face Auto Capture UI component.
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.