DOT Android Palm library

v9.1.0

Introduction

DOT Android Palm provides components for palm capture and related functionalities which are easy to integrate into an Android application.

Requirements

DOT Android Palm has the following requirements:

Minimum Android API level 24
Minimum Kotlin Gradle plugin version 1.7.0 (if used)

Distribution

Modularization

DOT Android Palm 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 Palm is divided into following modules:

dot-palm-core (Required) - provides API for all the features and functionalities.
dot-palm-detection (Optional) - enables the palm detection feature.

Each feature module can have other modules as their dependency and cannot be used without it, see the table below.

Table 1. Module dependencies
Module	Dependency
`dot-palm-detection`	`dot-palm-core`

Maven Repository

DOT Android Palm 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 Palm into your project, the first step is to include the Innovatrics maven repository to your settings.gradle.kts file.

build.gradle.kts

dependencyResolutionManagement {
    repositories {
        maven {
            url = URI("https://maven.innovatrics.com/releases")
        }
    }
}

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

build.gradle.kts

dependencies {
    implementation("com.innovatrics.dot:dot-palm-detection:$dotVersion")
}

In order to optimize application size, we also recommend adding the following excludes to your application’s build.gradle.kts file.

build.gradle.kts

android {
    packaging {
        resources {
            excludes += listOf(
                "**/jnidispatch.dll",
                "**/libjnidispatch.a",
                "**/libjnidispatch.jnilib",
                "**/*.proto",
            )
        }
    }
}

Supported Architectures

DOT Android Palm 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.kts:

build.gradle.kts

splits {
    abi {
        isEnable = true
        reset()
        include("arm64-v8a")
        isUniversalApk = false
    }
}

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

Licensing

In order to use DOT SDK 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.kts:

build.gradle.kts

android {
    defaultConfig {
        applicationId = "com.innovatrics.dot.samples"
    }
}

The application ID can be also retrieved in runtime by calling DotSdk.getApplicationId().

In order to obtain the license, please contact your Innovatrics’ representative specifying the application 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 Palm declares the following permission in AndroidManifest.xml:

AndroidManifest.xml

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

Basic Setup

Initialization

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

Table 2. DOT Android Palm feature modules
Feature module	Class
`dot-palm-detection`	`DotPalmDetectionModuleConfiguration`

InitializeDotSdkUseCase class in the Samples project shows how to initialize DOT SDK with DotPalmLibraryConfiguration and all feature modules. DotSdk.initialize() method should be called on background thread.

Keep in mind that if you try to use any component without initialization or any feature which was not added during initialization, it will throw an exception. Also be aware that while the app is in background, the system may kill the process to free resources. In such a case, you need to reinitialize the SDK when the app is brought back to the foreground. We recommend to check the SDK initialization status (using DotSdk.isInitialized() method) in your Fragment’s onViewCreated(). This technique is implemented in the Samples project.

Deinitialization

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

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

Components

Overview

DOT Android Palm 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 Palm 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

PALM DETECTOR: A component for performing palm detection on an image.
PALM AUTO CAPTURE CONTROLLER: A component for capturing good quality images of human palm.

List of UI Components

UI PALM AUTO CAPTURE: A visual component for capturing good quality images of a human palm.

Non-UI Components

Palm Detector

The PalmDetector interface provides a palm detection functionality.

Create a PalmDetector:

val palmDetector = PalmDetectorFactory.create()

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

val palms = palmDetector.detect(image)

Palm Auto Capture Controller

The PalmAutoCaptureController interface provides a stateful palm auto capture functionality.

Create PalmAutoCaptureController:

val configuration = PalmAutoCaptureController.Configuration(
    validators = validators,
    //…
)
val palmAutoCaptureController = PalmAutoCaptureControllerFactory.create(configuration)

You can use detectionArea to specify the region in the input image which will be used for palm detection. For example, if you want to ignore top 30% and bottom 30% of the input image, you can do it as follows:

val configuration = PalmAutoCaptureController.Configuration(
    validators = validators,
    detectionArea = RectangleDouble(0.0, 0.3, 1.0, 0.7),
    //…
)

If detectionArea is not specified, the source input image is used for palm detection.

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

val sample = Sample(timestampMillis, image)
val processingResult = palmAutoCaptureController.process(sample)

The controller evaluates the image requirements for each sample (frame). Once there are minValidSamplesInRowToStartCandidateSelection valid samples in a row, candidate selection is started with duration of candidateSelectionDurationMillis milliseconds. After the candidate selection is finished, the best palm image candidate is returned and the palm 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().

