Android User Guide for MRZ Integration

In this guide, you will learn step by step on how to build a MRZ scanner application with Dynamsoft Capture Vision Android SDK.

Android User Guide for MRZ Integration

Supported Machine-Readable Travel Document Types

The Machine Readable Travel Documents (MRTD) standard specified by the International Civil Aviation Organization (ICAO) defines how to encode information for optical character recognition on official travel documents.

Currently, the SDK supports three types of MRTD:

Note: If you need support for other types of MRTDs, our SDK can be easily customized. Please contact support@dynamsoft.com.

ID (TD1 Size)

The MRZ (Machine Readable Zone) in TD1 format consists of 3 lines, each containing 30 characters.

ID (TD2 Size)

The MRZ (Machine Readable Zone) in TD2 format consists of 2 lines, with each line containing 36 characters.

Passport (TD3 Size)

The MRZ (Machine Readable Zone) in TD3 format consists of 2 lines, with each line containing 44 characters.

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.

Add the SDK

Open the file [App Project Root Path]\app\build.gradle and add the Maven repository:

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

Add the references in the dependencies:

 dependencies {
     implementation 'com.dynamsoft:dynamsoftcapturevisionbundle:2.2.3000'
 }

Read more about the modules of dynamsoftcapturevisionbundle

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

Build Your First Application

In this section, we will explain how to create a HelloWorld implementation similar to our simple MRZScanner app for reading the MRZ zone from camera video input.

Note:

Android Studio 2024.1.1 is used here in this guide.

You can get similar source code from

MRZScanner Sample(Java)

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 Views Activity.
When prompted, set your app name to 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 99.6% of devices on the Google Play Store (last update: October 2023).

Include the Libraries

Add the SDK to your new project. Please read Add the SDK section for more details.

Deploy the CharacterModel & Template

A CharacterModel is a model file trained using deep neural networks for character recognition. A Template file in the Dynamsoft Capture Vision SDK offers a customizable configuration for optimizing barcode recognition, label recognition, document normalization, and bytes parsing settings. This enables users to tailor the capture process to their specific needs. For MRZ scanning, you have to include the required the MRZ CharacterModel and Template in your project first.

Right-click on the app folder, click New->Directory and select the src\main\assets to create an assets folder. Under the assets folder create two new folders, CharacterModel and Templates.
Copy the MRZ.data to the CharacterModel folder.
Copy the MRZScanner.json to the Templates folder.

Initialize License

Initialize the license in the file MainActivity.java.

import com.dynamsoft.license.LicenseManager;
public class MainActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        if (savedInstanceState == null) {
            LicenseManager.initLicense("DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9", this, (isSuccess, error) -> {
                error.printStackTrace();
            });
        }
    }
}

Note:

The license string here grants a time-limited free trial which requires network connection to work.

You can request for a 30-day trial license via the Trial License link.

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

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

 import com.dynamsoft.dce.CameraView;
 import com.dynamsoft.dce.CameraEnhancer;
 import com.dynamsoft.dce.utils.PermissionUtil;
 public class MainActivity extends AppCompatActivity {
     CameraEnhancer mCamera;
     @Override
     protected void onCreate(Bundle savedInstanceState) {
         ...
         // Add camera view for previewing video.
         PermissionUtil.requestCameraPermission(this);
         CameraView cameraView = findViewById(R.id.camera_view);
         mCamera = new CameraEnhancer(cameraView, this);
     }
 }

Initialize Capture Vision Router

Import and initialize the CaptureVisionRouter and set the previously created CameraEnhancer instance as its input.

 import com.dynamsoft.cvr.CaptureVisionRouter;
 import com.dynamsoft.cvr.CaptureVisionRouterException;
 public class MainActivity extends AppCompatActivity {
     ...
     private CaptureVisionRouter mRouter;
     @Override
     protected void onCreate(Bundle savedInstanceState) {
         ...
         mRouter = new CaptureVisionRouter(this);
         try {
             mRouter.setInput(mCamera);
         } catch (CaptureVisionRouterException e) {
             throw new RuntimeException(e);
         }
     }
 }

