DOT Android Document library

v2.3.1

Introduction

DOT Android Document as a part of DOT Android libraries family provides document related operations such as auto capture.

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

List of Non-UI components

DOCUMENT DETECTOR: A component for performing document detection on an image.
IMAGE PARAMETERS ANALYZER: A component for computing image parameters such as sharpness, brightness or hotspots score.
DOCUMENT AUTO CAPTURE CONTROLLER: A component for capturing good quality photos suitable for optical character recognition.

List of UI components

DOCUMENT AUTO CAPTURE: A visual component for capturing good quality photos suitable for optical character recognition.

Distribution

The library is distributed as an *.aar package stored in the Innovatrics public Maven repository. It can be easily integrated into Android Studio project. The first step is to include the Innovatrics Maven public repository and Google repository to your top level build.gradle file.

build.gradle

allprojects {
    repositories {
        jcenter()
        google()
        maven {
            url 'http://maven.innovatrics.com/releases'
        }
    }
}

Then, specify the dependency on DOT Android Document library in the module’s build.gradle file. Dependencies of this library will be downloaded alongside the library. Version x.y.z should be replaced with the current latest version.

build.gradle

dependencies {
    …
    implementation 'com.innovatrics.android:dot-document:x.y.z'
    …
}

Sample Project

The sample project demonstrates the usage and configuration of DOT Android Document. To run the sample, import it first into Android Studio.

Permissions

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

AndroidManifest.xml

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

Supported architectures

DOT Android Document provides binaries for armeabi-v7a, arm64-v8a, x86 and x86_64 architectures. If the APK splits are not specified, the generated APK file will contain binaries for all available architectures. However, DOT Android Document binaries are too large for embedding all variants into a single APK file. Therefore we recommended to use APK splits. To generate armeabi-v7a, arm64-v8a, x86 and x86_64 APKs, add the following section into your module build.gradle:

build.gradle

splits {
    abi {
        enable true
        reset()
        include 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
        universalApk false
    }
}

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

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-document:.

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.

Non-UI Components

Document Detector

DocumentDetector interface and it’s implementation DefaultDocumentDetector provide a stateless document detection functionality.

Build DocumentDetector as follows:

DocumentDetector documentDetector = new DefaultDocumentDetector.Builder().build();

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

DetectionResult detect(BgraRawImage bgraRawImage);

Image Parameters Analyzer

ImageParametersAnalyzer interface and it’s implementation DefaultImageParametersAnalyzer provide a stateless image parameters analysis functionality.

Build ImageParametersAnalyzer as follows:

ImageParametersAnalyzer imageParametersAnalyzer = new DefaultImageParametersAnalyzer.Builder().build();

To perform the analysis, call the following method in the background thread:

ImageParameters analyze(BgraRawImage bgraRawImage);

Document Auto Capture Controller

DocumentAutoCaptureController interface and it’s implementation DefaultDocumentAutoCaptureController provides a stateful document auto capture functionality.

First, build a DocumentAutoCaptureController as follows:

DocumentAutoCaptureFrameParametersEvaluator documentAutoCaptureFrameParametersEvaluator = new PlaceholderEvaluatorFactory.Builder(placeholderFrame)
    .build()
    .create();
DocumentAutoCaptureController documentAutoCaptureController = new DefaultDocumentAutoCaptureController.Builder()
    .documentAutoCaptureFrameParametersEvaluator(documentAutoCaptureFrameParametersEvaluator)
    .detectionFrame(detectionFrame)
    .imageParametersFrame(imageParametersFrame)
    .onDetectionListener(this::handleDetectionEvent)
    .onStayStillPhaseEnterListener(this::handleStayStillPhaseEnterEvent)
    .onCaptureListener(this::handleCaptureEvent)
    .build();

Alternatively, you can build a custom DocumentAutoCaptureFrameParametersEvaluator using a combination of validators. You can use existing DocumentAutoCaptureFrameParametersValidator implementations or you can implement your own:

DocumentAutoCaptureFrameParametersEvaluator documentAutoCaptureFrameParametersEvaluator = new DefaultDocumentAutoCaptureFrameParametersEvaluator.Builder()
    .addValidator(new DocumentNotDetectedValidator.Builder().build())
    .addValidator(new DocumentSmallValidator.Builder().build())
    .addValidator(new SharpnessLowValidator.Builder().build())
    .addValidator(new HotspotsScoreHighValidator.Builder().build())
    .build();

`DefaultDocumentAutoCaptureController.Builder` arguments