class DemoPalmAutoCaptureFragment : PalmAutoCaptureFragment() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        start()
    }

    //…
}

The PalmAutoCaptureFragment requires a configuration. To provide configuration data, you should override the provideConfiguration() method in your subclass implementation. This method should return an instance of the PalmAutoCaptureFragment.Configuration data class with the desired parameters.

class DemoPalmAutoCaptureFragment : PalmAutoCaptureFragment() {

    override fun provideConfiguration() = Configuration(
        placeholder = Placeholder.Visible(
            type = configuration.placeholderType,
        ),
        isDetectionLayerVisible = configuration.showDetectionLayer,
        //…
    )

    //…
}

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" />

Video Recording for Identity Proofing

UI components support video recording. You can enable this feature in the component’s configuration using the isVideoCaptureEnabled parameter. The duration of the captured video is limited to a maximum of 8 seconds, corresponding to the end of the processing session. The captured video is bundled into the component’s result binary content and can be retrieved via the Digital Identity Service (DIS) for the purposes of Identity proofing.

UI Palm Auto Capture

The fragment with instructions for obtaining quality palm images suitable for further processing.

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

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

Start the palm auto capture process:

Check whether DOT Android Palm 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 Palm is no longer initialized and the palm auto capture process must not be started.
If DOT Android Palm is initialized, you can call the start() method immediately. If not, you need to initialize DOT Android Palm and then call start().

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

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

Call start() method again in case you need to start over the palm 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 palm auto capture process prematurely, call the stop() method.

Quality Attributes of the Output Image

You may adjust quality requirements for the output image. To perform this, you can use pre-defined instances - QualityAttributeThresholds - from QualityAttributeThresholds.Presets with recommended thresholds and pass it to BasePalmAutoCaptureFragment.Configuration by setting the qualityAttributeThresholds. You can also create your own instance of QualityAttributeThresholds from scratch or based on pre-defined instances according to your needs.

Possible ways how to create QualityAttributeThresholds:

// The standard preset
val standard = QualityAttributeThresholds.Presets.standard

// Modified thresholds based on the standard preset
val modified = standard.copy(
    minConfidence = minConfidence,
    minSharpness = null,
)

// Custom thresholds
val custom = QualityAttributeThresholds(
    minConfidence = minConfidence,
    minSharpness = null,
)

Available presets (pre-defined instances with thresholds) in QualityAttributeThresholds.Presets:

standard - The resulting image suitable for evaluation on Digital Identity Service. See the thresholds.

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_palm_palm_auto_capture_instruction_brightness_too_high">Less light needed</string>
<string name="dot_palm_palm_auto_capture_instruction_brightness_too_low">More light needed</string>
<string name="dot_palm_palm_auto_capture_instruction_candidate_selection">Hold still…</string>
<string name="dot_palm_palm_auto_capture_instruction_palm_not_detected">Scan palm</string>
<string name="dot_palm_palm_auto_capture_instruction_palm_out_of_bounds">Center palm</string>
<string name="dot_palm_palm_auto_capture_instruction_sharpness_too_low">More light needed</string>
<string name="dot_palm_palm_auto_capture_instruction_size_too_large">Move back</string>
<string name="dot_palm_palm_auto_capture_instruction_size_too_small">Move closer</string>
<string name="dot_palm_palm_auto_capture_instruction_template_extraction_quality_too_low">More light needed</string>

Colors

You may customize the colors used by DOT Android Palm 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_candidate_selection_text">#ff131313</color>
<color name="dot_instruction_text">#ff131313</color>
<color name="dot_placeholder">#ffffffff</color>
<color name="dot_placeholder_candidate_selection">#ff00bfb2</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" />

Drawables

You can also override the following drawable resources.

R.drawable.dot_palm_palm_auto_capture_placeholder_left
R.drawable.dot_palm_palm_auto_capture_placeholder_left_candidate_selection
R.drawable.dot_palm_palm_auto_capture_placeholder_right
R.drawable.dot_palm_palm_auto_capture_placeholder_right_candidate_selection

Common Classes

`ImageSize`

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

val imageSize = ImageSize(width, height)

`Image`

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

val image = Image(format, size, bytes)

To create an instance from Bitmap:

val image = ImageFactory.create(bitmap)

`DetectionPosition`

DTO which represents a position of a detected palm. To create an instance:

val detectionPosition = DetectionPosition(topLeft, topRight, bottomRight, bottomLeft)

Security guidelines

