VDDocumentCapture¶

Presentation¶

The goal of this framework is to capture some document images, guiding the user in a self-contained and accessible system.

This SDK captures the document images with the device rear camera.

This SDK retrieves this information:

Document type.
Document obverse (front side).
Document reverse (back side).

Some permissions are required by the framework:

Camera.

In order to improve the user experience, the camera takes the photo from the document automatically (without touching the screen), this is done due to its automatic document recognition. Manual capture with button is still possible, the button appears when configurable time has passed without automatic document capture.

The SDK is localised in English and Spanish. By default English language is selected and the language is automatically switched to Spanish if the device locale is Spanish.

The SDK can be configured using a dictionary. All possible keys and values can be checked in Configuration.

Specifications¶

Android minimum SDK version: API Level 21 (Android 5) (mobile devices only).
SDK compatible with Harmony OS.
Supported platforms: 'x86', 'x86_64', 'armeabi-v7a', 'arm64-v8a'.
SDK size: 260 KB (approx.).
Additionally, some dependencies will be needed. These are:

Artifact Size

common-core-X.Y.Z.aar 232 KB

common-core-jvm-X.Y.Z.jar 106 KB

common-logger-X.Y.Z.aar 19 KB

common-logger-firebase-X.Y.Z.aar (optional library) 17 KB

common-image-processing.aar is available for different architectures so its final size is the result of adding the size of each of the supported architectures.

Architecture Size

x86 8.6 MB

x86_64 9.2 MB

armeabi-v7a 6.9 MB

arm64-v8a 7.5 MB

(All sizes have been calculated with Android Studio .aar analyzer)

Each mobile device on the market uses a unique software architecture. Thus, each mobile device does NOT install the full weight of the image processing library, but installs the part of the weight associated with its architecture. In fact, this process of dividing the weight according to the architecture also takes place when the APP is uploaded to the Play Store.

The integrator should not include anything in the app because Google Play will manage the complete APK (including all architectures) which size is bigger than individual ones. To separate that APK and show the user which is going to download the app it's real size based on the architecture the device is accessing to Google Play.

This is explained here (abis) and here (APK splits).

In case the integrator wants to check the different APK sizes, or just build for one architecture only. The following code can be added to the app gradle (as stated in the links provided):

splits {
    abi {
        enable true

        reset()

        include 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'

        universalApk true
    }
}

Image captured is the biggest image with 4:3 aspect ratio with 8MP maximum. (~350KB-750KB). The format is JPEG.

Integration¶

Create a new Android project.
Import the framework (document-capture.aar) as a module (New... > Module > Import .JAR/.AAR Package) into your app.
Add the following dependency: implementation project (":document-capture") (same name as aar) to the app gradle file.
Implement the interface named IVDDocumentCapture.
Import the rest of .aar/.jar the same way (only steps 2 and 3).

Add the following dependencies to the app gradle file:

        implementation "androidx.appcompat:appcompat:1.6.1"
        implementation "androidx.constraintlayout:constraintlayout:2.1.4"
        implementation "androidx.lifecycle:lifecycle-viewmodel-ktx:2.7.0"
        implementation "androidx.exifinterface:exifinterface:1.3.7"
        implementation "com.github.bumptech.glide:glide:4.16.0"
        implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.9.23"
        implementation "org.jetbrains.kotlin:kotlin-reflect:1.9.23"
        implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3"

Add "largeHeap" parameter and the required activities declaration into the AndroidManifest.xml as follows:
```
  <application
      android:largeHeap="true">
  </application>
```

Disabling allowBackup¶

By default the SDK allows the application to participate in the backup infrastructure, this behaviour can be altered by adding android:allowBackup="false" to the application tag in the manifest file from the created application.

When this directive has been overridden tools:replace="android:allowBackup" must be added to the application tag as well, including adding the tools namespace xmlns:tools="http://schemas.android.com/tools" to the manifest tag.

See this page for more details.

Example of use¶

import com.dasnano.vddocumentcapture.VDDocumentCapture;

public class SomeClass implements VDDocumentCapture.IVDDocumentCapture ...