documentAutoCaptureFrameParametersEvaluator - Evaluator component for evaluating a frame from the camera.
minValidFramesInARowForStayStillPhase - Minimum number of valid frames in a row to enter the "stay still" phase.
stayStillPhaseDurationMillis - Duration of the "stay still" phase in milliseconds.
detectionFrame - Frame of a submitted image (via the DocumentAutoCaptureController.detect() method) where document should be detected. The frame defines an area inside the image. E.g. if you post images of size 1080x1920 and you want to ignore top and bottom areas, you can use the detectionFrame as follows:
```
...
.detectionFrame(Rect.of(0, 590, 1080, 1330))
...
```
Full image is used if detectionFrame is not defined.
imageParametersFrame - Frame of a submitted image (via the DocumentAutoCaptureController.detect() method) where image parameters (sharpness, brightness hotspots score…) should be calculated. The frame defines an area inside the image. E.g. if you post images of size 1080x1920 and you want to calculate image parameters just from the center of the image, you can use the imageParametersFrame as follows:
```
...
.imageParametersFrame(Rect.of(80, 670, 1000, 1250))
...
```
Full image is used if imageParametersFrame is not defined.
onDetectionListener - Listener to be called on each document detection periodically.
onStayStillPhaseEnterListener - Listener to be called on the "stay still" phase is started. This event happens once in a auto capture process.
onCaptureListener- Listener to be called on auto capture process is done.

In order to get callbacks from the controller, implement these listeners from DocumentAutoCaptureController interface: OnDetectionListener, OnStayStillPhaseEnterListener and OnCaptureListener.

To capture a good quality document photo, call the detect() method using the camera preview frames repeatedly:

void detect(Nv21Image nv21Image);

The controller evaluates the document image requirements for each frame. Once there are minValidFramesInARowForStayStillPhase valid frames in a row, the "stay still" phase is entered for stayStillPhaseDurationMillis milliseconds. As soon as "stay still" phase times out, the best document image candidate is returned via OnCaptureListener and the process is over.

In case you want to force the capture event, call the requestCapture() method. Document image candidate will be returned via the OnCaptureListener as soon as detect() method is called the next time.

void requestCapture();

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

void restart();

UI Components

Document Auto Capture

The fragment with a document placeholder on the screen. The component is embedded into the application as a fragment from Android Support Library. The fragment is abstract, so it must be subclassed. In order to configure the behavior of DocumentAutoCaptureFragment, use DocumentAutoCaptureArguments:

DocumentAutoCaptureArguments documentAutoCaptureArguments = new DocumentAutoCaptureArguments.Builder().build();

Bundle arguments = new Bundle();
arguments.putSerializable(DocumentAutoCaptureFragment.ARGUMENTS, documentAutoCaptureArguments);

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

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

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

The following arguments are wrapped in DocumentAutoCaptureArguments:

