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
`DynamsoftCaptureVisionRouter.aar`	The capture vision router library of Dynamsoft’s capture vision SDK is used by users to interact with image processing and semantic processing products in their applications. It takes an image source as input and provides processing results, which can include final results or intermediate results.
`DynamsoftDocumentNormalizer.aar`	The document normalizer library of Dynamsoft’s capture vision SDK includes document normalizer related algorithms and APIs.
`DynamsoftCore.aar`	The core library of Dynamsoft’s capture vision SDK includes common basic structures and intermediate result related APIs.
`DynamsoftImageProcessing.aar`	The image processing library of Dynamsoft’s capture vision SDK incorporates a collection of basic and specialized image processing algorithms designed to support other SDK modules such as Document Normalizer.
`DynamsoftLicense.aar`	The license library of Dynamsoft’s capture vision SDK includes license related APIs.
`DynamsoftUtility.aar`	The utility library of Dynamsoft’s Capture Vision SDK includes multiple implementations of image source adapters, image exporter, and other utility APIs.
`DynamsoftCameraEnhancer.aar`	The Dynamsoft Camera Enhancer SDK provides camera control, camera enhancements, and basic UI configuration features.

Copy the above five 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:dynamsoftcapturevisionrouter:2.0.10'
   implementation 'com.dynamsoft:dynamsoftdocumentnormalizer:2.0.10'
   implementation 'com.dynamsoft:dynamsoftcameraenhancer:4.0.0'
   implementation 'com.dynamsoft:dynamsoftutility:1.0.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.DCECameraView
     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.DCECameraView>

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.