...

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.your_layout);
    // Start SDK. A delegate to receive delegated methods (this) and a Context to debug or use files (getApplicationContext() or this in a activity) are needed.
    // Creation of a list of documents is needed, this list can be obtained from VDDocumentCapture.getCountryDocuments(context) dictionary. If the document needed is "VD_PASSPORT" or AT_DrivingLicense_2004"", they must be provided to the SDK independently (an array with just itself).
    if (!VDDocumentCapture.isStarted()) {
        List<String> spainDocs = new ArrayList<>();
        spainDocs.add("ES_IDCard_2006");
        spainDocs.add("ES_IDCard_2015");

        Map<String, String> configuration = new HashMap<>();
        configuration.put(VDDocumentConfiguration.CLOSE_BUTTON, "YES");

        ////////////// Veridas' recommended configuration //////////////
        configuration.put("capturebackgroundcolor", "#80000D44");
        configuration.put("continuebuttonbackgroundcolor", "#000D44");
        configuration.put("popupvalidationbackgroundcolor", "#000D44");
        configuration.put("documentdetectedoklevel1color", "#BADAAE");
        configuration.put("documentdetectedoklevel2color", "#87BF72");
        configuration.put("documentdetectedoklevel3color", "#53A335");
        configuration.put("documentdetectedveryclosecolor", "#EB8D00");
        configuration.put("documentdetectedveryfarcolor", "#EB8D00");
        configuration.put("textbackgroundcolor", "#000D44");
        configuration.put("repeatbuttonbackgroundcolor", "#FFFFFF");
        configuration.put("repeatbuttontextcolor", "#000D44");
        configuration.put("validationbackgroundcolor", "#ACB0C3");
        configuration.put("checkdocumenttextcolor", "#000D44");
        configuration.put("shutterbuttonmessagebackgroundcolor", "#000D44");
        configuration.put("tickcirclecolor", "#DCEFD4");
        configuration.put("tickcolor", "#53A335");
        configuration.put("tutorialbackgroundcolor", "#FFFFFF");
        configuration.put("tutorialtextcolor", "#000D44");
        configuration.put("tutorialcontinuebuttoncolor", "#000D44");
        configuration.put("tutorialtitlecolor", "#000D44");

        // Start the SDK
        VDDocumentCapture.startWithDocumentIDs(this, getApplicationContext(), spainDocs, configuration);
    }
}

...

// In another place you can stop the process (not recommended).
private boolean someMethod() {
    // Stop it whenever you want.
    VDDocumentCapture.stop(someContext);
}

...

// Interface methods

@Override
public void VDDocumentCaptured(ByteArrayInputStream byteArray, VDEnums.VDCaptureType captureType, List<VDDocumentType> documentType){
    // DEPRECATED
    // Do as needed with  the ByteArrayInputStream, the capture type and the possible VDDocumentsType of the captured document.

}

@Override
public void VDDocumentCutCaptured(ByteArrayInputStream byteArrayInputStream, VDEnums.VDCaptureType vdCaptureType, List<VDEnums.VDDocumentType> list) {
    // DEPRECATED
    // Do as needed with the ByteArrayInputStream of the cut of the document, the capture type and the possible VDDocumentsType of the captured document.
}

@Override
public void VDDocumentCaptured(byte[] byteArray, VDEnums.VDCaptureType captureType, List<VDDocument> documentType) {
     // Do as needed with  the image byte array, the capture type and the possible VDDocument of the captured document.
}

@Override
public void VDDocumentCutCaptured(byte[] byteArray, VDEnums.VDCaptureType captureType, List<VDDocument> documentType) {
    // DEPRECATED
    // Do as needed with the byte array of the cut of the document, the capture type and the possible VDDocument of the captured document.
}

@Override
public void VDDocumentCaptureFinished(boolean processFinished) {
    // Document capture finished. If processFinished is true, it means that all the captures have been taken. If it is false, it means that the user has closed the SDK
}

@Override
public void VDTimeWithoutPhotoTaken(int seconds, VDEnums.VDCaptureType vdCaptureType) {
   // Called when the number of seconds passed without taking the photo.
 }

Workflow¶

The next diagram represents the current workflow of the framework. Some method names may be shortened due to legibility issues.

Workflow

Logging events¶

The SDK logs various events, please refer to Logging Events to learn more about this subject.

Third party libraries¶

OpenCV 4.1.0 (main page. documentation). Library used for image manipulation.
Firebase: storage 20.0.0 (main page). Used for logging purposes. Only needed when using the VDLoggerFirebase library.
Glide: 4.16.0 (main page). Used for image loading.

Artifact	Size
common-core-X.Y.Z.aar	232 KB
common-core-jvm-X.Y.Z.jar	106 KB
common-logger-X.Y.Z.aar	19 KB
common-logger-firebase-X.Y.Z.aar (optional library)	17 KB

Architecture	Size
x86	8.6 MB
x86_64	9.2 MB
armeabi-v7a	6.9 MB
arm64-v8a	7.5 MB