Create a CapturedResultReceiver and register with the CaptureVisionRouter instance to get the result of MRZ parsing.

 import com.dynamsoft.core.basic_structures.CapturedResultReceiver;
 import com.dynamsoft.dlr.RecognizedTextLinesResult;
 import com.dynamsoft.dcp.ParsedResult;
 ...
 public class MainActivity extends AppCompatActivity {
     @Override
     protected void onCreate(Bundle savedInstanceState) {
         ...
         mRouter.addResultReceiver(new CapturedResultReceiver() {
             @Override
             public void onParsedResultsReceived(@NonNull ParsedResult result)
             {
             }
         });
     }
 }

Initialize settings via a MRZ scanning template.

 try {
     mRouter.initSettingsFromFile("MRZScanner.json");
 } catch (CaptureVisionRouterException e) {
     throw new RuntimeException(e);
 }

Override MainActivity.onResume and MainActivity.onPause functions to start/stop video MRZ scanning. After scanning starts, the SDK will automatically recognize and parse the text in the MRZ area from the video frame, and send the parsed MRZ result to the callback function.

 import com.dynamsoft.dce.CameraEnhancerException;
 public class MainActivity extends AppCompatActivity {
     ...
     @Override
     public void onResume() {
         super.onResume();
         // Start video MRZ reading
         try {
             mCamera.open();
         } catch (CameraEnhancerException e) {
             e.printStackTrace();
         }
         mRouter.startCapturing("ReadPassportAndId", new CompletionListener() {
             @Override
             public void onSuccess() {}
             @Override
             public void onFailure(int errorCode, String errorString) {
                 runOnUiThread(() -> showDialog("Error", String.format(Locale.getDefault(), "ErrorCode: %d %nErrorMessage: %s", errorCode, errorString)));
             }
         });
     }
     @Override
     public void onPause() {
         super.onPause();
         // Stop video MRZ reading
         try {
             mCamera.close();
         } catch (CameraEnhancerException e) {
             e.printStackTrace();
         }
         mRouter.stopCapturing();
     }
 }

Extract Parsed Results

import com.dynamsoft.dcp.ParsedResultItem;
...
@Override
public void onParsedResultsReceived(@NonNull ParsedResult result) {
    if (!succeed) {
        onParsedResultReceived(result);
    }
}
...
private void onParsedResultReceived(ParsedResult result) {
    if (result.getItems() == null) {
        return;
    }
    // ParsedResult contains an array of ParsedResultItem, which stores the parse fields and values.
    // If the library failed to parse the content, the array length will be 0.
    if (result.getItems().length == 0) {
        // Do something when the library fails to parse the content.
    } else {
        // The assembleString method is implemented below. It gets all parse fields and assemble them into a string.
        String labelText = assembleString(result.getItems()[0]);
        if (labelText != null) {
            // Do something to display the result.
        }else {
            // Do something when the library fails to parse the content.
        }
    }
}
// This method is an example for how to extract the parsed information from a ParsedResultItem.
private String assembleString(ParsedResultItem item) {
    HashMap<String, String> entry = item.getParsedFields();
    String number = entry.get("passportNumber") == null ? entry.get("documentNumber") : entry.get("passportNumber");
    return "Document Type: " + item.getCodeType() + "\n" +
            "Document Number: " + number + "\n" +
            "Surname: " + entry.get("primaryIdentifier") + "\n" +
            "Given name: " + entry.get("secondaryIdentifier") + "\n" +
            "Gender: " + entry.get("sex") + "\n" +
            "Issuing State: " + entry.get("issuingState") + "\n" +
            "Nationality: " + entry.get("nationality") + "\n" +
            "Date of Birth(YY-MM-DD): " + entry.get("dateOfBirth") + "\n" +
            "Date of Expiry(YY-MM-DD): " + entry.get("dateOfExpiry") + "\n";
}

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 the connected device and launches it.

You can also download the similar source code of all the steps above:

MRZScanner Sample(Java)