Getting Started with Android

In this guide, you will learn step by step on how to build a document normalization application with Dynamsoft Document Normalizer Android SDK.

Read more on Dynamsoft Document Normalizer Features

Getting Started with Android
- Requirements
- Build Your First Application

Requirements

Supported OS: Android 5.0 (API Level 21) or higher.
Supported ABI: armeabi-v7a, arm64-v8a, x86 and x86_64.
Development Environment: Android Studio 2022.2.1 or higher.

Build Your First Application

In this section, let’s see how to create a HelloWorld app for normalizing documents from camera video input.

Note:

Android Studio 2022.2.1 is used here in this guide.

You can get the source code of the HelloWord app from the following link

Java.

Kotlin.

Create a New Project

Open Android Studio, select File > New > New Project.
Choose the correct template for your project. In this sample, we use Empty Activity.
When prompted, choose your app name ‘HelloWorld’ and set the Save location, Language, and Minimum SDK (we use 21 here).
Note:
- With minSdkVersion set to 21, your app is compatible with more than 94.1% of devices on the Google Play Store (last update: March 2021).

Add the SDK

There are two ways to add the SDK into your project - Manually and Maven.

Add the Library Manually

Download the SDK package from the Dynamsoft website. After unzipping, You can find the following aar files under the Dynamsoft\Libs directory:

File	Description
`DynamsoftDocumentNormalizer.aar`	The Dynamsoft Document Normalizer SDK which includes the document normalizer related APIs.
`DynamsoftCore.aar`	The core library of the Dynamsoft Capture Vision SDK which includes basic structures and intermediate result related APIs.
`DynamsoftCaptureVisionRouter.aar`	The CaptureVisionRouter is used to coordinate the image-processing and semantic-processing products that are being used in the application. It accepts an image source and returns processing results which may contain final results or intermediate results.
`DynamsoftImageProcessing.aar`	The image processing library of the Dynamsoft Capture Vision SDK, and so includes the image processing algorithms and APIs.
`DynamsoftLicense.aar`	This module includes the licensing API.
`DynamsoftCameraEnhancer.aar`	The Dynamsoft Camera Enhancer SDK defines the camera control and frame preprocessing API.
`DynamsoftUtility.aar (Optional)`	The module includes functional APIs that support you to integrate the input, filtering the results, generating result images, etc.

Copy the above six (seven if the Utility is included) aar files to the target directory HelloWorld\app\libs

Open the file HelloWorld\app\build.gradle and add reference in the dependencies:

 dependencies {
      implementation fileTree(dir: 'libs', include: ['*.aar'])

      def camerax_version = '1.1.0'
      implementation "androidx.camera:camera-core:$camerax_version"
      implementation "androidx.camera:camera-camera2:$camerax_version"
      implementation "androidx.camera:camera-lifecycle:$camerax_version"
      implementation "androidx.camera:camera-view:$camerax_version"
 }

Note:

DCE 4.x is based on Android CameraX, so you need to add the CameraX dependency manually.

Click Sync Now. After the synchronization completes, the SDK is added to the project.

Add the Library via Maven

Open the file HelloWorld\app\build.gradle and add the remote repository:

 repositories {
      maven {
         url "https://download2.dynamsoft.com/maven/aar"
      }
 }

Add reference in the dependencies:

dependencies {
   implementation 'com.dynamsoft:dynamsoftdocumentnormalizerbundle:2.2.10'
}

Click Sync Now. After the synchronization completes, the SDK is added to the project.

Initialize License

Import the LicenseManager class and initialize the license in the file MyApplication.java.

import com.dynamsoft.license.LicenseManager;

public class MyApplication extends Application {
   private static final String TAG = "MyApplication";
   private static final String LICENSE = "DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9";

   @Override
   public void onCreate() {
      super.onCreate();
      LicenseManager.initLicense(LICENSE, this, (isSuccess, error) -> {
            if (!isSuccess) {
               Log.e(TAG, "InitLicense Error: " + error);
            }
      });
   }
}

Note:

Network connection is required for the license to work.

The license string here will grant you a time-limited trial license.

If the license has expired, you can go to the customer portal to request for an extension.

MainActivity for Realtime Document Normalization

Initialize Camera Module

In the Project window, open app > res > layout > activity_main.xml and create a DCE camera view section under the root node.

 <com.dynamsoft.dce.CameraView
     android:id="@+id/camera_view"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     app:layout_constraintBottom_toBottomOf="parent"
     app:layout_constraintLeft_toLeftOf="parent"
     app:layout_constraintRight_toRightOf="parent"
     app:layout_constraintTop_toTopOf="parent">
 </com.dynamsoft.dce.CameraView>

Import the camera module, initialize the camera view and bind to the created Camera Enhancer instance in the file MainActivity.java.

...
   
import com.dynamsoft.dce.CameraView;
import com.dynamsoft.dce.CameraEnhancer;
import com.dynamsoft.dce.CameraEnhancerException;
import com.dynamsoft.dce.utils.PermissionUtil;

public class MainActivity extends AppCompatActivity {
   private CameraEnhancer mCamera;