Our video injection prevention feature relies heavily on following established security best practices as outlined in the Android Developer website’s Security guidelines. Specifically, the App Integrity and Networking sections provide crucial foundations for this functionality. The Play Integrity API ensures your app binary remains unaltered, preventing potential vulnerabilities that could be exploited for video injection. Networking Security guidelines help secure communication channels. These guidelines help prevent unauthorized modification of data streams. By adhering to these security principles, you create a robust environment where our video injection prevention features can function optimally, safeguarding you from tampered content.

OWASP Mobile Application Security

We also strongly recommend following the OWASP Mobile Application Security guidelines. The OWASP Mobile Application Security (MAS) flagship project provides a security standard for mobile apps (OWASP MASVS) and a comprehensive testing guide (OWASP MASTG) that covers the processes, techniques, and tools used during a mobile app security test, as well as an exhaustive set of test cases that enables testers to deliver consistent and complete results.

Target Android API level to 36.

Fixed

Fixed output image offset.

9.0.2 - 2026-01-22

Changed

Minimum Kotlin Gradle plugin version to 1.7.0.

9.0.1 - 2026-01-08

Technical release. No changes.

9.0.0 - 2025-12-16

Added

Class DotSdk.Configuration.
Class Libraries.
Class DotPalmLibraryConfiguration.
Class DotPalmDetectionModuleConfiguration.
Class CameraConfiguration.
Class AutoCaptureConfiguration.
Class CommonConfiguration.
Class com.innovatrics.dot.core.math.IntervalDouble.
Class com.innovatrics.dot.core.math.IntervalFloat.
Class com.innovatrics.dot.camera.image.ImageFactory.
Class Image.
Enum ImageFormat.
Class PalmImageQuality.
Property PalmQuality.imageQuality.
Sealed interface Placeholder.
Class BasePalmAutoCaptureFragment.
Class Preview.
Sealed interface UiState.
Class com.innovatrics.dot.palm.autocapture.ui.PalmAutoCaptureFragment.
Class QualityAttributeThresholds.Presets.

Changed

Interface PalmAutoCaptureDetectionValidator to PalmAutoCaptureFrameParametersValidator.
Property PalmDetector.Palm.palmQuality to PalmDetector.Palm.quality.
Property PalmAutoCaptureController.Configuration.detectionNormalizedRectangle to PalmAutoCaptureController.Configuration.detectionArea.
Method signature BitmapFactory.create().
Property PalmAutoCaptureController.Sample.bgraRawImage to PalmAutoCaptureController.Sample.image.
Property PalmAutoCaptureDetection.bgraRawImage to PalmAutoCaptureDetection.image.
Property PalmAutoCaptureResult.bgraRawImage to PalmAutoCaptureResult.image.
Method signature PalmDetector.detect().

Removed

Class DotSdkConfiguration. Use DotSdk.Configuration instead.
Class Logger.
Class com.innovatrics.dot.core.validation.IntervalDouble. Use com.innovatrics.dot.core.math.IntervalDouble instead.
Class com.innovatrics.dot.core.validation.IntervalFloat. Use com.innovatrics.dot.core.math.IntervalFloat instead.
Class Nv21Image.
Class BgraRawImageFactory. Use com.innovatrics.dot.camera.image.ImageFactory instead.
Enum ImageRotation.
Class BgraRawImage. Use Image instead.
Property PalmDetector.Palm.imageParameters. Use PalmDetector.Palm.quality.imageQuality instead.
Class ImageParameters. Use PalmImageQuality instead.
Enum PlaceholderType. Use Placeholder instead.
Class com.innovatrics.dot.palm.autocapture.PalmAutoCaptureFragment. Use com.innovatrics.dot.palm.autocapture.ui.PalmAutoCaptureFragment instead.
Class QualityAttributeThresholdPresets. Use QualityAttributeThresholds.Presets instead.

8.17.0 - 2025-12-05

Changed

Default value of QualityAttributeThresholdPresets.standard.sizeInterval.max to 0.48.
Default value of SizeTooLargeValidator.maxEdgeLengthToImageShorterSideRatioThreshold to 0.48.

8.16.4 - 2025-11-10

Technical release. No changes.

8.16.3 - 2025-11-05

Technical release. No changes.

8.16.2 - 2025-10-24

Technical release. No changes.

8.16.1 - 2025-10-17

Fixed

Stability issue that occurred when the fragment was destroyed before its view was created.

8.16.0 - 2025-10-16

Fixed

Improved stability of camera initialization by handling potential exceptions.

8.15.1 - 2025-09-23

Fixed

Palm Auto Capture component: Stability issue that occurred when a user did not grant camera permission and the fragment was destroyed.