(Optional) [0] int cameraId – The camera ID
(Optional) [CENTER_INSIDE] ScaleType cameraPreviewScaleType – The camera preview scale type
- CENTER_INSIDE
- CENTER_CROP
(Optional) [DocumentNotDetectedValidator.Builder#DEFAULT_THRESHOLD_CONFIDENCE] Double confidenceThreshold – Detection confidence threshold
(Optional) [SharpnessLowValidator.Builder#DEFAULT_THRESHOLD] Double sharpnessLowThreshold – Low sharpness threshold
(Optional) [BrightnessLowValidator.Builder#DEFAULT_THRESHOLD] Double brightnessLowThreshold – Low brightness threshold
(Optional) [BrightnessHighValidator.Builder#DEFAULT_THRESHOLD] Double brightnessHighThreshold – High brightness threshold
(Optional) [HotspotsScoreHighValidator.Builder#DEFAULT_THRESHOLD] Double hotspotsScoreHighThreshold – Hotspots score threshold

As soon as the fragment is created, the camera preview starts. To start the auto capture process wait until onAutoCaptureReady() callback is called and then call the start() method. You can also start the process any time later.

In case you want to force the capture event, call the postCaptureRequest() method. Document image candidate will be returned via the onPhotoCaptured() callback asynchronously.

In case you want to restart the auto capture process (e.g. you want tu capture both sides of the document, one after another), call the restart() method. The whole process will start from the beginning.

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.

<!-- Document Auto Capture -->
<string name="dot_document_auto_capture_instruction_avoid_reflections">Avoid reflections</string>
<string name="dot_document_auto_capture_instruction_center_document">Center document</string>
<string name="dot_document_auto_capture_instruction_hold_still">Hold still…</string>
<string name="dot_document_auto_capture_instruction_less_light_needed">Less light needed</string>
<string name="dot_document_auto_capture_instruction_more_light_needed">More light needed</string>
<string name="dot_document_auto_capture_instruction_move_back">Move back</string>
<string name="dot_document_auto_capture_instruction_move_closer">Move closer</string>
<string name="dot_document_auto_capture_instruction_scan_document">Scan document</string>

Dimensions

You may customize the dimensions used by DOT Android Document in your application. To use custom dimensions, override the specific dimension.

<!-- Document Auto Capture -->
<dimen name="dot_document_auto_capture_card_placeholder_outline_dash_path_effect_interval">8dp</dimen>
<dimen name="dot_document_auto_capture_card_placeholder_outline_stroke_width">3dp</dimen>

Colors

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

<!-- Document Auto Capture -->
<color name="dot_document_auto_capture_card_placeholder_outline">#ff000000</color>
<color name="dot_document_auto_capture_card_placeholder_outline_stay_still_phase">#ff00ff00</color>
<color name="dot_document_auto_capture_instruction_background">#ffffffff</color>
<color name="dot_document_auto_capture_window_background">#ff000000</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.DocumentAutoCaptureInstruction">
    ...
</style>

Requesting camera permission if it is already denied.

2.3.0 - 2021-05-14

Added

DocumentAutoCaptureArguments.Builder: Method confidenceThreshold().
DocumentAutoCaptureArguments.Builder: Method sharpnessLowThreshold().
DocumentAutoCaptureArguments.Builder: Method brightnessLowThreshold().
DocumentAutoCaptureArguments.Builder: Method brightnessHighThreshold().
DocumentAutoCaptureArguments.Builder: Method hotspotsScoreHighThreshold().
BrightnessHighValidator.Builder: Method threshold().
BrightnessLowValidator.Builder: Method threshold().
DocumentDoesNotFitPlaceholderValidator.Builder: Method detectedToPlaceholderCornersDistanceThreshold().
DocumentLargeValidator.Builder: Method documentWidthToImageWidthRatioThreshold().
DocumentNotDetectedValidator.Builder: Method confidenceThreshold().
DocumentSmallValidator.Builder: Method documentWidthToImageWidthRatioThreshold().
HotspotsScoreHighValidator.Builder: Method threshold().
SharpnessLowValidator.Builder: Method threshold().

Changed

All DocumentAutoCaptureFrameParametersValidator implementations: Instance creation via a Builder.
PlaceholderEvaluatorFactory: Instance creation via a Builder.

2.2.1 - 2021-03-29

Added

Support for x86 and x86_64 architectures.

2.2.0 - 2021-03-17

Changed

Update documentation.

Fixed

Configuration change issue in Document Auto Capture UI component.

2.1.0 - 2021-01-25

Added

Callback DocumentAutoCaptureFragment.onAutoCaptureReady().
Method DocumentAutoCaptureFragment.start().

Changed

DocumentAutoCaptureFragment: Auto Capture process is not started implicitly. Client needs to call method DocumentAutoCaptureFragment.start() to start the process.
DocumentAutoCaptureFragment: As soon as the photo is captured all views are reset.

2.0.1 - 2021-01-21

Fixed

Issue in method DocumentAutoCaptureFragment.restart().

2.0.0 - 2021-01-11

Added

Possibility to restart the Document Auto Capture Controller component (method DocumentAutoCaptureController.restart()).
Possibility to restart the Document Auto Capture UI component (method DocumentAutoCaptureFragment.restart()).
New non-UI component: Image Parameters Analyzer.
DefaultDocumentAutoCaptureController.Builder: Method detectionFrame().
DefaultDocumentAutoCaptureController.Builder: Method imageParametersFrame().
HotspotsScoreHighValidator for validating hotspots presence.

Changed

Update target Android SDK version to 30 (Android 11).
DetectionResult DTO does not contain sharpness and brightness anymore (these are present in ImageParameters DTO).
DefaultDocumentAutoCaptureController.Builder: Method detectionResultEvaluator() renamed to documentAutoCaptureFrameParametersEvaluator().
DetectionResultEvaluator renamed to DocumentAutoCaptureFrameParametersEvaluator.
DefaultDetectionResultEvaluator renamed to DefaultDocumentAutoCaptureFrameParametersEvaluator.
DetectionAttributeValidator renamed to DocumentAutoCaptureFrameParametersValidator.
DetectionHint renamed to DocumentAutoCaptureHint.
Update documentation.

Removed

DocumentDetector: Method DetectionResult detectDocument(Nv21Image nv21Image).
DefaultDocumentAutoCaptureController.Builder: Method croppingFrame().

1.1.0 - 2020-11-25

Added

Possibility to force capture in Document Auto Capture Controller component (method DocumentAutoCaptureController.requestCapture()).
Possibility to force capture in Document Auto Capture UI component (method DocumentAutoCaptureFragment.postCaptureRequest()).

Changed

Update documentation.

Fixed

Proguard rules.

1.0.0 - 2020-07-31

Changed

Preview image is cropped before document detection (placeholder area and margin).
Document Auto Capture design.
Update documentation.

Fixed

Fix camera preview freezing.
Placeholder position calculation for cameraPreviewScaleType: ScaleType.CENTER_CROP.

0.3.0 - 2020-07-13

Minor changes.

0.2.0 - 2020-07-11

Changed

Update documentation.

0.1.0 - 2020-07-10

Added

First release.