   @Override
   protected void onCreate(Bundle savedInstanceState) { 

      ...

      CameraView cameraView = findViewById(R.id.camera_view);
      mCamera = new CameraEnhancer(cameraView, MainActivity.this);
 
      PermissionUtil.requestCameraPermission(MainActivity.this);
   }
}

Initialize Capture Vision Router

Import and initialize the capture vision router, and set the created Camera Enhancer instance as the input image source.

...

import com.dynamsoft.cvr.CaptureVisionRouter;
import com.dynamsoft.cvr.CaptureVisionException;

public class MainActivity extends AppCompatActivity {
      
   ...

   private CaptureVisionRouter mRouter;

   @Override
   protected void onCreate(Bundle savedInstanceState) { 
         
      ...

      mRouter = new CaptureVisionRouter(MainActivity.this);
      try {
            mRouter.setInput(mCamera);
      } catch (CaptureVisionRouterException e) {
            e.printStackTrace();
      }
   }
}

Add a Captured Result Receiver and Filter

Add a result receiver to get the normalized image results.

...

import com.dynamsoft.core.basic_structures.CapturedResultReceiver;
import com.dynamsoft.core.basic_structures.ImageData;
import com.dynamsoft.cvr.EnumPresetTemplate;
import com.dynamsoft.ddn.NormalizedImagesResult;

public class MainActivity extends AppCompatActivity {
      
   ...

   public static ImageData mNormalizedImageData;
   private boolean mJumpToOtherActivity = false;

   @Override
   protected void onCreate(Bundle savedInstanceState) { 
         
      ...
         
      mRouter.addResultReceiver(new CapturedResultReceiver() {
            @Override
            public void onNormalizedImagesReceived(NormalizedImagesResult result) {
               if (mJumpToOtherActivity && result.getItems().length > 0) {
                  mJumpToOtherActivity = false;

                  mNormalizedImageData = result.getItems()[0].getImageData();

                  Intent intent = new Intent(MainActivity.this, ResultActivity.class);
                  startActivity(intent);
               }
            }
      });
   }
}

Add a result cross filter to validate the normalized image result across multiple frames.

...

import com.dynamsoft.utility.MultiFrameResultCrossFilter;

public class MainActivity extends AppCompatActivity {
      
   ...

   @Override
   protected void onCreate(Bundle savedInstanceState) { 
         
      ...
         
      MultiFrameResultCrossFilter filter = new MultiFrameResultCrossFilter();
      filter.enableResultCrossVerification(CRIT_NORMALIZED_IMAGE, true);
      mRouter.addResultFilter(filter);
   }
}

Start and Stop Video Document Normalization

Override the MainActivity.onResume function to open camera and start video document normalization, override the MainActivity.onPause function to close camera and stop video document normalization.

public class MainActivity extends AppCompatActivity {
      
   ...

   @Override
   public void onResume() {
      super.onResume();
      try {
            mCamera.open();
            mRouter.startCapturing(EnumPresetTemplate.PT_DETECT_AND_NORMALIZE_DOCUMENT);
      } catch (CameraEnhancerException | CaptureVisionRouterException e) {
            e.printStackTrace();
      }
   }

   @Override
   public void onPause() {
      super.onPause();
      try {
            mCamera.close();
      } catch (CameraEnhancerException e) {
            e.printStackTrace();
      }

      mRouter.stopCapturing();
   }
}

Add onCaptureBtnClick function to start the video document normalization. After start capturing, the SDK will process the video frames from the Camera Enhancer, then send the normalized image results to the registered result receiver.
```
public class MainActivity extends AppCompatActivity {
      
   ...

   public void onCaptureBtnClick(View v) {
     mJumpToOtherActivity = true;
   }
}
```

Additional Steps in MainActivity

In the Project window, open app > res > layout > activity_main.xml, create a button under the root node to capture the quads detected on the image.

...

<Button
   android:id="@+id/btn_capture"
   android:layout_width="130dp"
   android:layout_height="50dp"
   android:layout_marginBottom="8dp"
   android:onClick="onCaptureBtnClick"
   android:text="Capture"
   app:layout_constraintBottom_toBottomOf="parent"
   app:layout_constraintEnd_toEndOf="parent"
   app:layout_constraintHorizontal_bias="0.5"
   app:layout_constraintStart_toStartOf="parent" />

ResultActivity for Displaying the Normalized Image

Display the Normalized Image

Create a new empty activity named ResultActivity.

In the Project window, open app > res > layout > activity_result.xml, create a image view under the root node to display the result image.

<ImageView
   android:id="@+id/iv_normalize"
   android:layout_width="match_parent"
   android:layout_height="match_parent"/>

Display the normalized image.

import com.dynamsoft.core.basic_structures.CoreException;

public class ResultActivity extends AppCompatActivity {

   @Override
   protected void onCreate(@Nullable Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.activity_result);

      ImageView ivNormalize = findViewById(R.id.iv_normalize);

      try {
            ivNormalize.setImageBitmap(MainActivity.mNormalizedImageData.toBitmap());
      } catch (CoreException e) {
            e.printStackTrace();
      }
   }
}

Build and Run the Project

Select the device that you want to run your app on from the target device drop-down menu in the toolbar.
Click the Run app button, then Android Studio installs your app on your connected device and starts it.

You can download the similar source code here:

Java.
Kotlin.