8.15.0 - 2025-08-25

Added

Transaction counting is disabled by default, it can be enabled in your license.
Property DotSdkConfiguration.transactionCountingToken. If transaction counting is enabled in your license, you must provide a valid transaction counting token.
Analytics reporting is enabled by default, it can be disabled in your license.

Changed

Minimum Android API level to 24.
Update SAM to 1.50.5 - support 16 KB page size.

8.14.2 - 2025-08-15

Technical release. No changes.

8.14.1 - 2025-07-29

Changed

Update SAM to 1.50.0 - minor improvements.

Fixed

Conflict with different versions of libc++_shared library.
PalmDetector.detect(): Incorrect detection position points.

8.14.0 - 2025-07-07

Added

Enum HandPosition.
Enum HandOrientation.
Class PalmQuality.
Class TemplateExtractionQualityTooLowValidator.
Property PalmDetector.Palm.handPosition.
Property PalmDetector.Palm.handOrientation.
Property PalmDetector.Palm.palmQuality.
Property QualityAttributeThresholds.minTemplateExtractionQuality.
Default value of QualityAttributeThresholdPresets.standard.minTemplateExtractionQuality set to 0.7.
String resource dot_palm_palm_auto_capture_instruction_template_extraction_quality_too_low.

Changed

Default value of QualityAttributeThresholdPresets.standard.sizeInterval.max to 0.8.
Default value of constructor parameter SizeTooLargeValidator.maxEdgeLengthToImageShorterSideRatioThreshold to 0.8.
Update SAM to 1.49.1 - minor improvements.

8.13.0 - 2025-06-19

Added

Property PalmAutoCaptureFragment.Configuration.minValidFramesInRowToStartCandidateSelection.
Property PalmAutoCaptureFragment.Configuration.candidateSelectionDurationMillis.
Verification of PalmAutoCaptureController.Configuration.minValidFramesInRowToStartCandidateSelection value.
Verification of PalmAutoCaptureController.Configuration.candidateSelectionDurationMillis value.

Changed

Default value of PalmAutoCaptureController.Configuration.candidateSelectionDurationMillis to 2_000.

Fixed

Stability issue that occurred when the instruction style was customized.

8.12.1 - 2025-06-04

Technical release. No changes.

8.12.0 - 2025-06-02

Added

Enum PlaceholderType.
Property PalmAutoCaptureFragment.Configuration.placeholderType.
Drawable resource dot_palm_palm_auto_capture_placeholder_right.
Drawable resource dot_palm_palm_auto_capture_placeholder_right_candidate_selection.

Changed

Deprecated class Nv21Image.
Deprecated method BgraRawImageFactory.create(nv21Image).

8.11.1 - 2025-05-21

Technical release. No changes.

8.11.0 - 2025-05-06

Added

Property PalmAutoCaptureFragment.Configuration.isCameraPreviewVisible.

Changed

Enhanced license verification.
Reduced delay during the capture finalization.

Fixed

Stability issue affecting Android 5 and Android 6 devices.

8.10.0 - 2025-04-03

Technical release. No changes.

8.9.0 - 2025-04-01

Changed

Update SAM to 1.44.6 - minor improvements.
Default value of QualityAttributeThresholdPresets.standard.minSharpness to 0.07.
Default value of constructor parameter SharpnessTooLowValidator.threshold to 0.07.

8.8.0 - 2025-03-26

Added

Class com.innovatrics.dot.camera.image.BgraRawImageFactory.
Video Capture feature in UI components.
Property PalmAutoCaptureFragment.Configuration.isVideoCaptureEnabled.

Changed

Deprecated method com.innovatrics.dot.palm.image.BgraRawImageFactory.create(yuv420Image). Use com.innovatrics.dot.camera.image.BgraRawImageFactory.create(yuv420Image) instead.

8.7.2 - 2025-03-06

Fixed

Freezing issue in the auto capture component during the candidate selection phase.

8.7.1 - 2025-03-06

Fixed

Class Logger.

8.7.0 - 2025-02-06

Changed

Drawable resource dot_palm_palm_auto_capture_placeholder_left.
Drawable resource dot_palm_palm_auto_capture_placeholder_left_candidate_selection.
Target Android API level to 35.

8.6.1 - 2025-01-14

Technical release. No changes.

8.6.0 - 2025-01-09

Technical release. No changes.

8.5.2 - 2024-10-30

Technical release. No changes.

8.5.1 - 2024-10-28

Technical release. No changes.

8.5.0 - 2024-10-24

Added

First release.

DOT Android Palm library

v9.1.0#

v9.1.0